boost-skill-cli 1.0.296__tar.gz → 1.0.298__tar.gz

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -89,7 +89,10 @@ toolchain
 toolkits
 traceback
 tracebacks
+typosquat
+typosquatted
 unkilled
+unlinking
 unregister
 unstaged
 untap

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/CLAUDE.md

@@ -101,8 +101,15 @@ line coverage. Target `boost_cli/core` behavior with assertions, not just import
   (structural pattern matching, `X | Y` runtime unions in non-annotation context).
 - **Three item kinds, one scanner.** `core/catalog.scan_dir` indexes `skill`
   (SKILL.md), `rule` (.mdc/.cursorrules/.windsurfrules/.clinerules), and
-  `workflow` (commands/agents/workflows Markdown). **Only `skill` installs** —
-  `store.install` refuses non-skill kinds; rules/workflows are search/tap-only.
+  `workflow` (commands/agents/workflows Markdown). **All three install**, and
+  each honors `scope`: `store.install` dispatches to `_install_rule` /
+  `_install_workflow` and only raises for a kind outside those three. They land
+  in different places, which is the part to get right — a skill is copied into
+  the canonical store and symlinked out, a rule is materialised into each
+  agent's context file (`rules.CONTEXT_FILES`, e.g. `~/.claude/CLAUDE.md`), and
+  a workflow is rendered per agent (TOML for Gemini, see
+  `workflows.TOML_COMMAND_AGENTS`). Installing a rule therefore edits a file the
+  user reads every session — treat it as more invasive than a skill, not less.
 
 ## Parallel work & concurrent loops
 

{boost_skill_cli-1.0.296/boost_skill_cli.egg-info → boost_skill_cli-1.0.298}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.296
+Version: 1.0.298
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -911,7 +911,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/README.md

@@ -195,7 +195,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.296'
-__version_tuple__ = version_tuple = (1, 0, 296)
+__version__ = version = '1.0.298'
+__version_tuple__ = version_tuple = (1, 0, 298)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.296
+Version: 1.0.298
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -911,7 +911,9 @@ boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 [`docs/index.html`](docs/index.html), and for every flag of every command see
 [`docs/commands.html`](docs/commands.html). For a GIF of one flagship command
 per group — recorded live with [VHS](https://github.com/charmbracelet/vhs) — see
-[`docs/carousel.html`](docs/carousel.html).
+[`docs/carousel.html`](docs/carousel.html). For how boost is put together
+internally — C4 diagrams of the context, containers, engine components and the
+install path — see [`docs/architecture/`](docs/architecture/README.md).
 
 | Group | Commands |
 |---|---|

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/boost_skill_cli.egg-info/SOURCES.txt

@@ -114,6 +114,11 @@ docs/mcp-hub.html
 docs/rag-architecture.md
 docs/roadmap.html
 docs/.claude/settings.local.json
+docs/architecture/README.md
+docs/architecture/c4-components-core.md
+docs/architecture/c4-containers.md
+docs/architecture/c4-context.md
+docs/architecture/c4-dynamic-install.md
 docs/carousel/gifs/distill.gif
 docs/carousel/gifs/doctor.gif
 docs/carousel/gifs/explain.gif
@@ -217,6 +222,7 @@ docs/roadmap/items/install-resolves-skill-dependencies.md
 docs/roadmap/items/install-scope-user-or-project.md
 docs/roadmap/items/installed-skill-trust-audit.md
 docs/roadmap/items/integrity-verification-boost-verify.md
+docs/roadmap/items/internal-architecture-diagrams.md
 docs/roadmap/items/invocation-pid-logging-for-crash-correlation.md
 docs/roadmap/items/journal-rotation-race-and-handle-leak.md
 docs/roadmap/items/layering-guard-import-linter.md
@@ -297,6 +303,7 @@ docs/roadmap/items/sbom-declares-the-wrong-version.md
 docs/roadmap/items/sbom-on-every-release-cyclonedx-syft.md
 docs/roadmap/items/sbom-release-event-never-fires.md
 docs/roadmap/items/scan-and-sync-rules-and-workflows.md
+docs/roadmap/items/scheduled-toolchain-lock-regeneration.md
 docs/roadmap/items/scorecard-findings-triage.md
 docs/roadmap/items/second-type-checker-pyright.md
 docs/roadmap/items/secret-and-pii-scanning-of-installed-skills.md
@@ -352,6 +359,7 @@ requirements/lint-tools.in
 requirements/lint-tools.txt
 requirements/mutation-tools.in
 requirements/mutation-tools.txt
+requirements/platform-pins.lock
 requirements/release-tools.in
 requirements/release-tools.txt
 requirements/test-tools.in
@@ -506,6 +514,7 @@ tests/unit/test_perf_gate.py
 tests/unit/test_pkg_confusions.py
 tests/unit/test_pkg_injection.py
 tests/unit/test_pkg_secrets.py
+tests/unit/test_platform_pins.py
 tests/unit/test_policy.py
 tests/unit/test_post_deploy_smoke.py
 tests/unit/test_projectlock.py

boost_skill_cli-1.0.298/docs/architecture/README.md

@@ -0,0 +1,45 @@
+# boost architecture
+
+C4-model diagrams of how boost is put together, in Mermaid so they render on GitHub and stay
+reviewable in a diff. Read them in order — each one opens a box the previous one drew.
+
+| Level | Diagram | Answers |
+|-------|---------|---------|
+| 1 | [System context](c4-context.md) | Who uses boost and what it talks to |
+| 2 | [Containers](c4-containers.md) | The processes and the directories on disk |
+| 3 | [Core components](c4-components-core.md) | How the 45 engine modules group, and the layering rule |
+| — | [Dynamic: install](c4-dynamic-install.md) | What `boost install` actually does, step by step |
+
+Subsystem designs live beside these rather than inside them:
+[rag-architecture.md](../rag-architecture.md) covers retrieval in depth, and
+[DEBUGGING.md](../DEBUGGING.md) covers the diagnostic surfaces.
+
+## The three invariants worth knowing before you read code
+
+**1. Layering is enforced.** `cli → commands → core`, checked by `import-linter` in `make lint` and
+CI. `core/` is the engine and the only layer the mutation gate targets; `commands/` is thin glue.
+Putting behaviour in the command layer means it is covered by neither.
+
+**2. Paths resolve at call time.** `core/paths.py` reads `$HOME` (or `$BOOST_HOME`) on every call
+rather than caching at import. That is not incidental — it is what lets the whole test suite point
+a temporary directory at `HOME` and exercise real install paths without touching your machine.
+
+**3. Optional is always optional.** Dense retrieval falls back to BM25; the AI bridge falls back to
+heuristics. The shipped runtime is stdlib-only and `[project].dependencies` is empty. Any new
+dependency belongs behind an extra, and any new path through it needs a degraded branch.
+
+## Keeping these honest
+
+These diagrams are hand-written, not generated, so they can drift. They describe *structure* —
+layers, boundaries, which component owns which decision — rather than anything that changes with a
+routine edit, so drift should be rare and visible. The claims most worth re-checking when the
+engine changes:
+
+- the component groupings in [c4-components-core.md](c4-components-core.md), against
+  `ls boost_cli/core/`
+- the layering contract, against `[tool.importlinter]` in `pyproject.toml`
+- the install sequence, against `core/store.py::install`
+- the agent-target split, against `agents.linking_agents()` and `agents.native_store_agents()`
+
+Command-level reference is generated and lives elsewhere: `docs/commands.html` is built from the
+`COMMANDS` registry by `scripts/build_command_reference.py`. Do not hand-edit it.

boost_skill_cli-1.0.298/docs/architecture/c4-components-core.md

@@ -0,0 +1,92 @@
+# C4 Level 3 — Components of the core engine
+
+`boost_cli/core/` is the engine: 45 modules that hold all the behaviour. This diagram groups them
+into the ten components that actually have distinct responsibilities, and shows the one-way
+dependency rule the build enforces.
+
+```mermaid
+C4Component
+  title Component Diagram — boost_cli/core
+
+  Container(cli, "boost_cli/cli.py", "Python", "COMMANDS registry; lazy dispatch")
+  Container(cmds, "boost_cli/commands/", "Python", "Thin CLI glue — parse, format, delegate")
+
+  Container_Boundary(core, "boost_cli/core — the engine") {
+    Component(registry, "Registry & catalog", "registry, catalog, frontmatter, staleness", "Clones taps; classifies skill / rule / workflow")
+    Component(bm25, "BM25 retrieval", "rag", "Always-on, zero-dependency full-content index")
+    Component(dense, "Dense retrieval", "dense, embed", "Optional vectors behind the [rag] extra")
+    Component(ai, "AI bridge", "ai, faithfulness, stackprobe, imperative", "LLM-assisted paths; heuristics when absent")
+    Component(resolve, "Resolution", "resolve, scopes, updatediff", "Dependency closure; user vs project scope")
+    Component(store, "Store & lock", "store, lockfile, projectlock, integrity, installscan", "Install, uninstall, sync; owns the lock file")
+    Component(targets, "Agent targets", "agents, rules, workflows, adapters, claude_settings, mcphost", "Per-agent formats, linking and MCP grammar")
+    Component(trust, "Trust & safety", "provenance, minisign, ed25519, secretscan, injectscan, typosquat, capabilities, policy, trustaudit", "Signing, scanning and governance")
+    Component(found, "Foundation", "paths, config, util, output", "Path resolution at call time; rendering")
+    Component(obs, "Diagnostics & I/O", "logs, journal, gitutil, nethttp", "Rotating log, pulse feed, git and HTTP")
+  }
+
+  Rel(cli, cmds, "Lazy-imports one module per invocation")
+  Rel(cmds, registry, "Taps and indexes")
+  Rel(cmds, bm25, "Searches")
+  Rel(cmds, store, "Installs and syncs")
+  Rel(cmds, trust, "Audits")
+  Rel(bm25, registry, "Indexes the catalog of")
+  Rel(dense, bm25, "Falls back to")
+  Rel(ai, bm25, "Reranks results from")
+  Rel(resolve, registry, "Looks up dependencies in")
+  Rel(store, resolve, "Expands the request with")
+  Rel(store, targets, "Links and materialises through")
+  Rel(store, trust, "Gates the install on")
+  Rel(registry, obs, "Clones via")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+Every component depends on **Foundation** (`paths`, `config`, `util`, `output`); those arrows are
+omitted because drawing ten of them into one box hides the structure rather than showing it.
+
+## The layering rule is enforced, not aspirational
+
+`import-linter` runs in `make lint` and CI, with the contract declared in `pyproject.toml`:
+
+```text
+layers = ["cli", "commands", "core"]
+```
+
+Higher layers may import lower ones, never the reverse. `core/` must import neither `commands/` nor
+`cli`, and `commands/` must not reach up into `cli`. There is exactly one allowlisted exception —
+`boost_cli.commands.configuration -> boost_cli.cli` — because `boost completions` reads the
+`COMMANDS` registry, which lives in `cli.py` by design. Any other upward import fails the build.
+
+This is why behaviour belongs in `core/` and not in `commands/`: the mutation gate targets
+`boost_cli/core` at an 80% kill floor, so logic placed in the command layer is covered by neither
+mutation testing nor the layering contract.
+
+## Why retrieval is two components, not one
+
+`rag.py` is the always-on BM25 engine — pure stdlib, full-content index, auto-builds on first
+search. It is what the required `eval` gate floors at recall@k ≥ 0.85 over the pinned golden set.
+
+`dense.py` is optional vector retrieval, active only when both the `[rag]` extra and an embeddings
+key are present, and falling back to BM25 otherwise. Modelling them as one "search" component would
+hide the property that matters most: **the zero-dependency path is the default, and the optional
+one can never be a hard requirement.**
+
+The same shape governs the AI bridge. `ai.py` shells out to the `claude` CLI or
+`ANTHROPIC_API_KEY` when available and degrades to heuristics when not, so `search --smart`,
+`explain` and `distill` get worse without a key, never broken.
+
+## Three item kinds, one scanner
+
+`catalog.scan_dir` walks a tap's clone and classifies every file into one of three kinds:
+
+| Kind | Recognised by | Installable |
+|------|---------------|-------------|
+| `skill` | `SKILL.md` | yes — copied into the canonical store |
+| `rule` | `.mdc`, `.cursorrules`, `.windsurfrules`, `.clinerules` | yes — materialised into each agent's context file |
+| `workflow` | Markdown under `commands/`, `agents/`, `workflows/` | yes — rendered per agent, TOML for Gemini |
+
+Per-agent *formats* are pure functions in `core/`: `rules.CONTEXT_FILES` maps an agent with no
+rules directory to its context file, and `workflows.TOML_COMMAND_AGENTS` marks the agents whose
+slash commands are TOML. Gemini's `commands/` slot is `.toml`
+(`workflows.render_gemini_command`) while its `agents/` slot stays verbatim Markdown — getting that
+backwards produces a file the agent silently never loads.

boost_skill_cli-1.0.298/docs/architecture/c4-containers.md

@@ -0,0 +1,78 @@
+# C4 Level 2 — Containers
+
+The deployable and persistent pieces inside boost. Everything here lives on one machine: boost has
+no server side, and every path is resolved at call time from `$HOME` (or `$BOOST_HOME`) by
+`core/paths.py`, which is what makes `HOME=<tempdir>` sandboxing work in tests.
+
+```mermaid
+C4Container
+  title Container Diagram — boost
+
+  Person(dev, "Developer", "Runs boost commands")
+  System_Ext(agents, "AI coding agents", "Claude Code, Cursor, Windsurf, Gemini CLI")
+  System_Ext(github, "GitHub", "Registry repos and skill sources")
+
+  Container_Boundary(boost, "boost") {
+    Container(cli, "boost CLI", "Python 3.9+, stdlib only", "78 commands in 8 groups; lazy-imports one module per invocation")
+    Container(mcp, "MCP server", "JSON-RPC over stdio", "Exposes search/install/doctor as agent tools")
+    Container(web, "boost serve", "http.server", "Local read-only web UI")
+    Container(engine, "core engine", "Python package", "Catalog, retrieval, store, trust — see the component diagram")
+  }
+
+  Boundary(state, "boost state — ~/.boost") {
+    ContainerDb(repos, "repos/", "shallow git clones", "Tapped registries")
+    ContainerDb(cache, "cache/", "JSON", "Catalogs built from frontmatter")
+    ContainerDb(statedir, "state/", "JSON", "Pins, policy, profiles, snapshots")
+  }
+
+  Boundary(installed, "installed skills") {
+    ContainerDb(store, "~/.agents/skills", "files + .skill-lock.json v3", "Canonical store — single source of truth")
+    ContainerDb(links, "~/.claude, ~/.cursor, ~/.windsurf", "symlinks into the store", "Three linking agents")
+    ContainerDb(gemini, "~/.gemini", "GEMINI.md + TOML commands", "Rules and workflows only")
+  }
+
+  Rel(dev, cli, "Invokes")
+  Rel(agents, mcp, "Calls tools", "stdio")
+  Rel(cli, engine, "Delegates to")
+  Rel(mcp, engine, "Delegates to")
+  Rel(web, engine, "Reads from")
+  Rel(engine, github, "Clones and searches", "git, REST")
+  Rel(engine, repos, "Clones taps into")
+  Rel(engine, cache, "Indexes catalogs into")
+  Rel(engine, statedir, "Persists policy and pins")
+  Rel(engine, store, "Copies skills into")
+  Rel(engine, links, "Symlinks out to")
+  Rel(engine, gemini, "Materialises rules and commands")
+  Rel(agents, store, "Reads directly", "Gemini CLI only")
+  Rel(agents, links, "Reads")
+
+  UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")
+```
+
+## Four agent targets, but only three get symlinks
+
+Gemini CLI implements the Agent Skills standard and discovers `~/.agents/skills` — the canonical
+store — *directly*, so it is configured with `links_skills: false`. Linking into `~/.gemini/skills`
+as well would put one skill in two of its discovery tiers, where the `.agents` alias out-ranks
+whatever was linked, costing a "Skill conflict detected" line per skill per session and buying
+nothing.
+
+That distinction is load-bearing for anything you write:
+
+- Iterate `agents.linking_agents()` for anything symlink-shaped — linking, unlinking, stale-link
+  sweeps, coverage counts.
+- Use `agents.enabled_agents()` for rules and workflows, which materialise into `~/.gemini/` like
+  any other agent's dotdir. `agents.native_store_agents()` is the complement, for reporting.
+
+## Why the canonical store exists
+
+One copy of each skill lives in `~/.agents/skills`; every linking agent gets a symlink to it. That
+is what makes "install once, available everywhere" true without N copies drifting apart, and it is
+why `.skill-lock.json` lives beside the store rather than per-agent. Uninstall removes the copy and
+sweeps the links; `boost sync` reconciles reality against the lock.
+
+## The state directory is not the store
+
+`~/.boost` is *derived* data — clones, indexes and preferences that boost can rebuild. `~/.agents`
+is *user* data: the skills themselves. Deleting `~/.boost` costs a re-tap and a re-index; deleting
+`~/.agents/skills` uninstalls everything. Keeping them apart is deliberate.

boost_skill_cli-1.0.298/docs/architecture/c4-context.md

@@ -0,0 +1,45 @@
+# C4 Level 1 — System context
+
+Who uses boost, and what it talks to. This is the only diagram that shows boost as a single box;
+every other diagram in this directory opens that box.
+
+```mermaid
+C4Context
+  title System Context — boost
+
+  Person(dev, "Developer", "Installs and governs agent skills")
+
+  System(boost, "boost", "CLI + MCP server that finds, installs and governs the skill, rule and workflow files AI coding agents run on")
+
+  System_Ext(agents, "AI coding agents", "Claude Code, Cursor, Windsurf, Gemini CLI")
+  System_Ext(github, "GitHub", "Hosts registry repos (taps) and skill sources")
+  System_Ext(llm, "Anthropic API / claude CLI", "Optional LLM-assisted ranking and authoring")
+  System_Ext(embed, "Voyage / OpenAI embeddings", "Optional vectors for dense retrieval")
+  System_Ext(pypi, "PyPI", "Distributes the boost-skill-cli package")
+
+  Rel(dev, boost, "Runs commands", "terminal")
+  Rel(dev, pypi, "Installs boost from", "pipx / pip")
+  Rel(agents, boost, "Calls boost_search / boost_install", "MCP, JSON-RPC over stdio")
+  Rel(boost, github, "Clones taps and searches code", "git, REST")
+  Rel(boost, agents, "Writes skills, rules and slash-commands", "files + symlinks")
+  Rel(boost, llm, "Ranks, explains, distills", "optional, degrades to heuristics")
+  Rel(boost, embed, "Embeds the catalog", "optional, falls back to BM25")
+
+  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+## What the boundaries mean
+
+**boost never requires the network to be useful.** Both external AI services are optional and
+degrade rather than fail: `core/ai.py` falls back to heuristics when neither the `claude` CLI nor
+`ANTHROPIC_API_KEY` is present, and `core/dense.py` falls back to BM25 when the `[rag]` extra or an
+embeddings key is missing. Only tapping and installing genuinely need GitHub.
+
+**The agents are consumers, not integrations.** boost does not drive an agent or run inside one.
+It writes files into the locations agents already read, so a skill installed once is visible to
+every configured agent with no per-agent wiring — see
+[c4-containers.md](c4-containers.md) for where those files land.
+
+**The shipped runtime is stdlib-only.** `[project].dependencies` is empty by design, so the arrow
+to PyPI carries a package with no runtime dependency closure of its own. Everything optional lives
+behind an extra.

boost_skill_cli-1.0.298/docs/architecture/c4-dynamic-install.md

@@ -0,0 +1,63 @@
+# C4 Dynamic — what `boost install` actually does
+
+The install path is where most of the engine meets. This is the `user`-scope skill case; rules and
+workflows branch at step 5 into `_install_rule` / `_install_workflow`, and `project` scope writes
+real directories inside the repo instead of symlinking out of the canonical store.
+
+```mermaid
+C4Dynamic
+  title Dynamic Diagram — boost install <name> (user scope, kind=skill)
+
+  Person(dev, "Developer", "Runs the command")
+
+  Container_Boundary(engine, "boost_cli") {
+    Component(cmd, "commands/pkg", "Python", "Thin CLI glue")
+    Component(cat, "core/registry + catalog", "Python", "Resolves the entry")
+    Component(res, "core/resolve", "Python", "Dependency closure")
+    Component(trust, "core/policy + capabilities + scanners", "Python", "Governance gate")
+    Component(store, "core/store", "Python", "Copy and link")
+    Component(targets, "core/agents + rules + workflows", "Python", "Per-agent materialisation")
+    Component(lock, "core/lockfile + integrity", "Python", "Records the digest")
+  }
+
+  ContainerDb(canon, "~/.agents/skills", "files", "Canonical store")
+  ContainerDb(links, "~/.claude, ~/.cursor, ~/.windsurf", "symlinks", "Linking agents")
+
+  Rel(dev, cmd, "1. boost install <name>")
+  Rel(cmd, cat, "2. Look up the entry in the cached catalog")
+  Rel(cmd, res, "3. Expand to the full dependency closure")
+  Rel(cmd, store, "4. install(entry)")
+  Rel(store, trust, "5. Gate: policy, capabilities, typosquat, secrets, injection")
+  Rel(store, canon, "6. Copy the skill directory in")
+  Rel(store, targets, "7. Link and materialise per agent")
+  Rel(targets, links, "8. Symlink into each linking agent")
+  Rel(store, lock, "9. Record version + sha256 in .skill-lock.json")
+  Rel(store, dev, "10. Report what was written")
+
+  UpdateRelStyle(store, trust, $offsetY="-20")
+  UpdateRelStyle(store, lock, $offsetY="20")
+```
+
+## The parts that are easy to get wrong
+
+**Step 5 fails closed.** The gate raises `BoostError` rather than warning. A skill whose declared
+capabilities exceed policy, or that trips the secret / prompt-injection / typosquat scanners, is
+not installed at all — there is no "installed but quarantined" state to reason about later.
+
+**Step 7 is not "symlink into every agent".** Only `agents.linking_agents()` get symlinks. Gemini
+CLI reads `~/.agents/skills` natively and is deliberately excluded, because linking into
+`~/.gemini/skills` too would put one skill in two of its discovery tiers and produce a "Skill
+conflict detected" line per skill per session. Rules and workflows *do* materialise into
+`~/.gemini/`, so the right helper depends on what you are writing —
+see [c4-containers.md](c4-containers.md).
+
+**Step 9 is binding, not advisory.** `core/integrity` makes the recorded digest enforceable, which
+is what lets `boost sync` and `boost doctor` tell "the user edited this skill" apart from "the tap
+moved underneath it". `core/staleness` is the single source of truth for the second question.
+
+## Where uninstall differs
+
+Uninstall is not the reverse of this diagram. It removes the canonical copy, sweeps every symlink
+that pointed at it — including stale links left by an agent that was disabled since install — and
+drops the lock entry. Sweeping links for agents that are *not* currently enabled is the part
+hand-rolled reversals miss, which is why `store.uninstall` owns it rather than the command layer.

{boost_skill_cli-1.0.296 → boost_skill_cli-1.0.298}/docs/roadmap/items/dependabot-regeneration-drops-platform-pins.md

@@ -2,15 +2,15 @@
 id: dependabot-regeneration-drops-platform-pins
 board: code
 section: internals
-status: planned
+status: shipped
 category: Build · Bug
 complexity: M
 impact: High
 wow: 3
 note: every pip bump PR is unmergeable — 2 of 2 observed, both red on the install step
 order: 36
-owner:
-pr:
+owner: loop/dependabot-lock-guard
+pr: 342
 title: Dependabot cannot regenerate the hash-pinned locks
 ---
 <b>Every Dependabot PR that touches <code>requirements/*.txt</code> is unmergeable</b>, and the
@@ -49,6 +49,19 @@ Dependabot bump can be <i>reproduced</i> rather than merged — take the version
 re-resolve that one package universally, and every other pin (markers included) stays as committed.
 Both open bumps were landed that way: <code>hypothesis</code> 6.161.6 to 6.163.0 and
 <code>twine</code> 6.2.0 to 7.0.0, four changed lines across five locks, with
-<code>colorama</code> and <code>pywin32-ctypes</code> intact. What remains is the config half —
-stopping Dependabot raising these at all — which is deliberately still open because its effect is
-only observable on the next scheduled run.
+<code>colorama</code> and <code>pywin32-ctypes</code> intact.
+<b>Shipped:</b> both remaining halves. The <code>/requirements</code> entry now carries
+<code>open-pull-requests-limit: 0</code>, which switches off <i>version</i> updates — the ones that
+regenerate the lock — while <b>security</b> updates ignore the limit and keep firing, so the entry
+still earns its place. The <code>/</code> entry is untouched; narrowing that one is
+[[dependabot-root-pip-entry-duplicates-requirements]].
+And the guard the card asked for exists: <code>requirements/platform-pins.lock</code> records every
+marker-gated pin <b>by name and marker but not version</b>, so a routine bump leaves it untouched
+and only a change in the <i>shape</i> of a resolution moves a line.
+<code>lock_toolchain.py --audit</code> diffs the locks against it and <b>runs first inside
+<code>--check</code></b>, before uv is invoked at all — it reads only committed files, so it also
+runs in the unit suite and on a runner that could not resolve. A lost pin now fails naming the
+package, the group and the marker it lost, and prints the <code>-P</code> command that reproduces
+the bump properly. A <i>lost</i> pin and a <i>new</i> pin are reported differently on purpose: the
+same textual drift, but one is a broken install on a platform CI never resolves on and the other is
+routine — collapsing them into one "stale" message is how this stayed invisible the first time.

boost_skill_cli-1.0.298/docs/roadmap/items/internal-architecture-diagrams.md

@@ -0,0 +1,44 @@
+---
+id: internal-architecture-diagrams
+board: code
+section: docsite
+status: shipped
+category: Docs · Onboarding
+complexity: M
+impact: Med
+wow: 3
+note: 45 core modules and an enforced layering rule, with no diagram of either
+order: 12
+owner: loop/architecture-diagrams
+pr: 345
+title: The engine had no architecture diagram — and the one written rule was documented backwards
+---
+boost had <b>no internal architecture diagram of any kind</b>. <code>docs/rag-architecture.md</code>
+covers retrieval and <code>docs/DEBUGGING.md</code> covers diagnostics, but nothing described the
+shape of the thing: 45 modules in <code>boost_cli/core</code>, 78 commands across 12 command
+modules, four agent targets that are deliberately <i>not</i> symmetric, and a
+<code>cli&nbsp;&rarr;&nbsp;commands&nbsp;&rarr;&nbsp;core</code> layering rule that
+<code>import-linter</code> enforces on every build. A new contributor — or a new agent session —
+had to reconstruct all of that from <code>ls</code>.
+
+Shipped as C4-model diagrams in Mermaid under <code>docs/architecture/</code>, so they render on
+GitHub and stay reviewable in a diff rather than being a binary nobody updates: context, containers,
+core components, and a dynamic walk through <code>boost install</code>. Mermaid was already a
+dependency-free choice here — the repo had none before this, so nothing new ships.
+
+Writing them turned up a documentation bug worth more than the diagrams. <code>CLAUDE.md</code>
+stated <b>"Only <code>skill</code> installs — <code>store.install</code> refuses non-skill kinds;
+rules/workflows are search/tap-only."</b> That is backwards: <code>store.install</code> dispatches
+to <code>_install_rule</code> and <code>_install_workflow</code>, every kind honours
+<code>scope</code>, and it raises only for a kind outside the three. The consequence is not
+cosmetic — installing a <i>rule</i> materialises it into the agent's context file, so a
+<code>boost install</code> of a rule appends to <code>~/.claude/CLAUDE.md</code> and is read every
+session afterwards. Every agent reading <code>CLAUDE.md</code> to learn this repo was being told the
+most invasive install kind could not happen. Corrected in the same change, with the landing places
+for all three kinds spelled out.
+
+The diagrams are hand-written rather than generated, which is a deliberate trade: they describe
+structure — layers, boundaries, which component owns which decision — not anything that moves on a
+routine edit, so drift should be rare and visible in review. <code>docs/architecture/README.md</code>
+lists the four claims most worth re-checking against the code when the engine changes, so the
+staleness question has an answer rather than being left to erode.

boost_skill_cli-1.0.298/docs/roadmap/items/scheduled-toolchain-lock-regeneration.md

@@ -0,0 +1,45 @@
+---
+id: scheduled-toolchain-lock-regeneration
+board: code
+section: internals
+status: planned
+category: Build · Gap
+complexity: M
+impact: Med
+wow: 2
+note: the toolchain lock now has no proactive update path — by choice, but nothing replaces it yet
+order: 36
+owner:
+pr:
+title: The toolchain lock has no proactive update path any more
+---
+<code>#342</code> set <code>open-pull-requests-limit: 0</code> on the <code>/requirements</code>
+Dependabot entry, because Dependabot cannot regenerate a hash-pinned universal lock without dropping
+the pins whose environment markers exclude them on the resolving platform (see
+[[dependabot-regeneration-drops-platform-pins]]). That was the right call — every pip bump it raised
+was unmergeable — but it reverses the reason the entry was added in the first place: <b>a pin with no
+update path is only half the job</b>, and the dev/CI toolchain now has none.
+
+The trade is bounded rather than silent, which is why this is <code>Med</code> and not
+<code>High</code>. Dependabot <b>security</b> updates ignore the limit and still fire;
+<code>pip-audit.yml</code> runs weekly against the resolved closure and <b>blocks</b> on a live CVE
+(Dependabot only ever opened a PR); and <code>osv-scanner.yml</code> covers what a PR introduces. So
+the exposure is not "a vulnerable pin sits there unnoticed" — it is
+<b>stale-but-not-vulnerable tooling</b>, drifting further from upstream every week until something
+forces a bump.
+
+The replacement the card already named: regenerate on a schedule with
+<code>scripts/lock_toolchain.py --upgrade</code> and open the PR from that, so the resolution stays
+universal and every conditional pin survives. Four points worth getting right rather than guessing.
+<b>First</b>, it needs <code>uv</code> and the network — the required gate's <code>--check</code>
+already assumes both on CI, but no scheduled job currently sets them up. <b>Second</b>,
+<code>--upgrade</code> re-resolves all five groups, so a weekly cadence would land large multi-group
+diffs; per-group jobs, or a lower cadence, keep a bump reviewable, and the reason <code>-P</code>
+exists at all is that a bare <code>--upgrade</code> buries one package in unrelated churn.
+<b>Third</b>, a new workflow is not free in this repo: it must be zizmor-clean with every
+<code>uses:</code> pinned to a <i>peeled</i> commit SHA, carry narrow <code>permissions</code>, and
+— if it is ever made a required context — grow a <code>merge_group:</code> trigger, which
+<code>check_required_checks.py</code> enforces. <b>Fourth</b>, nothing needs to guard the output:
+<code>lock_toolchain.py --audit</code> and <code>requirements/platform-pins.lock</code> already fail
+closed on a lost marker-gated pin, so a regeneration job that got it wrong would be caught the same
+way a Dependabot PR now is.