mcode-sl/AGENTS.md

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.