From 56b0de687e728cb9d81550dd1c9d0228e07e0d99 Mon Sep 17 00:00:00 2001
From: lex00 <121451605+lex00@users.noreply.github.com>
Date: Fri, 7 Aug 2026 14:28:15 -0600
Subject: [PATCH] the agent lead-in: shortest path, and what wastes your time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What #61 asked for, at the scope it asked for: not a second README but
the inverse of one — the three commands, the params variable, the
check/e2e-equals-CI rule, and the list of things that look like breakage
and are not (the foreign-cluster guard, the ha first-boot restart, the
turn endings upstream is mid-change on). CLAUDE.md is a symlink so there
is exactly one file to keep true, and the pointer to status keeps even
this one from being trusted over reality.

Two of the issue's own bullets aged out before the file existed — the
registration API is documented now and the light-tier restarts are gone
— which is the rot argument for keeping it short made by the issue
itself.

Closes #61.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017BQGewVRzp9FS1jXn1H6A6
---
 AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 45 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e42713a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# For agents
+
+The shortest correct path, and the things that will waste your time. The
+[docs site](https://intentius.io/fountain-ops/) has the paragraphs;
+[status](https://intentius.io/fountain-ops/status/) is authoritative over
+anything written in the present tense anywhere else, this file included.
+
+## The path
+
+- `just doctor` first, always. It ends on the literal next command.
+- `just up` is the entry point; `just down` deletes the whole throwaway
+  cluster, so failure recovery is cheap — re-running `up` is safe and never
+  rotates the secret.
+- Build parameters go through the variable, not positionally:
+  `just params="--param tier=ha" up`.
+- `just check` is literally CI's check job and `just e2e` its e2e job. Run
+  `check` before proposing any change; `e2e` before claiming a deploy-path
+  change works.
+- Registration is `POST /api/auth/register` — no browser needed — and the
+  instance's first verified account becomes the admin, so register before
+  exposing anything.
+
+## Things that look like breakage and are not
+
+- Every recipe that touches a cluster refuses a kube context other than
+  `k3d-fountain-local`. The refusal is a guard, not a bug;
+  `ALLOW_FOREIGN_CLUSTER=1` is the deliberate override.
+- At `tier=ha` on a brand-new database, one replica may show `RESTARTS 1`,
+  once: both replicas race to create the migrations table and the loser's
+  retry wins ([#90](https://github.com/INTENTIUS/fountain-ops/issues/90)).
+  At `light`, any restart is a real finding.
+- How a conversation turn *ends* against the emulator varies by fountain
+  release and is being actively worked on upstream. `just verify-conversation`
+  reports which ending it observed; do not chase the ending, and do not add
+  assertions about it.
+
+## Things that will waste your time if edited directly
+
+- `.github/workflows/*.yml` are rendered from `ci/`, `pages/` and
+  `e2e-k8s/` TypeScript declarations — edit those and run `just ci`;
+  `just ci-check` fails CI on a hand edit.
+- `dist/` is build output. The docs pages under `docs-site/` are source.
+- The roadmap is [the issues](https://github.com/INTENTIUS/fountain-ops/issues);
+  there is no roadmap file to update.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file