@caddis/cli 0.2.5 → 0.3.0

package/bundles/antigravity-plugin/session_end_agy.py

@@ -22,6 +22,25 @@ def _artifact_root(root: str) -> str:
     return os.path.join(str(root), ".caddis")
 
 
+
+def _hook_note(feature, exc, root=None):
+    """Record a swallowed failure in the caddis hook ledger. Never raises, never prints.
+
+    agy hooks ship FLAT at the plugin root while hook_log.py ships under scripts/, and in
+    the source repo this file sits in claude-harness/agy/ with hook_log.py one level up in
+    claude-harness/scripts/. Try both layouts.
+    """
+    try:
+        _here = os.path.dirname(os.path.abspath(__file__))
+        for _cand in (os.path.join(_here, "scripts"),
+                      os.path.join(os.path.dirname(_here), "scripts")):
+            if os.path.isdir(_cand) and _cand not in sys.path:
+                sys.path.insert(0, _cand)
+        import hook_log as _hl  # noqa: E402
+        _hl.record(os.path.basename(__file__).replace(".py", ""), feature, exc, root)
+    except Exception:
+        pass
+
 def main() -> None:
     try:
         data = json.load(sys.stdin)
@@ -43,8 +62,8 @@ def main() -> None:
         }
         with open(os.path.join(art, "usage-log.jsonl"), "a", encoding="utf-8") as fh:
             fh.write(json.dumps(record) + "\n")
-    except Exception:
-        pass  # never fail the turn
+    except Exception as _exc:
+        _hook_note("agy usage-log write", _exc)  # never fail the turn
     # No stdout: agy interprets a Stop hook's stdout as a decision object.
 
 

package/bundles/antigravity-plugin/skills/_registry.md

@@ -85,6 +85,8 @@
 | Ship Merge | `ship-merge/` | Merge an already-green, already-reviewed PR behind an explicit deploy-confirm, monitor the deploy, validate prod, then clean up the branch — only on green. |
 | Ship Pr | `ship-pr/` | Open a reviewed PR for the current feature branch — rebase-safe push, PR create/update, monitor CI, STOP at green. Never merges, never deploys (that's /ship-merge). |
 | Spawn Hub | `spawn-hub/` | Hand the Advisory Hub role to a fresh session — run the mechanical audit, then generate the succession prompt with a context self-check the new Hub must pass |
+| Spawn Session | `spawn-session/` | Hand the WORK to a fresh session — generate the handover from the repo, then validate the successor by re-deriving its answers |
+| Statusline | `statusline/` | Install the caddis status line into Claude Code and agy — one renderer, once per machine |
 | Tdd | `tdd/` | Run a strict red-green-refactor TDD cycle for a unit of behavior |
 | Ui Brief | `ui-brief/` | Design-first UI brief — lock the aesthetic before writing any code |
 | Usage Review | `usage-review/` | Review local caddis usage over a window, surface prioritised recommendations, and apply config changes in one step |

package/bundles/antigravity-plugin/skills/advisory-hub/reference/succession.md

@@ -92,5 +92,27 @@ the funnel's `offered` count, and why is it NOT `SUM(OfferedInd)`?"* — the nai
 the correct one 4,783, because the raw flags do not nest. A Hub that only skimmed **fails visibly
 instead of silently**, which is the entire point.
 
+### Four rules that make the self-check mean something
+
+Shared with `/caddis:spawn-session`, which transfers the WORK where this transfers the ROLE. Both
+run on `scripts/caddis_spawn.py`, so a fix lands in both.
+
+1. **DERIVE the questions from what CHANGED. Do not choose them.** An agent picking its own exam
+   picks what it remembers, which is the thing under test. Spread them: oldest settled decisions
+   catch a successor that read only the recent sections; the newest changes catch one that read only
+   the summary.
+2. **A SUPERSEDED fact is the highest-signal question there is**, because the obvious answer is the
+   stale one. The measured discriminator was *"which model serves chat?"* — the answer had changed
+   **twice**, and naming only the most recent replacement proved the history had not been read.
+3. **Every question must be answerable from a committed file**, verified with
+   `caddis_spawn.py verify-question`, not assumed. A question whose answer is not written down tests
+   memory — the thing this mechanism replaces.
+4. **Store NO answer key. Re-derive at validation time.** A stored key freezes the outgoing agent's
+   belief: if it was wrong, the key is wrong and the check certifies the error. Re-deriving validates
+   the DOCUMENT as well as the reader — and validating only the reader is precisely what failed, when
+   a Hub passed a thirteen-question check on a handover containing four factual errors.
+
+**Six questions maximum.** Past six the successor writes an essay and the outgoing agent skims it.
+
 ---
 

package/bundles/antigravity-plugin/skills/fastapi-dev/SKILL.md

@@ -295,6 +295,6 @@ async def create_record(record: RecordCreate, service: ...):
 | Resource | Path |
 |----------|------|
 | FastAPI instructions | `instructions/fastapi.instructions.md` |
-| SQL expert skill | `skills/coding/sql/SKILL.md` |
+| SQL expert skill | the `sql` skill |
 | Python instructions | `instructions/python.instructions.md` |
 | Security instructions | `instructions/security.instructions.md` |

package/bundles/antigravity-plugin/skills/ship/SKILL.md

@@ -103,5 +103,5 @@ Release tag:     <tag> → <sha> | n/a
 
 ## Skill reference
 Full procedures for the Gitea lane (CI monitoring, prod validation, queue triage, failure remediation)
-are in `skills/devops/deploy-local/SKILL.md`. For the GitHub lane, the `gh-cli` skill covers `gh run`
+are in the `deploy-local` skill (ships in the optional `caddis-extras` plugin — enable it with `claude plugin enable caddis-extras`). For the GitHub lane, the `gh-cli` skill covers `gh run`
 usage. Load whichever matches the detected lane when a step needs more detail.

package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md

@@ -99,5 +99,5 @@ Cleanup:       remote branch ✗ deleted / local ✗ deleted / backup ref droppe
 - Local-only lane: no PR, no merge — refuse and point at `/ship`.
 
 ## Skill reference
-Gitea deploy monitoring, prod validation, failure triage: `skills/devops/deploy-local/SKILL.md`.
+Gitea deploy monitoring, prod validation, failure triage: the `deploy-local` skill (ships in the optional `caddis-extras` plugin — enable it with `claude plugin enable caddis-extras`).
 GitHub `gh pr merge` / `gh run` usage: the `gh-cli` skill.

package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md

@@ -98,5 +98,5 @@ human-confirmed door.
 - Local-only lane: refuse + point at `/ship`. On the default branch: stop + point at `/ship`.
 
 ## Skill reference
-Gitea API monitoring + failure triage: `skills/devops/deploy-local/SKILL.md`. GitHub `gh pr` / `gh run`
+Gitea API monitoring + failure triage: the `deploy-local` skill (ships in the optional `caddis-extras` plugin — enable it with `claude plugin enable caddis-extras`). GitHub `gh pr` / `gh run`
 usage: the `gh-cli` skill. Load whichever matches the detected lane.

package/bundles/antigravity-plugin/skills/spawn-hub/SKILL.md

@@ -151,8 +151,12 @@ audit trail this pattern has.
 generator:**
 
 ```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" preflight
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_inventory.py" --with-tests
 ```
+
+`preflight` **refuses on a dirty tree**: the incoming Hub pulls, so uncommitted work is invisible to
+it. Commit first, or name every uncommitted file in the handover.
 (falls back to `scripts/caddis_inventory.py` in a source checkout; skip the step if absent — it
 degrades open like every other machine step here.)
 
@@ -191,6 +195,28 @@ Then write the judgement half yourself. It must contain:
    > pass while understanding nothing. Rotate it, and prefer a fact the *most recent* milestone
    > established, since that is what the incoming Hub is least likely to have absorbed.
 
+   > **DERIVE the questions from what CHANGED — do not choose them.** An agent that picks its own
+   > exam picks what it remembers, which is the thing under test. Spread them: the oldest settled
+   > decisions catch a Hub that read only the recent sections; the most recent changes catch one
+   > that read only the summary; **a SUPERSEDED fact is the highest-signal question of all**,
+   > because the obvious answer is the stale one.
+
+   > **Every question must be answerable from a committed file. Prove it, do not assume it:**
+   >
+   > ```
+   > python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" verify-question \
+   >   --answer-in .caddis/kb/some-note.md --needle "the phrase that answers it"
+   > ```
+   >
+   > A question whose answer is not written down tests memory — the thing this mechanism exists to
+   > replace. It is not a harder question; it is the old failure wearing an exam's clothes.
+
+   > **Store NO answer key.** Re-derive each answer from the repo when the incoming Hub replies. A
+   > stored key freezes your belief at capture time: if you were wrong, the key is wrong and the
+   > check certifies the error. Re-deriving validates the DOCUMENT as well as the reader — which is
+   > exactly what `.caddis/parking-lot/done/004-*` found missing, where a Hub passed a
+   > thirteen-question check on a handover carrying four factual errors.
+
    Good traps share a shape: a figure that looks obvious, a correct value that differs, and a reason
    rooted in the data rather than in the code. On the reference project, one generation asked why the
    funnel's `offered` is not `SUM(OfferedInd)` (naive 3,814, correct 4,783 — the raw flags do not
@@ -250,8 +276,15 @@ exists to shed.
 ```
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" handover-check \
   --doc .caddis/advisory-hub-reports/hub-NN.spawn.md
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" check \
+  --doc .caddis/advisory-hub-reports/hub-NN.spawn.md
 ```
 
+The second one blocks on a **commit hash or test count given as current state**. Both go stale
+within the hour — measured twice — and the fix is never a fresher number, it is to write the command
+that produces it. A historical hash is only noted, not blocked: those are durable, and flagging them
+is how a check earns a reputation for crying wolf.
+
 It fails when the prompt names a file that does not exist. **Validate the DOCUMENT, not just the
 reader.** The context self-check in Step 4 proves the incoming Hub read carefully; it proves nothing
 about whether what it read was true. One incoming Hub passed a thirteen-question check on a handover

package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: spawn-session
+description: Hand the WORK to a fresh session — generate the handover from the repo, then validate the successor by re-deriving its answers
+---
+
+# /caddis:spawn-session — generate the handover, then validate the successor
+
+Use this when a session is long enough that its own recall has become the risk. It replaces
+`/caddis:handoff` for that case: `/handoff` writes down what you remember, and **what you remember
+is the failure mode.**
+
+**Sibling, not duplicate, of `/caddis:spawn-hub`.** `spawn-hub` hands over a validation ROLE;
+this hands over the WORK. Both run on `scripts/caddis_spawn.py`, so a fix to the machinery lands in
+both.
+
+## The failure this exists to catch
+
+A long session does not forget. **It recalls superseded facts fluently.** Measured in one session:
+
+- two throughput figures the agent had **itself withdrawn**, re-quoted days later
+- *"E8 is blocked on F1"* repeated for three days without a re-test
+- a commit hash written into a handover that went stale **within the hour**
+
+Each was stated with conviction and was wrong. Asking that agent what it knows cannot find any of
+it.
+
+The successor is what to pick up first: **$ARGUMENTS** (if empty, derive it from the parking-lot
+and the active plan).
+
+---
+
+## Round 0 — validate your OWN handover. No relay trip.
+
+**Do this before writing the prompt.** It is the cheapest round and the one this whole command is
+about: in the manual run, a child caught a stale hash the parent could have caught alone — a wasted
+relay trip, and the relay trip is the expensive part.
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" preflight
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" fingerprint --with-tests
+```
+(falls back to `scripts/caddis_spawn.py` in a source checkout.)
+
+`preflight` **refuses on a dirty tree** — the successor pulls, so uncommitted work is invisible to
+it and it will either redo that work or build on a state that does not exist. Commit first.
+
+### Capture from the repo, never from recall
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_inventory.py" --with-tests
+```
+
+Then add the four things the inventory cannot derive:
+
+| Capture | Why |
+|---|---|
+| **Open parking-lot count** | The integrity check. A successor that revives 13 of 15 has silently dropped two, and nothing else would show it. |
+| **WITHDRAWN and SUPERSEDED facts, as an explicit list** | Highest-value content, easiest to lose. Two withdrawn figures were re-quoted by their own author. |
+| **Anything learned this session that lives in no file** | A screenshot of the consuming UI changed a task's priority. It existed only in the chat. |
+| **State verified, not asserted** — run the tests, the gate, `git status` | One handover said "1,066 tests"; it was 1,090 an hour later. |
+
+**Nothing may be written from recall.** Every number comes from a command run during this capture,
+or from a file quoted by path.
+
+### Then check what you wrote
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" check --doc .caddis/spawn-session/<id>-prompt.md
+```
+
+It **blocks** on a commit hash or test count given as current state, and on any path that does not
+exist. It only **notes** a historical hash — those are durable, and flagging them was how the first
+version produced seven findings on one document and taught the reader to skim.
+
+**A claim that cannot be re-derived does not go in the handover.**
+
+---
+
+## Round 1 — the questions. One relay trip.
+
+**Up to six. Derived from what changed, never chosen.** An agent that picks its own exam picks what
+it remembers, which is the thing under test.
+
+| Slot | Source | Catches |
+|---|---|---|
+| 1–2 | the **oldest** settled decisions | a successor that read only the recent sections |
+| 3–4 | what changed **most recently** | one that read only the summary |
+| 5 | a fact that was **SUPERSEDED** | the highest-signal question — the obvious answer is the stale one |
+| 6 | a live **hazard or cost** | forces a consequence, not a fact |
+
+**At least one question's obvious answer must be WRONG.** In the manual run the discriminator was
+*"which model serves chat?"* — the answer had changed **twice**, and a successor naming only the
+most recent replacement had not read the history.
+
+**Every question must be answerable from a committed file. Prove it:**
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" verify-question \
+  --answer-in .caddis/kb/some-note.md --needle "the phrase that answers it"
+```
+
+A question whose answer is not written down tests memory — the thing being replaced. It is not a
+harder question; it is the old failure wearing an exam's clothes.
+
+### Store NO answer key
+
+Do not write `<id>-key.md`. Two reasons, and the second is the one that matters:
+
+1. The child can read it. Any exclusion rule is one path-glob away from failing.
+2. **A stored key freezes your belief at capture time.** If you were wrong, the key is wrong, and
+   the check certifies the error.
+
+**Re-derive each answer from the repo at validation time instead.** That validates the DOCUMENT and
+the READER at once — which is exactly what `.caddis/parking-lot/done/004-*` said was missing, where
+a successor passed a thirteen-question check on a handover containing four factual errors.
+
+### What the child sends back
+
+Three lines, carried by the user:
+
+```
+SPAWN <id> | head <sha> | <n> tests | answers in .caddis/spawn-session/<id>-answers.md
+Q1-Q6 answered with citations. <n> commands run. <n> facts I could not find in a file.
+<one line: the single most important thing I believe about the current state>
+```
+
+The fingerprint lets you detect a stale or mismatched paste **before grading anything**.
+
+**The third line is the real test.** A successor that understood the work states the current state
+in one sentence. One that merely parsed the files produces a generic line, and that is visible
+immediately.
+
+---
+
+## The verdict — three, not two
+
+| Verdict | Condition | You write |
+|---|---|---|
+| **PASS** | every answer correct, citations check out | a short go-ahead naming the first task |
+| **ACCEPT WITH CORRECTIONS** | broadly right; one or two facts stale or a citation wrong | the corrections, each with the file that proves it |
+| **REJECT** | a settled decision misremembered, a withdrawn figure quoted, or a hazard misunderstood | an instruction to re-read named sections and re-answer. **Do not let it start work** |
+
+**REJECT exists because a confidently wrong successor is more dangerous than a confused one.** In
+this project the failure has never been *"I don't know"* — it has been a fluent wrong answer.
+
+The vocabulary matches `/caddis:validate-phase` on purpose: same discipline, different object.
+
+**Two REJECTs on one spawn means the HANDOVER is at fault, not the successor. Regenerate it** rather
+than coaching the child through it.
+
+### When the fault is yours, fix the class
+
+If validation finds an error that came from your handover, **fix the source document in the same
+turn** — and fix the class, not the instance. In the manual run a successor found a stale commit
+hash; the fix was not a fresher hash, it was to **remove hashes from both documents** and write the
+command instead. A handover patched per-instance goes stale again on the next commit.
+
+---
+
+## Round 2 — the first task, scoped small, reviewed. One relay trip.
+
+**Not more questions.** Two rounds of questions would be overkill; two rounds of the right things
+are not.
+
+**The questions validate RECALL. The first task validates JUDGEMENT** — and a successor can answer
+six questions perfectly and still build the wrong thing. In the manual run round 2 caught a wrong
+instruction from the parent, a wrong fact left by a predecessor, and a better design than the parent
+had specified.
+
+Round 1's verdict sets round 2's size:
+
+| Round 1 | Round 2 task |
+|---|---|
+| PASS | a normal next item; review the outcome |
+| ACCEPT WITH CORRECTIONS | a **small, reversible** item that writes nothing permanent; review closely |
+| REJECT | no task — re-read and re-answer |
+
+Review the result **by re-deriving it**, exactly as you reviewed the answers — not by reading the
+successor's account of it.
+
+### Then stop gating
+
+**After round 2 passes, stop.** A successor that answered six questions with citations and then did
+one real task correctly has demonstrated as much as a gate can. Continuing to review every item
+turns you into a bottleneck and the successor into a relay — which is the cost this command exists
+to remove.
+
+---
+
+## Files — all three committed
+
+```
+.caddis/spawn-session/
+    <id>-prompt.md     generated by you. The user pastes its "For the successor" section
+    <id>-answers.md    written by the CHILD
+    <id>-verdict.md    written by you, after re-deriving
+```
+
+`<id>` is short, unique and sortable — `2026-08-16-a`. Two spawns on one day must not collide.
+
+They are committed for the same reason the register is a file: **a validation that happened only in
+chat cannot be reviewed**, and cannot be re-read when the next handover asks what good looked like.
+
+## Refuse to
+
+| Refusal | Why |
+|---|---|
+| Run with a dirty tree | uncommitted work is invisible to the successor |
+| Write a commit hash or test count as current state | both went stale within the hour, twice |
+| Write a question whose answer is not in a committed file | it would test memory |
+| Store an answer key | it freezes your belief, and the child can read it |
+| Grade your own answers | you validate; the child answers |
+| Proceed when the open-item count is unknown | that count is the integrity check |

package/bundles/antigravity-plugin/skills/statusline/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: statusline
+description: Install the caddis status line into Claude Code and agy — one renderer, once per machine
+---
+
+# /statusline — set up the status bar
+
+Wire the caddis status line into every coding agent on this machine. One Python renderer serves
+both hosts. It installs at **user scope**, so every project gets the line and no project holds a
+copy that can drift.
+
+## What the user gets
+
+Claude Code:
+
+```
+⌂ claudster-source | saajunaid/caddis ⎇ main +2 ●1 ?3 ↑1 | ◆ Opus 5 (1M context) v2.1.239 |
+◉ 412k/1M [███░░░░░]  41%  | ⚡ 386k cached | effort:high | style:Plain | thinking |
+5h:12% 7d:40% | 💻 57% (37 GB) | ⏺ relay | ◷ 07:58
+```
+
+agy (Antigravity):
+
+```
+▛▜ agy | ● idle | 🧠 Gemini 3.6 Flash (High) (high) | 📁 claudster-source | ⎇ main ?3 |
+◉ 48.5k/1M [░░░░░░░░]  5%  | ⚡ 40k cached | q 62% | 💻 57% (37 GB) | ⏺ relay | ◷ 08:01
+```
+
+Both lines come from `caddis_statusline.py`. It has two profiles, because the two hosts send
+different field names — agy's payload is a sibling of Claude Code's, not a copy.
+
+## Run it
+
+Find the renderer in this install and run it. Try these paths in order and use the first that exists:
+
+- `${CLAUDE_PLUGIN_ROOT}/scripts/caddis_statusline.py`
+- `claude-harness/scripts/caddis_statusline.py` (working inside the caddis source repo)
+
+Then:
+
+```bash
+python <path>/caddis_statusline.py --install          # both hosts
+python <path>/caddis_statusline.py --install --host claude
+python <path>/caddis_statusline.py --install --host agy
+python <path>/caddis_statusline.py --install --dry-run # print, write nothing
+```
+
+`--install` does four things:
+
+1. Copies the renderer to `~/.caddis/statusline.py` — a **stable** path. Pointing the host
+   settings at the plugin cache would break on every caddis upgrade, because the version number
+   is in that path.
+2. Creates `~/.caddis/statusline.json` with the default toggles. It never overwrites an existing one.
+3. Backs up each host's `settings.json` to `settings.json.bak-caddis-statusline`.
+4. Sets `statusLine` in `~/.claude/settings.json` and `~/.gemini/antigravity-cli/settings.json`,
+   preserving every other key. A host that is not installed is skipped, not failed.
+
+Report the tool's own output to the user. Then tell them the line appears on the **next** session —
+neither host re-reads `settings.json` mid-session.
+
+## Verify
+
+```bash
+python ~/.caddis/statusline.py --check                        # what is wired where
+python ~/.caddis/statusline.py --sample --profile claude      # preview, no host needed
+python ~/.caddis/statusline.py --sample --profile agy
+```
+
+`--check` exits non-zero when a host's `statusLine` is missing or points somewhere else.
+
+## Change the look
+
+Edit `~/.caddis/statusline.json`. Every key is optional; a missing file means defaults.
+
+| key | default | what it controls |
+|---|---|---|
+| `color` | `true` | ANSI colour |
+| `icons` | `true` | Unicode segment icons. These are plain Unicode, **not** Nerd Font glyphs |
+| `progress_bar` | `true` | the `[███░░░░░]` context bar |
+| `bar_width` | `8` | bar cells |
+| `token_counts` | `true` | `◉ 412k/1M` |
+| `cached_tokens` | `true` | `⚡ 386k cached` — bold and bright by design, never width-gated |
+| `ram` | `true` | `💻 57% (37 GB)` |
+| `ram_min_width` | `0` | hide RAM below this terminal width; `0` always shows it |
+| `clock` | `true` | `◷ 07:58` |
+| `relay` | `true` | `⏺ relay` when a parked resume pointer exists |
+| `rate_limits` | `true` | `5h:12% 7d:40%` (Claude Code only) |
+| `session_id` | `false` | `#a1b2c3d4` |
+| `git` | `true` | branch, staged/unstaged/untracked counts, ahead/behind |
+| `separator` | `"\|"` | segment separator |
+
+Config changes take effect on the next render. No reinstall needed.
+
+## Notes for you, not the user
+
+- Do **not** hand-edit either `settings.json` to wire this. `--install` reads, merges and writes
+  back, so it cannot drop an unrelated key. Hand edits have dropped `trustedWorkspaces` before.
+- The renderer never crashes the host. A bad payload, a missing field, or an unreadable config
+  degrades to fewer segments; a hard failure degrades to the directory name.
+- RAM on Windows uses `ctypes` `GlobalMemoryStatusEx`, an in-process call. Do not replace it with
+  `Get-CimInstance Win32_OperatingSystem` — that cost about 300 ms on **every** render in the
+  PowerShell line this replaced.
+- If the user asks why their old `~/.claude/statusline-custom.sh` or
+  `~/.gemini/statusline/statusline.ps1` no longer runs: nothing points at them any more. They are
+  superseded, not deleted. Both are safe to remove once the user is happy with the new line.

package/bundles/antigravity-plugin/skills/use-model/SKILL.md

@@ -55,9 +55,21 @@ A wholly new provider: add a row to `PROVIDERS` in `oss_model.py` (base_url, mod
 pass an unknown provider name with `OSS_BASE_URL`+`OSS_MODEL` set — no table edit required.
 
 ## First-time install
-Put `claude-harness/scripts/` (or your plugin's `scripts/` dir) on `PATH`, or add a shell profile
-function. `/setup-project-ai` documents the one-liner for your platform (PowerShell profile function /
-bash alias) — it does not silently edit your shell profile.
+
+```
+npm i -g @caddis/cli     # puts claude-oss / claude-glm / claude-deepseek on PATH
+caddis keys              # prompts for each provider key, validates it, writes ~/.caddis/keys.env
+claude-glm --print-config    # zero-token check: endpoint, model, key all resolved
+```
+
+npm does the PATH work on Windows, macOS and Linux. No profile edit, no script copying, no
+Python needed on the lane path — the resolver is ported into the CLI, because the npm tarball
+ships only `dist` and `bundles`.
+
+`npx` runs the default `caddis` binary only; the lane binaries need the global install above.
+
+**Plugin-only installs** (no npm CLI) keep the original route: put the plugin's `scripts/`
+directory on `PATH`, or add a shell profile function. caddis never silently edits your profile.
 
 ## Exit codes
 `claude-oss`/`claude-glm` propagate the wrapped `claude` process's exit code, except a resolver failure

package/bundles/antigravity-plugin/warm_start_agy.py

@@ -131,14 +131,33 @@ def truncate_relay(text: str) -> str:
     return text
 
 
+
+def _hook_note(feature, exc, root=None):
+    """Record a swallowed failure in the caddis hook ledger. Never raises, never prints.
+
+    agy hooks ship FLAT at the plugin root while hook_log.py ships under scripts/, and in
+    the source repo this file sits in claude-harness/agy/ with hook_log.py one level up in
+    claude-harness/scripts/. Try both layouts.
+    """
+    try:
+        _here = os.path.dirname(os.path.abspath(__file__))
+        for _cand in (os.path.join(_here, "scripts"),
+                      os.path.join(os.path.dirname(_here), "scripts")):
+            if os.path.isdir(_cand) and _cand not in sys.path:
+                sys.path.insert(0, _cand)
+        import hook_log as _hl  # noqa: E402
+        _hl.record(os.path.basename(__file__).replace(".py", ""), feature, exc, root)
+    except Exception:
+        pass
+
 def main() -> None:
     try:
         _reconfig = getattr(sys.stdout, "reconfigure", None)
         if _reconfig:
             try:
                 _reconfig(encoding="utf-8")
-            except Exception:
-                pass
+            except Exception as _exc:
+                _hook_note("agy stdout utf-8 reconfigure", _exc)
         try:
             data = json.load(sys.stdin)
         except Exception:

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.24",
+  "version": "1.3.25",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/architecture-design/SKILL.md

@@ -241,4 +241,4 @@ def fetch_records(status: str = None, page: int = 1):
 | Architect agent | `agents/architect.agent.md` |
 | FastAPI dev skill | `skills/coding/fastapi-dev/SKILL.md` |
 | Streamlit dev skill | `skills/frontend/streamlit-dev/SKILL.md` |
-| SQL expert skill | `skills/coding/sql/SKILL.md` |
+| SQL expert skill | the `sql` skill |

package/bundles/antigravity-plugin-extras/skills/caching-patterns/SKILL.md

@@ -382,4 +382,4 @@ This pattern is complementary to chunk retry (Step 6 + Gotcha 6) — the 3-layer
 |----------|------|
 | Streamlit dev skill | `skills/frontend/streamlit-dev/SKILL.md` |
 | Streamlit instructions | `instructions/streamlit.instructions.md` |
-| SQL expert skill | `skills/coding/sql/SKILL.md` |
+| SQL expert skill | the `sql` skill |

package/bundles/antigravity-plugin-extras/skills/webapp-development/SKILL.md

@@ -283,6 +283,6 @@ st.plotly_chart(create_trend_chart(filter_type), use_container_width=True)
 |----------|------|
 | Streamlit dev skill | `skills/frontend/streamlit-dev/SKILL.md` |
 | FastAPI dev skill | `skills/coding/fastapi-dev/SKILL.md` |
-| SQL expert skill | `skills/coding/sql/SKILL.md` |
+| SQL expert skill | the `sql` skill |
 | Caching patterns | `skills/coding/caching-patterns/SKILL.md` |
 | UX design skill | `skills/frontend/ux-design/SKILL.md` |

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.74",
+  "poolVersion": "1.3.77",
   "bundles": {
-    "antigravity-plugin": "1.3.74",
-    "antigravity-plugin-extras": "1.3.24"
+    "antigravity-plugin": "1.3.77",
+    "antigravity-plugin-extras": "1.3.25"
   }
 }