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

docs/DECISIONS.md

@@ -0,0 +1,84 @@
+# DECISIONS
+
+Stable IDs; newest at the bottom. Each records context, choice, alternatives, consequences.
+
+## D1 — Vault-first credentials, `api.zai` direct; credential.json fallback
+
+- **Context:** the Aygea Claude statusline used `~/.secretvault/credential.json`
+  (`url` + `clientKey` → `vault.itsaygea.com` proxy). The user wants this repo public
+  and machines to need nothing but their existing SecretVault (`zai_api_key`).
+- **Choice:** read `zai_api_key` via `secretvault run` (name from env, default
+  `zai_api_key`), hit `https://api.z.ai/api/monitor/usage/quota/limit`; fall back to
+  credential.json → `${url}/proxy/zai/...`. Key reaches curl via a 0600 header file
+  (`--header @file`), never argv.
+- **Alternatives:** bake the proxy URL + require credential.json everywhere (rejected:
+  repo would document private infra as a requirement); store JSON {url,key} in the
+  vault (rejected: existing secret is a plain key).
+- **Consequences:** one secret per machine is the only setup; trial
+  `mcode-endpoint-key-pairing-2026-10-19` pins the pairing. Proxy users still work.
+
+## D2 — mcode statusline mechanics (verified facts, release-pinned)
+
+Confirmed by reading the 0.6.12 bundle — re-verify after every mcode update.
+Files (SHA-256): `chunks/launcher-AVQRYDKB.js` `2c4337e3…edfbe3`,
+`chunks/chunk-X3PES5WL.js` `600c23d…09ee5` under
+`~/.minimax-code/releases/0.6.12/lib/node_modules/@minimax-ai/code/`.
+
+- Config source: `<dataDir>/config.yaml` → `tui.statusLine` (array) +
+  `tui.customStatusLine` (`Pv()` in launcher chunk).
+- Valid statusLine items: `current-dir, session-title, git-branch, review-link,
+  plan-mode, approval-mode, model-with-reasoning, model, context-window, subagent,
+  token-quota, cache-read-ratio, context-remaining, context-meter, custom-command`.
+- Custom command runner: only active when `custom-command` is in `statusLine` **and**
+  `build-mode` is not; command required (non-empty). Schema:
+  `display: inline|block`, `position: above|below`, `colorMode: plain|ansi`,
+  `intervalSeconds` (default 0 = off, clamp ≥10), `timeoutMs` (default 5000,
+  clamp 500–30000), block `maxLines` default 3 (clamp 1–5).
+- Invocation: `{command}` parsed + spawned with `cwd = workspace_dir`, JSON on stdin
+  (`{protocol, event: startup|interval|session-change|workspace-change, session_id,
+  workspace_dir, model, session_title, tui_version}`), stdout capped ~8 KiB
+  (exact cap expression `Q1` not disambiguated: `8*1024` vs `8e3` — inferred).
+  stdout becomes the `custom-command` item **only on exit 0 without timeout**;
+  inline mode renders the first line; `colorMode: ansi` keeps escape codes when the
+  terminal color level > 0, strips otherwise.
+- **Consequence:** our script must be silent-fail (`exit 0`, empty output when unknown)
+  and must not rely on stdin content.
+
+## D3 — mcode is the scheduler; refresh decoupled in-process
+
+- **Context:** the Claude statusline needed a systemd timer because Claude Code has no
+  interval hook. mcode's `customStatusLine.intervalSeconds` re-runs the command itself.
+- **Choice:** no cron/systemd. On each call: fresh cache (≤150s) → print; stale → spawn
+  detached (`setsid`, fallback `& disown`) flock-guarded refresh (`--refresh-bg`) and
+  show the still-valid value (≤360s) or nothing.
+- **Consequences:** zero extra services; segment self-heals; offline machines just hide
+  the segment after 6 min. Timer coexistence is harmless (same cache file).
+
+## D4 — Shared cache with the Claude Aygea statusline
+
+- **Choice:** keep schema `{pct, reset_iso, ts}` at `~/.cache/aygea-sl/quota.json`
+  exactly as the Claude refresher writes it (reset written as local ISO; epoch
+  conversions have GNU/BSD branches).
+- **Consequence:** both ecosystems interop; any writer refreshes both. Constrained the
+  parser to ISO strings instead of the internally simpler `reset_ms`.
+
+## D5 — Config merge safety rails
+
+- **Context:** user requirement: atomic, previous-entry aware, must never break a config
+  holding API keys. Two early bugs (in-place write; backup taken after merge) proved the point.
+- **Choice:** python3 stdlib line surgery limited to the `tui:` block; refuses multiple
+  `tui:` blocks or duplicate keys; validates result (structural + PyYAML when available);
+  writes temp + fsync + `os.replace`; preserves mode (0600 for new); timestamped backup
+  copied **before** first modification; byte-exact elsewhere (incl. trailing newline).
+- **Alternatives:** PyYAML full round-trip (rejected: reformats/comments lost); yq
+  (rejected: extra dependency on every machine).
+- **Consequences:** merge is monotonic and reviewable; `docs/FEATURE-MATRIX.md` gates
+  remaining platform risk.
+
+## D6 — Public repo + Gitea over SSH port 2222
+
+- **Choice:** repo `git.itsaygea.com/admin/mcode-sl` (`main`); remote via SSH; the
+  curl one-liner points at `…/raw/branch/main/install.sh`. No secrets in the repo by
+  design (D1).
+- **Consequences:** see `AGENTS.md` → "SSH to Gitea" for the port-22 incident record,
+  accepted host-key fingerprint, and the repeat guard.

docs/FEATURE-MATRIX.md

@@ -0,0 +1,20 @@
+# FEATURE-MATRIX
+
+Status: `confirmed` (verified within stated coverage) / `inferred` / `unknown`.
+Evidence links point at trials, digests, or recorded commands.
+
+| Capability | Status | Coverage / limits | Evidence |
+|---|---|---|---|
+| Quota fetch via SecretVault key → `api.z.ai` | confirmed | this machine; key `zai_api_key` | `trials/mcode-endpoint-key-pairing-2026-10-19/record.md` |
+| Quota fetch via credential.json → `vault.itsaygea.com` proxy | confirmed | code path exercised in dev; falls back only | same record |
+| Statusline segment output (value, clock, remaining, colors, thresholds) | confirmed | plain + 256 + truecolor modes exercised with mock caches | session commands, `CHANGELOG` 2026-10-19 |
+| Stale/hidden behavior (≤150s fresh; ≤360s stale shown; >360s hidden) | confirmed | mock-cache tests, exit 0 always | session commands |
+| mcode config schema + clamps (0.6.12) | confirmed | release-pinned; re-check on updates | `docs/DECISIONS.md` D2 |
+| Config merge: atomic write, 0600, backup-before-change, refusal, byte-preservation, uninstall | confirmed | Linux host, 14/14 matrix | `trials/config-merge-safety-2026-10-19/` |
+| Piped (`curl \| bash`) install with embedded copy | confirmed | embed byte-identical (S5) | same |
+| Segment renders in live mcode TUI (ANSI + emoji) | **inferred** | passthrough verified in code; not yet seen on screen | D2; pending user restart |
+| macOS end-to-end (install, date -r, no flock/setsid, `install -m`, vm_stat) | **unknown** | written portable, never run on macOS | TODO |
+| Ubuntu rollout ×2 | **unknown** | not yet executed | TODO |
+| secretvault CLI present + secret readable on other machines | **unknown** | assumed per user statement; verify at rollout | TODO |
+| Background refresh survives mcode process-group kills | confirmed (by construction) | `setsid` detach; not adversarially tested | D3 rationale |
+| mcode update resilience | **unknown** | bundle re-read required each release | D2 repeat guard |

docs/PROJECT-HANDOFF.md

@@ -0,0 +1,37 @@
+# PROJECT-HANDOFF
+
+How to resume work in this repo.
+
+## Entry sequence
+
+1. `CURRENT_STATE.md` — objective, what's confirmed, exact next action.
+2. `TODO.md` — prioritized work with acceptance criteria.
+3. Latest file in `handoffs/` — where the last stage stopped and why.
+4. `TRIALS.md` — don't repeat what a verdict already settled.
+5. `git status` + `git log` — see what's in flight.
+
+## Authoritative records
+
+- Decisions + verified mcode internals: `docs/DECISIONS.md` (D2 is release-pinned —
+  re-verify after mcode updates).
+- Capability truth table: `docs/FEATURE-MATRIX.md` (update status as evidence lands).
+- Regression gate for the installer: `trials/config-merge-safety-2026-10-19/verify.sh`
+  (must pass 14/14 before committing installer changes).
+- Host-specific facts (Gitea SSH on 2222, key fingerprints): `AGENTS.md` → "SSH to Gitea".
+
+## Handoff protocol
+
+At a meaningful stage boundary write `handoffs/<date>-<topic>.md` from
+`handoffs/TEMPLATE.md`: stopping point, verified results + evidence links, corrected
+assumptions, blockers, exact next action with acceptance criteria, reproduction
+commands, and git state (branch, commit, push result). Preserve prior handoffs; link
+artifacts instead of duplicating logs.
+
+## Environment assumptions (this project)
+
+- Linux host `mewtwo` (Ubuntu-based, PVE); MiniMax Code 0.6.12 at
+  `~/.minimax-code/releases/0.6.12/`; data dir `~/.minimax/`.
+- `secretvault` CLI at `~/.local/bin/secretvault`; secret `zai_api_key` (production).
+- Remote: `git@git.itsaygea.com:admin/mcode-sl.git` — port 2222, see `AGENTS.md`.
+
+Nothing above is portable to other machines without re-verification (see FEATURE-MATRIX).

docs/README.md

@@ -0,0 +1,5 @@
+# docs
+
+- `PROJECT-HANDOFF.md` — how to resume work here; where authoritative records live.
+- `DECISIONS.md` — indexed decisions (ADR-style) with evidence.
+- `FEATURE-MATRIX.md` — capability × verification status; the honest state of the world.