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
This commit is contained in:
aygea committed
1 parent
9ad073d4fc
commit
fd8e8cbbd7
20 files changed
+619
No files matched your search
@@ -0,0 +1,75 @@
|
||||
# Handoff: 2026-10-19 — initial release, install, push, docs scaffold
|
||||
|
||||
## Objective and stopping point
|
||||
|
||||
Build a self-contained z.ai GLM usage segment for the MiniMax Code statusline
|
||||
(`zai-usage.sh` + self-extracting `install.sh`), install it on this machine, publish to
|
||||
`git.itsaygea.com/admin/mcode-sl`, and scaffold the evidence-backed docs structure.
|
||||
Stopped at the stage boundary: installed + pushed; TUI visual check and cross-machine
|
||||
rollout deliberately left for next stages.
|
||||
|
||||
## Verified results and evidence
|
||||
|
||||
- `confirmed` — Safety matrix 14/14 on Linux: `trials/config-merge-safety-2026-10-19/output.txt`
|
||||
(atomic write, 0600, backup == pre-merge original, duplicate-tui refusal untouched,
|
||||
piped-install embed byte-identical, uninstall clean).
|
||||
- `confirmed` — Key/endpoint pairing: `trials/mcode-endpoint-key-pairing-2026-10-19/record.md`
|
||||
(vault key → api.z.ai 200; proxy 401; credential.json clientKey → proxy 200).
|
||||
- `confirmed` — Live install on this machine: secret found, backup
|
||||
`~/.minimax/config.yaml.bak.20261019-231642`, cache primed (`🔥 1% · 4:16a(4h59m)`),
|
||||
provider/apiKey intact in `~/.minimax/config.yaml`.
|
||||
- `confirmed` — Push: `main` → `git@git.itsaygea.com:admin/mcode-sl.git`; raw URL serves
|
||||
a valid installer whose embedded copy matches the installed script.
|
||||
- `inferred` — TUI rendering (colors/emoji): passthrough verified in bundle code
|
||||
(`docs/DECISIONS.md` D2), not yet observed on screen.
|
||||
- File digests at stage start: `zai-usage.sh` `ca2141a5…fa63c61`,
|
||||
`install.sh` `a6c433da…4989a1`, `README.md` `d0e5bc42…576d5fb`.
|
||||
|
||||
## Corrected assumptions and limitations
|
||||
|
||||
- Assumed the user's Gitea answered SSH on 22 → actually Docker on **2222**; port 22 is
|
||||
the host sshd. Wrong host keys were briefly written to `~/.ssh/known_hosts` and then
|
||||
replaced (incident + repeat guard: `AGENTS.md` → "SSH to Gitea").
|
||||
- `credential.json`'s clientKey is NOT the same credential as vault `zai_api_key`.
|
||||
- macOS portability is designed-in but unproven (FEATURE-MATRIX `unknown`).
|
||||
- mcode facts are pinned to 0.6.12 bundle digests; any update invalidates D2 until re-read.
|
||||
|
||||
## Unresolved questions and blockers
|
||||
|
||||
- Does the segment render correctly in the live TUI? (needs user restart)
|
||||
- Do the other machines (2× Ubuntu, 1× macOS) have `secretvault` + `zai_api_key`?
|
||||
- Does `zai_api_key` survive rotation without endpoint changes?
|
||||
|
||||
## Exact next action
|
||||
|
||||
User restarts MiniMax Code and confirms rendering; then run the curl one-liner on the
|
||||
two Ubuntu boxes. Acceptance: segment visible with colors; matrix rerun green on each
|
||||
Linux box; FEATURE-MATRIX rows updated from `unknown`.
|
||||
|
||||
## Reproduction
|
||||
|
||||
```bash
|
||||
# installer (any machine)
|
||||
curl -fsSL https://git.itsaygea.com/admin/mcode-sl/raw/branch/main/install.sh | bash
|
||||
# segment preview / refresh
|
||||
printf '{}' | ~/.local/bin/mcode-zai-usage
|
||||
~/.local/bin/mcode-zai-usage --refresh
|
||||
# regression gate
|
||||
bash trials/config-merge-safety-2026-10-19/verify.sh
|
||||
```
|
||||
|
||||
Requires: bash, jq, curl, python3; secretvault + `zai_api_key` for the primary path.
|
||||
|
||||
## Local artifacts
|
||||
|
||||
- `~/.minimax/config.yaml` — live config (backups `~/.minimax/config.yaml.bak.*`).
|
||||
- `~/.cache/aygea-sl/quota.json` — quota cache (safe to delete; self-heals).
|
||||
- `~/.secretvault/credential.json` — legacy proxy credential (never committed).
|
||||
|
||||
## Git state
|
||||
|
||||
- Branch: `main`
|
||||
- Commit: see `git log --oneline -1` (docs-scaffold commit follows the `first commit`
|
||||
`9ad073d`; final handoff commit reported in the stage summary, not here)
|
||||
- Push: pushed to `git@git.itsaygea.com:admin/mcode-sl.git`
|
||||
- Working tree: expected clean after the docs-scaffold commit
|
||||
@@ -0,0 +1,39 @@
|
||||
# Handoff: <date> — <topic>
|
||||
|
||||
## Objective and stopping point
|
||||
|
||||
<What the stage set out to do; where exactly it stopped.>
|
||||
|
||||
## Verified results and evidence
|
||||
|
||||
<Claims with status (`confirmed`/`inferred`/`unknown`), each linked to its evidence:
|
||||
trial record, output file, digest, or command. No unevidenced claims.>
|
||||
|
||||
## Corrected assumptions and limitations
|
||||
|
||||
<What we believed at the start that turned out wrong; hard limits of the result.>
|
||||
|
||||
## Unresolved questions and blockers
|
||||
|
||||
<Open questions, with who/what is needed to resolve them.>
|
||||
|
||||
## Exact next action
|
||||
|
||||
<Single next step + acceptance criteria.>
|
||||
|
||||
## Reproduction
|
||||
|
||||
```bash
|
||||
<exact commands, host requirements>
|
||||
```
|
||||
|
||||
## Local artifacts
|
||||
|
||||
<Ignored/local files this work depends on and where to recover them.>
|
||||
|
||||
## Git state
|
||||
|
||||
- Branch: <branch>
|
||||
- Commit: <hash — never self-referential; report the final handoff commit after it exists>
|
||||
- Push: <pushed to <remote> / failed: <reason>>
|
||||
- Working tree: <clean / modified files listed>
|
||||
Reference in new issue
Block a user