docs: AGENTS.md + evidence-backed scaffold (state, trials, decisions, handoff)

- AGENTS.md operating rules incl. Gitea SSH port-2222 note + known_hosts incident
- CURRENT_STATE / TODO / CHANGELOG / TRIALS
- trials: endpoint-key pairing; config-merge safety matrix 14/14 (verify.sh + output)
- docs: DECISIONS (mcode 0.6.12 bundle facts, digest-pinned), FEATURE-MATRIX, PROJECT-HANDOFF
- handoffs: TEMPLATE + 2026-10-19 initial-install record

AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md — mcode-status
+
+Aygea z.ai GLM usage segment for the MiniMax Code statusline. Three shipped files:
+`zai-usage.sh` (the segment), `install.sh` (self-extracting installer with an embedded
+copy), `README.md` (public-facing docs). No `src/` — root is the project.
+
+## Starting or resuming work
+
+1. Read `CURRENT_STATE.md`, then relevant `TODO.md` entries and the latest file in
+   `handoffs/`. Check `TRIALS.md` before repeating any investigation.
+2. Inspect `git status` / `git log` before editing. The remote is
+   `git@git.itsaygea.com:admin/mcode-sl.git` (see SSH notes below).
+3. Pick one bounded objective with explicit acceptance criteria; finish it before
+   starting another.
+
+## Storage and isolation
+
+- Scratch work goes in `tmp/` (git-ignored). Durable evidence goes in `trials/<topic>-<date>/`
+  or `evidence/`. OS temp dirs are not durable evidence.
+- **Never commit secrets.** The z.ai key lives in SecretVault (`zai_api_key`) and is read
+  at runtime via `secretvault run`; `~/.secretvault/credential.json` never enters the repo.
+- Host-specific paths (e.g. `/home/aygea/.minimax-code/releases/<ver>/...`) are recorded
+  in docs as facts about *this* machine, not portable assumptions.
+
+## Evidence and confidence
+
+Mark every technical claim in docs as `confirmed` (directly verified, scope stated),
+`inferred` (supported interpretation), or `unknown` (untested). Record input paths,
+SHA-256 digests, tool versions, and exact commands. Rule of thumb here:
+
+- Anything read out of the mcode bundle is confirmed **for that release only**
+  (`0.6.12`, digests in `docs/DECISIONS.md`); re-verify after every mcode update.
+- Anything not run on real hardware (e.g. macOS) stays `unknown`, however portable
+  the code looks.
+- The safety matrix in `trials/config-merge-safety-2026-10-19/` is the regression gate
+  for `install.sh` — run it before committing installer changes.
+
+## Trials
+
+Uncertain approach or capability question → bounded trial under
+`trials/<topic>-<YYYY-MM-DD>/` with question, scope, commands, expected vs observed,
+verdict (`confirmed` / `rejected` / `inconclusive` / `blocked`), and a repeat guard.
+Conventions + template: `trials/README.md`. Index: `TRIALS.md`. Preserve failed runs.
+
+## Implementation and verification
+
+- `install.sh` embeds a copy of `zai-usage.sh`. Checkout installs prefer the sibling
+  file; after editing `zai-usage.sh`, regenerate the embedded copy (command in README)
+  so `curl | bash` stays identical — the S5 check in the safety matrix enforces this.
+- `bash -n` both scripts, then run the safety matrix, before committing.
+- The statusline contract: always `exit 0`, print nothing when unknown, never block on
+  the network (refresh is a detached background job). Violating this freezes the TUI.
+
+## Collaboration and Git
+
+- Commit reviewed work at stage boundaries; push to `origin main` when the work is
+  verified (established policy for this repo). Report push failures plainly.
+- Preserve others' uncommitted work; never reset/discard what you didn't write.
+
+### SSH to Gitea (read before touching the remote)
+
+`git.itsaygea.com` runs **Gitea in Docker with SSH on port 2222**. Port 22 on that
+hostname is the *host machine's own sshd* — a different server with different host keys.
+
+- `~/.ssh/config` carries the stanza that makes plain `git push` work:
+  `Host git.itsaygea.com` → `Port 2222`, `User git`, `IdentityFile ~/.ssh/id_ed25519`.
+- Registered account key: **"Mewtwo Aygea"**,
+  `SHA256:Xc++/NLDGWbXqnzLWleNOhK8/NIgtSBN0xGxNx3gUfs` (= local `id_ed25519.pub`).
+- Gitea host key (ED25519) accepted 2026-10-19:
+  `SHA256:VpdMjgEGpmRPyLhbOpYvrFNWNAxglINkKTgJo5T/sOQ`.
+- **Incident record:** on 2026-10-19 a first probe hit port 22, produced a
+  "REMOTE HOST IDENTIFICATION HAS CHANGED" warning, and wrong (host) keys were briefly
+  appended to `~/.ssh/known_hosts` under this hostname. They were removed and replaced
+  with the real port-2222 keys. Repeat guard: any future host-key warning for
+  `git.itsaygea.com` must be checked against the fingerprint above **and** rescanned on
+  port 2222 (`ssh-keyscan -p 2222`) — never trust a key captured from port 22. If the
+  server was not reinstalled, treat it as an incident.
+
+## Stage completion and handoff
+
+At a meaningful boundary: run acceptance checks → update `CURRENT_STATE.md`, `TODO.md`,
+`CHANGELOG.md`, `TRIALS.md` → write a handoff under `handoffs/` (template there) →
+review the diff → commit → push → report handoff path, commit hash, push result, and
+working-tree status separately. Not after every minor action.