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
2026-10-19 23:25:21 -07:00
1 parent 9ad073d4fc
commit fd8e8cbbd7
@@ -0,0 +1,11 @@
+# trials
+
+Bounded experiments. One directory per trial: `trials/<topic>-<YYYY-MM-DD>/` containing
+`record.md` and, where possible, a re-runnable `verify.sh` plus its captured `output.txt`.
+
+Required sections: question/hypothesis, scope + acceptance criteria, inputs (paths,
+hashes, tool versions), procedure (exact commands), expected vs observed, evidence
+paths, verdict (`confirmed` / `rejected` / `inconclusive` / `blocked`), and a repeat
+guard (what would justify another attempt). Preserve failed runs.
+
+Index lives in `TRIALS.md`. Routine edits and ordinary test runs do not need a trial.
@@ -0,0 +1,15 @@
+PASS S1 fresh-install rc
+PASS S1 created-tui message
+PASS S1 new config mode 0600
+PASS S1 no tmp leftovers
+PASS S2 idempotent rerun
+PASS S3 update rc
+PASS S3 backup equals pre-merge original
+PASS S3 provider intact + keys updated
+PASS S4 duplicate-tui refused
+PASS S4 file untouched on refusal
+PASS S4 refusal reason reported
+PASS S5 embedded copy identical
+PASS S6 uninstall rc
+PASS S6 keys removed, items kept
+== 14 passed, 0 failed ==
@@ -0,0 +1,19 @@
+# Trial: install.sh config-merge safety matrix
+
+- **Date:** 2026-10-19
+- **Question / hypothesis:** the `~/.minimax/config.yaml` surgery is atomic, idempotent,
+  backs up before change, refuses ambiguous input, keeps everything outside the `tui:`
+  block byte-identical, and works identically from a checkout or a piped install.
+- **Scope / acceptance:** the 14 checks in `verify.sh` (S1–S6) all pass.
+- **Inputs:** `install.sh` `a6c433da2cde4d92387c4de5845f6770ed71df55548499654e579869d84989a1`,
+  `zai-usage.sh` `ca2141a50b528072d7ca2a4842cd9d6c535fc036e2ff34f816fafc713fa63c61`.
+- **Environment:** bash, GNU coreutils, python3 (PyYAML present → YAML validation active),
+  mktemp sandboxes with overridden `$HOME` (no live config touched).
+- **Procedure:** `bash trials/config-merge-safety-2026-10-19/verify.sh`
+- **Expected vs observed:** expected 14/14; observed 14/14 (`output.txt`).
+  First recorded run also caught two runner-script typos (`T1b`/`T2u` under `set -u`),
+  fixed before the clean run — both were test-harness bugs, not installer bugs.
+- **Verdict:** confirmed (Linux, this host).
+- **Repeat guard / limits:** rerun after any change to `install.sh` (required by
+  `AGENTS.md`), after mcode updates that change config.yaml's generated shape, and once
+  on macOS — pass/fail there is currently `unknown` (BSD stat/date/`install` differences).
@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Trial: config-merge safety matrix for install.sh
+#
+# Re-runnable acceptance check for the ~/.minimax/config.yaml surgery:
+# fresh create, idempotency, backup-before-change, byte preservation,
+# duplicate-structure refusal, piped/embedded install, uninstall.
+#
+# Usage: bash verify.sh            (from anywhere; uses mktemp sandboxes)
+# Exit 0 when every check passes.
+set -u
+export LC_ALL=C
+REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+pass=0; fail=0
+ok(){ if [ "$2" = "0" ]; then pass=$((pass+1)); printf 'PASS %s\n' "$1"; else fail=$((fail+1)); printf 'FAIL %s\n' "$1"; fi; }
+
+# S1 fresh install: creates tui block, 0600
+T1=$(mktemp -d); HOME=$T1 bash "$REPO/install.sh" >"$T1.log" 2>&1; ok "S1 fresh-install rc" $?
+grep -q created-tui "$T1.log"; ok "S1 created-tui message" $?
+[ "$(stat -c '%a' "$T1/.minimax/config.yaml" 2>/dev/null)" = 600 ]; ok "S1 new config mode 0600" $?
+ls "$T1"/.minimax/config.yaml.tmp.* >/dev/null 2>&1; [ $? -ne 0 ]; ok "S1 no tmp leftovers" $?
+
+# S2 idempotent rerun
+HOME=$T1 bash "$REPO/install.sh" >"$T1.b.log" 2>&1
+grep -q already-configured "$T1.b.log"; ok "S2 idempotent rerun" $?
+
+# S3 existing config: update in place, backup == pre-merge original
+T2=$(mktemp -d); mkdir -p "$T2/.minimax"
+printf 'logLevel: info\nprovider:\n  x:\n    apiKey: keepme\ntui:\n  statusLine:\n    - current-dir\n  customStatusLine:\n    command: /old/path\n    intervalSeconds: 30\n' > "$T2/.minimax/config.yaml"
+cp "$T2/.minimax/config.yaml" "$T2/orig.yaml"
+HOME=$T2 bash "$REPO/install.sh" >"$T2.log" 2>&1; ok "S3 update rc" $?
+cmp -s "$(ls -t "$T2"/.minimax/config.yaml.bak.* | head -1)" "$T2/orig.yaml"; ok "S3 backup equals pre-merge original" $?
+grep -q "apiKey: keepme" "$T2/.minimax/config.yaml" && grep -q "colorMode: ansi" "$T2/.minimax/config.yaml"; ok "S3 provider intact + keys updated" $?
+
+# S4 duplicate top-level tui blocks: refuse, file untouched
+T3=$(mktemp -d); mkdir -p "$T3/.minimax"
+printf 'a: 1\ntui:\n  statusLine:\n    - current-dir\nb: 2\ntui:\n  statusLine:\n    - model\nc: 3\n' > "$T3/.minimax/config.yaml"
+cp "$T3/.minimax/config.yaml" "$T3/orig.yaml"
+HOME=$T3 bash "$REPO/install.sh" >"$T3.log" 2>&1; [ $? -ne 0 ]; ok "S4 duplicate-tui refused" $?
+cmp -s "$T3/.minimax/config.yaml" "$T3/orig.yaml"; ok "S4 file untouched on refusal" $?
+grep -q merge-refused "$T3.log"; ok "S4 refusal reason reported" $?
+
+# S5 piped/embedded install (only install.sh present) -> embedded == zai-usage.sh
+T4=$(mktemp -d); cp "$REPO/install.sh" "$T4/"
+HOME=$T4 bash "$T4/install.sh" >"$T4.log" 2>&1
+cmp -s "$T4/.local/bin/mcode-zai-usage" "$REPO/zai-usage.sh"; ok "S5 embedded copy identical" $?
+
+# S6 uninstall: removes keys, keeps other items
+HOME=$T2 bash "$REPO/install.sh" --uninstall >"$T2.u.log" 2>&1; ok "S6 uninstall rc" $?
+! grep -q customStatusLine "$T2/.minimax/config.yaml" && ! grep -q custom-command "$T2/.minimax/config.yaml" && grep -q "current-dir" "$T2/.minimax/config.yaml"; ok "S6 keys removed, items kept" $?
+
+printf '== %s passed, %s failed ==\n' "$pass" "$fail"
+rm -rf "$T1" "$T2" "$T3" "$T4"
+[ "$fail" -eq 0 ]
@@ -0,0 +1,24 @@
+# Trial: mcode endpoint / key pairing
+
+- **Date:** 2026-10-19
+- **Question / hypothesis:** the SecretVault secret `zai_api_key` (plain 48–49 char
+  string) is the direct z.ai API key, not the `vault.itsaygea.com` proxy clientKey;
+  therefore the statusline should default to `https://api.z.ai`.
+- **Scope / acceptance:** three HTTP probes return codes consistent with exactly one
+  pairing per key; no key material printed.
+- **Inputs / environment:** host `mewtwo` (Ubuntu, PVE), curl with `--max-time 8`,
+  key fetched via `secretvault run --secret zai_api_key -- bash -c 'printf %s "$zai_api_key"'`;
+  legacy key from `~/.secretvault/credential.json` (`.clientKey`, 51 chars).
+- **Procedure:**
+  ```bash
+  # codes only; -o /dev/null -w '%{http_code}'
+  vault-key  @ https://vault.itsaygea.com/proxy/zai/api/monitor/usage/quota/limit
+  vault-key  @ https://api.z.ai/api/monitor/usage/quota/limit
+  cred-key   @ https://vault.itsaygea.com/proxy/zai/api/monitor/usage/quota/limit
+  ```
+- **Expected vs observed:** expected one 200; observed
+  `401 (vault@proxy) / 200 (vault@zai) / 200 (cred@proxy)`.
+- **Verdict:** confirmed — vault key is the direct z.ai credential; proxy clientKey is
+  separate. `zai-usage.sh` implements vault→`api.z.ai` first, credential.json→proxy fallback.
+- **Repeat guard:** revisit if the vault secret is rotated to a proxy clientKey, or if
+  `api.z.ai` starts rejecting it (401 after rotation).