# 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.