boost-skill-cli 1.0.385__tar.gz → 1.0.387__tar.gz

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.385
+Version: 1.0.387
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/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.385'
-__version_tuple__ = version_tuple = (1, 0, 385)
+__version__ = version = '1.0.387'
+__version_tuple__ = version_tuple = (1, 0, 387)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.385
+Version: 1.0.387
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/boost_skill_cli.egg-info/SOURCES.txt

@@ -248,6 +248,8 @@ docs/roadmap/items/invocation-pid-logging-for-crash-correlation.md
 docs/roadmap/items/journal-rotation-race-and-handle-leak.md
 docs/roadmap/items/keyless-dense-tier-local-static-embeddings.md
 docs/roadmap/items/keyless-semantic-search-for-everyone.md
+docs/roadmap/items/langchain-integration-explainer-page.md
+docs/roadmap/items/langchain-langgraph-langsmith-integration.md
 docs/roadmap/items/layering-guard-import-linter.md
 docs/roadmap/items/license-compliance-scanning.md
 docs/roadmap/items/lighthouse-ci-on-the-pages-site.md

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/docs/index.html

@@ -64,17 +64,25 @@
     font-size: 14px; color: var(--text-2); text-decoration: none; white-space: nowrap;
   }
   header .nav ul a:hover { color: var(--text); background: var(--panel); }
-  header .nav ul a.cta { color: var(--text); font-weight: 600; }
+  /* var(--bg), not var(--text): this pill's background is the light Aurora
+     gradient, so near-white text measures 1.38:1 against its cyan stop — a
+     3x WCAG AA failure. No gate caught it: axe cannot evaluate contrast over
+     a gradient and files it as "incomplete" rather than a violation, and
+     scripts/a11y_check.py only grades solid token pairs. style/boost.css:479
+     already had this right; this inline rule was overriding it on cascade
+     order. Matches .btn-grad in the hero, which measures ~8:1. */
+  header .nav ul a.cta { color: var(--bg); font-weight: 600; }
 
   /* Small screens: the fourteen links get their own full-width row and scroll,
      with 40px tap targets — mirrors the .site-nav rules in style/boost.css.
      Stated here because this page's inline nav styling would otherwise win
      against the shared sheet on cascade order. */
   @media (max-width: 720px) {
-    header .nav { flex-wrap: wrap; gap: 6px 18px; padding: 8px 0 6px; }
+    header .nav { flex-wrap: wrap; gap: 6px 18px; padding: 8px 24px 6px; }
     header .nav ul {
       width: 100%; margin-left: 0; flex-wrap: nowrap; gap: 6px;
       -webkit-overflow-scrolling: touch; scroll-snap-type: x proximity;
+      scroll-padding-inline-start: 24px;
       margin-inline: -24px; padding-inline: 24px; padding-bottom: 4px;
       -webkit-mask-image: linear-gradient(90deg, #000 0 calc(100% - 26px), transparent);
               mask-image: linear-gradient(90deg, #000 0 calc(100% - 26px), transparent);
@@ -243,6 +251,16 @@
   .flow-row.one { grid-template-columns: minmax(0, 460px); justify-content: center; }
   .flow-row.two { grid-template-columns: 1fr 1fr; }
   .flow-row.three { grid-template-columns: 1fr 1fr 1fr; }
+  /* Four agents, four columns. The ladder only ever uses counts that divide
+     4 — any other number strands the last card alone on its own row with the
+     rest of that row empty, which is what `.three` did to Gemini CLI at every
+     width above the 620px collapse. */
+  .flow-row.four { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+  /* Below ~900px four tracks squeeze each card to 165px and the Gemini
+     caption to three lines (128px / four lines by 621px), so step to 2x2 —
+     still a divisor of 4, so still no orphan. The max-width:620px rule
+     further down takes it to a single column and wins there on source order. */
+  @media (max-width: 900px) { .flow-row.four { grid-template-columns: 1fr 1fr; } }
   .node {
     background: var(--surface-1);
     box-shadow: inset 0 1px 0 0 rgba(255,255,255,.06), inset 0 -1px 0 0 rgba(0,0,0,.3);
@@ -425,7 +443,7 @@
   @media (max-width: 620px) {
     section { padding: 84px 0 10px; }
     .cards, .caps, .mini { grid-template-columns: 1fr; }
-    .flow-row.two, .flow-row.three { grid-template-columns: 1fr; }
+    .flow-row.two, .flow-row.three, .flow-row.four { grid-template-columns: 1fr; }
     .stats { gap: 10px; }
     .stat { padding: 18px 10px; }
   }
@@ -616,7 +634,7 @@ facilitate structured divergent thinking:
           <svg width="14" height="26" viewBox="0 0 14 26" fill="none" aria-hidden="true"><path d="M7 0v22m0 0l-5.5-6M7 22l5.5-6" stroke="currentColor" stroke-width="2"/></svg>
           <span>symlinks</span>
         </div>
-        <div class="flow-row three reveal">
+        <div class="flow-row four reveal">
           <div class="node agent">
             <span class="tag">Agent</span>
             <h3>Claude Code</h3>

boost_skill_cli-1.0.387/docs/roadmap/items/langchain-integration-explainer-page.md

@@ -0,0 +1,66 @@
+---
+id: langchain-integration-explainer-page
+board: code
+section: docsite
+status: planned
+category: Docs · Interop
+complexity: M
+impact: Med
+wow: 4
+note: the eval.html genre, pointed at the LangChain stack — and it can only document what has shipped
+order: 89
+title: an explainer page for the LangChain / LangGraph / LangSmith integration
+---
+A companion to <b>production-ready LangChain / LangGraph / LangSmith integration</b>: one
+<code>docs/langchain.html</code> that shows what the integration <i>is</i> — architecture and
+sequence diagrams, annotated code you can paste, and the reasoning behind each seam — rather than
+an API list. The audience is a Python engineer deciding whether boost's catalogue is worth wiring
+into their agent, and that decision is made from a diagram and a twenty-line snippet, not from
+a reference table.
+
+<b>The genre already exists here.</b> <code>docs/eval.html</code> does exactly this job for the
+evaluation system — architecture plus sequence diagrams plus a simple-vs-technical cheat sheet — and
+it is the template to follow rather than reinvent. So are its mechanics: a page-specific
+<code>&lt;style&gt;</code> block built <i>only</i> on <code>style/boost.css</code>
+<code>:root</code> tokens, so the Aurora palette stays recolourable from one file, and diagrams as
+<b>inline SVG on those same tokens</b> rather than a diagram library. A hardcoded hex in a diagram
+silently opts that diagram out of every future theme change, and an external script opts the page
+out of loading at all on a strict CSP.
+
+<b>What the page has to cover</b>, one section per seam, each with a diagram and a runnable snippet:
+retrieval (<code>BoostRetriever</code> over the BM25 + dense fusion, with the measured recall@k /
+hit@1 / MRR / nDCG@k shown as numbers because they exist); a <code>SKILL.md</code> loaded as prompt
+content with its frontmatter surviving as metadata; a LangGraph graph that pulls a procedure
+<i>mid-run</i> instead of pre-loading every one into the system prompt; and a LangSmith trace of
+that graph, next to a plain statement that the required gate stays offline, deterministic and
+key-free.
+
+<b>Three constraints that are specific to this repo</b>, all of them cheap to satisfy if known up
+front and expensive to retrofit:
+
+<b>No page ships unlinked.</b> <code>tests/unit/test_docsite_chrome.py</code> holds a
+<code>_PAGES</code> tuple and asserts every page carries the footer and is reachable from all the
+others. Adding the tenth page therefore means touching the nav and footer of the nine that exist —
+it is a small edit, but it is not optional and it is not automatic.
+
+<b>The budget already fits — measured, so nobody has to guess.</b>
+<code>scripts/page_budget.py</code> allows a hand-written page 150 kB / 2,000 elements / depth 20.
+Today <code>eval.html</code> is 35.5 kB / 528 elements / depth 10 and <code>mcp-hub.html</code>, the
+largest hand-written page, is 50.0 kB / 607. A diagram-and-snippet page of this shape lands in the
+same range, so it needs <b>no</b> new <code>BUDGETS</code> entry — and if it ever does, the entry
+carries a <code>why</code> string rather than raising the default for every page.
+
+<b>Accessibility is enforced with numbers, not vibes.</b> The axe-core sweep and
+<code>scripts/a11y_check.py</code> gate WCAG 2.1 AA, and this genre trips it in a predictable place:
+a diagram that encodes meaning in colour alone, or a link distinguished only by hue. The precedent
+is already commented in <code>eval.html</code> — <code>--sky</code> on <code>--text-3</code> is
+2.47:1 against the 3:1 that WCAG 1.4.1 requires, so its links carry an underline as the non-colour
+cue. Diagram legends need the same treatment: shape or label, never colour by itself.
+
+<b>Sequencing, and the one rule that keeps it honest.</b> The page cannot precede the code — a
+demonstration of an unbuilt integration is fiction, and a snippet nobody ran is a bug with syntax
+highlighting. So each section ships with the phase it documents (retrieval with phase 1, the graph
+with phase 2, the trace with phase 3), and every snippet on the page should be extracted and
+executed by a test rather than pasted in and trusted. That last part is a new discipline for this
+docsite, not an existing one; it is worth adopting here first precisely because this page's whole
+value is that its code runs.

boost_skill_cli-1.0.387/docs/roadmap/items/langchain-langgraph-langsmith-integration.md

@@ -0,0 +1,89 @@
+---
+id: langchain-langgraph-langsmith-integration
+board: code
+section: planned
+status: planned
+category: Feature
+complexity: L
+impact: High
+wow: 4
+note: a second consumer class for the catalogue — blocked on one dependency conflict boost already owns
+order: 88
+title: production-ready LangChain / LangGraph / LangSmith integration
+---
+Every agent boost supports today is a <b>coding</b> agent that reads files off disk — Claude Code,
+Cursor, Windsurf, Gemini CLI. The catalogue itself is not coding-specific: it is 10,000+ retrievable
+procedures with frontmatter, provenance and a lock file. A LangChain application cannot reach any of
+it, so the same procedure has to be re-written as a prompt string by hand. This item is about making
+the catalogue addressable from a Python agent runtime as well as from a dotfile.
+
+<b>Three surfaces, and they are not equally justified.</b>
+
+<code>langchain</code> — a <code>BoostRetriever</code> implementing <code>BaseRetriever</code> over
+the engine <code>boost search</code> already uses: BM25 (<code>core/rag.py</code>) fused with
+optional dense retrieval (<code>core/dense.py</code>) through <code>rag.rrf_fuse</code>. The
+retrieval quality is already measured — the required gate floors recall@k, hit@1, MRR and nDCG@k
+against <code>tests/eval/golden.jsonl</code> — so this surface ships with numbers rather than
+claims. Plus a document loader that turns a <code>SKILL.md</code> into prompt content with its
+frontmatter preserved as metadata.
+
+<code>langgraph</code> — skills as procedures a graph pulls <i>mid-run</i>: a node that retrieves
+the right skill for the current state and injects it, rather than stuffing every procedure into the
+system prompt. boost's <code>workflow</code> item kind is already the closest thing it has to a
+graph node, and <code>core/workflows.py</code> already renders per-runtime formats
+(<code>TOML_COMMAND_AGENTS</code> for Gemini), so a LangGraph renderer is a new target for existing
+machinery, not a new concept.
+
+<code>langsmith</code> — hosted tracing plus datasets/evaluators. boost already has a four-tier
+eval story (Tier 1 BM25 floors, 1b <code>ranx</code> significance, 2a/2b LLM rerank and recommend,
+2c <code>ragas</code> faithfulness) and a baseline keyed by query-set digest. LangSmith would host
+the golden set and run online evals against real traffic. It must <b>not</b> replace the required
+gate, which is deliberately pure-stdlib BM25 needing no API key — a required check that depends on
+a SaaS account is a required check that fails when someone else's billing lapses.
+
+<b>What "production ready" forces, specifically.</b>
+
+<b>It cannot be an extra — the Python floor decides it.</b> boost is
+<code>requires-python = "&gt;=3.9"</code> and CI tests 3.9 / 3.12 / 3.14 across Linux, macOS and
+Windows. Measured 2026-08-02: <code>langchain</code> 1.3.14 declares
+<code>&gt;=3.10.0,&lt;4.0.0</code> and <code>langsmith</code> 0.10.15 declares <code>&gt;=3.10</code>. So
+an extra would either fail to resolve on the 3.9 leg or force boost to drop 3.9 for every user,
+including those who never touch LangChain. A separately versioned distribution that depends on
+<code>boost-skill-cli</code> keeps the floor a property of the integration.
+
+<b>There is a dependency conflict boost already owns, and it blocks this.</b> The
+<code>[eval]</code> extra pins <code>langchain-core&lt;0.4</code>,
+<code>langchain-community&lt;0.4</code> and <code>langchain-openai&lt;1</code>, because ragas 0.2.x
+hard-imports a <code>ChatVertexAI</code> path that langchain ≥1.0 removed. One environment cannot
+hold both that pin and langchain 1.x. The good news is measured: <b>ragas 0.4.3 declares
+<code>langchain</code>, <code>langchain-core</code>, <code>langchain-community</code> and
+<code>langchain_openai</code> with no upper bound at all</b>, and still supports Python ≥3.9. So the
+first step is small, independently valuable, and testable on its own — move <code>[eval]</code>
+from <code>ragas&gt;=0.2,&lt;0.3</code> to 0.4 and delete the three pins. Nothing else should be built
+until that lands, or the project holds two incompatible langchain majors.
+
+<b>The existing rules still apply.</b> Nothing in the integration may be imported by the CLI or by
+the required gate — the discipline <code>[eval]</code> already follows. It must degrade cleanly
+without an API key, the way <code>embed.py</code> falls back Voyage → OpenAI → local
+<code>bge-small-en-v1.5</code>; a key is a quality upgrade, never the entry fee. And it carries its
+own tests without lowering the 80% coverage or 80% mutation floors.
+
+<b>Delivery order.</b> Each phase is independently shippable, and phase 0 is worth doing on its own
+merits whatever happens to the rest.
+
+<b>0 &middot; unpin.</b> Move <code>[eval]</code> to <code>ragas&gt;=0.4</code> and delete the three
+langchain pins, freeing the langchain major. Contained, testable, no new surface.
+<b>1 &middot; retrieve.</b> A <code>boost-langchain</code> distribution carrying
+<code>BoostRetriever</code> and the <code>SKILL.md</code> loader — the smallest thing that makes the
+catalogue reachable from a LangChain app, and the one with measured retrieval quality behind it.
+<b>2 &middot; orchestrate.</b> The LangGraph node, plus a graph-shaped render target in
+<code>core/workflows.py</code> beside the existing per-agent formats.
+<b>3 &middot; observe.</b> LangSmith tracing, and the golden set published as a LangSmith dataset so
+online evals run against the same queries the offline gate uses.
+
+<b>One scoping decision shapes phase 1's API</b> and should be settled before it starts: a LangChain
+<i>application</i> pulling skills at runtime is the consumer all three phases serve, whereas a
+LangChain <i>developer</i> who just wants these procedures in their editor is already served by
+<code>boost install</code> with no langchain dependency at all. Phase 1 should be designed for the
+former — a retriever, not an installer — and the docs should point the latter at the CLI so the new
+package does not accumulate a second, redundant install path.

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/docs/roadmap.html

@@ -124,8 +124,8 @@
       <!-- ROADMAP:stats -->
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
-      <div class="stat"><b>4</b><span>Planned</span></div>
-      <div class="stat"><b>204</b><span>Loop finds</span></div>
+      <div class="stat"><b>5</b><span>Planned</span></div>
+      <div class="stat"><b>206</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -618,6 +618,93 @@ message, so routing it through the helper would change user-facing errors.</p></
           <span class="m">Wow <b class="wow">★★★★</b></span>
         </div>
       </article>
+
+      <article class="cap rcard" id="langchain-langgraph-langsmith-integration">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Feature</span></div>
+        <h3>production-ready LangChain / LangGraph / LangSmith integration</h3>
+        <p>Every agent boost supports today is a <b>coding</b> agent that reads files off disk — Claude Code,
+Cursor, Windsurf, Gemini CLI. The catalogue itself is not coding-specific: it is 10,000+ retrievable
+procedures with frontmatter, provenance and a lock file. A LangChain application cannot reach any of
+it, so the same procedure has to be re-written as a prompt string by hand. This item is about making
+the catalogue addressable from a Python agent runtime as well as from a dotfile.
+
+<b>Three surfaces, and they are not equally justified.</b>
+
+<code>langchain</code> — a <code>BoostRetriever</code> implementing <code>BaseRetriever</code> over
+the engine <code>boost search</code> already uses: BM25 (<code>core/rag.py</code>) fused with
+optional dense retrieval (<code>core/dense.py</code>) through <code>rag.rrf_fuse</code>. The
+retrieval quality is already measured — the required gate floors recall@k, hit@1, MRR and nDCG@k
+against <code>tests/eval/golden.jsonl</code> — so this surface ships with numbers rather than
+claims. Plus a document loader that turns a <code>SKILL.md</code> into prompt content with its
+frontmatter preserved as metadata.
+
+<code>langgraph</code> — skills as procedures a graph pulls <i>mid-run</i>: a node that retrieves
+the right skill for the current state and injects it, rather than stuffing every procedure into the
+system prompt. boost's <code>workflow</code> item kind is already the closest thing it has to a
+graph node, and <code>core/workflows.py</code> already renders per-runtime formats
+(<code>TOML_COMMAND_AGENTS</code> for Gemini), so a LangGraph renderer is a new target for existing
+machinery, not a new concept.
+
+<code>langsmith</code> — hosted tracing plus datasets/evaluators. boost already has a four-tier
+eval story (Tier 1 BM25 floors, 1b <code>ranx</code> significance, 2a/2b LLM rerank and recommend,
+2c <code>ragas</code> faithfulness) and a baseline keyed by query-set digest. LangSmith would host
+the golden set and run online evals against real traffic. It must <b>not</b> replace the required
+gate, which is deliberately pure-stdlib BM25 needing no API key — a required check that depends on
+a SaaS account is a required check that fails when someone else's billing lapses.
+
+<b>What "production ready" forces, specifically.</b>
+
+<b>It cannot be an extra — the Python floor decides it.</b> boost is
+<code>requires-python = "&gt;=3.9"</code> and CI tests 3.9 / 3.12 / 3.14 across Linux, macOS and
+Windows. Measured 2026-08-02: <code>langchain</code> 1.3.14 declares
+<code>&gt;=3.10.0,&lt;4.0.0</code> and <code>langsmith</code> 0.10.15 declares <code>&gt;=3.10</code>. So
+an extra would either fail to resolve on the 3.9 leg or force boost to drop 3.9 for every user,
+including those who never touch LangChain. A separately versioned distribution that depends on
+<code>boost-skill-cli</code> keeps the floor a property of the integration.
+
+<b>There is a dependency conflict boost already owns, and it blocks this.</b> The
+<code>[eval]</code> extra pins <code>langchain-core&lt;0.4</code>,
+<code>langchain-community&lt;0.4</code> and <code>langchain-openai&lt;1</code>, because ragas 0.2.x
+hard-imports a <code>ChatVertexAI</code> path that langchain ≥1.0 removed. One environment cannot
+hold both that pin and langchain 1.x. The good news is measured: <b>ragas 0.4.3 declares
+<code>langchain</code>, <code>langchain-core</code>, <code>langchain-community</code> and
+<code>langchain_openai</code> with no upper bound at all</b>, and still supports Python ≥3.9. So the
+first step is small, independently valuable, and testable on its own — move <code>[eval]</code>
+from <code>ragas&gt;=0.2,&lt;0.3</code> to 0.4 and delete the three pins. Nothing else should be built
+until that lands, or the project holds two incompatible langchain majors.
+
+<b>The existing rules still apply.</b> Nothing in the integration may be imported by the CLI or by
+the required gate — the discipline <code>[eval]</code> already follows. It must degrade cleanly
+without an API key, the way <code>embed.py</code> falls back Voyage → OpenAI → local
+<code>bge-small-en-v1.5</code>; a key is a quality upgrade, never the entry fee. And it carries its
+own tests without lowering the 80% coverage or 80% mutation floors.
+
+<b>Delivery order.</b> Each phase is independently shippable, and phase 0 is worth doing on its own
+merits whatever happens to the rest.
+
+<b>0 &middot; unpin.</b> Move <code>[eval]</code> to <code>ragas&gt;=0.4</code> and delete the three
+langchain pins, freeing the langchain major. Contained, testable, no new surface.
+<b>1 &middot; retrieve.</b> A <code>boost-langchain</code> distribution carrying
+<code>BoostRetriever</code> and the <code>SKILL.md</code> loader — the smallest thing that makes the
+catalogue reachable from a LangChain app, and the one with measured retrieval quality behind it.
+<b>2 &middot; orchestrate.</b> The LangGraph node, plus a graph-shaped render target in
+<code>core/workflows.py</code> beside the existing per-agent formats.
+<b>3 &middot; observe.</b> LangSmith tracing, and the golden set published as a LangSmith dataset so
+online evals run against the same queries the offline gate uses.
+
+<b>One scoping decision shapes phase 1's API</b> and should be settled before it starts: a LangChain
+<i>application</i> pulling skills at runtime is the consumer all three phases serve, whereas a
+LangChain <i>developer</i> who just wants these procedures in their editor is already served by
+<code>boost install</code> with no langchain dependency at all. Phase 1 should be designed for the
+former — a retriever, not an installer — and the docs should point the latter at the CLI so the new
+package does not accumulate a second, redundant install path.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>L</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">a second consumer class for the catalogue — blocked on one dependency conflict boost already owns</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>
@@ -6833,6 +6920,70 @@ here changes that &mdash; only the odds that the next step change is noticed the
           <span class="m">main passes this budget on run-to-run luck — its own three runs are 0.810, 0.840, 0.850</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="langchain-integration-explainer-page">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Docs · Interop</span></div>
+        <h3>an explainer page for the LangChain / LangGraph / LangSmith integration</h3>
+        <p>A companion to <b>production-ready LangChain / LangGraph / LangSmith integration</b>: one
+<code>docs/langchain.html</code> that shows what the integration <i>is</i> — architecture and
+sequence diagrams, annotated code you can paste, and the reasoning behind each seam — rather than
+an API list. The audience is a Python engineer deciding whether boost's catalogue is worth wiring
+into their agent, and that decision is made from a diagram and a twenty-line snippet, not from
+a reference table.
+
+<b>The genre already exists here.</b> <code>docs/eval.html</code> does exactly this job for the
+evaluation system — architecture plus sequence diagrams plus a simple-vs-technical cheat sheet — and
+it is the template to follow rather than reinvent. So are its mechanics: a page-specific
+<code>&lt;style&gt;</code> block built <i>only</i> on <code>style/boost.css</code>
+<code>:root</code> tokens, so the Aurora palette stays recolourable from one file, and diagrams as
+<b>inline SVG on those same tokens</b> rather than a diagram library. A hardcoded hex in a diagram
+silently opts that diagram out of every future theme change, and an external script opts the page
+out of loading at all on a strict CSP.
+
+<b>What the page has to cover</b>, one section per seam, each with a diagram and a runnable snippet:
+retrieval (<code>BoostRetriever</code> over the BM25 + dense fusion, with the measured recall@k /
+hit@1 / MRR / nDCG@k shown as numbers because they exist); a <code>SKILL.md</code> loaded as prompt
+content with its frontmatter surviving as metadata; a LangGraph graph that pulls a procedure
+<i>mid-run</i> instead of pre-loading every one into the system prompt; and a LangSmith trace of
+that graph, next to a plain statement that the required gate stays offline, deterministic and
+key-free.
+
+<b>Three constraints that are specific to this repo</b>, all of them cheap to satisfy if known up
+front and expensive to retrofit:
+
+<b>No page ships unlinked.</b> <code>tests/unit/test_docsite_chrome.py</code> holds a
+<code>_PAGES</code> tuple and asserts every page carries the footer and is reachable from all the
+others. Adding the tenth page therefore means touching the nav and footer of the nine that exist —
+it is a small edit, but it is not optional and it is not automatic.
+
+<b>The budget already fits — measured, so nobody has to guess.</b>
+<code>scripts/page_budget.py</code> allows a hand-written page 150 kB / 2,000 elements / depth 20.
+Today <code>eval.html</code> is 35.5 kB / 528 elements / depth 10 and <code>mcp-hub.html</code>, the
+largest hand-written page, is 50.0 kB / 607. A diagram-and-snippet page of this shape lands in the
+same range, so it needs <b>no</b> new <code>BUDGETS</code> entry — and if it ever does, the entry
+carries a <code>why</code> string rather than raising the default for every page.
+
+<b>Accessibility is enforced with numbers, not vibes.</b> The axe-core sweep and
+<code>scripts/a11y_check.py</code> gate WCAG 2.1 AA, and this genre trips it in a predictable place:
+a diagram that encodes meaning in colour alone, or a link distinguished only by hue. The precedent
+is already commented in <code>eval.html</code> — <code>--sky</code> on <code>--text-3</code> is
+2.47:1 against the 3:1 that WCAG 1.4.1 requires, so its links carry an underline as the non-colour
+cue. Diagram legends need the same treatment: shape or label, never colour by itself.
+
+<b>Sequencing, and the one rule that keeps it honest.</b> The page cannot precede the code — a
+demonstration of an unbuilt integration is fiction, and a snippet nobody ran is a bug with syntax
+highlighting. So each section ships with the phase it documents (retrieval with phase 1, the graph
+with phase 2, the trace with phase 3), and every snippet on the page should be extracted and
+executed by a test rather than pasted in and trusted. That last part is a new discipline for this
+docsite, not an existing one; it is worth adopting here first precisely because this page's whole
+value is that its code runs.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">the eval.html genre, pointed at the LangChain stack — and it can only document what has shipped</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.0.385 → boost_skill_cli-1.0.387}/style/boost.css

@@ -526,12 +526,17 @@ footer .foot-legal { margin-top: 13px; font-size: 12.5px; color: var(--text-3);
    scrollable rather than truncated. */
 @media (max-width: 720px) {
   .site-nav, header .nav {
-    flex-wrap: wrap; align-items: center; gap: 6px 18px; padding: 8px 0 6px;
+    flex-wrap: wrap; align-items: center; gap: 6px 18px; padding: 8px 24px 6px;
   }
   .site-nav ul, header .nav ul {
     width: 100%; flex-wrap: nowrap; gap: 6px;
     overflow-x: auto; -webkit-overflow-scrolling: touch;
     scrollbar-width: none; scroll-snap-type: x proximity;
+    /* Without this the snapport starts at the scrollport's content edge, so
+       the browser scrolls straight past the padding-inline below to satisfy
+       scroll-snap-align:start — the strip loads at scrollLeft 24 and clips the
+       first link mid-word. Inset the snapport by the same 24px instead. */
+    scroll-padding-inline-start: 24px;
     /* bleed past .wrap's 24px gutter, then pad it back so nothing is clipped */
     margin-inline: -24px; padding-inline: 24px; padding-bottom: 4px;
     -webkit-mask-image: linear-gradient(90deg, #000 0 calc(100% - 26px), transparent);