AGENTS.md · diff
git:20260706.1e2e913 to git:20260815.844bc33
19 added, 0 removed. Audit A to A.
# a2ui-catalogue — Agent Entry Point
**This file exists so that ANY coding agent (Gemini, Antigravity, Codex, Claude, …)
finds the working rules.** The canonical rules live in `CLAUDE.md` — read it in full
before doing anything. `project.yaml` is the inventory (deployments, script IDs,
policy, declared processes); never carry identifiers from conversation memory when
the manifest declares them.
## Non-negotiables (summary — CLAUDE.md is authoritative)
1. **Every operation goes through a declared process.**
`python3 ops/ops.py list` → `python3 ops/ops.py run <process>`.
If the operation you need is not declared, declare it in `project.yaml`
`processes:` first, then run it. **Raw `clasp push` / `clasp deploy` or ad-hoc
command chains are forbidden** — improvisation is the failure mode this system
exists to prevent. "ops.py run X *or* standard clasp push" is not a plan; it is
the bug.
2. **Nothing new is published** to a2uicatalog.ai or any public surface without
explicit per-artifact opt-in from Curtis (`policy.published` in `project.yaml`,
enforced by tests). Never `git add -A`. Commits go through
`python3 ops/ops.py commit "<msg>"`; push through `ops.py run repo-publish`.
3. **Renderer source is ground truth.** When `atoms/schema.yaml` prose and a
renderer `.gs` file disagree about a field shape, the renderer wins
(known case: `spring_nodes` edges are `{from, to}` node IDs, not the
documented `{a, b}` index pairs).
4. **Verify before shipping:** `python3 -m pytest tests/ -q`. Check
`ops/log.jsonl` before re-diagnosing anything — a previous run may have
already recorded it.
5. Encoded `?p=` URLs are emitted by `scripts/make_url.py` only — never
hand-typed or copied between surfaces.
+ 6. **Mutating git commands must name the repo explicitly:**
+ `git -C <path> add|commit|push`. Ambient cwd and a leading `cd` do not
+ count — the shell cwd resets between calls. Commits and pushes go through
+ the declared processes in rule 2, never raw git.
+
+ ## This checkout is incomplete on its own
+
+ `ops/`, `thoughts/`, `a2uithoughts.md`, `improve.yaml` and `improve_probes` are
+ **symlinks into a sibling private repo and are not tracked here.** A standalone
+ clone of this repo has none of them, so every `ops.py` invocation above will
+ fail until they exist. Maintainers: clone the private repo as a sibling
+ directory and run its bootstrap.
+
+ - **CI must check out both repos and recreate the links** before running
+ `ops.py` — see `.github/workflows/deploy-full-catalog.yml`.
+ - If something reports "file not found" for a path that plainly exists on your
+ machine, run `git ls-files <path>` before theorising — an untracked symlink
+ is the usual answer.
+
Private-side operations (clasp identities, deploy mechanics, GAS gotchas) are
documented in the **a2ui-private** repo's `AGENTS.md` — read that too before any
deployment work.
If you take actions in this repo, log what you did and why in your own scratch
file under `/home/curtis/a2ui-private/` (agent logs never go in this public tree).