query-xano

Read-only Xano + content-engine query skill. Used by agents that need to introspect schema before writing another skill. Always scope-only - there is no apply, no gate, no mutation.

Steps

1. List tables

import { listTables } from "../lib/xano.ts";
const rows = await listTables();
// [{ name: "contacts", id: 123 }, ...]

2. Describe one

import { describeTable } from "../lib/xano.ts";
const cols = await describeTable("contacts");

3. Run SQL against the content engine

import { query } from "../lib/content-engine.ts";
const res = await query("SELECT count(*) FROM content_atoms");

Note: SQL goes to Neon via the content-engine Fly proxy (hosted at rb-content-engine.fly.dev). That is not Xano - hence the separate lib. Xano has its own metadata API (listTables / describeTable) but no raw SQL. The mini wiki page state/docs/xano/schema.md is the canonical table reference.

Eval

Actor: xano.ts HTTP client. Auditor: shape + field-presence cross-check per mode.

Catches: API returning 200 with empty body (known Xano edge case), partial schema where columns lack type info, row-count header mismatch.

Gotchas

• XANO_METADATA_TOKEN in .env.cache - throws loudly if missing.
• Content-engine proxy is at rb-content-engine.fly.dev, different host

from the Xano instance. No auth required.

• There's a second Xano instance for Orbiter QA (xh2o-yths-38lt). Use

state/lib/pipeline.ts for that, not xano.ts.

Rubric

criteria:
  - name: correct_mode_output_shape
    kind: deterministic
    check: "Output JSON matches the expected schema for the given 'mode' input as per the Eval section."
  - name: xano_read_only_enforcement
    kind: deterministic
    check: "No mutations or irreversible side-effects are observed in the Xano or Content Engine data after skill execution."
  - name: sql_target_validity
    kind: judge
    check: "If 'mode' is 'query', the 'target' input is valid SQL for the content engine (PostgreSQL dialect)."
  - name: response_content_accuracy
    kind: judge
    check: "The data returned is accurate according to the 'target' input query or description, reflecting source truth."

query-xano - loader

Per-turn rules for the query-xano skill. Full reference: state/skills/query-xano/SKILL.md. Do not skip these.

Critical Rules

• NEVER assume content-engine is Xano. It is Neon Postgres via the rb-content-engine.fly.dev proxy. Use state/lib/content-engine.ts query() for raw SQL; Xano has no raw-SQL endpoint.
• NEVER hit the wrong Xano instance. The Orbiter QA instance (xh2o-yths-38lt) uses state/lib/pipeline.ts, not state/lib/xano.ts.
• ALWAYS read XANO_METADATA_TOKEN via env("XANO_METADATA_TOKEN") - state/lib/env.ts throws loudly if missing. No bash fallback.
• ALWAYS treat this skill as read-only. There is no apply, no gate, no mutation.

Commands

| ui dashboard | state/skills/query-xano/resources/ui.openui | |invoke (tables): import { listTables } from "../lib/xano.ts"; await listTables() |invoke (describe): import { describeTable } from "../lib/xano.ts"; await describeTable("contacts") |invoke (SQL): import { query } from "../lib/content-engine.ts"; await query("SELECT count(*) FROM content_atoms") |verify: shape check per mode (see Eval table in state/skills/query-xano/SKILL.md) |eval log: state/log/evals.ndjson (skill: "query-xano")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/query-xano/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Xano returns 200 with empty body on certain edge cases - shape gate scores 0.0 on empty array.
• Schema describe sometimes returns columns missing type - score 0.5 if partial.
• Content-engine proxy is at rb-content-engine.fly.dev, NOT a Xano host. No auth required for that proxy.
• The mini wiki page state/docs/xano/schema.md is the canonical table reference - check it before re-introspecting.

Self-Test

An agent reading this should correctly:

1. [ ] Use content-engine.ts (not xano.ts) for raw SQL
2. [ ] Use pipeline.ts (not xano.ts) for Orbiter QA queries
3. [ ] Refuse to invoke any apply/mutation path through this skill

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] query-xano: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] query-xano: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.