diff --git a/.coldstart/notebook/.raw/how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs.jsonl b/.coldstart/notebook/.raw/how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs.jsonl
index ce7be4e..071853d 100644
--- a/.coldstart/notebook/.raw/how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs.jsonl
+++ b/.coldstart/notebook/.raw/how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs.jsonl
@@ -1,3 +1,5 @@
 {"title":"how a new site-astro page acquires nav, footer and SVG defs","summary":"Nav.astro, Footer.astro and SvgDefs.astro carry no styling or defs of their own — the chrome CSS lives entirely in whichever page-level stylesheet the page imports, so a new page must import landing.css or docs.css for the nav/footer to look right EVEN IF it ships its own stylesheet, and must render <SvgDefs /> or every url(#rough)/url(#glow) reference in its own markup silently resolves to nothing (no console error, the stroke just renders unfiltered). Verified this session by building two new pages: docs.css was the stylesheet that carried the chrome, and the hand-drawn filter on the new figures only appeared once <SvgDefs /> was rendered on the page.","identityAliases":["new site-astro page","page chrome wiring","nav footer styling","SvgDefs filter defs"],"incidentAliases":["nav unstyled on new page","rough filter not applied","hand-drawn stroke missing"],"steps":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","role":"a page: imports docs.css for chrome + how.css for its own styles, renders SvgDefs then Nav then content then Footer"},{"path":"site-astro/src/styles/docs.css","role":"carries the nav/footer chrome CSS and the dark tokens for every non-home page"},{"path":"site-astro/src/components/Nav.astro","symbols":["Props"],"role":"markup only; the variant prop picks the active link and the install href"},{"path":"site-astro/src/components/SvgDefs.astro","role":"inline zero-size <svg><defs> holding #rough/#glow/#core/#warm/#flake, referenced by url(#...) from page markup"},{"path":"site-astro/src/components/Footer.astro","symbols":["taglines"],"role":"markup only; variant selects the tagline string"}],"invariants":["Nav/Footer/SvgDefs are unstyled markup — their appearance comes entirely from the page's stylesheet, never from the component","url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter","Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined"],"verified":["site-astro/src/pages/how-it-works/notebook.astro","site-astro/src/pages/how-it-works/navigation.astro","site-astro/src/components/Nav.astro","site-astro/src/components/Footer.astro","site-astro/src/components/SvgDefs.astro","site-astro/src/styles/docs.css","site-astro/src/styles/how.css"],"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","op":"put","v":1,"ts":"2026-08-09T10:05:32.726Z","head":"578f3ec476b0","anchors":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:1a01e0dc7278","head":"578f3ec476b0"},{"path":"site-astro/src/pages/how-it-works/navigation.astro","hash":"sha256:fe084da82216","head":"578f3ec476b0"},{"path":"site-astro/src/components/Nav.astro","hash":"sha256:8f39e6f12895","head":"578f3ec476b0"},{"path":"site-astro/src/components/Footer.astro","hash":"sha256:d72628133dd4","head":"578f3ec476b0"},{"path":"site-astro/src/components/SvgDefs.astro","hash":"sha256:855fadd756ae","head":"578f3ec476b0"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:7d9b9aaaa745","head":"578f3ec476b0"},{"path":"site-astro/src/styles/how.css","hash":"sha256:271af95a654d","head":"578f3ec476b0"}]}
 {"title":"how a new site-astro page acquires nav, footer and SVG defs","identityAliases":["docs sidebar component pattern"],"summary":"Nav.astro, Footer.astro and SvgDefs.astro carry no styling or defs of their own — the chrome CSS lives entirely in whichever page-level stylesheet the page imports, so a new page must import landing.css or docs.css for the nav/footer to look right EVEN IF it ships its own stylesheet, and must render <SvgDefs /> or every url(#rough)/url(#glow) reference in its own markup silently resolves to nothing. Confirmed again this session building 3 new docs sub-pages (/docs/navigation/, /docs/notebook/, /docs/under-the-hood/): each imports docs.css + how's own DocsSidebar.astro component, no per-page chrome CSS needed.","steps":[{"path":"site-astro/src/components/DocsSidebar.astro","role":"reusable sidebar (active prop), only new component this session — the one exception to 'components carry no styling': it ships a small scoped <style> block of its own on top of docs.css's .side rules"},{"path":"site-astro/src/pages/docs/navigation.astro","role":"new docs sub-page: imports docs.css for chrome, DocsSidebar for nav, Nav/Footer/SvgDefs same as any page"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","role":"new docs sub-page, same pattern"},{"path":"site-astro/src/components/Nav.astro","role":"markup only; variant prop picks active link"},{"path":"site-astro/src/styles/docs.css","role":"carries the nav/footer chrome CSS and dark tokens for every non-home page"}],"invariants":["Nav/Footer/SvgDefs are unstyled markup — appearance comes entirely from the page's stylesheet","url(#rough) on a page that does not render <SvgDefs /> fails silently","DocsSidebar.astro is the one component so far that DOES ship its own scoped <style> — see its own note for why (a docs.css global rule it must locally override)"],"verified":["site-astro/src/components/DocsSidebar.astro","site-astro/src/pages/docs/navigation.astro","site-astro/src/pages/docs/under-the-hood.astro","site-astro/src/components/Nav.astro","site-astro/src/styles/docs.css","site-astro/src/styles/how.css","site-astro/src/pages/how-it-works/notebook.astro"],"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","op":"put","v":1,"ts":"2026-08-10T18:51:51.928Z","head":"fdcb648611d7","anchors":[{"path":"site-astro/src/components/DocsSidebar.astro","hash":"sha256:8044650fa72f","head":"fdcb648611d7"},{"path":"site-astro/src/pages/docs/navigation.astro","hash":"sha256:d43204e50261","head":"fdcb648611d7"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","hash":"sha256:a7ffe7021ad0","head":"fdcb648611d7"},{"path":"site-astro/src/components/Nav.astro","hash":"sha256:7412a1f7527d","head":"fdcb648611d7"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:cabd593fda98","head":"fdcb648611d7"},{"path":"site-astro/src/styles/how.css","hash":"sha256:518ebee8e16f","head":"fdcb648611d7"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","head":"fdcb648611d7"}]}
 {"title":"how a new site-astro page acquires nav, footer and SVG defs","identityAliases":["new site-astro page","page chrome wiring","nav footer styling","SvgDefs filter defs","docs sidebar component pattern"],"summary":"Nav.astro, Footer.astro and SvgDefs.astro carry no styling or defs of their own — the chrome CSS lives entirely in whichever page-level stylesheet the page imports, so a new page must import landing.css or docs.css for the nav/footer to look right EVEN IF it ships its own stylesheet, and must render <SvgDefs /> or every url(#rough)/url(#glow) reference in its own markup silently resolves to nothing. Confirmed again this session building 3 new landing.css pages (/demo/, /live/, /notebook/'s Astro wrapper): each just imports landing.css and renders Nav/Footer/SvgDefs, no page-specific chrome CSS needed beyond a page-scoped <style> for its own unique sections.","steps":[{"path":"site-astro/src/components/Nav.astro","symbols":["Props","nav-drop","nav-drop-menu"],"role":"markup only; variant prop and demoActive pick which link/dropdown item gets 'active'"},{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines"],"role":"markup only; variant keys into a taglines map"},{"path":"site-astro/src/pages/demo/index.astro","role":"new page this session — landing.css + Nav/Footer/SvgDefs, no new chrome CSS"},{"path":"site-astro/src/pages/live/index.astro","role":"new page this session — same pattern"}],"invariants":["Nav/Footer/SvgDefs are unstyled markup — their appearance comes entirely from the page's stylesheet, never from the component","url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter","Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined (both were widened together this session for the new 'live' variant)","Nav's dropdown submenu is markup+classes only too — its active-state styling lives in the page stylesheet's '.nav-drop-menu a.active' rule, and the SITE-WIDE '.nav-links a.active::after' underline rule must be scoped with a direct-child combinator ('.nav-links>a.active') or it leaks onto nested dropdown items, drawing an unwanted full-width underline under whichever submenu item happens to be active"],"verified":["site-astro/src/components/Nav.astro","site-astro/src/components/Footer.astro","site-astro/src/pages/demo/index.astro","site-astro/src/pages/live/index.astro","site-astro/src/pages/index.astro"],"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","op":"put","v":1,"ts":"2026-08-26T19:35:23.950Z","head":"b0e998cf87a1","anchors":[{"path":"site-astro/src/components/Nav.astro","hash":"sha256:47409c440654","head":"b0e998cf87a1"},{"path":"site-astro/src/components/Footer.astro","hash":"sha256:f67267f5bf38","head":"b0e998cf87a1"},{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:4b92d0cdd5ac","head":"b0e998cf87a1"},{"path":"site-astro/src/pages/live/index.astro","hash":"sha256:0f3c6cc49e9d","head":"b0e998cf87a1"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:46674c8a42cf","head":"b0e998cf87a1"}]}
+{"title":"how a new site-astro page acquires nav, footer and SVG defs","identityAliases":["new site-astro page","page chrome wiring","nav footer styling","SvgDefs filter defs","docs sidebar component pattern","backdrop import requirement"],"incidentAliases":["page has no background field","page text unreadable grey","missing backdrop import"],"summary":"A new page needs THREE imports, not one, and each fails silently on its own: its page-level stylesheet (landing.css or docs.css) because Nav.astro/Footer.astro/SvgDefs.astro carry no styling of their own; <SvgDefs /> in the markup or every url(#rough)/url(#glow) reference silently resolves to nothing; and styles/backdrop.css, which is NO LONGER OPTIONAL. backdrop.css used to be just the background field, so forgetting it only cost a gradient. It now also defines the text ramp (--text/--muted/--faint, plus --ink and --prose aliases), so a page that omits it gets no field AND falls back to whatever greys its stylesheet still happens to define. That is not hypothetical: pages/live/index.astro shipped without the backdrop import and was the one page on the site with no field at all until it was fixed this session. backdrop.css must also be imported LAST, after landing.css/docs.css, because its :root is what overrides theirs.","steps":[{"path":"site-astro/src/styles/backdrop.css","symbols":[":root","body::before"],"role":"REQUIRED third import - the background field and the text ramp; must come last so its :root wins"},{"path":"site-astro/src/pages/demo/index.astro","symbols":["readOut"],"role":"a correct example: tailwind + landing.css + backdrop.css, then Nav/Footer/SvgDefs"},{"path":"site-astro/src/pages/live/index.astro","role":"the counter-example - shipped without the backdrop import and silently had no field; fixed this session"},{"path":"site-astro/src/components/Nav.astro","symbols":["Props","nav-drop","nav-drop-menu"],"role":"markup only; variant prop picks which link is active"},{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines"],"role":"markup only; variant keys into a taglines map"}],"invariants":["Three imports, all silent on failure: page stylesheet, <SvgDefs />, and backdrop.css. Nothing errors when one is missing.","backdrop.css must be imported AFTER landing.css/docs.css - same :root specificity, so source order decides, and it is the one meant to win.","Nav/Footer/SvgDefs are unstyled markup - their appearance comes entirely from the page's stylesheet, never from the component.","url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter.","Nav and Footer each declare their own variant union and Footer keys a taglines map off it - adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined.","DocsSidebar.astro is the one component that ships its own scoped <style> - see its own note for why.","The site-wide '.nav-links a.active::after' underline rule must be scoped with a direct-child combinator ('.nav-links>a.active') or it leaks onto nested dropdown items."],"verified":["site-astro/src/pages/demo/index.astro","site-astro/src/pages/live/index.astro","site-astro/src/styles/backdrop.css"],"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","op":"put","v":1,"ts":"2026-09-06T17:35:49.658Z","head":"08da3b4bf2b2","anchors":[{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:1e4be26bcb26","head":"08da3b4bf2b2"},{"path":"site-astro/src/pages/live/index.astro","hash":"sha256:47f92ca46b8a","head":"08da3b4bf2b2"},{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:35ff4c406dd2","head":"08da3b4bf2b2"}]}
+{"title":"how a new site-astro page acquires nav, footer and SVG defs","identityAliases":["new page imports","page shell requirements","backdrop import required","footer styles missing"],"incidentAliases":["footer unstyled new page","columns pinned sticky","footer looks boxed"],"summary":"A new page needs THREE imports, not one, and every one of them fails silently: its page stylesheet (landing.css or docs.css), <SvgDefs /> for the brand mark, and backdrop.css LAST. backdrop.css is now load-bearing for three separate things, not one - the background field, the text ramp (:root --text/--muted/--faint, which must win over landing.css and docs.css, hence last), and as of this session the FOOTER, which it pulls in via `@import \"./footer.css\"` at the top of the file. Forgetting backdrop.css used to cost a gradient; it now costs the text colours and the entire footer chrome. /live/ shipped without it once, so this is an observed failure, not a hypothetical.","steps":[{"path":"site-astro/src/styles/backdrop.css","role":"REQUIRED third import, LAST; carries the field, the text ramp, and @import of footer.css"},{"path":"site-astro/src/styles/footer.css","role":"the footer's only rule set; reached only through backdrop.css's @import, never imported by a page directly"},{"path":"site-astro/src/components/Footer.astro","role":"markup only; renders nothing visible without footer.css reaching the page"},{"path":"site-astro/src/pages/live/index.astro","role":"the page that actually shipped without backdrop.css - the observed failure"}],"invariants":["backdrop.css must be imported LAST so its :root beats landing.css/docs.css/how.css","footer.css is reached ONLY through backdrop.css's @import - never add a per-page footer import, that reintroduces a third thing a new page can forget","the set of pages rendering <Footer /> and the set importing backdrop.css must stay identical; they matched exactly when this was verified"],"verified":["site-astro/src/styles/backdrop.css","site-astro/src/styles/footer.css","site-astro/src/components/Footer.astro","site-astro/src/pages/live/index.astro"],"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","op":"put","v":1,"ts":"2026-09-06T18:10:21.468Z","head":"dae09634b870","anchors":[{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:b9f948c1c097","head":"dae09634b870"},{"path":"site-astro/src/styles/footer.css","hash":"sha256:bc7a8c91cca4","head":"dae09634b870"},{"path":"site-astro/src/components/Footer.astro","hash":"sha256:02683b945836","head":"dae09634b870"},{"path":"site-astro/src/pages/live/index.astro","hash":"sha256:7093e765b5be","head":"dae09634b870"}]}
diff --git a/.coldstart/notebook/.raw/how-a-standalone-generated-viewer-page-gets-a-back-link-when.jsonl b/.coldstart/notebook/.raw/how-a-standalone-generated-viewer-page-gets-a-back-link-when.jsonl
index ece4899..831c566 100644
--- a/.coldstart/notebook/.raw/how-a-standalone-generated-viewer-page-gets-a-back-link-when.jsonl
+++ b/.coldstart/notebook/.raw/how-a-standalone-generated-viewer-page-gets-a-back-link-when.jsonl
@@ -1,2 +1,3 @@
 {"title":"how a standalone generated viewer page gets a back-link when embedded on the website","identityAliases":["home link placeholder","generated viewer back link","HOME_LINK substitution"],"summary":"coldstart graph and coldstart kb view each produce a single self-contained HTML file from a template carrying a <!--__HOME_LINK__--> placeholder; the CLI's own render call (renderGraphHtml / renderViewHtml) unconditionally clears that placeholder to '' because the standalone local file has nowhere to link back to, so the website build scripts (the only callers that want the link) must substitute the real <a id=\"home\"> anchor into the raw template BEFORE calling render — filling it in after render is a silent no-op.","incidentAliases":["notebook page no back link","graph page missing home link"],"steps":[{"path":"src/graph/view-template.ts","symbols":["GRAPH_TEMPLATE"],"role":"defines the placeholder + #home CSS, original pattern"},{"path":"src/graph/view.ts","symbols":["renderGraphHtml"],"role":"clears the placeholder to '' unconditionally"},{"path":"scripts/graph-viewer/build-site-page.mjs","role":"substitutes the real home link into the template before calling renderGraphHtml"},{"path":"src/kb/view-template.ts","symbols":["VIEW_TEMPLATE"],"role":"gained the same placeholder + #home CSS this session, mirroring the graph template"},{"path":"src/kb/view.ts","symbols":["renderViewHtml"],"role":"now also clears the placeholder for the standalone CLI case"},{"path":"scripts/kb-viewer/build-site-page.mjs","role":"new generator script — substitutes the real home link before calling renderViewHtml"}],"invariants":["the placeholder must be filled on the TEMPLATE string before calling render() — render always clears it, so filling it in after is a no-op that silently ships a link-less page","both viewers use the identical anchor markup/id (#home) and CSS convention — a future third generated viewer should follow the same order"],"verified":["src/graph/view-template.ts","src/graph/view.ts","scripts/graph-viewer/build-site-page.mjs","src/kb/view-template.ts","src/kb/view.ts","scripts/kb-viewer/build-site-page.mjs"],"id":"how-a-standalone-generated-viewer-page-gets-a-back-link-when","type":"flow","op":"put","v":1,"ts":"2026-08-26T19:35:23.899Z","head":"b0e998cf87a1","anchors":[{"path":"src/graph/view-template.ts","hash":"sha256:1fce631954d2","head":"b0e998cf87a1"},{"path":"src/graph/view.ts","hash":"sha256:fc7d4eca1c94","head":"b0e998cf87a1"},{"path":"scripts/graph-viewer/build-site-page.mjs","hash":"sha256:06a14e3a2f4e","head":"b0e998cf87a1"},{"path":"src/kb/view-template.ts","hash":"sha256:b360b09a08c9","head":"b0e998cf87a1"},{"path":"src/kb/view.ts","hash":"sha256:dfe46b1ff385","head":"b0e998cf87a1"},{"path":"scripts/kb-viewer/build-site-page.mjs","hash":"sha256:666bcaa58b10","head":"b0e998cf87a1"}]}
 {"title":"how a standalone generated viewer page gets a back-link when embedded on the website","identityAliases":["home link placeholder","generated viewer back link","HOME_LINK substitution"],"incidentAliases":["notebook page no back link","graph page missing home link"],"summary":"coldstart graph and coldstart kb view each produce a single self-contained HTML file from a template carrying a <!--__HOME_LINK__--> placeholder; the CLI's own render call (renderGraphHtml / renderViewHtml) unconditionally clears that placeholder to '' because the standalone local file has nowhere to link back to, so the website build scripts (the only callers that want the link) must substitute the real <a id=\"home\"> anchor into the raw template BEFORE calling render — filling it in after render is a silent no-op.","steps":[{"path":"src/graph/view-template.ts","symbols":["GRAPH_TEMPLATE"],"role":"defines the placeholder + #home CSS, original pattern"},{"path":"src/graph/view.ts","symbols":["renderGraphHtml"],"role":"clears the placeholder to '' unconditionally"},{"path":"scripts/graph-viewer/build-site-page.mjs","role":"substitutes the real home link into the template before calling renderGraphHtml; only its rationale COMMENT changed this session (notebook-privacy wording corrected), the substitution logic itself is untouched"},{"path":"src/kb/view-template.ts","symbols":["VIEW_TEMPLATE"],"role":"carries the same placeholder + #home CSS, mirroring the graph template"},{"path":"src/kb/view.ts","symbols":["renderViewHtml"],"role":"also clears the placeholder for the standalone CLI case"},{"path":"scripts/kb-viewer/build-site-page.mjs","role":"substitutes the real home link before calling renderViewHtml"}],"invariants":["the placeholder must be filled on the TEMPLATE string before calling render() — render always clears it, so filling it in after is a no-op that silently ships a link-less page","both viewers use the identical anchor markup/id (#home) and CSS convention — a future third generated viewer should follow the same order"],"verified":["scripts/graph-viewer/build-site-page.mjs","scripts/kb-viewer/build-site-page.mjs"],"anchors":[{"path":"src/graph/view-template.ts","hash":"sha256:1fce631954d2","head":"b0e998cf87a1"},{"path":"src/graph/view.ts","hash":"sha256:fc7d4eca1c94","head":"b0e998cf87a1"},{"path":"src/kb/view-template.ts","hash":"sha256:b360b09a08c9","head":"b0e998cf87a1"},{"path":"src/kb/view.ts","hash":"sha256:dfe46b1ff385","head":"b0e998cf87a1"},{"path":"scripts/graph-viewer/build-site-page.mjs","hash":"sha256:ca2509b50b93","head":"d50efe68cdc6"},{"path":"scripts/kb-viewer/build-site-page.mjs","hash":"sha256:666bcaa58b10","head":"d50efe68cdc6"}],"id":"how-a-standalone-generated-viewer-page-gets-a-back-link-when","type":"flow","op":"put","v":1,"ts":"2026-08-26T19:53:19.320Z","head":"d50efe68cdc6"}
+{"title":"how a standalone generated viewer page gets a back-link when embedded on the website","identityAliases":["home link placeholder","generated viewer back link","HOME_LINK substitution"],"incidentAliases":["notebook page no back link","graph page missing home link"],"summary":"coldstart graph and coldstart kb view each produce a single self-contained HTML file from a template carrying a <!--__HOME_LINK__--> placeholder; the CLI's own render call (renderGraphHtml / renderViewHtml) unconditionally clears that placeholder to '' because the standalone local file has nowhere to link back to, so the website build scripts (the only callers that want the link) must substitute the real <a id=\"home\"> anchor into the raw template BEFORE calling render - filling it in after render is a silent no-op. Note that src/kb/view-template.ts is hand-edited source, not generated output, despite what its header used to say: styling the #home anchor means editing that string directly and re-running build-site-page.mjs.","steps":[{"path":"src/graph/view-template.ts","symbols":["GRAPH_TEMPLATE"],"role":"defines the placeholder + #home CSS, original pattern"},{"path":"src/graph/view.ts","symbols":["renderGraphHtml"],"role":"clears the placeholder to '' unconditionally"},{"path":"scripts/graph-viewer/build-site-page.mjs","role":"substitutes the real home link into the template before calling renderGraphHtml"},{"path":"src/kb/view-template.ts","symbols":["VIEW_TEMPLATE"],"role":"carries the same placeholder + #home CSS; hand-edited source, no generator"},{"path":"src/kb/view.ts","symbols":["renderViewHtml"],"role":"also clears the placeholder for the standalone CLI case"},{"path":"scripts/kb-viewer/build-site-page.mjs","role":"substitutes the real home link before calling renderViewHtml"}],"invariants":["the placeholder must be filled on the TEMPLATE string before calling render() - render always clears it, so filling it in after is a no-op that silently ships a link-less page","both viewers use the identical anchor markup/id (#home) and CSS convention - a future third generated viewer should follow the same order","src/kb/view-template.ts has no generator; scripts/kb-viewer/ contains only build-site-page.mjs"],"verified":["src/kb/view-template.ts"],"id":"how-a-standalone-generated-viewer-page-gets-a-back-link-when","type":"flow","op":"put","v":1,"ts":"2026-09-06T18:10:21.531Z","head":"dae09634b870","anchors":[{"path":"src/kb/view-template.ts","hash":"sha256:293ab177fb81","head":"dae09634b870"}]}
diff --git a/.coldstart/notebook/.raw/site-astro-has-two-independent-stylesheets-that-must-be-hand.jsonl b/.coldstart/notebook/.raw/site-astro-has-two-independent-stylesheets-that-must-be-hand.jsonl
index dda7028..a0f789e 100644
--- a/.coldstart/notebook/.raw/site-astro-has-two-independent-stylesheets-that-must-be-hand.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-has-two-independent-stylesheets-that-must-be-hand.jsonl
@@ -4,3 +4,6 @@
 {"title":"site-astro has two independent stylesheets that must be hand-kept in sync","summary":"site-astro has no shared global stylesheet or CSS custom-property source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css instead — the two define the same-named tokens (--display/--sans/--mono/--frost/--ember/etc) independently, so a redesign applied to one leaves the other silently stale. A third stylesheet, how.css, was added for the how-it-works pages and deliberately does NOT follow that pattern: it defines no tokens of its own and is imported alongside docs.css, riding its tokens and chrome, with every rule scoped under body.how-page so it cannot leak into docs or blog which share that same docs.css. Prefer the how.css ride-on pattern for any new page family — it is the only one of the three that cannot drift.","identityAliases":["how.css ride-on pattern","third stylesheet"],"incidentAliases":["docs page looks different from home","font mismatch across pages","token drift between stylesheets"],"steps":[{"path":"site-astro/src/pages/index.astro","role":"imports landing.css; the only page on that stylesheet"},{"path":"site-astro/src/styles/landing.css","role":"home page token source (tokens, nav/hero/notebook styling)"},{"path":"site-astro/src/styles/docs.css","role":"docs+blog stylesheet; redefines the same token names independently, no @import from landing.css"},{"path":"site-astro/src/pages/docs.astro","role":"imports docs.css plus its own Google Fonts <link> block"},{"path":"site-astro/src/styles/how.css","role":"the third pattern: zero tokens of its own, imported after docs.css, all rules scoped under body.how-page"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","role":"imports docs.css AND how.css together — the ride-on pattern in use"}],"invariants":["Nav.astro and Footer.astro are styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component","landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void; a palette change in one needs the matching edit by hand or the dark palette diverges silently","how.css declares no token of its own and must stay that way — its only local definitions are --paper/--paper-ink/--paper-line/--faint/--ember-dim under body.how-page, which docs.css does not define","anything added to how.css must stay scoped under .how-page or it leaks into docs and blog, which load the same docs.css"],"verified":["site-astro/src/styles/how.css","site-astro/src/styles/landing.css","site-astro/src/styles/docs.css","site-astro/src/pages/index.astro","site-astro/src/pages/docs.astro","site-astro/src/pages/how-it-works/notebook.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-08-09T10:05:32.751Z","head":"578f3ec476b0","anchors":[{"path":"site-astro/src/styles/how.css","hash":"sha256:271af95a654d","head":"578f3ec476b0"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:26649633ac9c","head":"578f3ec476b0"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:7d9b9aaaa745","head":"578f3ec476b0"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:8d22655929c5","head":"578f3ec476b0"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:bc28f6dfe03e","head":"578f3ec476b0"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:1a01e0dc7278","head":"578f3ec476b0"}]}
 {"title":"site-astro has two independent stylesheets that must be hand-kept in sync","summary":"site-astro has no shared global stylesheet or CSS custom-property source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css instead — the two define the same-named tokens (--display/--sans/--mono/--frost/--ember/etc) independently, so a redesign applied to one leaves the other silently stale. A third stylesheet, how.css, was added for the how-it-works pages and deliberately does NOT follow that pattern: it defines no tokens of its own and is imported alongside docs.css, riding its tokens and chrome, with every rule scoped under body.how-page so it cannot leak into docs or blog which share that same docs.css. What makes the ride-on possible is that docs.css declares its palette on a bare :root with no body-class qualifier — so any page can pick its own body class and still inherit the full dark token set (body.essay-page re-scopes to a LIGHT palette; that is the one body class that changes the theme). Prefer the how.css ride-on pattern for any new page family — it is the only one of the three that cannot drift.","identityAliases":["how.css ride-on pattern","third stylesheet","unscoped root tokens"],"incidentAliases":["docs page looks different from home","token drift between stylesheets","new page wrong theme"],"steps":[{"path":"site-astro/src/pages/index.astro","role":"imports landing.css; the only page on that stylesheet"},{"path":"site-astro/src/styles/landing.css","role":"home page token source (tokens, nav/hero/notebook styling)"},{"path":"site-astro/src/styles/docs.css","symbols":[":root","body.essay-page"],"role":"docs+blog stylesheet; redefines the same token names independently on a bare :root, and carries the nav/footer chrome for every non-home page"},{"path":"site-astro/src/pages/docs.astro","role":"imports docs.css plus its own Google Fonts <link> block"},{"path":"site-astro/src/styles/how.css","role":"the third pattern: zero tokens of its own, imported after docs.css, all rules scoped under body.how-page"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","role":"imports docs.css AND how.css together — the ride-on pattern in use"}],"invariants":["Nav.astro and Footer.astro are styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component","landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void; a palette change in one needs the matching edit by hand or the dark palette diverges silently","docs.css's palette sits on a bare :root — a new page family gets the dark theme by importing it under ANY body class; only body.essay-page re-scopes to light","how.css declares no token of its own and must stay that way — its only local definitions are --paper/--paper-ink/--paper-line/--faint/--ember-dim under body.how-page, which docs.css does not define","anything added to how.css must stay scoped under .how-page or it leaks into docs and blog, which load the same docs.css"],"verified":["site-astro/src/styles/how.css","site-astro/src/styles/landing.css","site-astro/src/styles/docs.css","site-astro/src/pages/index.astro","site-astro/src/pages/docs.astro","site-astro/src/pages/how-it-works/notebook.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-08-09T10:15:57.394Z","head":"7bb5ae6d6b3b","anchors":[{"path":"site-astro/src/styles/how.css","hash":"sha256:ac2e9c3bd01b","head":"7bb5ae6d6b3b"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:bd70ef86ae7d","head":"7bb5ae6d6b3b"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:7d9b9aaaa745","head":"7bb5ae6d6b3b"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:b3266cef71ea","head":"7bb5ae6d6b3b"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:bc28f6dfe03e","head":"7bb5ae6d6b3b"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:1a01e0dc7278","head":"7bb5ae6d6b3b"}]}
 {"title":"site-astro has two independent stylesheets that must be hand-kept in sync","identityAliases":["nav layout dimension drift"],"summary":"site-astro has no shared global stylesheet or CSS custom-property source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css instead — the two define the same-named tokens (--display/--sans/--mono/--frost/--ember/etc) AND the same nav layout rules (height, gap, z-index, mobile-menu offsets) independently, so a change to one leaves the other silently stale. A third stylesheet, how.css, rides docs.css's tokens/chrome instead of duplicating them and is the pattern to prefer for new page families.","incidentAliases":["header resizes between pages","nav height changes on navigation","header jumps switching pages"],"steps":[{"path":"site-astro/src/pages/index.astro","role":"imports landing.css; the only page on that stylesheet"},{"path":"site-astro/src/styles/landing.css","role":"home page token + nav-layout source (height:64px, gap:28px, z-index:50)"},{"path":"site-astro/src/styles/docs.css","symbols":[":root","nav",".nav-in",".side"],"role":"docs+blog stylesheet; redefines the same tokens AND nav dimensions independently"},{"path":"site-astro/src/pages/docs.astro","role":"imports docs.css plus its own Google Fonts <link> block"},{"path":"site-astro/src/styles/how.css","role":"the third pattern: zero tokens/nav rules of its own, rides docs.css"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","role":"imports docs.css AND how.css together — the ride-on pattern in use"}],"invariants":["landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — a palette change in one needs the matching edit by hand or the dark palette diverges silently","landing.css and docs.css ALSO independently duplicate nav layout dimensions (nav-in height/gap, z-index, .nav-mobile top offset, .side sticky top) — verified this session: docs.css's nav had drifted to 60px height/20px gap/z-index 30 while landing.css was 64px/28px/50, so the header visibly resized crossing from home to /docs/. Fixed by making docs.css's nav block byte-identical to landing.css's again (including .side's sticky top/max-height, which must track the nav height too)","how.css declares no token or nav rule of its own and must stay that way","docs.css's palette and nav rules sit on bare selectors (:root, nav) with no body-class qualifier — a new page family gets them just by importing docs.css"],"verified":["site-astro/src/pages/index.astro","site-astro/src/styles/landing.css","site-astro/src/styles/docs.css","site-astro/src/pages/docs.astro","site-astro/src/styles/how.css","site-astro/src/pages/how-it-works/notebook.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-08-10T18:51:51.882Z","head":"fdcb648611d7","anchors":[{"path":"site-astro/src/pages/index.astro","hash":"sha256:84935811908d","head":"fdcb648611d7"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:2d67c90c7632","head":"fdcb648611d7"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:cabd593fda98","head":"fdcb648611d7"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:d404bd2d8258","head":"fdcb648611d7"},{"path":"site-astro/src/styles/how.css","hash":"sha256:518ebee8e16f","head":"fdcb648611d7"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","head":"fdcb648611d7"}]}
+{"title":"site-astro has two independent stylesheets that must be hand-kept in sync","identityAliases":["backdrop.css shared visual","page-wide background definition"],"incidentAliases":["background changed on one page only","gradient missing on docs","dot grid still showing"],"summary":"site-astro has no shared token source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css, and the two define the same-named tokens (--display/--sans/--mono/--frost/--ember) AND the same nav layout rules independently, so a change to one leaves the other silently stale. There is ONE exception, and it is the pattern to copy for anything page-wide: styles/backdrop.css defines the body::before background field alone and is imported by EVERY page shell alongside whichever of landing.css/docs.css it uses — so editing backdrop.css changes the background of home, docs and blog in one edit, and a page that forgets to import it silently has no field at all. how.css is a third pattern again: zero tokens or nav rules of its own, riding docs.css, and the one to prefer for a new page family.","steps":[{"path":"site-astro/src/styles/backdrop.css","symbols":["body::before"],"role":"the ONE shared page-wide visual — sole definition of the background field, imported by every page shell"},{"path":"site-astro/src/pages/index.astro","symbols":["softwareAppJsonLd"],"role":"imports landing.css AND backdrop.css; the only page on landing.css"},{"path":"site-astro/src/styles/landing.css","symbols":[":root",".two",".hero"],"role":"home token + nav-layout source; must NOT set its own body/section backgrounds or it fights the shared field"},{"path":"site-astro/src/styles/docs.css","symbols":[":root","nav"],"role":"docs+blog stylesheet; redefines the same tokens and nav dimensions independently"},{"path":"site-astro/src/pages/docs.astro","symbols":["Head"],"role":"imports docs.css plus backdrop.css — gets the shared field for free"}],"invariants":["backdrop.css is the ONLY place a page-wide background may be defined. A per-section or per-page background (a section on --ink-1, a .hero::before glow) paints over the shared field and re-bands the page — that is what it replaced.","landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently","Nav.astro and Footer.astro are shared components styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component itself"],"verified":["site-astro/src/styles/backdrop.css","site-astro/src/styles/landing.css","site-astro/src/pages/index.astro","site-astro/src/pages/docs.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-09-04T08:42:59.462Z","head":"43401f352e9d","anchors":[{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:477469b7a917","head":"43401f352e9d"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:f6af78c47f49","head":"43401f352e9d"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:bbc5f364e028","head":"43401f352e9d"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:caefad6f6d47","head":"43401f352e9d"}]}
+{"title":"site-astro has two independent stylesheets that must be hand-kept in sync","identityAliases":["backdrop.css shared visual","page-wide background definition"],"incidentAliases":["background changed on one page only","gradient missing on docs","dot grid still showing","traffic light dots removed from one stylesheet only"],"summary":"site-astro has no shared token source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css, and the two define the same-named tokens (--display/--sans/--mono/--frost/--ember) AND the same nav layout rules independently, so a change to one leaves the other silently stale. Removing the .tl traffic-light dots sitewide is the worked example: the rules existed in BOTH stylesheets and both had to be deleted by hand. There is ONE exception, and it is the pattern to copy for anything page-wide: styles/backdrop.css defines the body::before background field alone and is imported by EVERY page shell alongside whichever of landing.css/docs.css it uses - so editing backdrop.css changes the background of home, docs, blog and demo in one edit, and a page that forgets to import it silently has no field at all. how.css is a third pattern again: zero tokens or nav rules of its own, riding docs.css, and the one to prefer for a new page family.","steps":[{"path":"site-astro/src/styles/backdrop.css","symbols":["body::before"],"role":"the ONE shared page-wide visual - sole definition of the background field, imported by every page shell"},{"path":"site-astro/src/pages/index.astro","symbols":["softwareAppJsonLd"],"role":"imports landing.css AND backdrop.css"},{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".navsec"],"role":"home token + nav-layout source; must NOT set its own body/section backgrounds or it fights the shared field"},{"path":"site-astro/src/styles/docs.css","symbols":[":root","nav"],"role":"docs+blog stylesheet; redefines the same tokens and nav dimensions independently"},{"path":"site-astro/src/pages/docs.astro","symbols":["Head"],"role":"imports docs.css plus backdrop.css - gets the shared field for free"}],"invariants":["backdrop.css is the ONLY place a page-wide background may be defined. A per-section or per-page background (a section on --ink-1, a .hero::before glow) paints over the shared field and re-bands the page - that is what it replaced, and DESIGN.md 5 now names the field as the site's one signature device.","landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void - if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently","A shared component's chrome rules live in BOTH stylesheets, so deleting one (as with the .tl dots) means deleting it twice","Nav.astro and Footer.astro are shared components styled purely through CSS custom properties - changing their look for one page family means editing that family's stylesheet, never the component itself"],"verified":["site-astro/src/styles/backdrop.css","site-astro/src/styles/landing.css","site-astro/src/styles/docs.css","site-astro/src/pages/index.astro","site-astro/src/pages/docs.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-09-04T09:19:31.365Z","head":"54deea7bca84","anchors":[{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:477469b7a917","head":"54deea7bca84"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:61c7ab27ec9a","head":"54deea7bca84"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:82f376249103","head":"54deea7bca84"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:5b1f210cd987","head":"54deea7bca84"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:131c8ebc9124","head":"54deea7bca84"}]}
+{"title":"site-astro has two independent stylesheets that must be hand-kept in sync","identityAliases":["backdrop.css shared visual","page-wide background definition","stylesheet token drift","shared text ramp"],"incidentAliases":["grey text hard to read","low contrast body copy","token fixed on one page only","navbar narrower than body"],"summary":"site-astro has three page-level stylesheets that redefine the same things independently, and what is shared versus duplicated has MOVED: the text ramp is now centralised, everything else still is not. landing.css (home) and docs.css (docs, blog, and the base how.css rides on) each still define --frost/--ember/--line/--void and the whole nav and footer layout independently, so a change to one leaves the other silently stale. But --text/--muted/--faint/--ink/--prose are now defined ONLY in styles/backdrop.css, which every page shell imports last. That move was forced by a real drift: body.essay-page had been repaired to a readable --prose with a comment reading 'was #8b9ab2 at 6.9:1', so the blog got fixed while docs and the landing page kept a grey that measured 4.30:1 - below the AA floor - once the background field changed what text sat on. The same class of drift is still live for the container width: .docs was 1200px/24px while .nav-in and .wrap are 1120px/28px, which put the docs content edge 44px left of the nav's until it was fixed this session. backdrop.css is the pattern to copy for anything that must not drift; how.css is the other good pattern - zero tokens of its own, riding docs.css.","steps":[{"path":"site-astro/src/styles/backdrop.css","symbols":[":root","body::before"],"role":"the ONE shared definition - background field AND text ramp; imported last by every shell so its :root wins"},{"path":"site-astro/src/styles/landing.css","symbols":[":root",".wrap",".hero"],"role":"home tokens and nav layout; no longer defines the text ramp, still owns --frost/--ember/--line and its own nav rules"},{"path":"site-astro/src/styles/docs.css","symbols":[":root",".docs","body.essay-page"],"role":"docs+blog; redefines the same accent tokens and nav dimensions independently; .docs must stay 1120/28 to match .wrap"},{"path":"site-astro/src/styles/how.css","symbols":["body.how-page"],"role":"the good pattern - scoped overrides only, no tokens or nav rules of its own"},{"path":"site-astro/src/pages/index.astro","role":"imports landing.css then backdrop.css - the required order"}],"invariants":["The text ramp (--text/--muted/--faint/--ink/--prose) is defined ONLY in backdrop.css. Redefining any of them in a page stylesheet reintroduces the drift that made the blog readable and the docs not.","backdrop.css is also the ONLY place a page-wide background may be defined. A per-section background paints over the shared field and re-bands the page.","landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void - a palette change in one needs the matching edit in the other by hand.","Every content container is 1120px with 28px padding (.wrap, .nav-in, .docs). A container with its own width misaligns against the nav.","A shared component's chrome rules live in BOTH stylesheets, so deleting one (as with the .tl traffic-light dots) means deleting it twice."],"verified":["site-astro/src/styles/backdrop.css","site-astro/src/styles/landing.css","site-astro/src/styles/docs.css","site-astro/src/styles/how.css","site-astro/src/pages/index.astro"],"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","op":"put","v":1,"ts":"2026-09-06T17:35:49.709Z","head":"08da3b4bf2b2","anchors":[{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:35ff4c406dd2","head":"08da3b4bf2b2"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:2c51f1372cf9","head":"08da3b4bf2b2"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:5c6dfd9b8f8f","head":"08da3b4bf2b2"},{"path":"site-astro/src/styles/how.css","hash":"sha256:02bdedbf0f63","head":"08da3b4bf2b2"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:73ddc5b0a45e","head":"08da3b4bf2b2"}]}
diff --git a/.coldstart/notebook/.raw/site-astro-src-components-footer-astro-98a77858.jsonl b/.coldstart/notebook/.raw/site-astro-src-components-footer-astro-98a77858.jsonl
index 7c7a5b1..08b6680 100644
--- a/.coldstart/notebook/.raw/site-astro-src-components-footer-astro-98a77858.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-components-footer-astro-98a77858.jsonl
@@ -2,3 +2,4 @@
 {"anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline"]}],"id":"site-astro-src-components-footer-astro-98a77858","type":"file","op":"put","verified":[],"v":1,"ts":"2026-08-08T16:36:06.101Z","head":"06b42a096c95"}
 {"summary":"Shared footer, markup only. The `variant` prop keys directly into a `taglines` object literal to pick the footer tagline text — so unlike Nav, widening Footer's variant union is NOT enough: a variant with no matching taglines key silently renders an undefined tagline. Both were widened together this session when the 'how' variant was added.","identityAliases":["footer variant","taglines map"],"anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline"],"hash":"sha256:d72628133dd4","head":"578f3ec476b0"}],"id":"site-astro-src-components-footer-astro-98a77858","type":"file","op":"put","verified":["site-astro/src/components/Footer.astro"],"character":"single","v":1,"ts":"2026-08-09T10:05:32.816Z","head":"578f3ec476b0"}
 {"identityAliases":["footer component","footer tagline","footer variant","taglines map"],"summary":"Shared footer, markup only. The `variant` prop ('home'|'docs'|'blog'|'how'|'live') keys directly into a `taglines` object literal to pick the footer tagline text — so unlike Nav, widening Footer's variant union is NOT enough: a variant with no matching taglines key silently renders an undefined tagline. Widened again this session for the new 'live' hub page ('see it live · MIT').","anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline"],"hash":"sha256:f67267f5bf38","head":"b0e998cf87a1"}],"id":"site-astro-src-components-footer-astro-98a77858","type":"file","op":"put","verified":["site-astro/src/components/Footer.astro"],"character":"single","v":1,"ts":"2026-08-26T19:35:24.024Z","head":"b0e998cf87a1"}
+{"summary":"Shared footer, markup and link data only - all appearance comes from styles/footer.css, which reaches the page through backdrop.css's @import rather than any import here. Rebuilt this session from a single row of five links into four labelled columns (See it work / Understand it / Reference / Project) defined as a `columns` array in frontmatter, because most of the site's pages were reachable only from the nav dropdown. The `variant` prop ('home'|'docs'|'blog'|'how'|'live') still keys directly into a `taglines` object literal, so widening the union alone is NOT enough - a variant with no matching taglines key silently renders an undefined tagline. The column link groups are plain divs, NOT <nav>: landing.css's global nav rule is unscoped and boxes and sticky-positions anything matching it.","identityAliases":["footer component","footer tagline","footer variant","taglines map","footer columns"],"incidentAliases":["footer columns boxed","undefined footer tagline"],"anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline","columns"],"hash":"sha256:02683b945836","head":"dae09634b870"}],"id":"site-astro-src-components-footer-astro-98a77858","type":"file","op":"put","verified":["site-astro/src/components/Footer.astro"],"character":"single","v":1,"ts":"2026-09-06T18:10:21.508Z","head":"dae09634b870"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-pages-demo-index-astro-2e0c6d23.jsonl b/.coldstart/notebook/.raw/site-astro-src-pages-demo-index-astro-2e0c6d23.jsonl
index 82b98cf..733823e 100644
--- a/.coldstart/notebook/.raw/site-astro-src-pages-demo-index-astro-2e0c6d23.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-pages-demo-index-astro-2e0c6d23.jsonl
@@ -1,2 +1,5 @@
 {"identityAliases":["demo page","live session demo","recall timeline","keynote callout","term live terminal"],"incidentAliases":["demo page too slow","gaps look awkward on demo page","flywheel in its own section"],"summary":"The /demo/ page: a single continuous find→gs→capture→recall narrative told against this repo's own real command output, as two timed scenes ('01 first time', cold — 2 tool calls, writes a note; '02 second time', recalled — 0 tool calls). Each scene's summary callout (`.keynote`) must live INSIDE that scene's own `<section>`, as its last child, not as a sibling `<div class=\"wrap\">` between sections — placed outside, it got both the class's own margin AND the section's padding stacked, reading as a disconnected floating block on the wrong background. The `.recall.reveal` timeline's per-item pacing is driven by cumulative `data-t` delays in `runTimeline`, but a `.term.live` element's OWN internal typing+reveal duration (typeCommand's per-char delay, the post-type pause, then each output line's own `data-t`) runs independently of that countdown — its outer `data-t` must be sized to outlast that internal animation or the next timeline item fades in before the terminal finishes typing.","anchors":[{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:4b92d0cdd5ac","head":"b0e998cf87a1"}],"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","op":"put","verified":["site-astro/src/pages/demo/index.astro"],"character":"single","v":1,"ts":"2026-08-26T19:35:23.985Z","head":"b0e998cf87a1"}
 {"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description"]}],"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","op":"put","verified":[],"v":1,"ts":"2026-08-26T19:35:24.576Z","head":"b0e998cf87a1"}
+{"summary":"The /demo/ page: two static Claude Code panel replicas showing the same repo on two different days - COLD (recall hook searches the notebook, finds nothing, agent runs coldstart find then coldstart gs, answers, Stop hook writes the note) and WARM (different session, note matches and arrives with the prompt, zero tool calls). Rebuilt in 54deea7 from a JS-animated typewriter timeline into something FULLY RENDERED ON LOAD: no typing effect, no scroll triggers, zero opacity:0 elements, works with JS off and is screenshot-able. All command output is real unedited output from this repo, elided with a `… +N lines` line. The panel keeps its own neutral #1f1f1f ground rather than the site's frost/ember field, because it is a replica and should read as the real thing sitting on the page. Annotations are centred captions BETWEEN turn groups rather than a side rail, so the panel itself carries no marketing copy while still collapsing correctly on mobile. Two mechanics here are non-obvious and were both found by rendering rather than reading: Astro COLLAPSES template newlines, so each line of terminal output must be its own <div> under white-space:pre or the whole block runs onto one wrapped line; and the output box needs its own overflow-x:auto so long lines scroll inside the box instead of overflowing the page at 390px.","identityAliases":["demo page","claude code panel replica","cold and warm session panels","static demo transcript"],"incidentAliases":["terminal output on one line","astro strips newlines","demo page horizontal overflow","demo animation removed","opacity 0 hidden content"],"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description",".cc",".cc-body",".cc-bar",".cc-in",".turn",".tool",".ob",".note",".cap",".chip",".prose",".dsec",".dhead",".dclose"],"hash":"sha256:16aafe9b8961","head":"54deea7bca84"}],"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","op":"put","verified":["site-astro/src/pages/demo/index.astro"],"character":"single","v":1,"ts":"2026-09-04T09:19:10.074Z","head":"54deea7bca84"}
+{"summary":"The /demo/ page: two static Claude Code panel replicas, fully rendered on load - no typing effect, no scroll triggers, zero opacity:0, works with JS off. The scenario is 'how does authentication work in this codebase?' on an INVENTED Node/Express API, and the page says so in a line under the hero: the repo and its output are made up, only the command shapes and output format are real. It was previously a real captured session about coldstart's own co-change internals, which only demonstrates the tool to someone who already uses it. COLD panel: no note, one `coldstart find`, one `coldstart gs`, then the answer (Redis sessions, not JWTs, despite the variable being named token). WARM panel: a note arrives with the prompt, and the agent then runs ONE Read against the file the note named before answering. That read is deliberate and must not be removed - an earlier version claimed 'Zero tool calls, no reads', which is false about how agents behave and contradicts the freshness story on the same page. The honest framing the copy now uses is 'one read instead of a search'. The panel keeps its own neutral #1f1f1f ground rather than the site's field, because it is a replica.","identityAliases":["demo page","claude code panel replica","auth demo","cold and warm session panels"],"incidentAliases":["demo not relatable","zero tool calls claim","demo page overclaims","demo animation removed"],"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description",".cc",".cc-body",".cc-bar",".cc-in",".turn",".tool",".ob",".note",".cap",".chip",".prose",".dsec",".dhead",".dclose","readOut",".tally",".disclaim"],"hash":"sha256:1e4be26bcb26","head":"e52802156249"}],"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","op":"put","verified":["site-astro/src/pages/demo/index.astro"],"character":"single","v":1,"ts":"2026-09-06T17:33:53.824Z","head":"e52802156249"}
+{"summary":"The /demo/ page: two static Claude Code panel replicas, fully rendered on load - no typing effect, no scroll triggers, zero opacity:0, works with JS off. The hero does NOT pose the scenario question; it names what the page is ('What coldstart changes, inside the session'), because the auth question is already the first line inside the cold panel and having it as the headline too made the page ask twice and read as if auth were its subject. The question, the invented Node/Express repo (acme-api) and its output all live in the panels. There is no longer a standalone .disclaim paragraph - the 'example repo' honesty it carried is one clause of the single .hero-sub line, and that clause must survive any rewrite: a terminal on a page reads as captured output unless the copy says otherwise. Page title/description and both og fields restate the hero, so a hero rewrite that skips them leaves search and link previews on the old framing. COLD panel: no note, one `coldstart find`, one `coldstart gs`, then the answer (Redis sessions, not JWTs, despite the variable being named token). WARM panel: a note arrives with the prompt, and the agent then runs ONE Read against the file the note named before answering. That read is deliberate and must not be removed - an earlier version claimed 'Zero tool calls, no reads', which is false about how agents behave and contradicts the freshness story on the same page; the honest framing is 'one read instead of a search'. The panels keep their own neutral #1f1f1f ground rather than the site's field, because they are replicas.","identityAliases":["demo page","live session demo","claude code panel replica","cold and warm session panels","static demo transcript","demo hero copy","acme-api example repo"],"incidentAliases":["question asked twice","hero poses the question","disclaim paragraph removed","demo page framing"],"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description",".cc",".cc-body",".cc-bar",".cc-in",".turn",".tool",".ob",".note",".cap",".chip",".prose",".dsec",".dhead",".dclose","readOut",".tally",".disclaim",".demo-hero",".hero-sub"],"hash":"sha256:32b9cd4a434a","head":"935c13e94156"}],"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","op":"put","verified":["site-astro/src/pages/demo/index.astro"],"character":"single","v":1,"ts":"2026-09-06T18:16:22.904Z","head":"935c13e94156"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-pages-docs-astro-d1cf6fe9.jsonl b/.coldstart/notebook/.raw/site-astro-src-pages-docs-astro-d1cf6fe9.jsonl
index 2502560..12d6276 100644
--- a/.coldstart/notebook/.raw/site-astro-src-pages-docs-astro-d1cf6fe9.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-pages-docs-astro-d1cf6fe9.jsonl
@@ -3,3 +3,4 @@
 {"target":{"kind":"alias","key":"notebook docs section"},"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","op":"retract","v":1,"ts":"2026-08-16T16:51:41.552Z","head":"5ddc264e056c"}
 {"target":{"kind":"alias","key":"docs freshness section"},"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","op":"retract","v":1,"ts":"2026-08-16T16:51:41.564Z","head":"5ddc264e056c"}
 {"summary":"Docs landing page — sidebar reference layout on docs.css, with its own TechArticle JSON-LD and its own Google Fonts <link> block (not centralised in Head.astro). Sections are #overview, #install, #flow, #next; #next's fcards link out to the 3 docs sub-pages (navigation, notebook, under-the-hood) — there is no #notebook or #freshness section on this page itself, that content lives in the sub-pages now. Inline links in docs prose are styled per-link with style=\"color:var(--frost)\" — there is no link class in docs.css. Its closing sidebar-highlight script is one of 4 duplicated copies (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","identityAliases":["docs page","structured data","brand terminology binding","docs landing page"],"anchors":[{"path":"site-astro/src/pages/docs.astro","symbols":["techArticleJsonLd","doc-sec#notebook","doc-sec#freshness","overview","install","flow","next"],"hash":"sha256:9faa0af4d67d","head":"5ddc264e056c"}],"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","op":"put","verified":["site-astro/src/pages/docs.astro"],"character":"single","v":1,"ts":"2026-08-16T16:51:41.575Z","head":"5ddc264e056c"}
+{"summary":"Docs landing page - sidebar reference layout on docs.css, with its own TechArticle JSON-LD and its own Google Fonts <link> block (not centralised in Head.astro). Sections are #overview, #install, #flow, #next; #next's fcards link out to the 3 docs sub-pages (navigation, notebook, under-the-hood) - there is no #notebook or #freshness section here, that content lives in the sub-pages. Inline prose links are NOT styled per-link any more: docs.css carries '.content p a, .doc-sec p a, .prose p a, .doc-sec li a', so do not add style=\"color:var(--frost)\" to new links. The .flags/.flag-row table is the page's one key-value device and it is easy to misuse: #install once carried two consecutive .flags blocks where the second held Upgrading/Removing/Codex-hook-trust, so the frost mono key column scanned as six flags of which three were not flags. Sub-groups inside a section now take an <h3> (styled in docs.css) so two tables can never read as one list, commands go in a .term block rather than as long inline chips, and asides go in .callout. Its closing sidebar-highlight script is one of 4 duplicated copies (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","identityAliases":["docs landing page","docs.astro","install and setup section","coldstart init docs","flags table","docs sidebar sections"],"incidentAliases":["install section cluttered","two identical flag tables","code chips wall of text","upgrading removing rows"],"anchors":[{"path":"site-astro/src/pages/docs.astro","symbols":["techArticleJsonLd","doc-sec#notebook","doc-sec#freshness","overview","install","flow","next","flags","flag-row","doc-sec","callout"],"hash":"sha256:bc20dc3f63f0","head":"e6e8bea1e30c"}],"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","op":"put","verified":["site-astro/src/pages/docs.astro"],"character":"single","v":1,"ts":"2026-09-06T18:27:40.249Z","head":"e6e8bea1e30c"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-pages-index-astro-08d662bc.jsonl b/.coldstart/notebook/.raw/site-astro-src-pages-index-astro-08d662bc.jsonl
index 52ef939..84b9c7b 100644
--- a/.coldstart/notebook/.raw/site-astro-src-pages-index-astro-08d662bc.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-pages-index-astro-08d662bc.jsonl
@@ -6,3 +6,5 @@
 {"summary":"Homepage — v4 centered hero, Newsreader/IBM Plex Sans/JetBrains Mono. Section order is hero → notebook → flow (index) → philosophy → FAQ → install. The FAQ exists to fix a real defect: FAQPage JSON-LD was declared for five Q&A pairs that appeared NOWHERE in the rendered body, which Google's structured-data policy disallows. A single `faqs` array is now the one source — the visible <details> section maps over it AND faqJsonLd.mainEntity is derived from it via .map(), so the two cannot drift. Verified by stripping every ld+json block out of dist/index.html and confirming all five questions still appear in the body. The answer strings contain backticks, so the visible render splits each answer on '`' and wraps odd segments in <code>, while the JSON-LD strips backticks with .replace(/`/g,'') to keep schema text plain prose. Title tag and all three meta/og/twitter descriptions are category-slot copy governed by the entity-binding flow. Not in the import graph — Astro routes it by file path.","identityAliases":["homepage","index page","hero section","landing page astro","faq section"],"incidentAliases":["faq schema not visible","json-ld out of sync with html","backticks rendered literally"],"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd"],"hash":"sha256:d30a2555c5e0","head":"aaddf6e72e41"}],"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","op":"put","verified":["site-astro/src/pages/index.astro"],"character":"single","v":1,"ts":"2026-08-08T16:57:29.326Z","head":"aaddf6e72e41"}
 {"summary":"Homepage — v4 centred hero. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ -> install. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD (the JSON-LD maps over it and strips backticks), so adding a question means editing that one array and nothing else — this is what keeps the two from drifting, the defect the FAQ block exists to fix (JSON-LD declaring Q&A that appeared nowhere in the body, which Google's structured-data policy disallows). Verified this session by parsing dist/index.html: every FAQPage question string is present in the rendered body. The notebook and flow sections each end with a centred .how-link into the matching /how-it-works/ page.","identityAliases":["faq json-ld source","how-it-works entry links"],"incidentAliases":["faq schema not visible","json-ld out of sync with html"],"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link"],"hash":"sha256:8d22655929c5","head":"578f3ec476b0"}],"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","op":"put","verified":["site-astro/src/pages/index.astro"],"character":"single","v":1,"ts":"2026-08-09T10:05:32.788Z","head":"578f3ec476b0"}
 {"identityAliases":["homepage","index page","hero section","faq json-ld source","how-it-works entry links"],"incidentAliases":["faq schema not visible","json-ld out of sync with html"],"summary":"Homepage — v4 centred hero. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ -> install. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD, so adding a question means editing that one array only. The nav-section CTA that used to link straight to /graph/ ('View the graph') now reads 'See it live' and points at the new /live/ hub page instead, so visitors choose between the demo/graph/notebook rather than always landing on the graph.","anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link"],"hash":"sha256:46674c8a42cf","head":"b0e998cf87a1"}],"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","op":"put","verified":["site-astro/src/pages/index.astro"],"character":"single","v":1,"ts":"2026-08-26T19:35:24.035Z","head":"b0e998cf87a1"}
+{"summary":"Homepage. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD, so adding a question means editing that one array only. The layout is now TWO-COLUMN, not the v4 centred hero: four sections (hero, notebook, navigation, FAQ) each wrap their content in a .two grid with the argument in .col-a and the artifact in .col-b — hero pairs the copy with the install terminal, notebook pairs the intro plus .nb-steps with the note-card exhibit, navigation pairs the intro with the flow SVG, FAQ pairs the heading with the list. The philosophy section is deliberately left single-column: it has no artifact. Converting to two columns MOVED the .cta block and .meta-line above the terminal in source order; the copy itself is byte-identical to the pre-two-column version.","identityAliases":["two column homepage","col-a col-b sections","hero install terminal"],"incidentAliases":["homepage centred layout","sections not uniform"],"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link","class two","class col-a","class col-b"],"hash":"sha256:bbc5f364e028","head":"43401f352e9d"}],"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","op":"put","verified":["site-astro/src/pages/index.astro"],"character":"single","v":1,"ts":"2026-09-04T08:42:59.532Z","head":"43401f352e9d"}
+{"summary":"Homepage. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD, so adding a question means editing that one array only. Layout is the ORIGINAL centred, single-column, stacked one: the .two/.col-a/.col-b two-column conversion an earlier version of this note described was reverted wholesale in 0867280 after USER rejected it and measurement contradicted it. The copy was never touched by that experiment or its revert. The only change that survives here is that the three <span class=\"tl\"> traffic-light dots were removed from the hero terminal's .term-bar, part of a sitewide removal of 39 such spans across five pages.","identityAliases":["homepage","faqs array","hero install terminal","faq json-ld source"],"incidentAliases":["two column homepage reverted","homepage layout rejected","traffic light dots removed"],"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link","class two","class col-a","class col-b","class term-bar"],"hash":"sha256:5b1f210cd987","head":"54deea7bca84"}],"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","op":"put","verified":["site-astro/src/pages/index.astro"],"character":"single","v":1,"ts":"2026-09-04T09:19:10.061Z","head":"54deea7bca84"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-pages-specimen-plate-astro-652cc265.jsonl b/.coldstart/notebook/.raw/site-astro-src-pages-specimen-plate-astro-652cc265.jsonl
new file mode 100644
index 0000000..e1ce956
--- /dev/null
+++ b/.coldstart/notebook/.raw/site-astro-src-pages-specimen-plate-astro-652cc265.jsonl
@@ -0,0 +1,2 @@
+{"summary":"A disposable design specimen, not a shipped page: noindex, linked from nowhere, and deliberately self-contained — it imports NONE of the real stylesheets so it can be approved or deleted without touching the live site. It renders DESIGN.md's 5/7 .split layout with a set of drawing devices (Fig. numbering, dimension lines with knockout labels, a title-block footer, radius 0, a drawn column rail replacing DESIGN.md §5's position:fixed seam). Two mechanics here are reusable and were both found by rendering rather than reading: Astro COLLAPSES template newlines, so a terminal transcript built as one text block under `white-space:pre` runs onto a single line — one <div> per line is required; and `font-variant-ligatures:none` is needed because JetBrains Mono ligates `--` into what reads as an en dash, which misrepresents CLI flags like --match.","identityAliases":["design specimen page","plate specimen","throwaway design sample","noindex specimen"],"incidentAliases":["terminal output on one line","white-space pre not working","astro strips newlines","double dash looks like en dash"],"anchors":[{"path":"site-astro/src/pages/specimen/plate.astro","symbols":[".two",".termbody",".dim",".block",".fig","findCmd"],"hash":"sha256:e8fc205fa705","head":"43401f352e9d"}],"id":"site-astro-src-pages-specimen-plate-astro-652cc265","type":"file","op":"put","verified":["site-astro/src/pages/specimen/plate.astro"],"character":"single","v":1,"ts":"2026-09-04T08:42:59.543Z","head":"43401f352e9d"}
+{"target":{"kind":"note"},"reason":"The file site-astro/src/pages/specimen/plate.astro was deleted in 90368a1 along with site-astro/src/pages/specimen/index.astro. Both specimens were built on DESIGN.md 4's 5/7 split layout, which was retired in the same commit after measurement showed the reference class does not use an asymmetric two-column spine. Neither specimen was ever approved. The two reusable mechanics this note recorded are preserved in the note for site-astro/src/pages/demo/index.astro, which is where they are now load-bearing: Astro collapses template newlines, so a terminal transcript under white-space:pre needs one element per line; and font-variant-ligatures:none is needed because JetBrains Mono ligates -- into what reads as an en dash.","id":"site-astro-src-pages-specimen-plate-astro-652cc265","type":"file","op":"retract","v":1,"ts":"2026-09-04T09:19:10.019Z","head":"54deea7bca84"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-styles-backdrop-css-590ddcf8.jsonl b/.coldstart/notebook/.raw/site-astro-src-styles-backdrop-css-590ddcf8.jsonl
new file mode 100644
index 0000000..d09af71
--- /dev/null
+++ b/.coldstart/notebook/.raw/site-astro-src-styles-backdrop-css-590ddcf8.jsonl
@@ -0,0 +1,2 @@
+{"summary":"The single definition of the site's page-wide background: one fixed body::before carrying a 90deg frost-to-ember ramp (frost at the left edge, ember at the right, transparent 42%-58%), rotating to 180deg below 900px. Every page shell imports it alongside landing.css or docs.css, so one edit here changes home, docs and blog together. It previously held a 30px repeating dot grid; that was replaced because a tiled background pattern is the most common generated-site tell on the web and it also competed for the same z-index -1 layer as the ramp.","identityAliases":["backdrop stylesheet","page background field","frost ember gradient","body before background","shared page visual"],"incidentAliases":["dot grid background","repeating pattern looks templated","background bands per section"],"anchors":[{"path":"site-astro/src/styles/backdrop.css","symbols":["body::before"],"hash":"sha256:477469b7a917","head":"43401f352e9d"}],"id":"site-astro-src-styles-backdrop-css-590ddcf8","type":"file","op":"put","verified":["site-astro/src/styles/backdrop.css"],"character":"single","v":1,"ts":"2026-09-04T08:42:59.509Z","head":"43401f352e9d"}
+{"summary":"The site's single source for TWO page-wide things, and it is imported LAST by every page shell so its :root wins over landing.css/docs.css/how.css. (1) The background field: one fixed body::before carrying a 90deg frost-to-ember ramp, rotating to 180deg below 900px. It replaced a 30px dot grid, because a tiled background is the most common generated-site tell. (2) The TEXT RAMP - --text #eef2f8, --muted #c3c8d0, --faint #a3a9b2, plus --ink and --prose as aliases for the names docs.css and the essay pages use. The ramp moved here because it had been hand-copied into three stylesheets and had already drifted: body.essay-page carried a repaired --prose at 12.8:1 with a comment reading 'was #8b9ab2 at 6.9:1', so the blog was fixed and docs and the landing page were left behind. The old values were measured as FAILING: against the composited ground (the field changes what text sits on, costing ~24% of the contrast ratio) --muted fell to 5.28:1 and --faint to 4.30:1, which is below the 4.5 AA floor for normal text. Both also carried an R-B spread near 40, which DESIGN.md 11 identified as the real cause of the washed-out look - a blue-grey on a blue-black ground has too little hue separation from its own background. The new values are 13.4 / 9.0 / 6.4 on the worst ground with R-B spreads of 10 / 13 / 15.","identityAliases":["backdrop stylesheet","page background field","frost ember gradient","text ramp","shared token source","contrast tokens"],"incidentAliases":["grey text hard to read","low contrast body copy","washed out text","tokens drifted between stylesheets","dot grid background","page has no background field"],"anchors":[{"path":"site-astro/src/styles/backdrop.css","symbols":["body::before",":root","--text","--muted","--faint","--ink","--prose"],"hash":"sha256:35ff4c406dd2","head":"e52802156249"}],"id":"site-astro-src-styles-backdrop-css-590ddcf8","type":"file","op":"put","verified":["site-astro/src/styles/backdrop.css"],"character":"single","v":1,"ts":"2026-09-06T17:33:53.788Z","head":"e52802156249"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-styles-docs-css-e5e1acf9.jsonl b/.coldstart/notebook/.raw/site-astro-src-styles-docs-css-e5e1acf9.jsonl
index bfdd140..e5bb31e 100644
--- a/.coldstart/notebook/.raw/site-astro-src-styles-docs-css-e5e1acf9.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-styles-docs-css-e5e1acf9.jsonl
@@ -4,3 +4,5 @@
 {"summary":"Docs+blog stylesheet, token-synced to landing.css this session: fonts switched to Newsreader/IBM Plex Sans/JetBrains Mono, nav/footer chrome hardcoded to max-width:1120px + padding:0 28px (previously used a --nav-wrap custom property that gave docs 1200px and blog 1080px via a body-class cascade-order bug — body.essay-page's rule came after body.docs-page's in the file, and blog pages carry both classes, so essay-page silently won). Brand wordmark, page h1/h2, and essay headings now use serif --display; command names/flag tables/badges stay mono on purpose (technical-reference identity, mirrors landing.css's .op card treatment). Blog index (.essay-list/.essay-card) was rebuilt from a single-column stacked list into a 3-col card grid now that there are 9 posts — the stacked-list choice was made when there were only 2-3 and a grid looked broken.","identityAliases":["docs stylesheet","blog stylesheet","nav-wrap bug","essay card grid"],"incidentAliases":["docs blog font mismatch","nav width inconsistent","brand wordmark different font"],"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page"],"hash":"sha256:d431fe304296","head":"78e40d494806"}],"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","op":"put","verified":["site-astro/src/styles/docs.css"],"character":"single","v":1,"ts":"2026-08-08T07:54:46.948Z","head":"78e40d494806"}
 {"summary":"Docs+blog stylesheet, token-synced to landing.css: Newsreader/IBM Plex Sans/JetBrains Mono, nav/footer chrome hardcoded to max-width:1120px + padding:0 28px (previously a --nav-wrap custom property gave docs 1200px and blog 1080px via a body-class cascade-order bug — body.essay-page's rule came after body.docs-page's and blog pages carry both classes, so essay-page silently won). Blog index (.essay-list/.essay-card) is a 3-col card grid. Verified this session while adding a third page family: the dark palette is declared on a BARE :root with no body-class qualifier, so any page importing this file inherits it under any body class — body.essay-page is the only class that re-scopes to a light palette. That is why this file is also the de-facto chrome stylesheet: a new page family imports it for nav/footer styling and the dark tokens, then layers its own scoped stylesheet on top, without editing this file at all. Inline links in docs prose have no class — each is styled per-link with style=color:var(--frost).","identityAliases":["docs.css bare root","chrome stylesheet","dark token source"],"incidentAliases":["new page wrong theme","nav unstyled on new page"],"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in"],"hash":"sha256:7d9b9aaaa745","head":"7bb5ae6d6b3b"}],"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","op":"put","verified":["site-astro/src/styles/docs.css"],"character":"single","v":1,"ts":"2026-08-09T10:15:57.428Z","head":"7bb5ae6d6b3b"}
 {"summary":"Docs+blog stylesheet, token-synced to landing.css: Newsreader/IBM Plex Sans/JetBrains Mono, nav chrome now byte-identical to landing.css (64px height, 28px gap, z-index 50 — was drifted to 60px/20px/30, fixed this session). The docs-page sidebar lives here (.side, .side-group, .side a.active applies a background+left-border 'pill' to ANY active <a> under .side) — DocsSidebar.astro's group-header links share that selector and must explicitly opt out or they double-box. .chip.hot (an arbitrary blue-highlight tier on the supported-languages chips) was removed this session; all .chip now render uniformly. .term-body .ln needed display:block alongside white-space:pre or sibling command lines visually merge onto one row.","identityAliases":["docs styles","blog styles","chrome stylesheet","dark token source"],"incidentAliases":["header resizes between pages","sidebar group header double boxed","language chips arbitrarily highlighted","terminal lines merged onto one row"],"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in","nav",".nav-in",".side a.active",".chip",".term-body .ln"],"hash":"sha256:cabd593fda98","head":"fdcb648611d7"}],"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","op":"put","verified":["site-astro/src/styles/docs.css"],"character":"single","v":1,"ts":"2026-08-10T18:51:51.939Z","head":"fdcb648611d7"}
+{"summary":"Stylesheet for the docs pages, the blog index and blog posts (body.essay-page), and the base that how.css rides on. It no longer defines --ink/--prose/--muted/--faint: those come from backdrop.css, which every page shell imports after this one. It still owns --bg/--surface/--frost/--ember/--line and, independently of landing.css, the same nav and footer layout rules - that duplication is deliberate but unguarded, so a nav change here needs the matching edit in landing.css by hand. The .docs container is 1120px with 28px padding, which MATTERS: it was 1200/24, which put the docs content edge at 144px against the nav's 188px, so the logo read as indented against the sidebar. 1120/28 is what .nav-in and landing.css's .wrap use, and any new container should match it rather than invent its own width.","identityAliases":["docs stylesheet","essay page styles","docs container width","blog post styles"],"incidentAliases":["navbar not as wide as body","docs page asymmetric","sidebar misaligned with logo","content edge mismatch"],"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in","nav",".nav-in",".side a.active",".chip",".term-body .ln",".docs",".term-bar"],"hash":"sha256:5c6dfd9b8f8f","head":"e52802156249"}],"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","op":"put","verified":["site-astro/src/styles/docs.css"],"character":"single","v":1,"ts":"2026-09-06T17:33:53.814Z","head":"e52802156249"}
+{"summary":"Stylesheet for the docs pages, the blog index and blog posts (body.essay-page), and the base that how.css rides on. It no longer defines --ink/--prose/--muted/--faint: those come from backdrop.css, which every page shell imports after this one. It still owns --bg/--surface/--frost/--ember/--line and, independently of landing.css, the same nav and footer layout rules - that duplication is deliberate but unguarded, so a nav change here needs the matching edit in landing.css by hand. The .docs container is 1120px with 28px padding, which MATTERS: it was 1200/24, which put the docs content edge at 144px against the nav's 188px, so the logo read as indented against the sidebar. 1120/28 is what .nav-in and landing.css's .wrap use. TYPOGRAPHIC TRAP: 'p code, li code, .prose code' gives every inline code span a bordered ember chip (background + border + radius + padding). That reads well at two or three per paragraph and turns a paragraph into a speckled field at ten - the install prose had 13 and looked cluttered for that reason alone. When docs copy needs many literals, move them into a .flags table or a .term block instead of leaving them inline; more chips is never the fix. '.doc-sec h3' is deliberately sans (var(--sans), 600, 15px) rather than the Newsreader display face the h2s use, so a subsection head ranks below its h2 by weight and family instead of competing with it.","identityAliases":["docs stylesheet","docs.css","inline code chip style","doc-sec h3","flags table styling","ember code chips"],"incidentAliases":["cluttered docs section","too many code chips","subsection heading unstyled"],"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in","nav",".nav-in",".side a.active",".chip",".term-body .ln",".docs",".term-bar","doc-sec","flags","flag-row","callout","term-body","lead-p"],"hash":"sha256:d5f16297671d","head":"e6e8bea1e30c"}],"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","op":"put","verified":["site-astro/src/styles/docs.css"],"character":"single","v":1,"ts":"2026-09-06T18:27:40.303Z","head":"e6e8bea1e30c"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-styles-footer-css-e509e4fe.jsonl b/.coldstart/notebook/.raw/site-astro-src-styles-footer-css-e509e4fe.jsonl
new file mode 100644
index 0000000..16f8fc0
--- /dev/null
+++ b/.coldstart/notebook/.raw/site-astro-src-styles-footer-css-e509e4fe.jsonl
@@ -0,0 +1,2 @@
+{"summary":"The site's ONLY footer rule set, replacing copies that had been duplicated in landing.css and docs.css. It is not imported by any page: backdrop.css carries `@import \"./footer.css\"` at its top, and every page shell already imports backdrop.css, so this reaches a page for free - deliberately, because a per-page import is one more thing a new page can silently forget. It defines no tokens, so being hoisted above backdrop.css's :root by Vite is harmless. Layout is a 5-column grid (identity block + four link columns) over a .foot-base rule with the tagline and a frost/ember key; it collapses to 2 columns under 1000px and 1 under 520px. The columns are DIVS on purpose - as <nav> elements they inherited landing.css's global `nav{position:sticky;border-bottom:1px solid var(--line)}` and rendered boxed and pinned.","identityAliases":["footer stylesheet","footer columns","foot-in grid","footer link surface"],"incidentAliases":["footer columns boxed","footer sticky columns","footer duplicated styles"],"anchors":[{"path":"site-astro/src/styles/footer.css","hash":"sha256:bc7a8c91cca4","head":"dae09634b870"}],"id":"site-astro-src-styles-footer-css-e509e4fe","type":"file","op":"put","verified":["site-astro/src/styles/footer.css"],"character":"single","v":1,"ts":"2026-09-06T18:10:21.495Z","head":"dae09634b870"}
+{"anchors":[{"path":"site-astro/src/styles/footer.css","symbols":["foot-in","foot-col","foot-id","foot-base","foot-temp","foot-blurb"]}],"id":"site-astro-src-styles-footer-css-e509e4fe","type":"file","op":"put","verified":[],"character":"single","v":1,"ts":"2026-09-06T18:10:27.780Z","head":"dae09634b870"}
diff --git a/.coldstart/notebook/.raw/site-astro-src-styles-landing-css-cc3a29d9.jsonl b/.coldstart/notebook/.raw/site-astro-src-styles-landing-css-cc3a29d9.jsonl
index fab61f6..a3c3613 100644
--- a/.coldstart/notebook/.raw/site-astro-src-styles-landing-css-cc3a29d9.jsonl
+++ b/.coldstart/notebook/.raw/site-astro-src-styles-landing-css-cc3a29d9.jsonl
@@ -8,3 +8,5 @@
 {"summary":"Homepage stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette, --void #070a11). Styles hero, notebook paper-card, flow/index section, nav, footer and the .faq block. Holds .how-link, the small centred pill linking each section to its /how-it-works/ page: it is deliberately a LIGHT lift (rgba white/warm overlay) rather than a darker fill, because on this dark ground a darker background reads as a recess instead of a raised control — the same logic that makes .btn-ghost transparent and the Install CTA a solid frost fill.","identityAliases":["how-link button","raised not recessed"],"incidentAliases":["dash before section label","cta panel too wide","button does not look clickable"],"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta"],"hash":"sha256:26649633ac9c","head":"578f3ec476b0"}],"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","op":"put","verified":["site-astro/src/styles/landing.css"],"character":"single","v":1,"ts":"2026-08-09T10:05:32.798Z","head":"578f3ec476b0"}
 {"summary":"Homepage stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette, --void #070a11). Styles hero, notebook paper-card, flow/index section, nav, footer and the .faq block. Holds .how-link, the centred pill linking each section to its /how-it-works/ page: it is a DEEP BRAND-TINTED fill, not a neutral chip and not a translucent outline — the section's own hue mixed ~13% into the near-black ground at rest (frost for the index section, .warm/ember for the notebook), rising to ~22% on hover with the border going 33%->63%. Deliberately kept deep rather than bright so it does not compete with the solid-frost Install CTA in the nav. An earlier translucent-outline version read as faded and was rejected.","identityAliases":["how-link button","brand tinted button"],"incidentAliases":["button looks faded","button not clickable","hover effect too subtle"],"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta"],"hash":"sha256:bd70ef86ae7d","head":"7bb5ae6d6b3b"}],"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","op":"put","verified":["site-astro/src/styles/landing.css"],"character":"single","v":1,"ts":"2026-08-09T10:14:48.231Z","head":"7bb5ae6d6b3b"}
 {"identityAliases":["landing page CSS","design system","design tokens","frost ember palette","how-link button","note card dark theme","recall timeline styles"],"incidentAliases":["dropdown active underline","thick line under demo nav"],"summary":"Homepage + demo/live/notebook-wrapper stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette). Styles hero, nav (including the `.nav-drop` dropdown), footer, the `.faq` block, and the shared `.card`/`.card-top`/`.pill` note-card component — rewritten this session from a warm 'paper' theme to one dark treatment (`--ink-2` background, no rotation) used identically on the homepage exhibit and the /demo/ recall timeline (`.recall{gap:18px}`, `.recall .card{margin:8px 0}`). Fixed a real bug here: `.nav-links a.active::after` (the top-nav underline) was unscoped and leaked onto nested `.nav-drop-menu` items, drawing a thick underline under whichever dropdown item was active; now scoped to `.nav-links>a.active` / `.nav-links>.nav-drop>a.active` only.","anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta",".card",".recall",".keynote",".time-gap",".nav-drop",".nav-drop-menu",".nav-links"],"hash":"sha256:2dfa459e12c4","head":"b0e998cf87a1"}],"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","op":"put","verified":["site-astro/src/styles/landing.css"],"character":"single","v":1,"ts":"2026-08-26T19:35:23.975Z","head":"b0e998cf87a1"}
+{"summary":"Homepage stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette); also styles nav, footer, the .faq block and the shared .card note-card. Now built on a TWO-COLUMN SPINE: .two is a 5fr/7fr grid with .col-a (the argument, sticky at top:88px above 1024px) and .col-b (the artifact), collapsing to one column below 900px; its ::before draws the column hairline at left:calc((100% - 48px) * 5 / 12 + 24px). Every section uses that one shape and nothing is centred. Section backgrounds were removed on purpose — .navsec/.phil/.faq no longer sit on --ink-1, .nb no longer has its warm ground plus two radial blobs, and .hero::before's glow is gone — because backdrop.css now paints one continuous field under the whole page and sections are divided by a hairline instead of a band of colour.","identityAliases":["two column spine","col-a col-b grid","sticky argument column","section hairline separator"],"incidentAliases":["hero wider than other sections","hero spills past wrap","hero max-width override"],"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta",".card",".recall",".keynote",".time-gap",".nav-drop",".nav-drop-menu",".nav-links",".two",".col-a",".col-b",".hero-in",".navsec",".phil",".nb",".nb-intro",".nb-steps",".nb-exhibit",".wrap"],"hash":"sha256:f6af78c47f49","head":"43401f352e9d"}],"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","op":"put","verified":["site-astro/src/styles/landing.css"],"character":"single","v":1,"ts":"2026-09-04T08:42:59.521Z","head":"43401f352e9d"}
+{"summary":"Homepage stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette); also styles nav, footer, the .faq block and the shared .card note-card. Layout is STACKED, FULL-WIDTH, CENTRED sections - the .two/.col-a/.col-b two-column spine described by an earlier version of this note was reverted in 0867280 and no longer exists. It was reverted because a DOM probe across six dev-tool landing pages found that nextjs.org, vercel.com and railway.com use ZERO two-column grids, nobody repeats an asymmetric split as a page spine, and 5 of 6 centre some text; the spine also ran ~375px / ~44 chars per line, below the measured 429-550px band. What DID survive the revert is the removal of every per-section background: .navsec/.phil/.faq no longer sit on --ink-1, .nb no longer has its warm ground plus two radial blobs, and .hero::before's glow is gone, because backdrop.css now paints one continuous field under the whole page and sections are divided by a hairline instead of a band of colour. The .tl traffic-light rules were also deleted here (and in docs.css) when the dots were removed sitewide.","identityAliases":["landing stylesheet","homepage tokens","section hairline separator","no section background rule"],"incidentAliases":["two column spine reverted","col-a col-b removed","landing layout too narrow","prose measure too narrow","traffic light rules removed"],"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta",".card",".recall",".keynote",".time-gap",".nav-drop",".nav-drop-menu",".nav-links",".two",".col-a",".col-b",".hero-in",".navsec",".phil",".nb",".nb-intro",".nb-steps",".nb-exhibit",".wrap",".btn",".btn-primary"],"hash":"sha256:61c7ab27ec9a","head":"54deea7bca84"}],"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","op":"put","verified":["site-astro/src/styles/landing.css"],"character":"single","v":1,"ts":"2026-09-04T09:19:10.049Z","head":"54deea7bca84"}
diff --git a/.coldstart/notebook/.raw/src-kb-view-template-ts-0ad76008.jsonl b/.coldstart/notebook/.raw/src-kb-view-template-ts-0ad76008.jsonl
new file mode 100644
index 0000000..a105905
--- /dev/null
+++ b/.coldstart/notebook/.raw/src-kb-view-template-ts-0ad76008.jsonl
@@ -0,0 +1 @@
+{"summary":"The complete single-file notebook viewer as one exported string (VIEW_TEMPLATE), with __TITLE__ and __DATA_JSON__ substituted by renderViewHtml. It IS the source: unlike the graph viewer there is no generator for it - scripts/kb-viewer/ holds only build-site-page.mjs, which BAKES this template for the marketing site - so edit it here. Its file header used to claim the opposite ('generated from the design source; do not hand-edit') and was corrected. The :root token block is the shared brand surface for both the local `kb view` output and /notebook/ on the site, so theming it here is what keeps the two identical. Three decisions are load-bearing and are documented in the header: it stays LIGHT-grounded because it is a long-form reading surface for note prose; --file is frost and --flow is ember (a file note is a fixed address, a flow note is a path through the code), and the canvas graph reads separate brighter --file-node/--flow-node so text can keep the dark on-white values; the freshness scale stays a green/amber/red traffic light because that is status rather than brand, with --changed pushed redder specifically so it does not collide with the new ember --flow. Fonts stay system stacks on purpose - the output is opened as a local file, often offline, so a webfont here would look correct in the repo and fail for the user.","identityAliases":["notebook viewer template","kb view palette","VIEW_TEMPLATE","viewer theming","file note flow note colour"],"incidentAliases":["notebook looks blue and white","viewer off brand"],"anchors":[{"path":"src/kb/view-template.ts","symbols":["VIEW_TEMPLATE"],"hash":"sha256:293ab177fb81","head":"dae09634b870"}],"id":"src-kb-view-template-ts-0ad76008","type":"file","op":"put","verified":["src/kb/view-template.ts"],"character":"single","v":1,"ts":"2026-09-06T18:10:21.520Z","head":"dae09634b870"}
diff --git a/.coldstart/notebook/.raw/terminal-output-in-an-astro-template-breaks-the-build-two-di.jsonl b/.coldstart/notebook/.raw/terminal-output-in-an-astro-template-breaks-the-build-two-di.jsonl
new file mode 100644
index 0000000..b7200ef
--- /dev/null
+++ b/.coldstart/notebook/.raw/terminal-output-in-an-astro-template-breaks-the-build-two-di.jsonl
@@ -0,0 +1 @@
+{"title":"Terminal output in an .astro template breaks the build two different ways","summary":"An .astro file's whole template is compiled to a JS template literal AND its markup braces are Astro expressions, so pasting real command or source output into the markup fails the build twice over. (1) `${...}` is interpolated - a line like `redis.set(`sess:${token}`...)` fails with 'token is not defined'. (2) `{...}` is parsed as an expression - `JSON.stringify({ uid: user.id })` fails with 'Expected } but found await'. HTML-entity escaping does NOT fix either one: `&#36;{token}` is decoded back to `${token}` before the literal is emitted. The fix that works is to put the output in a frontmatter array of plain strings and map over it - frontmatter strings are immune to both - which is what `readOut` in demo/index.astro does. A THIRD, separate trap in the same territory: Astro also collapses template newlines, so a transcript written as one text block under white-space:pre renders as a single wrapped line; each line needs its own element. All three were found by building and rendering, never by reading the markup.","identityAliases":["astro template literal trap","astro brace expression trap","terminal output in astro","readOut frontmatter pattern"],"incidentAliases":["token is not defined","Expected } but found await","astro build fails on terminal output","astro strips newlines","white-space pre not working"],"steps":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["readOut",".ob"],"role":"carries the fix - terminal output as a frontmatter string array, mapped into one div per line"},{"path":"site-astro/src/pages/docs.astro","symbols":["term-body"],"role":"also renders terminal blocks; same rules apply to any output pasted here"}],"invariants":["Never paste raw command or source output straight into an .astro template. If it contains `$` followed by a brace, or any `{`, the build fails.","HTML entities do not escape either construct - the entity is decoded before the template literal is emitted.","One element per output line, because Astro collapses template newlines and white-space:pre alone will not save it.","The output box needs its own overflow-x:auto so long lines scroll inside the box instead of overflowing the page on mobile."],"verified":["site-astro/src/pages/demo/index.astro"],"id":"terminal-output-in-an-astro-template-breaks-the-build-two-di","type":"flow","op":"put","v":1,"ts":"2026-09-06T17:34:02.877Z","head":"e52802156249","anchors":[{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:1e4be26bcb26","head":"e52802156249"}]}
diff --git a/site-astro/DESIGN.md b/site-astro/DESIGN.md
index fb143da..b9d44d8 100644
--- a/site-astro/DESIGN.md
+++ b/site-astro/DESIGN.md
@@ -67,7 +67,7 @@ literal and continuous rather than sectioned:
 - **Nothing is opaque.** Every surface is a translucent wash, so panels sit
   *inside* the field instead of on top of it. This is the rule that makes a note
   card match the background rather than punch out of it.
-- The one memorable element is the **seam** (§5).
+- The one memorable element is the **field** (§5).
 
 Everything else stays quiet.
 
@@ -93,18 +93,13 @@ Everything else stays quiet.
 **The field.** One fixed pseudo-element — *not* `background-attachment:fixed`,
 which paints only the first viewport and is unreliable on iOS Safari:
 
-```css
-body::before{
-  content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
-  background:
-    radial-gradient(78% 88% at  -6% 26%, rgba(79,191,224,.20), transparent 66%),
-    radial-gradient(78% 88% at 106% 74%, rgba(239,148,72,.19), transparent 66%),
-    linear-gradient(102deg,#0a1019 0%,#0b0e14 48%,#150f09 100%);
-}
-```
+The shipped definition lives in `src/styles/backdrop.css` and is a **single
+90deg ramp** — see §5, which is the authority. An earlier draft of this section
+specified two radial blobs over a diagonal base; that was rejected in §12 (two
+aurora blobs are a `dark-glass` signature device and read as generated) and the
+CSS here is superseded by §5's.
 
-Below 860px the axis rotates to vertical (frost top, ember bottom) — the same
-two glows at `50% -4%` and `50% 104%`.
+Below 900px the axis rotates to vertical — frost top, ember bottom.
 
 **Text contrast.** Body copy is `--text`. Grey is for labels and captions, never
 for a paragraph. This is the single rule that most changes how the site reads:
@@ -155,62 +150,115 @@ Comparable numbers get `tabular-nums`. Prose is never centered, never past 66ch.
 
 ## 4. Layout system
 
-**The hard left rail.** One text edge for the whole site. Nothing is centered.
+> **Rewritten 2026-09-04 after measuring.** The previous version of this section
+> specified a 5/7 `.split` spine with a sticky argument column and "nothing is
+> ever centered". That was **asserted, never measured** — §11 measured type and
+> colour only, and its credibility silently transferred to an axis it never
+> touched. The spine was built (`43401f3`), looked wrong, and the measurement
+> taken afterwards contradicted it. Reverted in `0867280`.
+
+**Measured, 1440px, six dev-tool landing pages** (identical DOM probe: grids with
+exactly 2 tracks spanning >50% of the viewport; median width of `p`/`li` over 80
+chars; blocks over 30 chars with `text-align:center`):
+
+| Site | 2-col grids | ratios | prose px / chars | centred blocks |
+|---|---|---|---|---|
+| nextjs.org | **0** | — | 535 / 54 | 5 of 14 |
+| vercel.com | **0** | — | (no long prose) | 2 of 6 |
+| railway.com | **0** | — | 502 / 56 | 6 of 23 |
+| resend.com | 2 | 0.50, 0.50 | 450 / 50 | 8 of 27 |
+| linear.app | 10 | 0.18, 0.50, 0.42 | 550 / 79 | 1 of 26 |
+| bun.sh | 8 | 0.27–0.50 | 429 / 48 | 0 of 49 |
+
+Three things follow, and they are observations, not taste:
+
+1. **Half the class uses no two-column grid at all** — including nextjs.org, the
+   stated target. Full-width stacked sections with a constrained prose measure is
+   the dominant shape, not argument-left/artifact-right.
+2. **Nobody repeats an asymmetric split as the page's spine.** Where a 2-col grid
+   exists it is ~0.50 (equal) or extreme (0.18 / 0.27 — a nav rail, a different
+   thing). A 0.41 applied to *every* section is not a pattern any of them use.
+3. **Centred text is normal.** 5 of 6 centre some blocks.
+
+**So: stacked, full-width sections.**
 
 ```
-├── 1120px wrap, 12 columns, 24px gutter ──────────────────────────┤
-
-┌─ col 1 ──────────────── col 5 ┊ col 6 ─────────────── col 12 ─┐
-│ EYEBROW                       ┊                               │
-│ A heading that sits on the    ┊   ┌───────────────────────┐   │
-│ left rail and stops at 5 cols ┊   │  the artifact         │   │
-│                               ┊   │  terminal / note /    │   │
-│ Lead copy, ≤66ch, ragged      ┊   │  panel / diagram      │   │
-│ right, never centered.        ┊   └───────────────────────┘   │
-└───────────────────────────────┴───────────────────────────────┘
-   frost edge                   ┊                     ember edge
-                            the seam
+├── 1120px wrap ───────────────────────────────────────────────────┤
+
+┌─────────────────────────────────────────────────────────────────┐
+│                          EYEBROW                                │
+│                A heading, ≤ 22ch, centred                       │
+│           Lead copy, 500px measure, ≈ 54 chars/line             │
+│                                                                 │
+│      ┌───────────────────────────────────────────────┐          │
+│      │  the artifact — terminal / note / panel        │          │
+│      └───────────────────────────────────────────────┘          │
+└─────────────────────────────────────────────────────────────────┘
+ frost edge                                            ember edge
+        (the field runs continuously under all of it)
 ```
 
-Two section types, and only two:
-
-- **`.split`** — 5 / 7. Argument left, artifact right. Left column is
-  `position:sticky; top:56px` on ≥1024px, so the claim holds while a long
-  terminal scrolls past. The default.
-- **`.plain`** — one column, constrained to columns 1–8. FAQ, install, closing
-  CTA. Still on the left rail; the right third stays open for the ember edge.
-  **Not** a centered column.
+- **Prose measure: 500px, ≈ 54 chars/line.** The measured band is 429–550px /
+  48–79 chars; 500 sits inside it and matches nextjs.org almost exactly. The
+  rejected build ran ~375px / ~44 chars — below the band, which is what "the left
+  column is narrow causing long text" was describing.
+- **Centring is allowed** for headings, lead copy and closing CTAs. It is what
+  the class does. A section may go left-set when it has a reason; uniformity is
+  not the reason.
+- **A two-column grid is a per-section decision, not a spine.** If one is used,
+  it is 50/50. An artifact that needs full width takes full width.
 
-**Separator.** Sections are divided by a **full-bleed hairline**, lifted from
-`/how-it-works/`, which is the one piece of the current site worth keeping:
+**Separator.** Sections are divided by a **full-bleed hairline**:
 
 ```css
 section{padding:84px 0;}
 section + section{border-top:1px solid var(--line);}
 ```
 
-It marks the boundary without banding the background — the field stays
-continuous underneath. No section ever sets its own background colour.
+It marks the boundary without banding the background. **No section ever sets its
+own background colour** — this is the one rule from the previous version that
+survives, and it shipped in `0867280`: `.navsec`/`.phil`/`.faq` are off
+`--ink-1`, `.nb` has lost its warm ground and two radial blobs, `.hero::before`
+is gone.
 
-**Mobile (<860px).** `.split` collapses to one column, artifact under argument,
-sticky off, seam and ticks hidden, field rotated vertical.
+**Mobile (<860px).** Padding tightens; the field rotates to vertical (frost top,
+ember bottom). Nothing else has to change, which is the point of not having a
+spine.
 
 ---
 
-## 5. Signature device — the seam
+## 5. Signature device — the field
 
-One hairline running the full viewport height at the column-6 gutter,
-`background: var(--seam)` (frost→ember, top to bottom), `opacity: .34`.
+**The seam is retired.** It was a hairline at the column-6 gutter with section
+ticks — a device that only exists if there is a column-6 gutter, which §4 no
+longer has. It was also never built.
 
-- At each section's start it grows a **tick**: an 11px stub, a frost dot on the
-  line, and the section's short label in `label` type, sitting 34px above the
-  content so it rides in the separator gap.
-- The ticks are the page's table of contents, and the only place a section index
-  appears — which retires the `01 ·`/`02 ·` eyebrows, since the landing sections
-  are not a sequence and never were.
-- Hidden below 860px.
+The signature device is **the field itself**: one page-scale frost→ember ramp,
+cold at the left edge, warm at the right, defined once in `styles/backdrop.css`
+and imported by every page shell, so home, docs and blog sit on the same
+continuous ground.
 
-This is the whole flourish budget. Another decorative element means one goes.
+```css
+body::before{
+  content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
+  background:linear-gradient(90deg,
+    rgba(79,191,224,.17) 0%, transparent 42%,
+    transparent 58%, rgba(239,148,72,.16) 100%);
+}
+```
+
+Why this and not an added flourish:
+
+- It carries the product's own duality — the cold exact index, the warm
+  notebook — without labelling anything by hue.
+- It is **singular, not repeating.** The tell of a generated site is a *tiled*
+  background (a dot grid, a mesh); one continuous ramp across the whole document
+  is the opposite move. The 30px dot grid that used to live in this file is gone
+  for exactly that reason.
+- It replaces the per-section colour bands, so nothing paints over it.
+- It costs one element and zero JS.
+
+This is the whole flourish budget. Another decorative element means this one goes.
 
 ---
 
@@ -219,8 +267,7 @@ This is the whole flourish budget. Another decorative element means one goes.
 - **Content is never hidden by default.** No `opacity:0` waiting on JS. A reveal
   is CSS-only or it doesn't ship. This is the hard rule §0 violates today, and
   the specimen is verified at zero `opacity:0` elements.
-- Allowed: hover transitions ≤160ms, the scroll progress hairline, seam ticks
-  brightening as their section enters view.
+- Allowed: hover transitions ≤160ms, the scroll progress hairline.
 - Not allowed: typewriter effects, staggered line reveals, cumulative delay
   budgets, parallax, ambient floating shapes.
 - `prefers-reduced-motion: reduce` disables all of it, with identical content.
@@ -234,9 +281,12 @@ Motion for **marketing** is a separate artifact, not a page behaviour — see §
 **Static, fully rendered.** The whole session is present on load. No typing, no
 scroll triggers. Screenshot-able, works with JS off, scannable in three seconds.
 
-Layout: one `.split` — transcript left (cols 1–8), commentary rail right (cols
-9–12) with short annotations pointing at specific turns. The argument lives in
-the rail so the panel stays a faithful replica carrying no marketing copy.
+Layout: **one full-width column**, panel centred at 880px. The commentary rail
+this section originally specified is gone with §4's split — the annotations are
+now short centred captions *between* turn groups, outside the panel. The reason
+for putting them outside stands: the panel carries no marketing copy, so it
+stays a faithful replica. Captions collapse naturally on mobile, which a
+cols-9–12 rail did not.
 
 Two panels stacked, the same repo on two different days:
 1. **Cold** — no note yet. `find` → `gs` → answer → the Stop hook writes a note.
@@ -261,8 +311,19 @@ the real thing sitting on the page, not a themed imitation.
 | Inline code | `#d9a05b` on `rgba(255,255,255,.06)`, radius 4 |
 | Input bar | `#242424`, 1px `rgba(239,148,72,.45)`, send button `#a8604a` |
 
-Output is real, unedited command output from this repo — same rule as today's
-page. **No traffic-light dots anywhere**, on this panel or on any terminal.
+**The repo is invented, and the page says so.** The panels run against a
+fictional Node/Express API and the question is "how does authentication work in
+this codebase?" — the thing every developer asks in their first week. The
+earlier version used a real captured session about coldstart's own co-change
+internals, which only demonstrates the tool to someone who already uses it.
+
+That trades literal provenance for relatability, so the trade is stated on the
+page rather than hidden: a line under the hero says the repo and its output are
+invented, and that only the command shapes and the output format are real. A
+terminal reads as captured output unless the page says otherwise, so the
+disclaimer sits with the hero copy and not in a footnote.
+
+**No traffic-light dots anywhere**, on this panel or on any terminal.
 
 ---
 
@@ -297,7 +358,7 @@ Each step ends with a rendered screenshot check, not a CSS read.
 1. **`tokens.css`** — one `:root` imported by every page shell. Delete the
    duplicate blocks in `landing.css` and `docs.css`; settle `--wrap` at 1120px.
    Nothing looks different; this unblocks everything else.
-2. **The field, the seam, the separator** — and remove per-section backgrounds
+2. **The field and the separator** — and remove per-section backgrounds
    and the dot grid. First visible change, site-wide.
 3. **Contrast pass** — leads and prose to `--text`, grey confined to labels.
    Cheap, and the most immediately noticeable improvement.
@@ -423,7 +484,7 @@ polish comes from — *gradient as an edge treatment, not as atmosphere.*
   except tailwind. → Use the **flat ramp** shape, which puts both temperatures
   in a single gradient, instead of two opposing blobs.
 - **Use gradients freely at component scale** — hairlines, borders, small fills.
-  The seam (§5) is already exactly this move and should be joined by others.
+  The field (§5) is that move. The seam it replaced was never built.
 
 ---
 
diff --git a/site-astro/src/components/Footer.astro b/site-astro/src/components/Footer.astro
index 706c33c..0c1b871 100644
--- a/site-astro/src/components/Footer.astro
+++ b/site-astro/src/components/Footer.astro
@@ -1,12 +1,57 @@
 ---
+// Styling lives in styles/footer.css, which is pulled in by backdrop.css —
+// so a page gets the footer's chrome from the same import that gives it the
+// background field. See the comment at the top of footer.css.
 interface Props { variant?: 'home' | 'docs' | 'blog' | 'how' | 'live' }
 const { variant = 'docs' } = Astro.props;
+
+// The columns are the site's real IA. Most of these pages were previously
+// reachable only from the nav dropdown.
+const columns = [
+  {
+    title: 'See it work',
+    links: [
+      { href: '/demo/', label: 'Demo session' },
+      { href: '/live/', label: 'See it live' },
+      { href: '/notebook/', label: 'Notebook browser' },
+      { href: '/graph/', label: 'Codebase graph' },
+    ],
+  },
+  {
+    title: 'Understand it',
+    links: [
+      { href: '/how-it-works/', label: 'How it works' },
+      { href: '/how-it-works/navigation/', label: 'The navigation layer' },
+      { href: '/how-it-works/notebook/', label: 'The notebook layer' },
+      { href: '/vs/vector-rag/', label: 'Compared to vector RAG' },
+    ],
+  },
+  {
+    title: 'Reference',
+    links: [
+      { href: '/docs/', label: 'Docs' },
+      { href: '/docs/navigation/', label: 'find and gs' },
+      { href: '/docs/notebook/', label: 'kb commands' },
+      { href: '/docs/under-the-hood/', label: 'Under the hood' },
+    ],
+  },
+  {
+    title: 'Project',
+    links: [
+      { href: '/blog/', label: 'Blog' },
+      { href: 'https://github.com/AkashGoenka/coldstart', label: 'GitHub', ext: true },
+      { href: 'https://www.npmjs.com/package/@cstart/coldstart', label: 'npm', ext: true },
+      { href: 'https://github.com/AkashGoenka/coldstart/blob/main/CHANGELOG.md', label: 'Changelog', ext: true },
+    ],
+  },
+];
+
 const taglines = {
-  home: 'codebase memory for coding agents · MIT',
-  docs: 'docs · MIT',
-  blog: 'blog · MIT',
-  how: 'how it works · MIT',
-  live: 'see it live · MIT',
+  home: 'codebase memory for coding agents',
+  docs: 'docs',
+  blog: 'blog',
+  how: 'how it works',
+  live: 'see it live',
 };
 const tagline = taglines[variant];
 ---
@@ -14,14 +59,19 @@ const tagline = taglines[variant];
   <div class="foot-in">
     <div class="foot-id">
       <a class="brand" href="/"><svg class="mark s2" width="17" height="17" viewBox="0 0 32 32" aria-hidden="true"><circle class="core" cx="16" cy="16" r="8" fill="url(#glow)"/><use href="#flake" class="fl"/><circle class="fl" cx="16" cy="16" r="6" fill="none"/><circle class="core" cx="16" cy="16" r="3" fill="url(#core)"/></svg>coldstart</a>
-      <span class="foot-tagline">{tagline}</span>
-    </div>
-    <div class="foot-links">
-      <a href="/">Home</a>
-      <a href="/docs/">Docs</a>
-      <a href="/blog/">Blog</a>
-      <a href="https://github.com/AkashGoenka/coldstart">GitHub</a>
-      <a href="https://www.npmjs.com/package/@cstart/coldstart">npm</a>
+      <p class="foot-blurb">A static index and a written-down notebook, so an agent starts a task knowing where things are.</p>
     </div>
+    {columns.map((col) => (
+      <div class="foot-col">
+        <h3>{col.title}</h3>
+        {col.links.map((l) => (
+          <a href={l.href} class={l.ext ? 'ext' : undefined} rel={l.ext ? 'noopener' : undefined}>{l.label}</a>
+        ))}
+      </div>
+    ))}
+  </div>
+  <div class="foot-base">
+    <span class="foot-tagline">{tagline} · MIT</span>
+    <span class="foot-temp"><i class="f"></i>index<i class="e"></i>notebook</span>
   </div>
 </footer>
diff --git a/site-astro/src/components/Nav.astro b/site-astro/src/components/Nav.astro
index 4b66c66..f192197 100644
--- a/site-astro/src/components/Nav.astro
+++ b/site-astro/src/components/Nav.astro
@@ -61,7 +61,7 @@ const demoActive = variant === 'demo' || variant === 'graph' || variant === 'not
 .nav-drop-menu a{display:flex;flex-direction:column;gap:2px;padding:9px 12px;border-radius:8px;
   font-size:13.5px;color:#e7eef8;line-height:1.3;}
 .nav-drop-menu a:hover,.nav-drop-menu a.active{background:rgba(79,191,224,.1);}
-.nav-drop-menu a span{font-size:11.5px;color:#8b9ab2;font-weight:400;}
+.nav-drop-menu a span{font-size:11.5px;color:var(--faint);font-weight:400;}
 @media(prefers-reduced-motion:reduce){.nav-drop-menu,.nav-drop .caret{transition:none;}}
 </style>
 <script>
diff --git a/site-astro/src/notebook-page.html b/site-astro/src/notebook-page.html
index 5d42149..ebf9118 100644
--- a/site-astro/src/notebook-page.html
+++ b/site-astro/src/notebook-page.html
@@ -1,19 +1,21 @@
 <title>Coldstart Notebook — coldstart</title>
 <style>
   :root{
-    --ground:#eaeef3; --surface:#ffffff; --rail:#f5f8fc; --sunk:#eef2f7;
-    --ink:#161a22; --ink-soft:#39414f; --muted:#69748a; --faint:#9aa6b8;
-    --line:#dce2ec; --line-soft:#e8edf3;
-    --accent:#1f4fd8; --accent-soft:#e7ecfd; --accent-ink:#173bab;
-    --fresh:#137a3b; --fresh-bg:#e4f4ea;
-    --changed:#a85a06; --changed-bg:#fbeedd;
-    --missing:#bb1436; --missing-bg:#fbe3e8;
-    --unver:#5a6577; --unver-bg:#eceff4;
-    --flow:#0b7285; --flow-bg:#dcf1f4;
-    --file:#1f4fd8; --file-bg:#e7ecfd;
+    --ground:#e8eef1; --surface:#ffffff; --rail:#f0f5f8; --sunk:#e9f0f4;
+    --ink:#111820; --ink-soft:#374250; --muted:#5a6674; --faint:#6a7887;
+    --line:#d7e0e6; --line-soft:#e5ecf0;
+    --accent:#0f6f8c; --accent-soft:#dcf0f6; --accent-ink:#0b5a72;
+    --fresh:#0f7a44; --fresh-bg:#dff2e7;
+    --changed:#b3400b; --changed-bg:#f9e0d6;
+    --missing:#b3132f; --missing-bg:#fbe2e7;
+    --unver:#586372; --unver-bg:#e9edf1;
+    --flow:#8a5410; --flow-bg:#f8e9d8;
+    --file:#0f6f8c; --file-bg:#dcf0f6;
+    --file-node:#1287a8; --flow-node:#d1791f;
     --mono:ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
     --sans:system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
     --sh:0 1px 2px rgba(20,28,45,.05),0 4px 16px rgba(20,28,45,.06);
+    --top:#0d141d; --top-ink:#eef2f8; --top-faint:#93a3b4;
     --r:9px;
   }
   *{box-sizing:border-box}
@@ -26,31 +28,38 @@
 
   .app{display:grid;grid-template-rows:auto 1fr;height:100vh;overflow:hidden}
 
-  /* ---- top bar ---- */
+  /* ---- top bar ----
+     Deliberately DARK against the light reading surface. It is the one place
+     the viewer looks like coldstartmcp.devs nav, which is what makes a note
+     opened from the site and a note opened from `kb view` read as one product
+     - without darkening the note prose, which is what people actually read.
+     The 2px frost -> ember hairline under it is the sites own device. */
   .top{display:flex;align-items:center;gap:20px;padding:12px 20px;
-    background:var(--surface);border-bottom:1px solid var(--line);z-index:5}
-  #home{display:inline-flex;align-items:center;gap:5px;margin-right:2px;padding:5px 10px 5px 4px;border-radius:999px;font-family:var(--mono);font-size:11px;color:var(--faint);text-decoration:none;flex:none;transition:color .15s,background .15s}#home:hover{color:var(--accent);background:var(--accent-soft)}.brand{display:flex;flex-direction:column;justify-content:center;min-width:0;gap:1px}
+    background:var(--top);border-bottom:0;z-index:5;position:relative;color:var(--top-ink)}
+  .top::after{content:"";position:absolute;left:0;right:0;bottom:0;height:2px;
+    background:linear-gradient(90deg,#4fbfe0,#ef9448)}
+  #home{display:inline-flex;align-items:center;gap:5px;margin-right:2px;padding:5px 10px 5px 4px;border-radius:999px;font-family:var(--mono);font-size:11px;color:var(--top-faint);text-decoration:none;flex:none;transition:color .15s,background .15s}#home:hover{color:#4fbfe0;background:rgba(79,191,224,.13)}.brand{display:flex;flex-direction:column;justify-content:center;min-width:0;gap:1px}
   .brand .kicker{font-family:var(--mono);font-size:9.5px;letter-spacing:.11em;
-    text-transform:uppercase;color:var(--faint);font-weight:600;line-height:1}
+    text-transform:uppercase;color:var(--top-faint);font-weight:600;line-height:1}
   .brand .repo{display:inline-flex;align-items:center;gap:6px;font-size:17px;
-    font-weight:680;letter-spacing:-.02em;color:var(--ink);line-height:1.1}
-  .brand .repo::before{content:"";width:7px;height:7px;border-radius:50%;
-    background:var(--accent);flex-shrink:0}
+    font-weight:680;letter-spacing:-.02em;color:var(--top-ink);line-height:1.1}
+  .brand .repo::before{content:"";width:8px;height:8px;border-radius:50%;
+    background:radial-gradient(circle at 34% 30%,#ef9448,#4fbfe0);
+    box-shadow:0 0 10px rgba(79,191,224,.55);flex-shrink:0}
   .top .spacer{flex:1}
   .stat{display:flex;flex-direction:column;line-height:1.15}
-  .stat b{font-size:16px;font-variant-numeric:tabular-nums;letter-spacing:-.02em}
+  .stat b{font-size:16px;font-variant-numeric:tabular-nums;letter-spacing:-.02em;color:var(--top-ink)}
   .stat span{font-family:var(--mono);font-size:9.5px;letter-spacing:.09em;
-    text-transform:uppercase;color:var(--faint)}
+    text-transform:uppercase;color:var(--top-faint)}
   .fresh-meter{display:flex;align-items:center;gap:8px}
-  .meter-bar{width:120px;height:8px;border-radius:5px;background:var(--sunk);
+  .meter-bar{width:120px;height:8px;border-radius:5px;background:rgba(255,255,255,.11);
     overflow:hidden;display:flex}
   .meter-bar i{display:block;height:100%}
-  .segbtns{display:flex;background:var(--sunk);border-radius:8px;padding:3px}
+  .segbtns{display:flex;background:rgba(255,255,255,.08);border-radius:8px;padding:3px}
   .segbtns button{padding:5px 13px;border-radius:6px;font-size:12.5px;
-    font-weight:500;color:var(--muted)}
-  .segbtns button[aria-pressed=true]{background:var(--surface);color:var(--ink);
-    box-shadow:0 1px 2px rgba(20,28,45,.12);font-weight:600}
-
+    font-weight:500;color:var(--top-faint)}
+  .segbtns button[aria-pressed=true]{background:rgba(255,255,255,.94);color:#111820;
+    box-shadow:0 1px 2px rgba(0,0,0,.3);font-weight:600}
   /* ---- body split ---- */
   .split{display:grid;grid-template-columns:340px 1fr;min-height:0}
   .split.graph-mode{grid-template-columns:1fr}
@@ -73,7 +82,7 @@
     padding:9px 0;border-radius:9px;font-size:13px;font-weight:600;color:var(--muted);
     background:var(--sunk);border:1px solid transparent}
   .lens .ct{font-family:var(--mono);font-size:11px;font-weight:700;
-    padding:1px 6px;border-radius:20px;background:rgba(105,116,138,.16);color:var(--muted);
+    padding:1px 6px;border-radius:20px;background:rgba(90,102,116,.16);color:var(--muted);
     font-variant-numeric:tabular-nums}
   .lens[aria-pressed=true]{background:var(--surface);color:var(--ink);
     border-color:var(--line);box-shadow:var(--sh)}
@@ -233,7 +242,7 @@
 
   /* ---- graph ---- */
   .graph-wrap{position:relative;overflow:hidden;background:
-    radial-gradient(circle at 30% 20%, #f2f5fa, var(--ground))}
+    radial-gradient(circle at 30% 20%, #f0f5f8, var(--ground))}
   .graph-wrap canvas{display:block;width:100%;height:100%}
   .graph-legend{position:absolute;top:16px;left:16px;background:var(--surface);
     border:1px solid var(--line);border-radius:var(--r);padding:12px 14px;
@@ -317,8 +326,8 @@
       <canvas id="graphCanvas"></canvas>
       <div class="graph-legend">
         <div class="lg-t">Note graph</div>
-        <div class="lg-row"><i style="background:var(--file)"></i>file note</div>
-        <div class="lg-row"><i style="background:var(--flow)"></i>flow note</div>
+        <div class="lg-row"><i style="background:var(--file-node)"></i>file note</div>
+        <div class="lg-row"><i style="background:var(--flow-node)"></i>flow note</div>
         <div class="hint" id="graphHint">Only linked notes shown. Click a node to open it.</div>
       </div>
       <div class="graph-tip" id="graphTip"></div>
@@ -326,7 +335,7 @@
   </div>
 </div>
 
-<script>const DB = {"summary":{"total":122,"byType":{"file":100,"flow":22},"byFreshness":{"fresh":61,"changed":54,"missing":7},"repo":"coldstart","generated":"2026-08-26"},"notes":[{"id":"scripts-kb-viewer-build-site-page-mjs-35d52445","type":"file","character":"single","title":"scripts/kb-viewer/build-site-page.mjs","aliases":["notebook site page generator","kb view site build"],"status":"active","updated":"2026-08-26T19:36:28.412Z","edits":3,"anchors":[{"path":"scripts/kb-viewer/build-site-page.mjs","symbols":["HERE","ROOT","DIST","OUT","distImport","buildViewData","renderViewHtml","VIEW_TEMPLATE","template","generated","data","html"],"hash":"sha256:666bcaa58b10","state":"fresh"}],"freshness":"fresh","dir":"scripts/kb-viewer","outLinks":[],"body":"Generates `site-astro/src/notebook-page.html` — the same single-file viewer `coldstart kb view` produces, with this repo's own real notebook baked in. Mirrors `scripts/graph-viewer/build-site-page.mjs` exactly, including substituting the real `<a id=\"home\">` link into VIEW_TEMPLATE before calling renderViewHtml (renderViewHtml always clears the placeholder itself, so the substitution must happen on the template first — see the home-link-placeholder flow note). Requires `npm run build` first since it imports compiled `dist/kb/view.js` and `dist/kb/view-template.js` directly, not the TS source.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-pages-live-index-astro-b8d46da1","type":"file","character":"single","title":"site-astro/src/pages/live/index.astro","aliases":["see it live hub","three cards demo graph notebook","live hub page"],"status":"active","updated":"2026-08-26T19:35:24.584Z","edits":2,"anchors":[{"path":"site-astro/src/pages/live/index.astro","symbols":["title","description","cards"],"hash":"sha256:0f3c6cc49e9d","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/live","outLinks":[],"body":"The /live/ hub page: three cards (Walkthrough → /demo/, Graph → /graph/, Notebook → /notebook/) so the homepage's CTA doesn't have to pick one of the three real-data pages for the visitor — it links here instead of straight to /graph/. Plain new-page chrome (landing.css + Nav/Footer/SvgDefs, `Nav variant=\"live\"`), no dependency beyond an inline `cards` array mapped to `.livecard` anchors.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","character":"single","title":"site-astro/src/pages/demo/index.astro","aliases":["demo page","live session demo","recall timeline","keynote callout","term live terminal","demo page too slow","gaps look awkward on demo page","flywheel in its own section"],"status":"active","updated":"2026-08-26T19:35:24.576Z","edits":2,"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description"],"hash":"sha256:4b92d0cdd5ac","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/demo","outLinks":[],"body":"The /demo/ page: a single continuous find→gs→capture→recall narrative told against this repo's own real command output, as two timed scenes ('01 first time', cold — 2 tool calls, writes a note; '02 second time', recalled — 0 tool calls). Each scene's summary callout (`.keynote`) must live INSIDE that scene's own `<section>`, as its last child, not as a sibling `<div class=\"wrap\">` between sections — placed outside, it got both the class's own margin AND the section's padding stacked, reading as a disconnected floating block on the wrong background. The `.recall.reveal` timeline's per-item pacing is driven by cumulative `data-t` delays in `runTimeline`, but a `.term.live` element's OWN internal typing+reveal duration (typeCommand's per-char delay, the post-type pause, then each output line's own `data-t`) runs independently of that countdown — its outer `data-t` must be sized to outlast that internal animation or the next timeline item fades in before the terminal finishes typing.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"src-graph-view-ts-9f9d75ac","type":"file","character":"single","title":"src/graph/view.ts","aliases":["graph view writer","self-contained html output","open in browser","graph html placeholder substitution","home link placeholder","home link stripped","link back missing"],"status":"active","updated":"2026-08-26T19:35:24.045Z","edits":2,"anchors":[{"path":"src/graph/view.ts","symbols":["graphView","renderGraphHtml","noteAnchors","defaultGraphPath"],"hash":"sha256:fc7d4eca1c94","state":"fresh"}],"freshness":"fresh","dir":"src/graph","outLinks":[],"body":"The write-and-open half of `coldstart graph`: reads the notebook for note anchors, calls buildGraphPayload, bakes the result into GRAPH_TEMPLATE and writes a single self-contained HTML file, then opens it in the OS browser. `renderGraphHtml` substitutes `<!--__HOME_LINK__-->` with '' — the standalone CLI page has nowhere to link back to, so any caller that wants that link (the site build) must substitute it into the TEMPLATE before calling this. This exact mechanism was mirrored for the notebook viewer (`src/kb/view.ts` + `src/kb/view-template.ts`) this session — see the home-link-placeholder flow note for the full picture across both viewers.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","character":"single","title":"site-astro/src/pages/index.astro","aliases":["homepage","index page","hero section","landing page","landing page astro","home page astro","faq section","faq json-ld source","how-it-works entry links","faq schema not visible","json-ld out of sync with html"],"status":"active","updated":"2026-08-26T19:35:24.035Z","edits":8,"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link"],"hash":"sha256:46674c8a42cf","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages","outLinks":[],"body":"Homepage — v4 centred hero. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ -> install. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD, so adding a question means editing that one array only. The nav-section CTA that used to link straight to /graph/ ('View the graph') now reads 'See it live' and points at the new /live/ hub page instead, so visitors choose between the demo/graph/notebook rather than always landing on the graph.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-components-footer-astro-98a77858","type":"file","character":"single","title":"site-astro/src/components/Footer.astro","aliases":["footer component","footer tagline","home footer","footer variant","taglines map"],"status":"active","updated":"2026-08-26T19:35:24.024Z","edits":4,"anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline"],"hash":"sha256:f67267f5bf38","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Shared footer, markup only. The `variant` prop ('home'|'docs'|'blog'|'how'|'live') keys directly into a `taglines` object literal to pick the footer tagline text — so unlike Nav, widening Footer's variant union is NOT enough: a variant with no matching taglines key silently renders an undefined tagline. Widened again this session for the new 'live' hub page ('see it live · MIT').","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"src-kb-view-ts-1fba6747","type":"file","character":"single","title":"src/kb/view.ts","aliases":["notebook view rewritten","index.html mtime churn","notebook view","wikilink graph","note graph edges","buildViewData","notebook viewer data","note graph links","shared anchor links","kb view html","home link placeholder","empty note graph","notebook page no back link"],"status":"active","updated":"2026-08-26T19:35:24.015Z","edits":9,"anchors":[{"path":"src/kb/view.ts","symbols":["kbView","renderViewHtml","buildViewData","toClientNote","ignoreIndexHtml","openInBrowser","bodyMarkdown","ViewOptions","linkByAnchor"],"hash":"sha256:dfe46b1ff385","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":["wikilinks"],"body":"Builds the baked JSON for `kb view` and writes/opens the notebook's index.html. linkByAnchor draws graph edges between any two notes that anchor the same file (capped at 8/note), on top of hand-typed [[wikilinks]], because agents write almost no wikilinks on their own. `renderViewHtml` now also substitutes `<!--__HOME_LINK__-->` with '' this session, mirroring `src/graph/view.ts`'s `renderGraphHtml` — the standalone `kb view` CLI page has nowhere to link back to, so only the website build script (`scripts/kb-viewer/build-site-page.mjs`) fills the placeholder in, and only by substituting into the raw template BEFORE this function runs.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","character":"single","title":"site-astro/src/styles/landing.css","aliases":["design tokens","frost ember theme","frost ember palette","landing stylesheet","paper card","copy to clipboard button","faq section styling","how-link button","raised not recessed","brand tinted button","note card dark theme","recall timeline styles","dropdown active underline","thick line under demo nav"],"status":"active","updated":"2026-08-26T19:35:23.975Z","edits":10,"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta",".card",".recall",".keynote",".time-gap",".nav-drop",".nav-drop-menu",".nav-links"],"hash":"sha256:2dfa459e12c4","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/styles","outLinks":[],"body":"Homepage + demo/live/notebook-wrapper stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette). Styles hero, nav (including the `.nav-drop` dropdown), footer, the `.faq` block, and the shared `.card`/`.card-top`/`.pill` note-card component — rewritten this session from a warm 'paper' theme to one dark treatment (`--ink-2` background, no rotation) used identically on the homepage exhibit and the /demo/ recall timeline (`.recall{gap:18px}`, `.recall .card{margin:8px 0}`). Fixed a real bug here: `.nav-links a.active::after` (the top-nav underline) was unscoped and leaked onto nested `.nav-drop-menu` items, drawing a thick underline under whichever dropdown item was active; now scoped to `.nav-links>a.active` / `.nav-links>.nav-drop>a.active` only.","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-components-nav-astro-9dfe3071","type":"file","character":"single","title":"site-astro/src/components/Nav.astro","aliases":["nav component","site navigation","header nav","variant prop","active nav tab","nav variant union","how variant","demo dropdown","nav dropdown menu","dropdown active underline","thick blue line dropdown"],"status":"active","updated":"2026-08-26T19:35:23.964Z","edits":5,"anchors":[{"path":"site-astro/src/components/Nav.astro","symbols":["Props","nav-burger","nav-mobile","installHref","nav-links","nav-drop","nav-drop-menu","demoActive"],"hash":"sha256:47409c440654","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Shared nav component, markup only — all of its appearance comes from the page's stylesheet (landing.css for home/demo/live/notebook, docs.css everywhere else). The `variant` prop ('home'|'docs'|'blog'|'how'|'graph'|'demo'|'notebook'|'live', default 'docs') picks which link gets the `active` class. This session collapsed the separate Demo/Graph/Notebook links into one `.nav-drop` dropdown: the 'Demo' trigger still links straight to /demo/, `demoActive` (true for variant demo/graph/notebook/live) highlights the trigger, and a `.nav-drop-menu` lists all three with per-item descriptions. The npm link stays plain text; GitHub is icon-only on desktop but both render as plain text in the mobile menu (still not fixed).","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","character":null,"title":"how a new site-astro page acquires nav, footer and SVG defs","aliases":["new site-astro page","page chrome wiring","nav footer styling","SvgDefs filter defs","docs sidebar component pattern"],"status":"active","updated":"2026-08-26T19:35:23.950Z","edits":3,"anchors":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/navigation.astro","hash":"sha256:fe084da82216","state":"changed"},{"path":"site-astro/src/components/Nav.astro","hash":"sha256:47409c440654","state":"fresh"},{"path":"site-astro/src/components/Footer.astro","hash":"sha256:f67267f5bf38","state":"fresh"},{"path":"site-astro/src/components/SvgDefs.astro","hash":"sha256:855fadd756ae","state":"fresh"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:cabd593fda98","state":"changed"},{"path":"site-astro/src/styles/how.css","hash":"sha256:518ebee8e16f","state":"fresh"},{"path":"site-astro/src/components/DocsSidebar.astro","hash":"sha256:8044650fa72f","state":"changed"},{"path":"site-astro/src/pages/docs/navigation.astro","hash":"sha256:d43204e50261","state":"changed"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","hash":"sha256:a7ffe7021ad0","state":"changed"},{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:4b92d0cdd5ac","state":"fresh"},{"path":"site-astro/src/pages/live/index.astro","hash":"sha256:0f3c6cc49e9d","state":"fresh"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:46674c8a42cf","state":"fresh"}],"freshness":"changed","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"Nav.astro, Footer.astro and SvgDefs.astro carry no styling or defs of their own — the chrome CSS lives entirely in whichever page-level stylesheet the page imports, so a new page must import landing.css or docs.css for the nav/footer to look right EVEN IF it ships its own stylesheet, and must render <SvgDefs /> or every url(#rough)/url(#glow) reference in its own markup silently resolves to nothing. Confirmed again this session building 3 new landing.css pages (/demo/, /live/, /notebook/'s Astro wrapper): each just imports landing.css and renders Nav/Footer/SvgDefs, no page-specific chrome CSS needed beyond a page-scoped <style> for its own unique sections.\n\n## Steps\n\n1. `site-astro/src/components/Nav.astro` (`Props`, `nav-drop`, `nav-drop-menu`) — markup only; variant prop and demoActive pick which link/dropdown item gets 'active'\n2. `site-astro/src/components/Footer.astro` (`Props`, `taglines`) — markup only; variant keys into a taglines map\n3. `site-astro/src/pages/demo/index.astro` — new page this session — landing.css + Nav/Footer/SvgDefs, no new chrome CSS\n4. `site-astro/src/pages/live/index.astro` — new page this session — same pattern\n\n## Invariants\n\n- Nav/Footer/SvgDefs are unstyled markup — their appearance comes entirely from the page's stylesheet, never from the component\n- url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter\n- Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined\n- Nav/Footer/SvgDefs are unstyled markup — appearance comes entirely from the page's stylesheet\n- url(#rough) on a page that does not render <SvgDefs /> fails silently\n- DocsSidebar.astro is the one component so far that DOES ship its own scoped <style> — see its own note for why (a docs.css global rule it must locally override)\n- Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined (both were widened together this session for the new 'live' variant)\n- Nav's dropdown submenu is markup+classes only too — its active-state styling lives in the page stylesheet's '.nav-drop-menu a.active' rule, and the SITE-WIDE '.nav-links a.active::after' underline rule must be scoped with a direct-child combinator ('.nav-links>a.active') or it leaks onto nested dropdown items, drawing an unwanted full-width underline under whichever submenu item happens to be active","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-src-components-docssidebar-astro-93ed0ec3","site-astro-src-components-footer-astro-98a77858","site-astro-src-components-nav-astro-9dfe3071","site-astro-src-pages-demo-index-astro-2e0c6d23","site-astro-src-pages-docs-navigation-astro-e37c5fa9"]},{"id":"how-a-standalone-generated-viewer-page-gets-a-back-link-when","type":"flow","character":null,"title":"how a standalone generated viewer page gets a back-link when embedded on the website","aliases":["home link placeholder","generated viewer back link","HOME_LINK substitution","notebook page no back link","graph page missing home link"],"status":"active","updated":"2026-08-26T19:35:23.899Z","edits":1,"anchors":[{"path":"src/graph/view-template.ts","hash":"sha256:1fce631954d2","state":"fresh"},{"path":"src/graph/view.ts","hash":"sha256:fc7d4eca1c94","state":"fresh"},{"path":"scripts/graph-viewer/build-site-page.mjs","hash":"sha256:06a14e3a2f4e","state":"changed"},{"path":"src/kb/view-template.ts","hash":"sha256:b360b09a08c9","state":"fresh"},{"path":"src/kb/view.ts","hash":"sha256:dfe46b1ff385","state":"fresh"},{"path":"scripts/kb-viewer/build-site-page.mjs","hash":"sha256:666bcaa58b10","state":"fresh"}],"freshness":"changed","dir":"src/graph","outLinks":[],"body":"coldstart graph and coldstart kb view each produce a single self-contained HTML file from a template carrying a <!--__HOME_LINK__--> placeholder; the CLI's own render call (renderGraphHtml / renderViewHtml) unconditionally clears that placeholder to '' because the standalone local file has nowhere to link back to, so the website build scripts (the only callers that want the link) must substitute the real <a id=\"home\"> anchor into the raw template BEFORE calling render — filling it in after render is a silent no-op.\n\n## Steps\n\n1. `src/graph/view-template.ts` (`GRAPH_TEMPLATE`) — defines the placeholder + #home CSS, original pattern\n2. `src/graph/view.ts` (`renderGraphHtml`) — clears the placeholder to '' unconditionally\n3. `scripts/graph-viewer/build-site-page.mjs` — substitutes the real home link into the template before calling renderGraphHtml\n4. `src/kb/view-template.ts` (`VIEW_TEMPLATE`) — gained the same placeholder + #home CSS this session, mirroring the graph template\n5. `src/kb/view.ts` (`renderViewHtml`) — now also clears the placeholder for the standalone CLI case\n6. `scripts/kb-viewer/build-site-page.mjs` — new generator script — substitutes the real home link before calling renderViewHtml\n\n## Invariants\n\n- the placeholder must be filled on the TEMPLATE string before calling render() — render always clears it, so filling it in after is a no-op that silently ships a link-less page\n- both viewers use the identical anchor markup/id (#home) and CSS convention — a future third generated viewer should follow the same order","backlinks":[],"anchorLinks":["scripts-graph-viewer-build-site-page-mjs-9bf323da","scripts-kb-viewer-build-site-page-mjs-35d52445","src-graph-view-ts-9f9d75ac","src-kb-view-ts-1fba6747"]},{"id":"hooks-evidence-mjs-147e7dd5","type":"file","character":"single","title":"hooks/evidence.mjs","aliases":["mention-only drop","grep hits not reads","sed -i is an edit","tool_result confirmation","cursor no tool results","codex cmd regex","inline script read detection","bashContentRead","bashEditTargets","shell write detection","heredoc tag arbitrary","cat redirect tiered as read","heredoc tag not recognized"],"status":"active","updated":"2026-08-25T18:54:16.712Z","edits":5,"anchors":[{"path":"hooks/evidence.mjs","symbols":["extractEvidence","extractCursorEvidence","extractCodexEvidence","classifyBash","codexCmdStrings","makeCollector","contentReadFiles","segmentStats","segmentStatsCursor","normRel","inlineScriptTier","bashContentRead","redirectTargets","bashEditTargets"],"hash":"sha256:9fbcfb9db13e","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Per-host transcript-to-evidence extractors with tier classification (edit/read/gs/mention), and the one table deciding what shell activity counts as reading or writing a file. Host gotchas verified on real transcripts: Cursor's conversation JSONL has NO tool_result records, so its extractor trusts calls and compensates with a stat-existence check on EVERY claim; Codex pairs custom_tool_call to output by call_id and its exec input embeds shell with the cmd key appearing BOTH quoted and unquoted across rollout versions. Default-deny: an unknown bash verb contributes at most a mention. Reading through the SHELL counts as reading (read verbs, plus inline scripts in any language matched on the file-open call in their body); writing through the shell counts as writing (bashEditTargets: redirect, tee, sed -i, literal write arg). A heredoc tag is an ARBITRARY identifier — the old EOF/PY/JS whitelist missed PATCH, TS and MSG and made those scripts invisible to both surfaces. redirectTargets overrides the verb table so `cat > x <<EOF` is an edit, not a read. Measured while building this: attributing a whole command would over-tier 50.6% of inline reads; output VOLUME does not separate reads from searches (cat's median is 18 lines vs an inline script's 10); and the deterministic write rules cover 89.2% of shell writes, so the single-literal guess for computed paths was rejected at 5.8% marginal gain.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"hooks-cochange-nudge-mjs-2fa94d26","type":"file","character":"single","title":"hooks/cochange-nudge.mjs","aliases":["co-change edit nudge","edit list per task","cochange sidecar reader","resetEditTrack","mirrored cache dir","shell edit detection","editedFiles list","nudge silent on sed edits","heredoc edit not counted"],"status":"active","updated":"2026-08-25T18:54:16.701Z","edits":2,"anchors":[{"path":"hooks/cochange-nudge.mjs","symbols":["coChangeNudge","resetEditTrack","coChangePath","suggest","render","loadState","editedPath","EDIT_TOOLS","MIN_RATIO","ORPHAN_MS","editedFiles","SHELL_TOOLS"],"hash":"sha256:33dd367fbc19","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Detector (7) of the PostToolUse nudge: records each edited file per (session,agent) and, once a SECOND distinct file is edited, names the files git history says move with them. Three rules, all measured, none to re-derive: the list clears on every new user message; nothing fires below 2 distinct files (trivial one-file jobs); then it fires for any partner not already edited and not already named — those two exclusions are the whole quieting mechanism, no per-session cap is needed. An edit is an edit TOOL or a shell write: editedFiles() returns a LIST, because one command can write two files and reach the 2-file threshold by itself. Two things a future editor will get wrong: (a) the tmp sweep must match the exact key or `<sid>_<aid>`, NEVER a bare `<sid>` prefix, or it clears a different session whose id merely starts the same; (b) the cache-dir derivation is a hand-copy of getCacheDir/cacheKey because hooks cannot import dist/ — change one and tests/cochange-nudge.test.ts is the only thing that notices. Cursor is why EDIT_TOOLS carries `SearchReplace` and editedPath accepts `path` as well as `file_path`; that shape is verified against Cursor transcripts, NOT a live Cursor hook payload.","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","type":"flow","character":null,"title":"how the co-change signal reaches an agent that never runs gs","aliases":["co-change edit nudge","edited together injection","PostToolUse detector 7","unasked co-change","edit-time nudge","shell edits count as edits","sed heredoc edit nudge","nudge silent in auto mode","edited via script no nudge"],"status":"active","updated":"2026-08-25T18:54:16.648Z","edits":2,"anchors":[{"path":"hooks/cochange-nudge.mjs","hash":"sha256:33dd367fbc19","state":"fresh"},{"path":"hooks/nudge-handler.mjs","hash":"sha256:2eefdfc34529","state":"fresh"},{"path":"hooks/kb-recall.mjs","hash":"sha256:7a8923adf6e0","state":"fresh"},{"path":"src/indexer/cochange.ts","hash":"sha256:b77c94aa16f5","state":"fresh"},{"path":"hooks/evidence.mjs","hash":"sha256:9fbcfb9db13e","state":"fresh"},{"path":"tests/cochange-nudge.test.ts","hash":"sha256:bfb50fa6b9bd","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"The \"Edited together\" partners are delivered to the agent WITHOUT it asking, at the moment an edit lands, because agents do not reliably run `gs` before editing. What counts as \"an edit\" is the load-bearing part: an edit TOOL or a deterministic shell write (`>`/`>>`, `tee`, `sed -i`, or a write call naming a literal path, via bashEditTargets in hooks/evidence.mjs). Gating on tool names alone made the whole feature silent for an agent instructed to edit with sed/heredocs/scripts — which is the auto-mode default, so the agent that most needed the nudge was the one guaranteed never to get it. The delivery path shares NO code with the `gs` rendering path: it is detector (7) inside the PostToolUse nudge handler, it reads the keeper's `cochange.json` sidecar directly, and its gate is deliberately LOOSER than `gs` (ratio >= 0.3 of the seed's own commits, shared >= 2, top 5) because \"what am I forgetting\" is a recall question while the `gs` cut is tuned for precision. It needs no `init` wiring: PostToolUse is registered on all three hosts with a match-everything matcher, and cursor-nudge-handler delegates to the Codex one.\n\n## Steps\n\n1. `hooks/cochange-nudge.mjs` (`coChangeNudge`, `editedFiles`, `suggest`, `resetEditTrack`, `coChangePath`, `EDIT_TOOLS`, `SHELL_TOOLS`) — the whole feature: what counts as an edit, the per-task edit list, the gate, the message\n2. `hooks/evidence.mjs` (`bashEditTargets`, `redirectTargets`, `inlineScriptTier`) — decides which repo files a shell command WRITES — the shared table, so the nudge and the capture worklist cannot disagree\n3. `hooks/nudge-handler.mjs` (`handle`) — host entry — calls it as detector (7) at priority 3\n4. `tests/cochange-nudge.test.ts` — pins the shell-edit shapes and the deliberate silences\n\n## Invariants\n\n- UserPromptSubmit is the ONLY clearing signal. Elapsed time is the wrong shape for a task boundary — an auto-mode run edits for hours with no prompt, and a session id survives a resume days later. A settle clock, the session id, and a 30-min TTL were each tried and rejected as proxies for it. The 7-day sweep in resetEditTrack is garbage collection for abandoned files, never a boundary.\n- The nudge (PostToolUse) and the reset (UserPromptSubmit) are wired by SEPARATE init functions — wireClaudeHooks vs wireClaudeKbHooks — so a repo can have the nudge without the reset. There the list never clears; it degrades quietly rather than loudly, because each file is named at most once.\n- The edit list is its own tmp file, never folded into /tmp/find_nudge_<key>.json, which the search detectors and the preguard's deny-key depend on.\n- Hooks never import from dist/, so the hook MIRRORS getCacheDir/cacheKey. tests/cochange-nudge.test.ts asserts the two paths are equal — without it a rename on the TS side kills the feature silently.\n- only DETERMINISTIC shell writes count; a write to a computed path claims nothing. Measured: the deterministic rules cover 89.2% of real shell writes, and inferring the rest from 'the one source path in the script' added 5.8% while making it possible to name a file the script only READ\n- a heredoc tag is an arbitrary identifier (EOF, PATCH, TS, MSG) — never re-introduce a tag whitelist, it made whole scripts invisible\n- a redirect target is an edit even under a read verb, so `cat > x <<EOF` must not tier x as a read","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-notebook-capture-fires-v5-trigger-timed","hooks-cochange-nudge-mjs-2fa94d26","hooks-evidence-mjs-147e7dd5","hooks-kb-recall-mjs-bb2f72e8","hooks-nudge-handler-mjs-9ca0ef0b","how-the-moves-together-signal-reaches-gs-without-going-throu","src-indexer-cochange-ts-87067890"]},{"id":"hooks-codex-nudge-handler-mjs-f48031e6","type":"file","character":"single","title":"hooks/codex-nudge-handler.mjs","aliases":["codex nudge twin","duplicated detector logic","fix applied to one host only"],"status":"active","updated":"2026-08-25T18:44:33.078Z","edits":1,"anchors":[{"path":"hooks/codex-nudge-handler.mjs","symbols":["handle","resultText","grepPattern","kbSpiralHit"],"hash":"sha256:59c42aa2b899","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Codex's PostToolUse nudge. Verified this session by diffing it against hooks/nudge-handler.mjs: the two files are byte-identical apart from two header-comment lines (the filename and the name of the PreToolUse guard). It is a maintained copy, not a re-implementation, so any detector change must be applied to both in the same commit or Codex silently keeps the old behaviour. Cursor has no third copy — hooks/cursor-nudge-handler.mjs delegates here, so this file is the one that governs two of the three hosts.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap"]},{"id":"hooks-nudge-handler-mjs-9ca0ef0b","type":"file","character":"single","title":"hooks/nudge-handler.mjs","aliases":["postToolUse nudge detectors","grep spiral detector","seen_find_queries registration","cat treated as spiral","nudged while reading files"],"status":"active","updated":"2026-08-25T18:44:33.068Z","edits":1,"anchors":[{"path":"hooks/nudge-handler.mjs","symbols":["handle","resultText","grepPattern","kbSpiralHit","gitFingerprint","gitHead","matchAllGroup"],"hash":"sha256:2eefdfc34529","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Claude's PostToolUse nudge: 7 search-behaviour detectors over a per-(session,agent) /tmp state file, plus registration of every successful find's canonical key for the PreToolUse guard to deny against. What I verified this session is how it decides a call is a READ versus a SEARCH — it used to define a read as `tool === \"Read\"` and list `cat` inside SEARCH_RE, so an agent working through the shell (the auto-mode default) was told it was spiralling for reading files; three cats of three different files fired the anti-grep nudge. Read classification now comes from bashContentRead in evidence.mjs rather than from a regex here, so the nudge and the capture worklist cannot drift on what counts as reading. A command that both reads and searches (`cat x | grep y`) stays a search: the grep is the operative half.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","type":"flow","character":null,"title":"how a shell-mediated file read reaches the nudge and the capture worklist","aliases":["shell read classification","reading via bash","inline script read","intent vs attribution","cat counted as grep spiral","shell reads invisible to capture"],"status":"active","updated":"2026-08-25T18:44:33.030Z","edits":1,"anchors":[{"path":"hooks/evidence.mjs","hash":"sha256:d8b68b9a4e7f","state":"changed"},{"path":"hooks/nudge-handler.mjs","hash":"sha256:2eefdfc34529","state":"fresh"},{"path":"hooks/codex-nudge-handler.mjs","hash":"sha256:59c42aa2b899","state":"fresh"},{"path":"hooks/cursor-nudge-handler.mjs","hash":"sha256:745090ec3b11","state":"fresh"},{"path":"hooks/cursor-input.mjs","hash":"sha256:8fb374fcd6b4","state":"fresh"},{"path":"tests/shell-read-evidence.test.ts","hash":"sha256:233464173f1c","state":"fresh"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"One table in hooks/evidence.mjs decides what counts as reading a file, and it deliberately gives two different answers to two consumers: the PostToolUse nudge asks only whether content was put in front of the agent (bashContentRead), while the capture worklist asks which NAMED file was read (the tier attached to each path token). The same command can therefore clear the grep-spiral nudge while anchoring no note at all — `python3 -c 'print(open(sys.argv[1]).read())' src/cli.ts` is a real read with no literal path to attribute. Both surfaces reach that one table by three different host routes, so a fix applied to Claude's path alone leaves Codex and Cursor silently broken.\n\n## Steps\n\n1. `hooks/evidence.mjs` (`classifyBash`, `inlineScriptTier`, `bashContentRead`) — the single classification table: read verbs, inline-script file-open APIs, and per-token tier\n2. `hooks/nudge-handler.mjs` (`handle`) — Claude PostToolUse consumer — asks INTENT only, via bashContentRead\n3. `hooks/codex-nudge-handler.mjs` (`handle`) — Codex consumer, a verbatim twin of the Claude handler\n4. `hooks/cursor-nudge-handler.mjs` (`handle`) — Cursor consumer — delegates to the Codex handler through adaptCursorInput, so it inherits fixes without its own patch\n5. `hooks/cursor-input.mjs` (`adaptCursorInput`) — renames Cursor's Shell tool to Bash so the shared detectors match unchanged\n6. `tests/shell-read-evidence.test.ts` — pins all three hosts x both surfaces, because a one-host fix fails silently\n\n## Invariants\n\n- `cat` must never go back into SEARCH_RE in either nudge handler — it prints a whole file, which is a Read by another name\n- hooks/nudge-handler.mjs and hooks/codex-nudge-handler.mjs are verbatim twins apart from their header comment; patch both in the same change\n- inline scripts are classified BEFORE the segment split — the splitter cuts on `;`/`|` that are the script's own syntax, not shell operators\n- the read tier attaches only to the path named inside the read call; other path tokens in the same command stay mentions","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","hooks-codex-nudge-handler-mjs-f48031e6","hooks-evidence-mjs-147e7dd5","hooks-nudge-handler-mjs-9ca0ef0b","how-notebook-capture-fires-v5-trigger-timed"]},{"id":"src-cache-disk-cache-ts-1359262b","type":"file","character":"single","title":"src/cache/disk-cache.ts","aliases":["LoadProfile concept","cache segments","gs vs full profiles","disk persistence","cacheKey derivation","getCacheDir","cache path hash","mirrored by hooks","loadCachedIndex returned null","profile passed as second argument"],"status":"active","updated":"2026-08-25T18:18:29.577Z","edits":3,"anchors":[{"path":"src/cache/disk-cache.ts","symbols":["loadCachedIndex","saveCachedIndex","getCacheDir","cacheKey","LoadProfile"],"hash":"sha256:a309616de81d","state":"fresh"}],"freshness":"fresh","dir":"src/cache","outLinks":[],"body":"On-disk index cache with consumer-scoped segments and lazy loading. LoadProfile: 'find' loads table+core+graph (~200ms), 'gs' adds callgraph (500ms on warm cache), 'full' adds build data (keeper only). CLI readers use 'gs' to avoid keeper-only segments. Cache validity = version + gitHead + keeper watcher (no TTL). loadCachedIndex's SECOND positional parameter is baseCacheDir, not the profile — the profile is third, and passing it second silently yields a null cache that reads exactly like a cache miss. Verified 2026-08-25: cacheKey is `<basename>-<sha256(abs)[0:16]>` under coldstartHome()/indexes, and it now has a consumer the import graph cannot see — hooks/cochange-nudge.mjs HAND-COPIES that derivation, because hooks never import from dist/. tests/cochange-nudge.test.ts asserts the copy still agrees; renaming or rekeying here without running it silently breaks the edit-time nudge rather than failing a build.","backlinks":[],"anchorLinks":[]},{"id":"src-indexer-cochange-ts-87067890","type":"file","character":"single","title":"src/indexer/cochange.ts","aliases":["co-change derivation","git log name-status","rename carry forward","moves together pairs","canonicalizeRenames","co-edited partners","touched denominator","ratio denominator absent","no touched entry","denominator missing for file"],"status":"active","updated":"2026-08-25T18:18:29.565Z","edits":2,"anchors":[{"path":"src/indexer/cochange.ts","symbols":["deriveCoChange","canonicalizeRenames","parseCommits","coChangePartnersFor","loadCoChange","saveCoChange","CO_CHANGE_WINDOW","CO_CHANGE_K","coChangePath","CO_CHANGE_MIN_SUPPORT"],"hash":"sha256:b77c94aa16f5","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Derives \"which files move together\" by walking git log --name-status -M and counting files that change in the same commit; stores 8 partners per file, shows 3, min support 2, 12k-commit window (all measured, don't retune blind). The non-obvious part is canonicalizeRenames: -M labels ONLY the rename commit, so every older commit still records the old path and a renamed file silently splits into two half-histories whose older half is keyed to a path that no longer exists and can never be displayed. Because git log is newest-first, the fix is a single forward pass carrying an alias map — a rename old->new seen at commit i means every LATER entry in the stream (i.e. older commit) that says old means new — resolved transitively and only ever recorded backwards, so a path later reused by a different file keeps its own identity. Verified 2026-08-23 on arches: 12k commits in 596ms, 325KB sidecar. 2026-08-25, for consumers computing a RATIO: `touched` is NOT a count for every file in history — it is trimmed to `keep`, i.e. files that got a partner list plus those partners, so a file whose every pair fell below min-support has NO entry at all and any shared/touched calculation must read that absence as silence rather than a zero denominator. Every file that HAS partners does have its denominator, so a ratio gate needs no extra data.","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","how-the-moves-together-signal-reaches-gs-without-going-throu"]},{"id":"github-workflows-ci-yml-899ce9c2","type":"file","character":"single","title":".github/workflows/ci.yml","aliases":["CI workflow","GitHub Actions permissions","workflow permissions block","missing workflow permissions","codeql workflow alert","actions permissions warning"],"status":"active","updated":"2026-08-25T16:34:51.684Z","edits":1,"anchors":[{"path":".github/workflows/ci.yml","hash":"sha256:c93991865d01","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"CI workflow running build+test on ubuntu-latest and windows-latest (matrix added in #159, after ubuntu-only CI hid months of Windows-only bugs). Requires an explicit top-level `permissions: contents: read` block — its absence trips CodeQL's actions/missing-workflow-permissions check; the workflow only checks out/builds/tests so read-only is correct, matching the same block in verify-149-windows-hide.yml.","backlinks":[],"anchorLinks":[]},{"id":"tests-content-tokens-test-ts-1b6e539c","type":"file","character":"single","title":"tests/content-tokens.test.ts","aliases":["related section tests","content token tests","deriveRelatedFiles test","name echo test","related section regressed to full view","import neighbour leaked into related"],"status":"active","updated":"2026-08-23T10:33:43.536Z","edits":1,"anchors":[{"path":"tests/content-tokens.test.ts","symbols":["makeIndex","TOKEN_IN_CODE","TOKEN_IN_STRING","deriveRelatedFiles","deriveNameEchoFiles"],"hash":"sha256:2fd1da4eb640","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers the content-token channel end to end: extractContentTokens, deriveRelatedFiles, deriveNameEchoFiles, and how handleGetStructure renders the Related section. The rendering block is the regression guard for two rules that were each broken once — Related must appear in every gs view (it was full-view-only, so `--view symbols` on a large file dropped the name-reference neighbours that view is used to find), and an import-edge neighbour must stay excluded even in a view that lists no importers, because the heading promises 'no import edge' and the imports/importers lists cannot back that promise when a narrow view leaves them empty. Both directions of the edge are asserted; the exclusion reads index.outEdges/inEdges, not the rendered lists.","backlinks":[],"anchorLinks":[]},{"id":"src-server-tools-ts-cb60011b","type":"file","character":"hub","title":"src/server/tools.ts","aliases":["gs handler","symbol lookup","file presence check","symbol page rendering","bidirectional edges","moves together rendering","gs page builder","handleGetStructure","gs view gating","related section"],"status":"active","updated":"2026-08-23T10:33:43.525Z","edits":6,"anchors":[{"path":"src/server/tools.ts","symbols":["handleGetStructure","findFileByPath","buildCallersForFile","renderSymbolSlice","compileMatchPredicate"],"hash":"sha256:53676513658f","state":"fresh"}],"freshness":"fresh","dir":"src/server","outLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu"],"body":"handleGetStructure builds the gs symbol page for one file. Uses findFileByPath to lookup file: returns [fileId, IndexedFile] if found, null if not indexed. Distinguishes two states: null → file not in index (untracked), [fileId, file with file.symbols=[]] → file indexed but has zero symbols (e.g., CSS). Handles match filtering, symbol slicing, imports/importers, callers per symbol. Critical for kb write reuse: can call loadCachedIndex('gs') then index.files.get(path) to check presence.\n\n## Facets\n\n- **handleGetStructure** — Builds the gs page. findFileByPath distinguishes two states: null = not indexed, [fileId, file with symbols=[]] = indexed but symbol-less (e.g. CSS). It is SYNCHRONOUS and takes the index only, which is why git-derived co-change arrives as an optional THIRD parameter loaded by each caller. The `view` param gates ONLY the sections describing this file — wantSymbols/wantImports/wantImporters/wantInlineCallers. The two cross-file sections, Edited together and Related, are deliberately ungated and render in every view; both were full-view-only once and both misses were found the same way, by a real session asking for `--view symbols` on a god-file. Related is still computed AFTER co-change so co-change's picks can join its excludeIds and a path never prints under two headings. — [[how-the-moves-together-signal-reaches-gs-without-going-throu]]\n- **buildCallersForFile** — Given fileId and file, returns { exportedSymbol, callers[] } by iterating ALL symbolEdges filtering type==='calls' and checking edge.to is exported in the target. No pre-built reverse index; an O(n) walk of symbolEdges per file lookup.\n- **renderSymbolSlice** — calleesOf(symId) walks symbolEdges filtering type==='calls' && from===symId for outgoing targets — bidirectional pattern: callers via incoming edges, callees via outgoing.\n- **compileMatchPredicate** — Compiles the match filter: /regex/, a|b for OR, else case-insensitive substring. Returns null when no filter was requested.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"how-the-moves-together-signal-reaches-gs-without-going-throu","type":"flow","character":null,"title":"how the edited-together signal reaches gs without going through the index","aliases":["co-change sidecar","moves together section","cochange.json","git history signal","co-edited files gs","how the moves-together signal reaches gs without going through the index","edited together section","section missing in view symbols","narrowed gs view drops a section"],"status":"active","updated":"2026-08-23T10:33:43.496Z","edits":4,"anchors":[{"path":"src/index-manager.ts","hash":"sha256:cb324edbaeb8","state":"changed"},{"path":"src/indexer/cochange.ts","hash":"sha256:b77c94aa16f5","state":"fresh"},{"path":"src/cli.ts","hash":"sha256:e863c8636403","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:3f63d980bc9b","state":"changed"},{"path":"src/server/tools.ts","hash":"sha256:53676513658f","state":"fresh"}],"freshness":"changed","dir":"src","outLinks":[],"body":"The \"Edited together\" pairs shown by gs are NOT part of the code index and never travel through the cache pipeline — they live in a separate keeper-written sidecar (cochange.json) that each reader loads itself and hands to handleGetStructure as a THIRD argument. This is why gs can show them at all: handleGetStructure is synchronous and takes only an index, so there was no way to reach git from inside it. Consequence for anyone adding a similar signal: don't try to hang it off CodebaseIndex — the cache is consumer-scoped and gzip-swept, and a reader that already has an index still needs a second explicit load. It also means a surface that forgets to pass the argument silently renders nothing rather than erroring. The section was called \"Moves together\" until 2026-08-23; the old name survives in identityAliases on purpose so a search for it still lands here.\n\n## Steps\n\n1. `src/index-manager.ts` (`refreshCoChange`, `startWatching`, `scheduleCacheSave`) — keeper derives it at watch start and whenever HEAD moves, then writes the sidecar\n2. `src/indexer/cochange.ts` (`deriveCoChange`, `saveCoChange`, `loadCoChange`, `coChangePartnersFor`) — the git walk, the sidecar read/write, and the render selector\n3. `src/cli.ts` (`runGs`) — CLI reader loads the sidecar and passes it as the third argument\n4. `src/server/mcp.ts` (`registerToolHandlers`) — MCP reader re-loads it per call, since the keeper rewrites it on branch switch\n5. `src/server/tools.ts` (`handleGetStructure`) — renders the section in EVERY view, excluding this file's import-graph neighbours (index.outEdges/inEdges) rather than whichever lists the current view happens to print\n\n## Invariants\n\n- Derivation is keyed on git HEAD, not on file edits — an uncommitted change never re-walks history.\n- Absent sidecar renders NO section at all, never an empty one: silence must not read as 'nothing moves with this file'.\n- The sidecar is plain JSON, not .gz — saveCachedIndex sweeps *.gz on every save and would delete it.\n- The section is full-view only; the narrowed gs views never show it.\n- The section renders in every gs view. It was full-view-only until 2026-08-23, and the first real session that could have used it asked for `--view symbols` on a god-file, so the channel was unreachable at exactly the moment it was wanted. Do not re-gate it on view.\n- The exclusion set is read from index.outEdges/inEdges, NOT from importsOut/importersShown. The heading claims these pairs carry no import edge, and that claim is only true if every graph neighbour is excluded — narrow views populate neither list, and full view's importer list is capped, so a view-scoped exclusion leaks importers into the section under a false heading.\n- Absent sidecar renders NO section at all, never an empty one: silence must not read as 'nothing was edited with this file'.\n- The user-facing name is 'Edited together' everywhere: the gs heading, the graph viewer's relation label, `status`, the site docs and the agent guidance in coldstart.md and templates/. The graph viewer's label lives in scripts/graph-viewer/sphere.template.html and reaches src/graph/view-template.ts only via build-template.mjs, so a rename that skips that script silently leaves the old word in the shipped viewer.\n- BOTH cross-file sections — Edited together and Related — render in every gs view. Each was full-view-only once, and each time the miss surfaced the same way: a real session asked for `--view symbols` on a god-file, which is exactly when the other-file channels matter most. Only the sections describing THIS file (symbols/imports/importers/callers) are view-gated. Do not re-gate either one.\n- Both sections build their exclusion set from index.outEdges/inEdges, NOT from importsOut/importersShown. Both headings claim the pair carries no import edge, and that is only true if every graph neighbour is excluded — narrow views populate neither list, and full view's importer list is capped at IMPORTERS_LIST_CAP.","backlinks":["src-server-tools-ts-cb60011b"],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","src-cli-ts-c443bc51","src-index-manager-ts-e298456b","src-indexer-cochange-ts-87067890","src-server-mcp-ts-18031783","src-server-tools-ts-cb60011b","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"scripts-graph-viewer-build-site-page-mjs-9bf323da","type":"file","character":"single","title":"scripts/graph-viewer/build-site-page.mjs","aliases":["site graph page generator","build-site-page","graph viewer site build","home link missing on graph page","MODULE_NOT_FOUND dist import"],"status":"active","updated":"2026-08-23T08:55:06.098Z","edits":1,"anchors":[{"path":"scripts/graph-viewer/build-site-page.mjs","symbols":["OUT","distImport","GRAPH_TEMPLATE"],"hash":"sha256:06a14e3a2f4e","state":"changed"}],"freshness":"changed","dir":"scripts/graph-viewer","outLinks":[],"body":"Generates the site's copy of the graph viewer by importing the BUILT dist/ modules (loadCachedIndex, loadCoChange, buildGraphPayload, renderGraphHtml, GRAPH_TEMPLATE), so `npm run build` must run first or it fails with MODULE_NOT_FOUND. Two constraints learned by getting them wrong: it passes an empty notes array, because the notebook is this repo's private working memory and note titles are not marketing copy; and it substitutes the home link into GRAPH_TEMPLATE BEFORE calling renderGraphHtml, since renderGraphHtml clears that slot for the standalone CLI page which has nowhere to link back to. Output is site-astro/src/graph-page.html, not public/, so an Astro route can serve /graph/ in dev.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-pages-graph-index-astro-797635e1","type":"file","character":"single","title":"site-astro/src/pages/graph/index.astro","aliases":["graph route","graph page astro","serve graph html","graph 404 in astro dev","public dir directory index 404"],"status":"active","updated":"2026-08-23T08:55:06.087Z","edits":1,"anchors":[{"path":"site-astro/src/pages/graph/index.astro","symbols":["html","raw"],"hash":"sha256:b3841695f407","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/graph","outLinks":[],"body":"Serves /graph/ by inlining site-astro/src/graph-page.html (a complete standalone document with its own head, CSS and canvas script) via a ?raw import into a bare <Fragment set:html>. It exists as a ROUTE rather than as public/graph/index.html because `astro dev` serves public/ by exact path with no directory-index fallback: the file answered /graph/index.html and 404'd on /graph/, the URL the nav links to, while production resolved it fine — a dev-only break invisible in CI. Being a route also puts /graph/ in the sitemap. It strips the generated file's leading doctype because Astro emits its own ahead of the template.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-components-docssidebar-astro-93ed0ec3","type":"file","character":"single","title":"site-astro/src/components/DocsSidebar.astro","aliases":["docs sidebar","progressive disclosure sidebar","active group prop","empty sidebar section headers","group header with no items"],"status":"active","updated":"2026-08-23T08:55:06.073Z","edits":2,"anchors":[{"path":"site-astro/src/components/DocsSidebar.astro","symbols":["Props","groups",".gh-link","gh-link","is-active"],"hash":"sha256:114a6d940ca0","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Reusable docs sidebar: an `active` prop ('getting-started'|'navigation'|'notebook'|'under-the-hood') selects which group expands its anchor sub-list; other groups collapse to a single link. Only the ACTIVE group's label carries the `gh` class (uppercase, tracked, muted — docs.css `.side-group .gh`). Every group used to carry it, so on any page the three inactive groups rendered as section headers with nothing beneath them: headings labelling nothing. The `.gh-link` scoped override still exists and is load-bearing for a different reason — it cancels docs.css's global `.side a.active` pill so the active group header is not double-highlighted on top of the active sub-link's own pill.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"tests-cochange-test-ts-09288f99","type":"file","character":"single","title":"tests/cochange.test.ts","aliases":["cochange tests","git fixture repo","moves together tests","moves together test","deriveCoChange test","flaky only in full suite","vitest timeout leaks fixture state"],"status":"active","updated":"2026-08-23T08:55:06.059Z","edits":2,"anchors":[{"path":"tests/cochange.test.ts","symbols":["git","commit","makeIndex","gsText"],"hash":"sha256:df9963d3865c","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Covers deriveCoChange (the git walk) and the gs rendering of the Moves together section. Two things a future editor needs: the helpers `git`/`commit` take the repo dir as an explicit parameter and must keep doing so — they once read a module-level `repo` that each scratch-repo test swapped and restored, and when the ~90-commit partner-cap test overran vitest's 5s default under full-suite load vitest moved on while the swap was live, so later tests silently ran against the wrong repo and the suite failed only under load. That test now carries an explicit 60s timeout for the same reason. The rendering block asserts co-change appears in EVERY gs view and that import-graph neighbours stay excluded even in a view that lists neither imports nor importers.","backlinks":[],"anchorLinks":[]},{"id":"src-graph-dump-ts-043aa709","type":"file","character":"single","title":"src/graph/dump.ts","aliases":["graph payload builder","directory band assignment","adaptive clustering","relation kinds","codebase sphere data"],"status":"active","updated":"2026-08-23T07:09:22.362Z","edits":1,"anchors":[{"path":"src/graph/dump.ts","symbols":["assignClusters","buildGraphPayload","REL_IMPORT","REL_CALLS","REL_COEDIT","REL_NOTE"],"hash":"sha256:b74220e57359","state":"changed"}],"freshness":"changed","dir":"src/graph","outLinks":[],"body":"Turns an already-built index (plus the co-change sidecar and note anchors handed in by the caller) into the compact payload `coldstart graph` draws. Two things here are load-bearing and were both arrived at by getting them wrong: directory bands are chosen ADAPTIVELY by assignClusters (split any band over 13% one segment deeper, then fold slivers into a terminal 'other' that is itself allowed to stay small), because a fixed depth-2 cut put 1093 of arches's 1615 files in one band; and the named verbs on call edges come from aggregating index.symbolEdges per FILE PAIR, because every edge in index.edges is a plain import and carries no verb. This module deliberately loads nothing — no index build, no notebook read — so it stays a pure function that tests can drive.","backlinks":[],"anchorLinks":[]},{"id":"src-server-mcp-ts-18031783","type":"file","character":"single","title":"src/server/mcp.ts","aliases":["required note fields","no-shell client notes","TOOL_DEFINITIONS","mcp cli parity","kb_repair_aliases tool","offset browsing only","aliasesVerified closing move","MCP wiring","tool registration","handler dispatch","tool schema","long-lived server stale read","mcp tool missing section","stale sidecar in mcp"],"status":"active","updated":"2026-08-22T19:02:26.308Z","edits":9,"anchors":[{"path":"src/server/mcp.ts","symbols":["TOOL_DEFINITIONS","registerToolHandlers","missingFieldsWarning","flowStepsWarning","kb_repair_aliases"],"hash":"sha256:3f63d980bc9b","state":"changed"}],"freshness":"changed","dir":"src/server","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"MCP server tool registration and handler dispatch. TOOL_DEFINITIONS declares every tool (name, description, inputSchema); the CallToolRequestSchema switch dispatches by name to handlers that call shared engines and wrap results as {__rawText} for text or JSON. Adding a query command = one TOOL_DEFINITIONS entry + one case + a shared engine; REMOVING one means both, and the tool description too, since the description is the only place an MCP client learns a section exists. Verified 2026-08-23: unlike the CLI, this server is long-lived, so a sidecar it reads (co-change) must be re-loaded per call — a copy cached at startup goes stale the moment the keeper rewrites it on a branch switch.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — kb_write description injects the required-fields line","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-cli-ts-c443bc51","type":"file","character":"single","title":"src/cli.ts","aliases":["CLI entry point","command routing","keeper spawning","cache read strategy","parseQueryArgs","reader loads sidecar"],"status":"active","updated":"2026-08-22T19:02:12.600Z","edits":3,"anchors":[{"path":"src/cli.ts","symbols":["runGs","runConsumers","getIndex","runFind","parseQueryArgs"],"hash":"sha256:e863c8636403","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"CLI command routing and execution — entry point for `find`, `gs`, `index`, `consumers`, and `kb`. Key pattern: runGs calls ensureKeeper before the cache load (keeps the index fresh for uncommitted edits) while runConsumers loads the cache directly with no keeper (pure read for capture hooks); the choice turns on whether the command needs live freshness. runGs also loads the co-change sidecar itself and passes it into handleGetStructure — reader-side, because handleGetStructure cannot reach disk. parseQueryArgs is a flat switch over every flag any subcommand accepts, so a flag added for one command is silently accepted by all of them; removing a command means removing its flags here too or they linger as dead accepted input.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-status-ts-8c69c9ca","type":"file","character":"single","title":"src/status.ts","aliases":["npm update didn't take","update not picked up","keeper running old version","install health","wired hook path missing","version drift","moves-together not derived","gs shows no moves together","co-change silent shallow clone"],"status":"active","updated":"2026-08-22T19:02:12.589Z","edits":5,"anchors":[{"path":"src/status.ts","symbols":["runStatus","wiredHookPaths","indexFreshness","deriveRoot","relativeAge","fileSize"],"hash":"sha256:d9ea936f4f43","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"Renders `coldstart status`: a network-free table of every keeper (liveness via lockfile PID check, index freshness from cache meta.json mtime, keeper-state.json/repair.jsonl activity). The install-health section diagnoses the 'npm update didn't take' class — it compares each keeper's lock version to getCurrentVersion() and flags drift with a `coldstart restart` remedy, and via wiredHookPaths() scans .claude/settings.json as RAW TEXT (structure-agnostic regex for /…/hooks/<name>.mjs) to flag dangling wired hook paths with a `coldstart init` remedy. The per-root activity block also prints a moves-together line (2026-08-23) for a specific reason: co-change is silent on shallow clones and non-git dirs, and without a line saying how many commits were scanned that silence is indistinguishable from a bug.","backlinks":[],"anchorLinks":[]},{"id":"src-index-manager-ts-e298456b","type":"file","character":"single","title":"src/index-manager.ts","aliases":["keeper regenerates view","notes refresh HTML","kb-notes sidecar","auto mechanical symbol repair","mechanicalRepairStreak","auto symbol backfill keeper","MAX_AUTO_REPAIR_STREAK","sidecar refresh hook","autoMechanicalSymbolRepair","keeper sidecar refresh","refreshCoChange","co-change keyed on HEAD","auto repair silently off","keeper stopped backfilling"],"status":"active","updated":"2026-08-22T19:02:12.568Z","edits":6,"anchors":[{"path":"src/index-manager.ts","symbols":["IndexManager","refreshKbNotesIndex","regenerateKbViewIfPresent","handleNotebookRawBatch","handleBatch","triggerRebuild","scheduleCacheSave","auditFingerprints","startCacheWatcher","startWatching","scheduleRebuildRetry","IndexContext","autoMechanicalSymbolRepair","MAX_AUTO_REPAIR_STREAK","refreshCoChange"],"hash":"sha256:cb324edbaeb8","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"Keeper state machine: watch, patch-vs-rebuild, atomic cache save, plus the notebook sidecar refresh and (2026-08-23) the co-change sidecar refresh. autoMechanicalSymbolRepair fires right after every kb-notes-index rebuild and passes the just-built sidecar in memory; its MAX_AUTO_REPAIR_STREAK=3 guard is one-way — once the streak reaches the cap the method returns before running, so the pass that would reset it never happens and auto-backfill stays off for the keeper's lifetime (safe direction, now logged once naming `coldstart kb repair`). refreshCoChange is deliberately keyed on git HEAD rather than on the debounced file batch: history only changes when a commit lands, so re-walking on every patch would burn ~600ms for a byte-identical result. It is called from startWatching (seed) and from inside scheduleCacheSave's getGitHead().then, which is the one place the keeper already knows HEAD moved.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu"]},{"id":"src-indexer-invariants-ts-7c3ad34a","type":"file","character":"single","title":"src/indexer/invariants.ts","aliases":["invariant lint","index corruption check","lintIndexInvariants","rebuild trigger","constant rebuilds","index keeps rebuilding"],"status":"active","updated":"2026-08-22T17:11:07.187Z","edits":1,"anchors":[{"path":"src/indexer/invariants.ts","symbols":["lintIndexInvariants","assertedFile"],"hash":"sha256:f1ad4a72cd14","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Post-patch structural lint whose output is a rebuild trigger, not a warning — so any check it fails must be fixable by rebuilding, or the keeper loops. assertedFile encodes that trade-off explicitly: bare extends/implements targets are exempt from the file-existence check because flagging them would make every repo with inheritance rebuild forever, and the same reasoning applies to any new edge kind whose endpoints are not guaranteed to be indexed files.","backlinks":[],"anchorLinks":["how-synthetic-edges-stay-alive-across-incremental-patches"]},{"id":"src-indexer-patch-ts-d18fe20b","type":"file","character":"single","title":"src/indexer/patch.ts","aliases":["incremental patch","patchIndex","index patching","changed file batch","stale edges after edit","synthetic edges missing after patch"],"status":"active","updated":"2026-08-22T17:11:07.177Z","edits":1,"anchors":[{"path":"src/indexer/patch.ts","symbols":["patchIndex"],"hash":"sha256:c7955d82d0b1","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Incremental index patcher: pre-plans delete/update/skip for the whole batch before mutating anything, so a parse failure never strips a file's existing state. Its synthetic-edge re-derivation at the end is language-gated — each family only re-runs when a file of its language changed — which is what keeps derived edges alive across edits and also what would silently skip a family driven by a non-source input.","backlinks":[],"anchorLinks":["how-synthetic-edges-stay-alive-across-incremental-patches"]},{"id":"how-synthetic-edges-stay-alive-across-incremental-patches","type":"flow","character":null,"title":"how synthetic edges stay alive across incremental patches","aliases":["synthetic edges","rails synthetic edges","edge re-derivation","patch symbol edges","changedLangs gate","edges disappear after edit","endless rebuild loop","edge points at deleted file"],"status":"active","updated":"2026-08-22T17:11:07.149Z","edits":1,"anchors":[{"path":"src/indexer/patch.ts","hash":"sha256:c7955d82d0b1","state":"fresh"},{"path":"src/indexer/invariants.ts","hash":"sha256:f1ad4a72cd14","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Synthetic edges are never stored in the index — they are re-derived from scratch on every build AND every incremental patch, which is the only reason they survive an edit at all, because patchIndex replaces a changed file's symbolEdges wholesale and strips both directions of its flat edges on delete. The re-derivation inside patch is gated on the CHANGED FILE'S LANGUAGE (changedLangs.has('ruby') etc.), so any future synthetic-edge family whose input is not a source file of that language — e.g. one derived from the notebook — would never be refreshed by an ordinary code edit and needs its own trigger. A synthetic edge whose endpoint file no longer exists is not merely ignored: lintIndexInvariants check 3 reports it and the keeper queues a full rebuild, and since a rebuild re-runs the same derivation, a derivation that keeps emitting a dead endpoint rebuilds forever. Derivations must therefore filter endpoints against index.files themselves.\n\n## Steps\n\n1. `src/indexer/patch.ts` (`patchIndex`) — replaces a changed file's symbol edges wholesale, then re-runs each synthetic-edge family gated on the changed languages\n2. `src/indexer/invariants.ts` (`lintIndexInvariants`, `assertedFile`) — flags any symbol edge whose asserted file side is absent from index.files; a violation makes the keeper rebuild\n\n## Invariants\n\n- Synthetic edges are a derivation, never persisted data — anything written into the index by hand is wiped on the next patch of that file.\n- Every synthetic-edge derivation must drop endpoints not present in index.files, or invariant check 3 turns into a rebuild loop.\n- assertedFile deliberately exempts bare extends/implements targets from the existence check; only refs carrying a '#' (and the exports edge's from-side) assert a file.","backlinks":[],"anchorLinks":["src-indexer-invariants-ts-7c3ad34a","src-indexer-patch-ts-d18fe20b"]},{"id":"src-kb-lookup-ts-772ecb1e","type":"file","character":"single","title":"src/kb/lookup.ts","aliases":["notebook query","kb lookup","flow step resolution","flow anchoring","flow-note bridging","anchor derivation"],"status":"active","updated":"2026-08-18T13:32:29.093Z","edits":1,"anchors":[{"path":"src/kb/lookup.ts","symbols":["kbLookup","LookupFlowHit"],"hash":"sha256:e38615ce2a2b","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"Query interface for the notebook at a specific file-or-symbol address. The `kbLookup` function returns everything anchored there: file notes (facets, features, character), flow notes with their step positions, and lessons—all with live freshness stamps. Flow note anchors are derived at query time from flow steps, so backlinks never go stale. Flow notes bridge files the code graph cannot connect (same tmpdir, hand-typed names, convention-only links), operationalizing the design rule that notebook is the source of truth for runtime/data/convention-only edges.","backlinks":[],"anchorLinks":[]},{"id":"how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","type":"flow","character":null,"title":"how to wire a new query command to both CLI and MCP surfaces","aliases":["add query command","CLI MCP wiring","dual-surface query pattern"],"status":"active","updated":"2026-08-18T13:26:14.581Z","edits":1,"anchors":[{"path":"src/cli.ts","hash":"sha256:98bdb7bfb4d0","state":"changed"},{"path":"src/server/tools.ts","hash":"sha256:5a3326747281","state":"changed"},{"path":"src/server/find.ts","hash":"sha256:ec1c7ebf22d1","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:f8995189f3a1","state":"changed"},{"path":"src/index.ts","hash":"sha256:d4b06f304d61","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"To add a new query command (e.g., `trace`), implement a shared engine returning {__rawText} that both CLI and MCP call through thin wrappers. The pattern: CLI registration in main() → parse args → load cache → call shared engine → emit __rawText; MCP registration in TOOL_DEFINITIONS + CallToolRequestSchema → parse params → call shared engine → wrap __rawText in MCP response. This ensures identical results on both surfaces from one implementation.\n\n## Steps\n\n1. `src/cli.ts` (`runFind`, `runGs`, `getIndex`) — CLI wrapper: parseQueryArgs, load cache, call shared engine, print __rawText\n2. `src/server/tools.ts` (`handleFind`, `handleGetStructure`) — MCP adapter: calls shared engines, wraps __rawText in response object\n3. `src/server/find.ts` (`buildRichPage`) — shared engine (find): business logic, returns __rawText\n4. `src/server/mcp.ts` (`TOOL_DEFINITIONS`, `registerToolHandlers`) — MCP registration: tool schema definition and CallToolRequestSchema case handler\n5. `src/index.ts` (`main`, `makeCacheReader`) — entry dispatch: subcommand check for CLI, cache reader factory for MCP\n\n## Invariants\n\n- Every query command's shared engine returns {__rawText: string} with optional {error: string}\n- CLI: emit __rawText directly to stdout; MCP: wrap unchanged in content[0].text\n- Cache loading: getIndex (CLI, per-query) vs makeCacheReader (MCP, long-lived with mtime polling)","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","src-cli-ts-c443bc51","src-index-ts-c5fb8502","src-server-find-ts-d168bf57","src-server-mcp-ts-18031783","src-server-tools-ts-cb60011b","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-server-find-ts-d168bf57","type":"file","character":"hub","title":"src/server/find.ts","aliases":["why does find not show my note","note exists but find did not surface it","buildNoteMap path keyed","find notebook lane","ranking algorithm","term scoring"],"status":"active","updated":"2026-08-18T13:25:59.595Z","edits":4,"anchors":[{"path":"src/server/find.ts","symbols":["buildNoteMap","noteLine","buildRichPage","convergencePreview","collectCoverage","firstSentence","parseTerms","pickSearcher","computeImportRelations","docFreq"],"hash":"sha256:ec1c7ebf22d1","state":"changed"}],"freshness":"changed","dir":"src/server","outLinks":[],"body":"find's notebook lane is PATH-KEYED, not query-keyed: buildNoteMap() iterates active notes and maps anchor path -> note, so a note can only ever surface if its anchor file ALREADY ranked in find's code-side results. The query terms are used solely to break ties on hub files that anchor several notes (the `hits` count on the note's title+aliases+facet symbols), never to admit a note. Consequence verified 2026-07-28: a note whose file find does not rank is invisible to find no matter how strongly the note matches -- measured on 16 relevant hook injections, 7 (44%) anchored to a file find did NOT rank on the same terms (e.g. prompt words 'images beyond text maybe increase' -> site/docs.css, which contains no matching code token). The prompt-time recall hook, not find, is what reaches those. noteLine() renders the inline 'Summary:' at the read-decision point deliberately (ruling recorded at find.ts:457) -- do not hoist notes into a header block.\n\n## Facets\n\n- **buildNoteMap** — PATH-KEYED: iterates active notes and maps anchor path -> note. A note can only surface if its anchor file ALREADY ranked in find's code-side results. Query terms used only to break ties on hub files (hits count on title+aliases+facet symbols), never to admit a note. Consequence: a file find does not rank is invisible to find no matter how strongly the note matches.\n- **buildRichPage** — Lines 553–932: Main entry point. Calls collectCoverage() for term matching (body+name+path), then score() to rank candidates. score() (lines 588–603) = (term_coverage_set.size × 3) + (separator-folded name/path match weight / maxIdf). Ranking: idf (BM25-style log rarity) weights symbol name matches (NAME_W=3) and path matches (PATH_W=2). Re-rankable for frontier traversal via idf(), docFreq(), term coverage sets, separator-folded matching (foldSep strips -_).\n- **collectCoverage** — Lines 260–321: Returns Map<fileId, Set<queryTerms>>. External searchers (rg/git grep/grep) for body-content matches (lines 271–292) + symbol name/path index matches (lines 304–319). Node fallback reads indexed files.\n- **convergencePreview** — Lines 379–456: Scores matched lines by rarity-weighted LOCAL CONVERGENCE—sum of 1/DF over distinct query terms within ±WINDOW lines. Import lines boosted (1.5×). Clusters kept hits by proximity, ranked by peak score. Returns line-level evidence for file preview.","backlinks":[],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-index-ts-c5fb8502","type":"file","character":"hub","title":"src/index.ts","aliases":["command hangs","unknown command","MCP reader boots unexpectedly","command dispatch","graph building","index accumulation"],"status":"active","updated":"2026-08-18T13:25:59.573Z","edits":5,"anchors":[{"path":"src/index.ts","symbols":["main","buildIndex"],"hash":"sha256:d4b06f304d61","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"## Facets\n\n- **main** — Dispatch order is load-bearing, not stylistic. Everything past the subcommand block is treated as a flag-driven invocation (--daemon / --no-daemon / --probe / the default stdio MCP reader), and the unknown-command guard deliberately rejects only a first arg that does NOT start with '-'. So any bare flag falls through and BOOTS THE MCP READER. Fixed by handling --version/-v and --help/-h first by exact match.\n- **buildIndex** — Lines 221–223: allSymbolEdgesBuilt = buildSymbolEdges() accumulates into symbolEdges array, then assigned to CodebaseIndex.symbolEdges at line 274. Lines 225–268: isBarrel flag set on TS/JS files (reexportRatio > 0.5 && importedByCount > 1 && exports.length > 0), then domain-map cleaned and transitiveImportedByCount computed for graph traversal. These setup cycle-guard structures: isBarrel + reexportRatio + transitiveImportedByCount are load-bearing for traversal algorithms that need to bypass re-export hubs.","backlinks":[],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-indexer-symbol-edges-ts-907b1d63","type":"file","character":"single","title":"src/indexer/symbol-edges.ts","aliases":["edge building","call resolution","symbol edge creation","bare-name edges dropped"],"status":"active","updated":"2026-08-18T13:25:59.561Z","edits":1,"anchors":[{"path":"src/indexer/symbol-edges.ts","symbols":["buildSymbolEdges"],"hash":"sha256:8c0cbcb23ac3","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Builds symbol-level edges (calls/extends/implements/exports) by resolving call targets against imported files' exports. Critical: unresolvable bare-name 'calls' edges are dropped as noise (line 100–102) because query-time lookups use qualified symbolIds and bare names never match. Call resolution: Pass 1 tests direct export match; Pass 2 tests suffix match (Java 'Class.method', Ruby 'Module::Class') across qualified exports. Extends/implements bare names are kept (resolved at query time).","backlinks":[],"anchorLinks":[]},{"id":"src-types-ts-cdcae080","type":"file","character":"single","title":"src/types.ts","aliases":["edge types","SymbolEdge interface","IndexedFile structure","edge model"],"status":"active","updated":"2026-08-18T13:25:59.526Z","edits":1,"anchors":[{"path":"src/types.ts","symbols":["SymbolEdgeType","SymbolEdge","IndexedFile","CodebaseIndex"],"hash":"sha256:ad5ba9213feb","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Defines the edge types, SymbolEdge/Edge interfaces, and IndexedFile structure that all traversal and indexing logic builds on. SymbolEdge carries from/to (qualified symbolId or fileId), type (calls/extends/implements/exports), and optional line number. IndexedFile holds symbols, exports, isBarrel flag, reexportRatio, and importedByCount—these are load-bearing for cycle guards and barrier detection in graph traversal.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-pages-docs-under-the-hood-astro-9d2b1520","type":"file","character":"single","title":"site-astro/src/pages/docs/under-the-hood.astro","aliases":["under the hood docs page","supported languages section","lifecycle commands docs"],"status":"active","updated":"2026-08-16T16:51:41.613Z","edits":2,"anchors":[{"path":"site-astro/src/pages/docs/under-the-hood.astro","symbols":["#freshness","#lifecycle","#mcp","#languages"],"hash":"sha256:7eeb7e9309f7","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/docs","outLinks":[],"body":"One of the 4 docs sub-pages: covers index freshness (with the inline architecture SVG), lifecycle commands, MCP tool exposure, bring-your-own-semantics, and supported languages. The language chips (.langs/.chip) previously had a .chip.hot tier arbitrarily coloring some languages blue with no explanation — removed so all chips render uniformly. Its closing sidebar-highlight script is one of 4 duplicated copies, now scroll-position-based rather than IntersectionObserver-based (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-src-pages-docs-navigation-astro-e37c5fa9","type":"file","character":"single","title":"site-astro/src/pages/docs/navigation.astro","aliases":["docs navigation","find command reference","gs command reference","docs sub-page"],"status":"active","updated":"2026-08-16T16:51:41.602Z","edits":3,"anchors":[{"path":"site-astro/src/pages/docs/navigation.astro","symbols":["techArticleJsonLd"],"hash":"sha256:76baa0869608","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/docs","outLinks":[],"body":"Docs sub-page for coldstart find and gs commands. Follows docs.astro template: frontmatter imports (Head, SvgDefs, Nav, Footer, DocsSidebar), TechArticle JSON-LD, two doc sections (#find and #gs) with command signature, terminal examples, flags, and callouts. DocsSidebar uses active=\"navigation\". Its closing sidebar-highlight script is one of 4 duplicated copies, now scroll-position-based rather than IntersectionObserver-based (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-src-pages-docs-notebook-astro-474cc129","type":"file","character":"single","title":"site-astro/src/pages/docs/notebook.astro","aliases":["notebook docs","kb reference","docs sub-page template"],"status":"active","updated":"2026-08-16T16:51:41.586Z","edits":3,"anchors":[{"path":"site-astro/src/pages/docs/notebook.astro","symbols":["techArticleJsonLd"],"hash":"sha256:b28346763f30","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/docs","outLinks":[],"body":"Notebook reference page. Section ids (notebook, kb-search, kb-lookup, kb-write, kb-commit, kb-view, kb-maint, sharing) are linked by DocsSidebar and must be preserved. Trimmed this session: the 'why it can be trusted' bullet list, capture-internals detail (worklist lifecycle, per-agent keying), and a marketing callout were cut or condensed — that rationale now lives only at /how-it-works/notebook/, linked from this page instead of duplicated inline. The closing sidebar-highlight script is a scroll-position check, not IntersectionObserver — it's copied verbatim into 3 other docs pages (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script"]},{"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","character":"single","title":"site-astro/src/pages/docs.astro","aliases":["docs page","structured data","brand terminology binding","docs landing page"],"status":"active","updated":"2026-08-16T16:51:41.575Z","edits":5,"anchors":[{"path":"site-astro/src/pages/docs.astro","symbols":["techArticleJsonLd","doc-sec#notebook","doc-sec#freshness","overview","install","flow","next"],"hash":"sha256:9faa0af4d67d","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"Docs landing page — sidebar reference layout on docs.css, with its own TechArticle JSON-LD and its own Google Fonts <link> block (not centralised in Head.astro). Sections are #overview, #install, #flow, #next; #next's fcards link out to the 3 docs sub-pages (navigation, notebook, under-the-hood) — there is no #notebook or #freshness section on this page itself, that content lives in the sub-pages now. Inline links in docs prose are styled per-link with style=\"color:var(--frost)\" — there is no link class in docs.css. Its closing sidebar-highlight script is one of 4 duplicated copies (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","type":"flow","character":null,"title":"docs pages share a hand-duplicated sidebar scrollspy script, not an import","aliases":["docs sidebar scrollspy script","sidebar active section highlight","duplicated docs script","docs sidebar highlight mechanism","last sidebar item never highlighted","sidebar highlight stuck wrong item","docs sidebar highlight bug"],"status":"active","updated":"2026-08-16T16:51:41.501Z","edits":1,"anchors":[{"path":"site-astro/src/pages/docs.astro","hash":"sha256:9faa0af4d67d","state":"changed"},{"path":"site-astro/src/pages/docs/navigation.astro","hash":"sha256:76baa0869608","state":"changed"},{"path":"site-astro/src/pages/docs/notebook.astro","hash":"sha256:b28346763f30","state":"fresh"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","hash":"sha256:7eeb7e9309f7","state":"fresh"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"The sidebar active-section highlight script on the 4 docs pages (docs.astro, docs/navigation.astro, docs/notebook.astro, docs/under-the-hood.astro) is copy-pasted verbatim into each page's own closing <script> block, not extracted into a shared component or module — so any behavior change or bug fix has to be hand-applied to all 4 files identically. Verified this session while fixing a bug where the previous IntersectionObserver version (rootMargin '-70px 0px -70% 0px', i.e. a trigger band covering only the top ~30% of the viewport) never highlighted the LAST section's sidebar link on normal/large screens: a short last section's heading could stop being scrolled toward (footer below it, or the user simply stopping once it's comfortably in view) before its top ever crossed into that narrow band. Replaced the mechanism in all 4 files with a scroll/resize-driven position check that walks sections top-to-bottom and marks active the last one whose top has crossed a fixed offset line (70px + 30% of viewport height) — same visual trigger point as before, but not dependent on an element re-entering a band, so the last section reliably activates once scrolled to, regardless of footer height or viewport size.\n\n## Steps\n\n1. `site-astro/src/pages/docs.astro` (`setActive`) — one of 4 duplicate copies of the scrollspy script\n2. `site-astro/src/pages/docs/navigation.astro` (`setActive`) — duplicate copy\n3. `site-astro/src/pages/docs/notebook.astro` (`setActive`) — duplicate copy\n4. `site-astro/src/pages/docs/under-the-hood.astro` (`setActive`) — duplicate copy\n\n## Invariants\n\n- The script is not shared via import or component — changing scrollspy behavior means editing all 4 files identically, or a future page will silently regress.\n- The offset (70px + 30% of viewport height) intentionally mirrors the old IntersectionObserver's visual crossing point, so the highlight timing feels unchanged even though the mechanism is now scroll-position-based, not intersection-based.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand","site-astro-src-pages-docs-astro-d1cf6fe9","site-astro-src-pages-docs-navigation-astro-e37c5fa9","site-astro-src-pages-docs-notebook-astro-474cc129","site-astro-src-pages-docs-under-the-hood-astro-9d2b1520"]},{"id":"scripts-win-repro-detachedlauncher-cs-2d8b5bf1","type":"file","character":"single","title":"scripts/win-repro/DetachedLauncher.cs","aliases":["DETACHED_PROCESS launcher","Win32 CreateProcess repro","hooks-shape console repro","hooks flash confirmed fixed","DETACHED_PROCESS resolves inconclusive repro"],"status":"active","updated":"2026-08-11T05:36:34.763Z","edits":1,"anchors":[{"path":"scripts/win-repro/DetachedLauncher.cs","symbols":["Main"],"hash":"sha256:e65597a5876f","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Replaces an earlier launcher (NoConsoleLauncher.cs, deleted) that used .NET's ProcessStartInfo.CreateNoWindow and produced an inconclusive A/B (no flash in either branch, since CreateNoWindow leaves a hidden-but-attached console that a grandchild process just reuses). This launcher calls Win32 CreateProcess directly with the real DETACHED_PROCESS flag (0x00000008), giving the launched node.exe genuinely no console object at all — the actual condition an Electron app's (Claude Code/Cursor) hooks/*.mjs child process runs under. Verified on real Windows 11 hardware: unpatched shows a new console window, patched shows nothing, confirmed by both the automated IsWindowVisible poll and direct visual observation.","backlinks":[],"anchorLinks":[]},{"id":"scripts-win-repro-watch-ps1-7c70124a","type":"file","character":"single","title":"scripts/win-repro/watch.ps1","aliases":["windowsHide repro driver","IsWindowVisible watcher","Run-Case"],"status":"active","updated":"2026-08-11T05:36:34.734Z","edits":3,"anchors":[{"path":"scripts/win-repro/watch.ps1","symbols":["Run-Case"],"hash":"sha256:f5632bae5e65","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"PowerShell driver for the #149 A/B repro flow: compiles DetachedLauncher.cs via csc.exe, then Run-Case runs 4 cases (unpatched/patched daemon-shape via orchestrator.mjs, unpatched/patched hooks-shape by launching DetachedLauncher.exe directly) and polls the real Win32 IsWindowVisible API. Both pairs now produce a confirmed flash/no-flash split — the earlier winexe+CreateNoWindow launcher (NoConsoleLauncher.cs/orchestrator-noconsole.mjs, both since deleted) gave an inconclusive result and was replaced by DetachedLauncher.cs, which uses the real Win32 DETACHED_PROCESS flag instead. See the flow note for the full root-cause story.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"github-workflows-verify-149-windows-hide-yml-9fbe00a7","type":"file","character":"single","title":".github/workflows/verify-149-windows-hide.yml","aliases":["#149 verification workflow","windows-latest repro job"],"status":"active","updated":"2026-08-11T05:36:34.722Z","edits":3,"anchors":[{"path":".github/workflows/verify-149-windows-hide.yml","hash":"sha256:50753c85a820","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"Windows-latest CI workflow driving the #149 windowsHide A/B repro (see flow note), shipped in PR #151 (merged into main). workflow_dispatch-only — a branch-scoped push trigger was used temporarily to iterate before this was on the default branch, and was removed once the PR was ready. Now carries an explicit `permissions: contents: read` block, added to resolve a CodeQL 'missing-workflow-permissions' finding raised on the PR (the job only checks out code and runs a local script, so read-only contents access is sufficient).","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"how-the-149-windowshide-a-b-repro-verifies-windows-console-f","type":"flow","character":null,"title":"how the #149 windowsHide A/B repro verifies Windows console-flash on CI and real hardware","aliases":["windowsHide repro","windows-latest A/B test","console flash verification","how the #149 windowsHide A/B repro verifies Windows console-flash on CI","DETACHED_PROCESS launcher","hooks flash confirmed fixed","CreateNoWindow false negative","DETACHED_PROCESS resolves inconclusive repro"],"status":"active","updated":"2026-08-11T05:36:34.697Z","edits":3,"anchors":[{"path":".github/workflows/verify-149-windows-hide.yml","hash":"sha256:50753c85a820","state":"fresh"},{"path":"scripts/win-repro/orchestrator.mjs","hash":"sha256:af1639e9fed1","state":"fresh"},{"path":"scripts/win-repro/harness.mjs","hash":"sha256:1186af440d49","state":"fresh"},{"path":"scripts/win-repro/watch.ps1","hash":"sha256:f5632bae5e65","state":"fresh"},{"path":"scripts/win-repro/orchestrator-noconsole.mjs","hash":"sha256:43cbb5390ab5","state":"missing"},{"path":"scripts/win-repro/NoConsoleLauncher.cs","hash":"sha256:c8b642b5d6de","state":"missing"}],"freshness":"missing","dir":".github/workflows","outLinks":[],"body":"A windows-latest CI workflow (workflow_dispatch-only, now with an explicit `permissions: contents: read` block) empirically confirms whether a child_process option shape flashes a visible console window by polling the real Win32 IsWindowVisible API, and this now works for BOTH shapes coldstart needed to prove: the daemon/CLI shape (Node's own detached:true spawn, matching keeper.js's self-relaunch) AND the hooks/*.mjs shape (a plain child of a console-less Electron host like Claude Code/Cursor). The hooks shape required two failed attempts before landing: a GUI-subsystem (winexe) launcher using .NET's ProcessStartInfo.CreateNoWindow gave the intermediate node.exe a HIDDEN-but-still-attached console rather than none, so its own child (ping.exe) just reused that hidden console regardless of windowsHide — an inconclusive A/B (no flash in either branch). The fix was DetachedLauncher.cs, which calls Win32 CreateProcess directly with the real DETACHED_PROCESS flag (0x8), giving the child genuinely no console object. Under that condition the split is exactly as expected: unpatched flashes, patched doesn't. Confirmed both by the automated IsWindowVisible poll and direct human visual observation on real Windows 11 hardware — this closes the 'hooks shape not independently proven' gap and the fix shipped as part of PR #151 (merged).\n\n## Steps\n\n1. `.github/workflows/verify-149-windows-hide.yml` — windows-latest job entry point; workflow_dispatch-only, now scoped to `permissions: contents: read` (added to address a CodeQL missing-workflow-permissions finding on PR #151)\n2. `scripts/win-repro/orchestrator.mjs` — spawns harness.mjs via Node's detached:true+stdio:'ignore' spawn, mirroring keeper.js's own self-relaunch shape — proven mechanism for the daemon-shape A/B\n3. `scripts/win-repro/harness.mjs` — runs execFileSync with the option shape under test, with or without windowsHide\n4. `scripts/win-repro/DetachedLauncher.cs` (`Main`) — replaces the earlier CreateNoWindow-based launcher; calls Win32 CreateProcess directly with DETACHED_PROCESS so the launched node.exe has genuinely no console object — the actual condition hooks/*.mjs runs under when spawned by a console-less GUI host. This is what finally produced a clean, confirmed flash/no-flash split for the hooks shape\n5. `scripts/win-repro/watch.ps1` (`Run-Case`) — compiles DetachedLauncher.cs via csc.exe, then polls Win32 IsWindowVisible before/after each of the 4 cases (2 daemon-shape via orchestrator.mjs + 2 hooks-shape via DetachedLauncher.exe directly)\n\n## Invariants\n\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction, confirmed via a live 404) — a temp verification workflow scoped to a feature branch must use `on: push: branches: [<branch>]` instead\n- the cleanup step between A/B cases must never Stop-Process match conhost/WindowsTerminal/OpenConsole broadly — those can back the runner's own pwsh session; killing them crashed the very next `node` invocation with a console-pipe error. Only kill the actual test straggler (e.g. ping.exe) by name\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction, confirmed via a live 404) — iterate with a branch-scoped push trigger pre-merge, then drop it once merged\n- a console-flash A/B test only proves something when the code under test is the FIRST thing to request a console in the whole ancestor chain — Node's detached:true spawn (used unpatched, held constant across the A/B pair) satisfies this for the daemon shape, but layering ANY additional console-suppression (CreateNoWindow=true on an intermediate hop, or just launching through an already-console-having process like pwsh) gives that intermediate process a console — hidden or inherited — which then absorbs any downstream child's console need regardless of that child's own windowsHide setting, making the A/B pair indistinguishable\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction) — iterate with a branch-scoped push trigger pre-merge, then drop it once merged\n- a console-flash A/B test only proves something when the code under test is the FIRST thing to request a console in the whole ancestor chain — CreateNoWindow (.NET ProcessStartInfo) suppresses the WINDOW but still leaves a hidden console object attached, which downstream children silently reuse; only the raw Win32 DETACHED_PROCESS flag via CreateProcess gives a child genuinely zero console, which is the condition that makes the A/B pair distinguishable\n- run watch.ps1 with pwsh (PowerShell 7+), not Windows PowerShell 5.1 — the file is UTF-8 without a BOM (em-dashes in comments), and powershell.exe reads no-BOM files using the system codepage, mangling those bytes and breaking parsing","backlinks":[],"anchorLinks":["github-workflows-verify-149-windows-hide-yml-9fbe00a7","scripts-win-repro-harness-mjs-c2b8facb","scripts-win-repro-orchestrator-mjs-599e3c8d","scripts-win-repro-watch-ps1-7c70124a"]},{"id":"hooks-elicit-core-mjs-f3f159c1","type":"file","character":"single","title":"hooks/elicit-core.mjs","aliases":["shared elicit helpers","pending file handoff","worklist annotations","fail open annotation"],"status":"active","updated":"2026-08-11T04:28:44.606Z","edits":5,"anchors":[{"path":"hooks/elicit-core.mjs","symbols":["worklistEntries","noteAnnotations","consumerCounts","freshNotedSet","gitHead","logCaptureEvent","writePendingCapture","takePendingCapture","pendingPath","MAX_WORKLIST"],"hash":"sha256:cdd69e058357","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Host-neutral v5 capture helpers shared by all three elicit hooks AND the recall hooks: worklist annotation (kb status --json --paths + coldstart consumers --json, both fail-open to no-annotation), fresh-noted discount set, git-HEAD fingerprint, capture metrics (capture.jsonl), and the pending-capture handoff (writePendingCapture/takePendingCapture, one file per session id, 24h TTL). Consumed via relative import from sibling hook files — invisible to the TS import graph, which is why consumers reports zero for it. Re-read in full this session (unrelated task) and confirmed still accurate — re-stamping freshness only, no content change.","backlinks":[],"anchorLinks":[]},{"id":"claude-commands-capture-notes-md-3f9e019a","type":"file","character":"single","title":".claude/commands/capture-notes.md","aliases":["capture notes command","manual capture invocation"],"status":"active","updated":"2026-08-11T04:28:44.595Z","edits":1,"anchors":[{"path":".claude/commands/capture-notes.md","hash":"sha256:c2dbcaf67055","state":"changed"}],"freshness":"changed","dir":".claude/commands","outLinks":[],"body":"The /capture-notes command: its `!`-prefixed bash line passes ${CLAUDE_SESSION_ID} to kb-elicit.mjs --manual --session, which is the proof (used this session while building an unrelated plugin) that Claude Code substitutes a command's own session id into its bash execution body even though this isn't documented for slash commands generally — see the '${CLAUDE_SESSION_ID}' flow note.","backlinks":[],"anchorLinks":["how-commands-get-their-own-session-id-claude-session-id"]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-63c61af9","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/README.md","aliases":["plugin design caveats","clear boundary limitation","token tracker readme"],"status":"active","updated":"2026-08-11T04:28:44.584Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/README.md","hash":"sha256:dc6277333e9e","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker","outLinks":[],"body":"Documents the token-consumption-tracker plugin prototype's open caveats, verified this session by grepping real ~/.claude/projects/*.jsonl transcripts directly: /clear leaves no queryable trace inside the transcript JSONL (no SessionStart/clear record is ever written to the file, even though a SessionStart hook fires with source=\"clear\") even though it also confirmed /clear does not start a new transcript file — so v1 sums the whole session file rather than tracking a clear boundary, deferring a hook-based precision fix.","backlinks":[],"anchorLinks":[]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-72bc87ba","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","aliases":["token consumption command","slash command plugin"],"status":"active","updated":"2026-08-11T04:28:44.573Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","hash":"sha256:3c855346ac97","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands","outLinks":[],"body":"The /token-consumption slash command for the token-consumption-tracker plugin prototype. Its `!`-prefixed bash execution invokes scripts/usage.mjs with ${CLAUDE_SESSION_ID} and $(pwd) — see the '${CLAUDE_SESSION_ID}' flow note for why that substitution works despite not being documented for slash commands.","backlinks":[],"anchorLinks":["how-commands-get-their-own-session-id-claude-session-id"]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-4bc9d206","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts/usage.mjs","aliases":["token usage parser","transcript token counter","cwd path encoding"],"status":"active","updated":"2026-08-11T04:28:44.561Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts/usage.mjs","symbols":["encodeCwd","transcriptPathFor","main"],"hash":"sha256:84a8f33b46ed","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts","outLinks":[],"body":"New Phase-0/1 spike for a standalone token-consumption-tracker plugin: stream-parses the current session's transcript JSONL (assistant records' message.usage) to sum real token counts, with a turn-level (not call-level) coldstart-attribution pass keyed on tool names starting with mcp__coldstart__. Derives its own transcript path deterministically — cwd-encoded (each \"/\" and \".\" replaced with \"-\", confirmed against a real ~/.claude/projects dir name) plus an exact session id passed in by the caller, never a \"most recently modified file\" guess. Validated this session: output matched a manual jq sum over this session's own live transcript exactly.","backlinks":[],"anchorLinks":[]},{"id":"how-commands-get-their-own-session-id-claude-session-id","type":"flow","character":null,"title":"how commands get their own session id (${CLAUDE_SESSION_ID})","aliases":["CLAUDE_SESSION_ID substitution","session id in commands","command bash execution"],"status":"active","updated":"2026-08-11T04:28:44.521Z","edits":1,"anchors":[{"path":".claude/commands/capture-notes.md","hash":"sha256:c2dbcaf67055","state":"changed"},{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","hash":"sha256:3c855346ac97","state":"missing"}],"freshness":"missing","dir":".claude/commands","outLinks":[],"body":"Claude Code substitutes ${CLAUDE_SESSION_ID} into a command markdown file's `!`-prefixed bash execution body, giving a slash command its own session id even though the official docs say hook-style stdin fields (session_id, transcript_path) are documented as available to hooks only, not slash commands — this repo has two independent, working proofs of the substitution.\n\n## Steps\n\n1. `.claude/commands/capture-notes.md` — first proof: passes ${CLAUDE_SESSION_ID} to kb-elicit.mjs --manual --session\n2. `.claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md` — second independent proof: passes ${CLAUDE_SESSION_ID} to scripts/usage.mjs --session\n\n## Invariants\n\n- Not documented for slash commands by the official Claude Code docs (checked hooks.md) — only confirmed empirically via these two files' working behavior.\n- A companion gap: there is no equivalent substitution for a command's own transcript_path — it must be derived (cwd-encoding + session id), not read directly.","backlinks":[],"anchorLinks":["claude-commands-capture-notes-md-3f9e019a","claude-worktrees-token-consumption-tracker-token-consumption-72bc87ba"]},{"id":"scripts-win-repro-orchestrator-mjs-599e3c8d","type":"file","character":"single","title":"scripts/win-repro/orchestrator.mjs","aliases":["keeper spawn shape mirror"],"status":"active","updated":"2026-08-11T03:47:24.257Z","edits":2,"anchors":[{"path":"scripts/win-repro/orchestrator.mjs","symbols":["mode","dir","harness","child"],"hash":"sha256:af1639e9fed1","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Spawns harness.mjs detached with stdio:'ignore' and no windowsHide of its own, deliberately reproducing keeper.js's own self-relaunch shape so the repro tests child processes under the same no-console condition the real daemon runs under.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"scripts-win-repro-harness-mjs-c2b8facb","type":"file","character":"single","title":"scripts/win-repro/harness.mjs","aliases":["windowsHide option-shape harness"],"status":"active","updated":"2026-08-11T03:47:24.247Z","edits":2,"anchors":[{"path":"scripts/win-repro/harness.mjs","symbols":["mode","baseOpts","opts"],"hash":"sha256:1186af440d49","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Runs a single execFileSync call whose option shape matches either the unpatched src/indexer/git.ts call sites or the seven #149-patched sites, selected by a CLI arg ('windowsHide' | 'no-windowsHide'); swaps `ping` in for `git`/`rg` purely so the visibility poll in watch.ps1 has runtime to observe.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"src-indexer-git-ts-398eed6c","type":"file","character":"single","title":"src/indexer/git.ts","aliases":["getGitHead","getGitChangedFiles","getGitExactRenames","getGitNewFiles","getGitDirtyFiles","windowsHide missing git.ts","console flash on reconcile","#149 unpatched gap"],"status":"active","updated":"2026-08-11T03:47:23.747Z","edits":1,"anchors":[{"path":"src/indexer/git.ts","symbols":["getGitHead","getGitChangedFiles","getGitExactRenames","getGitNewFiles","getGitDirtyFiles"],"hash":"sha256:7feccf2f2bb6","state":"changed"}],"freshness":"changed","dir":"src/indexer","outLinks":[],"body":"Four execFileAsync('git', ...) calls (getGitHead, getGitChangedFiles, getGitExactRenames, getGitNewFiles/getGitDirtyFiles) that omit windowsHide — confirmed via a real windows-latest CI repro (see the #149 flow note in scripts/win-repro/) that this exact option shape DOES flash a visible console window on Windows. getGitHead runs on every debounced keeper cache save and the others run on every keeper-start reconcile, so this is a live, high-frequency instance of issue #149's bug, left unpatched by the initial 7-site fix. Not yet fixed as of this note.","backlinks":[],"anchorLinks":[]},{"id":"gitignore-a5cc2925","type":"file","character":"single","title":".gitignore","aliases":["repo root gitignore","docs folder ignore pattern","new files missing from git status","untracked files silently excluded","gitignore matching wrong nested directory"],"status":"active","updated":"2026-08-10T18:51:51.993Z","edits":1,"anchors":[{"path":".gitignore","hash":"sha256:6fdc237ac252","state":"changed"}],"freshness":"changed","dir":".","outLinks":[],"body":"Repo-root gitignore. Line 9 was a bare `docs/` pattern intended only for the repo-root internal-docs folder, but an unanchored gitignore pattern matches a directory of that name ANYWHERE in the tree — it was silently excluding `site-astro/src/pages/docs/` from git too, so 3 new page files created there this session never showed up in `git status` and would have been dropped from the PR entirely. Fixed by anchoring it to `/docs/`.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-pages-how-it-works-notebook-astro-7be582fd","type":"file","character":"single","title":"site-astro/src/pages/how-it-works/notebook.astro","aliases":["how-it-works notebook page","notebook loop page","ring figure","freshness states page","notebook mock section","kb view recreation","wanted screenshot not image recreation"],"status":"active","updated":"2026-08-10T18:51:51.967Z","edits":2,"anchors":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","symbols":["ring-svg","ring-card","loopGrad","state-grid","how-aside","nb-mock"],"hash":"sha256:ac83d3352f95","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"Concept-level explainer for the notebook loop: a four-station ring figure, then four cards for what happens to a note when its file changes (the [fresh]/[evidence changed]/[moved]/[anchor missing] strings are hand-copied from freshnessLine() in src/kb/freshness.ts and must be mirrored by hand). This session added a screenshot-free section right after the hero (.nb-mock, styled in how.css) — a built recreation of `kb view` showing a real note (src/server/tools.ts) from coldstart's own notebook, grounding the abstract loop explanation before it starts.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-styles-how-css-f5f7fefc","type":"file","character":"single","title":"site-astro/src/styles/how.css","aliases":["how-it-works stylesheet","how.css","ring figure styles","temperature figure styles","how-page scope","notebook mock styles"],"status":"active","updated":"2026-08-10T18:51:51.958Z","edits":2,"anchors":[{"path":"site-astro/src/styles/how.css","symbols":[".how-page .wrap",".how-sec",".how-sec-head",".ring-fig",".ring-card",".temp-fig",".temp-seam",".state-grid",".how-aside","@media (prefers-reduced-motion: reduce)",".nb-mock"],"hash":"sha256:518ebee8e16f","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/styles","outLinks":[],"body":"Stylesheet for the /how-it-works/ pages. Defines no design tokens of its own — rides docs.css's tokens/nav chrome, everything scoped under .how-page. Holds the two signature figures (.ring-* notebook loop, .temp-* index split) plus, added this session, .nb-mock — a hand-built HTML/CSS recreation of the notebook's `kb view` UI (top bar, file sidebar, note detail panel) used on the notebook how-it-works page instead of an embedded screenshot; it follows the same ride-on rule, using only --frost/--ember/--surface/--line from docs.css's bare :root.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","character":"single","title":"site-astro/src/styles/docs.css","aliases":["docs styles","blog styles","documentation CSS","docs stylesheet","blog stylesheet","nav-wrap bug","essay card grid","docs.css bare root","chrome stylesheet","dark token source","header resizes between pages","sidebar group header double boxed","language chips arbitrarily highlighted","terminal lines merged onto one row"],"status":"active","updated":"2026-08-10T18:51:51.939Z","edits":6,"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in","nav",".nav-in",".side a.active",".chip",".term-body .ln"],"hash":"sha256:cabd593fda98","state":"changed"}],"freshness":"changed","dir":"site-astro/src/styles","outLinks":[],"body":"Docs+blog stylesheet, token-synced to landing.css: Newsreader/IBM Plex Sans/JetBrains Mono, nav chrome now byte-identical to landing.css (64px height, 28px gap, z-index 50 — was drifted to 60px/20px/30, fixed this session). The docs-page sidebar lives here (.side, .side-group, .side a.active applies a background+left-border 'pill' to ANY active <a> under .side) — DocsSidebar.astro's group-header links share that selector and must explicitly opt out or they double-box. .chip.hot (an arbitrary blue-highlight tier on the supported-languages chips) was removed this session; all .chip now render uniformly. .term-body .ln needed display:block alongside white-space:pre or sibling command lines visually merge onto one row.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","character":null,"title":"site-astro has two independent stylesheets that must be hand-kept in sync","aliases":["landing.css docs.css split","site-astro design system","two stylesheet architecture","how.css ride-on pattern","third stylesheet","unscoped root tokens","nav layout dimension drift","header resizes between pages","nav height changes on navigation","header jumps switching pages"],"status":"active","updated":"2026-08-10T18:51:51.882Z","edits":6,"anchors":[{"path":"site-astro/src/pages/index.astro","hash":"sha256:84935811908d","state":"changed"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:2d67c90c7632","state":"changed"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:cabd593fda98","state":"changed"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:d404bd2d8258","state":"changed"},{"path":"site-astro/src/pages/blog/index.astro","hash":"sha256:ad1a1743e444","state":"fresh"},{"path":"site-astro/src/layouts/BlogPostLayout.astro","hash":"sha256:9b42858ab2ab","state":"fresh"},{"path":"site-astro/src/styles/how.css","hash":"sha256:518ebee8e16f","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","state":"fresh"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"site-astro has no shared global stylesheet or CSS custom-property source of truth: index.astro imports landing.css while docs.astro, blog/index.astro and BlogPostLayout.astro import docs.css instead — the two define the same-named tokens (--display/--sans/--mono/--frost/--ember/etc) AND the same nav layout rules (height, gap, z-index, mobile-menu offsets) independently, so a change to one leaves the other silently stale. A third stylesheet, how.css, rides docs.css's tokens/chrome instead of duplicating them and is the pattern to prefer for new page families.\n\n## Steps\n\n1. `site-astro/src/pages/index.astro` — imports landing.css; the only page on that stylesheet\n2. `site-astro/src/styles/landing.css` — home page token + nav-layout source (height:64px, gap:28px, z-index:50)\n3. `site-astro/src/styles/docs.css` (`:root`, `nav`, `.nav-in`, `.side`) — docs+blog stylesheet; redefines the same tokens AND nav dimensions independently\n4. `site-astro/src/pages/docs.astro` — imports docs.css plus its own Google Fonts <link> block\n5. `site-astro/src/styles/how.css` — the third pattern: zero tokens/nav rules of its own, rides docs.css\n6. `site-astro/src/pages/how-it-works/notebook.astro` — imports docs.css AND how.css together — the ride-on pattern in use\n\n## Invariants\n\n- Nav.astro and Footer.astro are shared components styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component itself\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently (this already happened once: docs.css still had a pre-redesign SF Mono/system-ui font stack after landing.css was fully re-themed to Newsreader/IBM Plex Sans/JetBrains Mono)\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently\n- Nav.astro and Footer.astro are styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void; a palette change in one needs the matching edit by hand or the dark palette diverges silently\n- how.css declares no token of its own and must stay that way — its only local definitions are --paper/--paper-ink/--paper-line/--faint/--ember-dim under body.how-page, which docs.css does not define\n- anything added to how.css must stay scoped under .how-page or it leaks into docs and blog, which load the same docs.css\n- docs.css's palette sits on a bare :root — a new page family gets the dark theme by importing it under ANY body class; only body.essay-page re-scopes to light\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — a palette change in one needs the matching edit by hand or the dark palette diverges silently\n- landing.css and docs.css ALSO independently duplicate nav layout dimensions (nav-in height/gap, z-index, .nav-mobile top offset, .side sticky top) — verified this session: docs.css's nav had drifted to 60px height/20px gap/z-index 30 while landing.css was 64px/28px/50, so the header visibly resized crossing from home to /docs/. Fixed by making docs.css's nav block byte-identical to landing.css's again (including .side's sticky top/max-height, which must track the nav height too)\n- how.css declares no token or nav rule of its own and must stay that way\n- docs.css's palette and nav rules sit on bare selectors (:root, nav) with no body-class qualifier — a new page family gets them just by importing docs.css","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-src-pages-blog-index-astro-eeb82beb","site-astro-src-pages-docs-astro-d1cf6fe9","site-astro-src-pages-how-it-works-notebook-astro-7be582fd","site-astro-src-pages-index-astro-08d662bc","site-astro-src-styles-docs-css-e5e1acf9"]},{"id":"new-vs-comparison-pages-are-hand-linked-from-existing-conten","type":"flow","character":null,"title":"new /vs/ comparison pages are hand-linked from existing content, not from Nav","aliases":["vs page linking","comparison page discovery","vector rag page"],"status":"active","updated":"2026-08-10T18:44:42.033Z","edits":1,"anchors":[{"path":"site-astro/src/pages/vs/vector-rag.astro","hash":"sha256:8df78e50986b","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/index.astro","hash":"sha256:19c4fdcc0bca","state":"fresh"},{"path":"site-astro/src/content/blog/why-coldstart-makes-zero-llm-calls.md","hash":"sha256:95f97d6898f5","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/vs","outLinks":[],"body":"A /vs/ page (e.g. vector-rag.astro) has no entry in Nav.astro or Footer.astro — discoverability is entirely from inline links placed in whichever existing pages already discuss the same tradeoff, not from a dedicated nav slot.\n\n## Steps\n\n1. `site-astro/src/pages/vs/vector-rag.astro` — the standalone comparison page itself, reuses how.css/docs.css chrome, no Nav/Footer entry\n2. `site-astro/src/pages/docs/under-the-hood.astro` — links to it from the 'Bring your own semantics' callout, next to the PHILOSOPHY.md link\n3. `site-astro/src/content/blog/why-coldstart-makes-zero-llm-calls.md` — links to it inline, at the sentence conceding RAG's fuzzy-conceptual-query advantage\n4. `site-astro/src/pages/how-it-works/index.astro` — links to it as a second ghost link in the closing CTA row, next to the blog link\n\n## Invariants\n\n- a new /vs/ page needs its own manual link-in placements chosen by content fit — there is no shared nav slot that auto-lists /vs/ pages","backlinks":[],"anchorLinks":[]},{"id":"github-workflows-pages-yml-80c02bfb","type":"file","character":"single","title":".github/workflows/pages.yml","aliases":["pages deploy workflow","github pages build","site deploy ci","fetch-depth checkout","sitemap lastmod wrong in ci","shallow clone build"],"status":"active","updated":"2026-08-09T17:41:18.462Z","edits":1,"anchors":[{"path":".github/workflows/pages.yml","symbols":["deploy"],"hash":"sha256:273b39654c8a","state":"changed"}],"freshness":"changed","dir":".github/workflows","outLinks":[],"body":"Builds site-astro and deploys it to GitHub Pages on pushes touching site-astro/** (or this file). The actions/checkout step carries an explicit `fetch-depth: 0` that is load-bearing rather than cosmetic: astro.config.mjs derives the sitemap's <lastmod> from per-file git history, and checkout's default shallow clone would silently reduce that to one uniform date. Deploy is fail-safe — if the build errors, deploy-pages never runs and the live site is left untouched.","backlinks":[],"anchorLinks":["how-the-sitemap-gets-its-lastmod-dates"]},{"id":"site-astro-astro-config-mjs-8801ef8e","type":"file","character":"single","title":"site-astro/astro.config.mjs","aliases":["astro config","sitemap integration","coldstartmcp.dev domain","site url config","site canonical url","lastmod serialize hook","sitemap missing lastmod","uniform lastmod dates"],"status":"active","updated":"2026-08-09T17:41:18.452Z","edits":2,"anchors":[{"path":"site-astro/astro.config.mjs","symbols":["defineConfig","historyUsable","sourceFileForRoute","lastCommitDate"],"hash":"sha256:268671d3ade6","state":"fresh"}],"freshness":"fresh","dir":"site-astro","outLinks":[],"body":"Astro site config: sets canonical `site` to https://coldstartmcp.dev (consumed by @astrojs/sitemap for absolute URLs) and registers the @astrojs/sitemap + @astrojs/tailwind integrations. The sitemap is generated at build time from the site's routes — no hand-maintained sitemap file. It now passes a serialize() hook that stamps each URL's <lastmod> from its source file's last git commit date: sourceFileForRoute() maps a route back to src/pages/*.astro (or src/content/blog/<slug>.md for posts), and lastCommitDate() shells out to git log. historyUsable is computed ONCE at module load via `git rev-parse --is-shallow-repository` — this guard exists because git log does not fail in a shallow clone, it returns that clone's single commit date for every file, which would stamp all 16 URLs with the same wrong timestamp.","backlinks":[],"anchorLinks":["how-the-sitemap-gets-its-lastmod-dates"]},{"id":"how-the-sitemap-gets-its-lastmod-dates","type":"flow","character":null,"title":"how the sitemap gets its lastmod dates","aliases":["sitemap lastmod","sitemap generation","fetch-depth shallow clone","astro sitemap serialize","uniform lastmod dates","identical timestamps sitemap","missing lastmod"],"status":"active","updated":"2026-08-09T17:41:18.427Z","edits":1,"anchors":[{"path":".github/workflows/pages.yml","hash":"sha256:273b39654c8a","state":"changed"},{"path":"site-astro/astro.config.mjs","hash":"sha256:268671d3ade6","state":"fresh"}],"freshness":"changed","dir":".github/workflows","outLinks":[],"body":"The sitemap's <lastmod> values are not produced by Astro or by the deploy workflow alone — they come from git history read at build time, so the correctness of every date depends on a setting in a DIFFERENT file: actions/checkout's fetch-depth in .github/workflows/pages.yml. A shallow clone does not make git log fail; it answers every path with the single commit it has, so per-file dates come back uniform and wrong rather than absent. That is why astro.config.mjs probes `git rev-parse --is-shallow-repository` up front and emits NO lastmod at all when history is unusable: a wrong lastmod on every URL is worse than none, because it trains Google to ignore the field.\n\n## Steps\n\n1. `.github/workflows/pages.yml` (`checkout`) — fetch-depth: 0 makes full git history available to the build; removing it silently disables lastmod\n2. `site-astro/astro.config.mjs` (`historyUsable`, `sourceFileForRoute`, `lastCommitDate`) — maps each route to its source file and stamps that file's last-commit date, guarded on clone depth\n\n## Invariants\n\n- fetch-depth: 0 in pages.yml is load-bearing for lastmod, not an optimisation\n- lastmod is omitted entirely rather than faked when git history is unusable\n- blog posts stamp from their markdown in src/content/blog, never from [slug].astro, so template edits do not restamp every post","backlinks":[],"anchorLinks":["github-workflows-pages-yml-80c02bfb","site-astro-astro-config-mjs-8801ef8e"]},{"id":"site-astro-src-pages-how-it-works-navigation-astro-b7403337","type":"file","character":"single","title":"site-astro/src/pages/how-it-works/navigation.astro","aliases":["how-it-works navigation page","temperature figure","index explainer page","find gs explainer"],"status":"active","updated":"2026-08-09T10:05:32.780Z","edits":1,"anchors":[{"path":"site-astro/src/pages/how-it-works/navigation.astro","symbols":["temp-fig","temp-seam","temp-col","zoom","zpan"],"hash":"sha256:fe084da82216","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"Concept-level explainer for the navigation layer: a two-column 'temperature' figure splitting what the index keeps exact (paths, symbols, imports, calls) from what it leaves to the model, then three panels for the map, find and gs. The seam between the columns is a plain 1px gradient div, not an SVG stroke — a rough-filtered wavy stroke was tried first and read as a stray scratch at this size. Same page shell as its sibling: docs.css + how.css, SvgDefs, Nav/Footer variant 'how'.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-scripts-generate-og-sh-37447c1d","type":"file","character":"single","title":"site-astro/scripts/generate-og.sh","aliases":["OG card generator","chrome-devtools screenshot","social card regeneration","og.png rebuild","chrome-devtools screenshot script","stale og card copied","screenshot failed silently","wrong fonts in og image"],"status":"active","updated":"2026-08-08T16:57:41.333Z","edits":3,"anchors":[{"path":"site-astro/scripts/generate-og.sh","symbols":["TEMPLATE_FILE","OUTPUT_FILE","TEMP_PNG","VIEWPORT","SCRIPT_DIR","REPO_ROOT"],"hash":"sha256:4eb03fafa437","state":"fresh"}],"freshness":"fresh","dir":"site-astro/scripts","outLinks":[],"body":"Regenerates public/og.png (the 1200x630 social card) from scripts/og.html by driving chrome-devtools-cli. Two environment constraints are the reason this is a script and not a one-liner: chrome-devtools REFUSES to write outside its allowed workspace roots, so the capture goes to a TMPDIR path and is copied into the repo afterwards; and resize_page silently does not apply, so the viewport must be set with 'emulate --viewport'. Rewritten this session after the first version could ship a stale card silently: it combined 'set -e' with '|| true' on every chrome-devtools call and used a FIXED temp path, so a failed capture left the previous run's PNG in place, passed the -f existence guard, and copied an old card into the repo while reporting success — which is also why 'ran it twice, identical output' was not evidence of reproducibility. Now uses a PID-unique temp path removed up-front and on EXIT via trap, no '|| true' swallowing, and hard failure if the viewport is not 1200x630 or the captured PNG is not 1200x630. It also awaits document.fonts.ready, without which the serif headline silently renders in a fallback face.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-public-llms-txt-0a80f88e","type":"file","character":"single","title":"site-astro/public/llms.txt","aliases":["llms.txt","LLM discovery file","agent-readable site summary","answer engine discovery","similarity score contrast lost"],"status":"active","updated":"2026-08-08T16:57:29.336Z","edits":3,"anchors":[{"path":"site-astro/public/llms.txt","hash":"sha256:7b4d30155654","state":"changed"}],"freshness":"changed","dir":"site-astro/public","outLinks":[],"body":"Machine-readable project summary for LLM crawlers/answer-engines, served at coldstartmcp.dev/llms.txt per the llms.txt convention. Its opening blockquote is a governed category slot and now leads 'coldstart is codebase memory for AI coding agents', where it previously led with navigation ('Codebase navigation and a codebase notebook'). When rewriting that line, keep the 'ranked with checkable evidence instead of a similarity score' contrast — it is the sharpest anti-embedding differentiator on the site and an earlier rewrite this session dropped it by accident before it was restored. Body lists core operations, doc links, and agent-facing usage notes; carries no numbers and no comparison language, consistent with the standing no-published-numbers and no-comparison-pages locks.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","type":"flow","character":null,"title":"site-astro coordinates SEO entity binding of 'coldstart' to 'codebase memory' across multiple surfaces","aliases":["coldstart brand positioning","codebase memory branding","SEO entity binding","site messaging consistency","category slot","codebase memory bigram","brand entity binding","memory led navigation second","memory plus navigation pair","generic memory wording"],"status":"active","updated":"2026-08-08T16:57:29.289Z","edits":2,"anchors":[{"path":"site-astro/src/components/Footer.astro","hash":"sha256:9dbf16ed662d","state":"changed"},{"path":"site-astro/src/pages/blog/index.astro","hash":"sha256:ad1a1743e444","state":"fresh"},{"path":"site-astro/public/llms.txt","hash":"sha256:7b4d30155654","state":"changed"},{"path":"site-astro/src/layouts/Head.astro","hash":"sha256:43e48691fd9a","state":"fresh"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:d30a2555c5e0","state":"changed"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:28ef179f54d6","state":"changed"}],"freshness":"changed","dir":"site-astro/src/components","outLinks":[],"body":"The site distinguishes 'category slots' from body copy, and only category slots are governed: the title tag, hero kicker, footer tagline, llms.txt opening line, og.png kicker, and every meta/og/twitter description must carry the exact bigram 'codebase memory' and nothing may compete with it there. Positioning is memory-led with navigation second, so body copy is still free to describe navigation (the FAQ answer in index.astro says 'navigation and memory layer' and that is deliberate, not a miss). The phrase is applied to roughly six high-value slots ONLY — pushing it everywhere is keyword stuffing, which measurably reduces answer-engine visibility. Verified this session: the bigram was previously absent from every one of these slots because each generic surface pitched 'memory + navigation' as a co-equal pair, which is why npm/GitHub (one-sentence descriptions, forced to choose) were on-message while the site was not.\n\n## Steps\n\n1. `site-astro/src/pages/index.astro` (`Head title`, `class kicker`) — home title tag, hero kicker, and the three meta/og/twitter descriptions\n2. `site-astro/src/pages/docs.astro` — docs title/description/keywords — keywords must lead with the bigram, not generic 'agent memory'\n3. `site-astro/src/pages/blog/index.astro` — blog index title and descriptions\n4. `site-astro/src/components/Footer.astro` — home-variant tagline only; docs/blog taglines are not category slots\n5. `site-astro/public/llms.txt` — opening blockquote — the single highest-leverage line for answer engines\n6. `site-astro/src/layouts/Head.astro` — og:image:alt, which must match the og.png card text\n\n## Invariants\n\n- Brand string is lowercase 'coldstart' everywhere (matches npm, CLI, GitHub, wordmark) — title tags are category-first, brand last.\n- og:image:alt in Head.astro and the kicker baked into public/og.png must say the same thing; changing one means regenerating the other via scripts/generate-og.sh.","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-public-llms-txt-0a80f88e","site-astro-src-components-footer-astro-98a77858","site-astro-src-layouts-head-astro-41b37e1f","site-astro-src-pages-blog-index-astro-eeb82beb","site-astro-src-pages-docs-astro-d1cf6fe9"]},{"id":"site-astro-scripts-og-html-5839ef55","type":"file","character":"single","title":"site-astro/scripts/og.html","aliases":["OG social card","1200x630","social preview"],"status":"active","updated":"2026-08-08T16:44:45.217Z","edits":1,"anchors":[{"path":"site-astro/scripts/og.html","hash":"sha256:d5c456e784ea","state":"fresh"}],"freshness":"fresh","dir":"site-astro/scripts","outLinks":[],"body":"Self-contained HTML template that renders coldstart's 1200×630 social media preview card. The design combines Newsreader serif for the headline (48px), JetBrains Mono for the kicker (uppercase, cyan, letterspaced), and IBM Plex Sans for muted sub-lines. The headline uses dual accent colors — frost cyan (#4fbfe0) on 'scratch' and warm amber (#ef9448) on 'session' — matching the live homepage hero styling. The snowflake SVG mark is inlined from SvgDefs.astro's path definition but rendered in cyan (#4fbfe0). Fonts are loaded from Google Fonts over HTTPS; the container is exactly 1200×630 with dark background (#070a11) and a bottom gradient rule (cyan → amber). Rendered to PNG by generate-og.sh.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-pages-blog-index-astro-eeb82beb","type":"file","character":"single","title":"site-astro/src/pages/blog/index.astro","aliases":["blog index page","blog listing","post collection"],"status":"active","updated":"2026-08-08T16:36:06.116Z","edits":2,"anchors":[{"path":"site-astro/src/pages/blog/index.astro","symbols":["posts","site","jsonLd"],"hash":"sha256:ad1a1743e444","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/blog","outLinks":[],"body":"Blog index page. The <Head /> component props (title, description, ogDescription) contain SEO strings that bind 'coldstart' to 'codebase memory' as part of the site's coordinated brand-positioning strategy. These strings must stay in sync with corresponding strings in Footer.astro, public/llms.txt, and Head.astro when the brand messaging evolves. Note: this file also imports docs.css and duplicates the Google Fonts <link> block, tracked separately in the stylesheet-split flow.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-layouts-head-astro-41b37e1f","type":"file","character":"single","title":"site-astro/src/layouts/Head.astro","aliases":["Head layout","shared meta tags","og:image:alt"],"status":"active","updated":"2026-08-08T16:36:06.109Z","edits":2,"anchors":[{"path":"site-astro/src/layouts/Head.astro","symbols":["Props","site","canonical","ogImage"],"hash":"sha256:43e48691fd9a","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/layouts","outLinks":[],"body":"Shared head layout component defining meta tags for all pages. The og:image:alt content attribute ('coldstart — codebase memory for AI coding agents') binds the coldstart brand to 'codebase memory' for social sharing, part of a coordinated SEO entity binding across the site.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"site-astro-src-content-config-ts-72ba7b55","type":"file","character":"single","title":"site-astro/src/content/config.ts","aliases":["blog collection schema","content config","frontmatter schema","readingTime convention"],"status":"active","updated":"2026-08-08T11:38:56.256Z","edits":3,"anchors":[{"path":"site-astro/src/content/config.ts","symbols":["blog","collections"],"hash":"sha256:4508d7ae272e","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/content","outLinks":[],"body":"Declares the `blog` content collection's zod schema — the single source of truth for what frontmatter every post file must carry (title, description, lead, keywords, kicker, ogDescription, publishDate, readingTime, tags, next, optional wordCount). `publishDate` uses `z.coerce.date()` so a plain YAML date string parses to a real Date for sorting. `readingTime` is a free-text string with no computation or validation behind it — verified this session by computing word-count-vs-stated-minutes across all 10 posts, the unenforced convention in use is roughly 200-230 words/minute; a new post's value should be checked against a similar-length existing post, not eyeballed.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"site-astro-src-content-blog-how-your-own-benchmark-lies-to-y-196459c3","type":"file","character":"single","title":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","aliases":["benchmark methodology post","how your own benchmark lies","benchmark guardrails post","reading time too long","wrong minutes estimate"],"status":"active","updated":"2026-08-08T11:38:38.797Z","edits":1,"anchors":[{"path":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","hash":"sha256:8a4f613d59c4","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content/blog","outLinks":[],"body":"Companion post to the critique piece above, aimed at whoever is building a benchmark rather than reading one: one section per guardrail (answer-blind queries, one-variable-per-arm including sub-agent ground-truth corruption, environment/rules-file drift between arms, establishing a nondeterminism floor before trusting a delta), each grounded in a real past incident rather than invented for the post. The answer-blind-query anecdote's source repo is deliberately left unnamed for privacy. Its own `readingTime` was first set to 9 min (about 163 words/minute for its length), inconsistent with the ~200-230 wpm the rest of the site's posts use, and corrected to 8 min before publishing.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"site-astro-src-content-blog-why-most-token-savings-tools-lie-1fc86b94","type":"file","character":"single","title":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","aliases":["token savings critique post","why most token savings tools lie","benchmark honesty post"],"status":"active","updated":"2026-08-08T11:38:38.788Z","edits":1,"anchors":[{"path":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","hash":"sha256:308716b65de7","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content/blog","outLinks":[],"body":"The renamed and rewritten critique post (was `what-the-numbers-actually-say.md`), arguing a token-savings number is only honest when measured across a whole session's usage record, not one call — covers the ~90%-cache-read/2%-tool-output cost ratio and a prompt-caching-invalidation mechanism (rewriting earlier context converts cheap cache reads into full-price cache writes) before landing on coldstart's own Arches (-64%) / JMRI (-31%) sweep numbers as the worked example. Deliberately names no competitor tool or anecdote, and deliberately omits an old, since-rebuilt notebook-capture-cost figure — both scoped out on purpose, stated as open gaps in the post itself rather than silently left out.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"blog-posts-chain-via-a-hand-maintained-circular-next-field","type":"flow","character":null,"title":"blog posts chain via a hand-maintained circular next field","aliases":["blog next field","post navigation chain","next post link"],"status":"active","updated":"2026-08-08T11:38:38.740Z","edits":1,"anchors":[{"path":"site-astro/src/content/config.ts","hash":"sha256:4508d7ae272e","state":"fresh"},{"path":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","hash":"sha256:308716b65de7","state":"changed"},{"path":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","hash":"sha256:8a4f613d59c4","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content","outLinks":[],"body":"Every blog post's `next` frontmatter field is a manually-authored pointer to another post's slug, and across the whole collection these links form exactly one closed loop (not derived from publishDate order, not validated at build time) that renders as the 'Next' link at the bottom of each post page.\n\n## Steps\n\n1. `site-astro/src/content/config.ts` — declares `next` as an optional plain string on the blog collection schema; nothing here checks that the value is a real, existing slug\n2. `site-astro/src/content/blog/why-most-token-savings-tools-lie.md` — one link in the loop; its `next` was repointed this session to splice a newly added post in after it, instead of straight to its old target\n3. `site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md` — new post spliced into the loop; its own `next` was set to the old target of the post before it, so the loop closes again with one more link\n\n## Invariants\n\n- the `next` chain across ALL posts must form exactly one closed loop with no missing or duplicate slug — inserting or removing a post means re-pointing the neighboring post(s) by hand, not just adding/deleting the one file\n- `next` values are raw slugs, unvalidated against real content-collection entries at build time — a stale slug after a rename or delete fails silently (a dead 'Next' link) rather than failing the build","backlinks":[],"anchorLinks":["site-astro-src-content-blog-how-your-own-benchmark-lies-to-y-196459c3","site-astro-src-content-blog-why-most-token-savings-tools-lie-1fc86b94","site-astro-src-content-config-ts-72ba7b55"]},{"id":"hooks-kb-elicit-mjs-08de0677","type":"file","character":"single","title":"hooks/kb-elicit.mjs","aliases":["findRepoRoot","frozen root marker","acompact","manual capture","baseline","nested subagent transcripts","kb-elicit","capture orchestrator","Stop hook","SubagentStop hook","manual capture entry point","soleMarkerUnderRoot","worklist deletion loses coverage forever","hand-deleted worklist file"],"status":"active","updated":"2026-08-06T12:54:32.329Z","edits":22,"anchors":[{"path":"hooks/kb-elicit.mjs","symbols":["findRepoRoot","freshestMarkerUnderRoot","resolveSubagentTranscript","markerMtime","argValue","readStdin"],"hash":"sha256:a6d2a6103578","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Claude Stop/SubagentStop capture orchestrator AND the shared --manual/on-demand entry point ALL THREE HOSTS invoke: reads the session marker, slices the transcript by stored lineCount, filters evidence through .coldstartignore, and steps the trigger state machine; most stops tick silently. Resume hazards handled: /compact shrinkage (stored lineCount > current lines -> reset) and a fresh marker meeting an already-large transcript (baseline, fire nothing). The repo root is FROZEN in the marker (state.root, via findRepoRoot walk-up to the nearest `.coldstart/notebook` ancestor) so a mid-session `cd` cannot admit a foreign absolute path into the worklist. --manual requires --session (2026-07-?? PR #133 tightened this — it no longer 'self-discovers the freshest marker', which guessed wrong across concurrent sessions), or falls back to `soleMarkerUnderRoot` when exactly one candidate marker exists under --root (refuses on 2+, ambiguous) — this is what lets Cursor/Codex's hook-injected /capture-notes work without a real --session on their command surface. --manual marks LISTED files captured while leaving armed/activeStops/stopsSinceFire/quietRun untouched, so it cannot change WHEN automatic capture next fires. 2026-08-06 FIX: the manual branch now also checks `worklistLost = !existsSync(worklistJsonPath(root, sid, 'main'))` (imported from hooks/capture-payload.mjs) and includes a captured READ-ONLY file in the listing when true — previously, hand-deleting `.worklist-<sid>-<aid>.json` left those files permanently invisible to manual capture even though they still needed a note, since captured=true was otherwise treated as done.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"how-notebook-capture-fires-v5-trigger-timed","type":"flow","character":null,"title":"how notebook capture fires (v5 trigger-timed)","aliases":["capture-notes","manual capture","capture on demand","fire capture now","durable worklist","worklist","capture sentinel","unified marker","cross-host session id","capture instructions","capture-instructions.md","permanent instructions file"],"status":"active","updated":"2026-08-06T11:17:53.830Z","edits":15,"anchors":[{"path":"hooks/kb-elicit.mjs","hash":"sha256:a6d2a6103578","state":"fresh"},{"path":"hooks/evidence.mjs","hash":"sha256:de7c023db93c","state":"changed"},{"path":"hooks/ignore.mjs","hash":"sha256:6b5fde7d5dc4","state":"fresh"},{"path":"hooks/trigger.mjs","hash":"sha256:d5d41f6fd44c","state":"fresh"},{"path":"hooks/capture-payload.mjs","hash":"sha256:cb889f7d6a57","state":"changed"},{"path":"hooks/kb-recall.mjs","hash":"sha256:41cc77ff40a0","state":"changed"},{"path":"hooks/cursor-kb-recall.mjs","hash":"sha256:81eb647451fe","state":"changed"},{"path":"hooks/codex-kb-recall.mjs","hash":"sha256:bfee03e28713","state":"changed"},{"path":"hooks/cursor-kb-elicit.mjs","hash":"sha256:4e5bdaa79e39","state":"fresh"},{"path":"hooks/codex-kb-elicit.mjs","hash":"sha256:b3f62e471f3f","state":"fresh"},{"path":"hooks/capture-sentinel.mjs","hash":"sha256:9ec243a69ec0","state":"fresh"},{"path":"src/init.ts","hash":"sha256:667ecf980a53","state":"changed"},{"path":"src/kb/write-guide.ts","hash":"sha256:9a8d307fce87","state":"fresh"},{"path":"src/kb/durable-worklist.ts","hash":"sha256:f3458ced167c","state":"fresh"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Capture is trigger-timed, not per-stop: every Stop silently updates per-file evidence and a score, and only when the trigger fires is the checklist payload delivered - the stop itself is never blocked; only git-HEAD drift blocks. Writing a note is really THREE decoupled writes (trigger-state marker, durable worklist file, notebook note) across 3 hosts x 2 agent roles x 2 fire modes, and this pipeline has regressed a different cell of that matrix on almost every past fix. As of 2026-08-06 all three hosts share ONE marker namespace, manual /capture-notes on Cursor/Codex is hook-injected with the real session id rather than typed by the agent, and the static instructions half of the payload lives in one permanent file instead of being duplicated per session - see Invariants for the full incident list before changing anything here.\n\n## Steps\n\n1. `hooks/kb-elicit.mjs` — (`step`, `soleMarkerUnderRoot`) — Claude's Stop/SubagentStop orchestrator AND the shared --manual/on-demand entry point ALL THREE HOSTS invoke (src/init.ts's USER_COMMANDS.capture.invocation is host-agnostic - it always shells out to this one file, never a host-specific elicit script). --manual requires --session, or falls back to soleMarkerUnderRoot when exactly one candidate marker exists under --root, refusing when 2+ are ambiguous.\n2. `hooks/evidence.mjs` — tiered evidence (edit/read/gs; mentions never count) for Claude's transcript format\n3. `hooks/ignore.mjs` — filters ignored files out of evidence at the root\n4. `hooks/trigger.mjs` — (`step`) — pure state machine (Claude/Cursor only - Codex does NOT import this, see cursor-kb-elicit.mjs/codex-kb-elicit.mjs below): score = uncaptured files + 2x settled edits + ALL stops since last fire; arm at 10; fire on descent, cap, or headDrift. A fire is ONE-SHOT: marks offered files captured=true and resets counters in the same call kb-elicit.mjs persists to the marker UNCONDITIONALLY, regardless of whether the worklist write below succeeds.\n5. `hooks/capture-payload.mjs` — (`writeDurableWorklist`, `buildCapturePayload`, `ensureCaptureInstructions`) — renders the FULL checklist for THIS turn (unchanged: always inlines the complete instructions text) and best-effort writes the durable pair .worklist-<sid>-<aid>.{json,md}. If that write is lost (hand-deleted, disk error), the marker still believes those files were offered, so nothing regenerates the pair short of a fresh edit. 2026-08-06: the static DECIDE-FIRST/per-note/FLOWS/WRITE instructions (~150 lines, byte-identical every fire) are no longer duplicated into every session's .md. They live ONCE in the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (shippedInstructionsTemplate, version-tagged via INSTRUCTIONS_VERSION so a future template edit self-heals a stale on-disk copy). renderCapturePayload substitutes {{CLI}}/{{ROOT}}/{{SID}}/{{AID}}/{{WORKLIST}} into that permanent body - the same placeholder mechanism the pre-existing `.coldstart/checklist.md` user-override already used; loadChecklistOverride still takes precedence when present. The per-session .worklist-<sid>-<aid>.md shrank to just the worklist + a pointer at the permanent file (~10KB -> ~400 bytes); the JSON half (files/tier/needsNote - what the worklist-deletion fix above actually protects) is untouched.\n6. `src/kb/durable-worklist.ts` — TS contract twin of the worklist writer/shape; kb write reads it to credit/trim/clear coverage on finalize\n7. `hooks/kb-recall.mjs` — Claude's UserPromptSubmit: consumes the pending file and injects capture FIRST\n8. `hooks/cursor-kb-elicit.mjs` — (`marker`) — Cursor's OWN Stop/SubagentStop capture logic (does not use trigger.mjs at all - has its own inline evidence/fire logic). As of 2026-08-06 writes its session-state marker to the SAME path kb-elicit.mjs's --manual reads: tmpdir()/coldstart-kb-<sid>-<aid>.json (previously coldstart-cursor-kb-<sid>-<aid>.json, a DIFFERENT file --manual could never see - see Invariants). The per-turn dedupe file (coldstart-cursor-kb-turn-<tid>-<aid>.done) is unrelated and keeps its own cursor-specific prefix.\n9. `hooks/codex-kb-elicit.mjs` — (`marker`) — Codex's OWN Stop/SubagentStop capture logic - also does not import trigger.mjs; ALWAYS fires decision:block on evidence (no arm/descent threshold at all, unlike Claude/Cursor's v5 trigger - a real asymmetry, not yet unified). As of 2026-08-06 writes to the same unified tmpdir()/coldstart-kb-<sid>-<aid>.json marker (previously coldstart-codex-kb-<sid>-<aid>.json).\n10. `hooks/capture-sentinel.mjs` — (`CAPTURE_SENTINEL`) — the literal string `<!-- coldstart:capture-notes -->` embedded in the Cursor/Codex capture command body (src/init.ts wireCursorCommand/wireCodexSkill, gated on UserCommand.hookInjected) so a host's own pre-prompt recall hook can recognize the submitted prompt IS /capture-notes and act on it.\n11. `hooks/cursor-kb-recall.mjs` — Cursor's beforeSubmitPrompt: when the submitted prompt contains CAPTURE_SENTINEL and a real session_id is present (which this hook always has, unlike the command surface itself), it runs `kb-elicit.mjs --manual --session <real sid> --root <root>` itself and injects the output via the existing additional_context/pending channel - deterministic, no LLM has to type a correct --session. Falls back to the command's own 'run this in the terminal' wording if the hook is disabled/fails.\n12. `hooks/codex-kb-recall.mjs` — Codex's UserPromptSubmit: same CAPTURE_SENTINEL detection and self-run of kb-elicit.mjs --manual, injected via hookSpecificOutput.additionalContext. Every early-exit (no notebook yet, empty query, search failed, no recall hits) falls back to delivering the manual-capture text alone via deliverManualOnlyAndExit, instead of exiting silently and swallowing an explicit /capture-notes.\n13. `src/init.ts` — (`wireCursorCommand`, `wireCodexSkill`, `UserCommand`) — UserCommand gained hookInjected?:boolean (true only for the capture command, not repair/repairAliases which need no session). When set, the Cursor/Codex command body opens with CAPTURE_SENTINEL and reworded fallback text instead of unconditionally telling the agent to run the terminal command.\n14. `src/kb/write-guide.ts` — (`MARKER_PREFIXES`, `flowEvidenceCount`) — the flow-evidence check that unions markers across a session's agents. Simplified 2026-08-06 from 3 per-host prefixes to the one unified prefix now that all hosts write the same marker file.\n\n## Invariants\n\n- mentions (grep hits, bare path tokens) never enter evidence — content tiers only\n- cap fires INJECT not block — validated spec deviation: dense sessions starve descent and repeated cap-blocks re-create the v4 agitation\n- pending file = tmpdir coldstart-kb-pending-<sid>.json, 24h TTL, consumed (deleted) on delivery\n- capture survives Claude Code /compact: a transcript shorter than the stored lineCount is reprocessed from its new start rather than dropping evidence (kb-elicit shrink guard)\n- manual capture is READ-ONLY on the session marker, so an on-demand capture can never perturb automatic firing\n- the manual path prints the payload directly - it does NOT write a pending file and does not go through kb-recall\n- manual self-discovers the session (no hook stdin): freshest tmpdir marker whose recorded relative files still resolve under --root\n- mentions (grep hits, bare path tokens) never enter evidence - content tiers only\n- cap fires INJECT not block - dense sessions starve descent and repeated cap-blocks re-create v4 agitation\n- pending file = tmpdir coldstart-kb-pending-<sid>.json, 24h TTL, consumed on delivery\n- capture survives Claude Code /compact via the kb-elicit shrink guard\n- manual capture is READ-ONLY on the session marker, so it cannot perturb automatic firing\n- the manual path prints the payload directly - no pending file, no kb-recall\n- manual self-discovers the session: freshest tmpdir marker whose recorded files resolve under --root\n- EMPIRICAL: descent has never fired in this repo; head-drift (commits) and cap (huge sessions) are the only automatic paths\n- score counts ALL stops since the last fire (engagement); quietRun counts only non-active stops (wind-down) - two different questions, two different counters\n- MIN_FILES_ARM=1 governs arming and descent (non-blocking); MIN_FILES=2 still governs head-drift and cap, because a one-file BLOCKING prompt is the v4 agitation the design exists to kill\n- a session that touches ZERO files never fires, however long it runs\n- manual capture marks the files it LISTED as captured, but leaves armed/activeStops/stopsSinceFire/quietRun untouched - it cannot change WHEN automatic capture fires, only what is still outstanding\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up to .coldstart/notebook), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist\n- capture survives Claude Code /compact via the kb-elicit shrink guard (a transcript shorter than stored lineCount is reprocessed from its new start, not dropped) - PR #81 fixed this after evidence collection silently died post-compact for the rest of a session\n- manual capture does NOT call trigger.step() and does not touch armed/activeStops/stopsSinceFire/quietRun - it only reads the marker and lists/marks worklist files, so it cannot change WHEN automatic capture next fires, only what is still outstanding\n- manual capture requires --session (or exactly one unambiguous marker under --root via soleMarkerUnderRoot); it no longer 'self-discovers the freshest marker' - that guessed wrong when multiple sessions had evidence, which PR #133 closed\n- EMPIRICAL: descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - not a threshold problem. Root cause (PR #96): a 2026-07-21 edit reclassified synthesis turns as quiet (correct, feeds descent) but left the score's engagement term reading activeStops instead of ALL stops since fire, deleting the only score-growth term a pure-discussion session has. Fixed by splitting into two counters: score uses stopsSinceFire (has enough happened), quietRun uses only non-active stops (has it wound down).\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist - PR #102 fixed a real case where a session that `cd`'d into ~/.claude/.../memory got those files recorded as if repo-local\n- captured=true means OFFERED by a fire, not WRITTEN by kb write - the manual path used to filter out every captured file, which silently dropped a session's own just-edited/new files from /capture-notes (PR #113); do not conflate the two states when touching either path\n- SubagentStop's capture prompt runs as the subagent's OWN turn, and a subagent's return value to its coordinator IS its last message - blocking a SubagentStop for the notebook step overwrote the actual deliverable until a subagent-only 'restate your result last' tail was added (PR #61); any new SubagentStop-blocking behavior needs the same tail or it will re-break this\n- the flow-note gate is a precision/recall knob that has swung to both extremes on the SAME axis with no automated test: PR #70 tightened it after a 32% junk-flow rate, then PR #100 found it had overcorrected to a hard zero (0 new flows in 6 days, every flow write folding into one pre-existing flow) six weeks later - only caught by eyeballing capture.jsonl rates by hand each time\n- concurrency identity: the durable worklist and the tmpdir evidence marker MUST share the exact key <sid>-<aid> (aid defaults to 'main'), never sid alone and never root alone - a subagent shares its parent's session id, so a looser key lets a subagent's capture clobber the main agent's list (PR #127 -> re-keyed by PR #133)\n- every worklist/marker write in this pipeline is deliberately best-effort (try/catch, 'capture must never fail because these could not be written') - correct for not blocking the agent, but means write failures are silent by design. There is no repair/reconciliation command today that checks marker state against worklist-file existence the way `kb repair` checks note shape against the sidecar - a hand-deleted .worklist-<sid>-<aid>.{json,md} stays gone forever for those files.\n- any change to this pipeline should be checked against the full matrix: 3 hosts (Claude/Cursor/Codex) x 2 roles (main/subagent) x 2 fire modes (automatic score-based / manual on-demand) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133)\n- capture survives Claude Code /compact via the kb-elicit shrink guard - PR #81 fixed evidence collection silently dying post-compact for the rest of a session\n- manual capture does NOT call trigger.step() and cannot change WHEN automatic capture next fires, only what is still outstanding\n- manual capture requires --session (or exactly one unambiguous marker under --root via soleMarkerUnderRoot)\n- EMPIRICAL (Claude/Cursor only): descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - PR #96 fixed a wrong score counter (activeStops instead of stopsSinceFire)\n- MIN_FILES_ARM=1 governs arming and descent (non-blocking); MIN_FILES=2 still governs head-drift and cap\n- a session that touches ZERO files never fires, however long it runs (Claude/Cursor)\n- evidence is attributed to the FROZEN repo root, so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist (PR #102)\n- captured=true means OFFERED by a fire, not WRITTEN by kb write - manual used to filter out every captured file, silently dropping a session's own just-edited/new files (PR #113 fixed this for edits)\n- 2026-08-06 FIX: a captured READ-ONLY file whose durable worklist artifact (.worklist-<sid>-<aid>.json) is missing - hand-deleted, or the write itself failed - is now re-included by manual capture even though captured=true, because there is no other live copy of that checklist anywhere. Checked via a fresh existsSync(worklistJsonPath(...)) at manual-capture time (hooks/kb-elicit.mjs), NOT via any change to trigger.mjs or automatic firing - deliberately narrow scope to avoid yet another regression cycle. Automatic firing does NOT self-heal a lost worklist; running /capture-notes (now working correctly on all 3 hosts, see below) is the recovery path.\n- SubagentStop's capture prompt runs as the subagent's OWN turn and IS its last message to the coordinator - blocking it for the notebook step overwrote the actual deliverable until a subagent-only 'restate your result last' tail was added (PR #61)\n- the flow-note gate is a precision/recall knob that has swung to both extremes on the SAME axis with no automated test: PR #70 tightened it (32% junk), PR #100 found it had overcorrected to zero six weeks later\n- concurrency identity: the durable worklist and the tmpdir evidence marker MUST share the exact key <sid>-<aid> (aid defaults to 'main'), never sid alone and never root alone (PR #127 -> re-keyed by PR #133)\n- 2026-08-06 MAJOR FIX, previously undiscovered: `/capture-notes` for ALL THREE HOSTS always ran the SAME shared hooks/kb-elicit.mjs --manual (src/init.ts's invocation is host-agnostic), which reads/writes tmpdir()/coldstart-kb-<sid>-<aid>.json. But Cursor's and Codex's OWN automatic Stop hooks (cursor-kb-elicit.mjs, codex-kb-elicit.mjs) wrote to DIFFERENT, host-prefixed marker files (coldstart-cursor-kb-*, coldstart-codex-kb-*) that the shared script's regex/glob never matched. Net effect: manual capture on Cursor/Codex could NEVER see evidence gathered by their own automatic Stop hooks - it always hit 'no notebook-capture evidence yet', even after last session's soleMarkerUnderRoot fallback, because there was nothing under the searched prefix to find. Every existing manual-capture test (this repo's own, before this fix) hand-seeded a coldstart-kb-* marker directly and so never caught it. FIXED by unifying all three hosts onto ONE marker prefix (coldstart-kb-) - src/kb/write-guide.ts's flowEvidenceCount already treated the three prefixes as one logical union by design, which is what made this discoverable: it was already assuming host-agnostic evidence that the marker filenames didn't actually deliver.\n- 2026-08-06 FIX: Cursor/Codex commands have no way to pass a real session id INTO the command body the way Claude's `!`-expansion does (confirmed via official docs, not just transcripts - no ! expansion in .cursor/commands/*.md, no session var on Codex skill bodies). Their own pre-prompt hooks (beforeSubmitPrompt / UserPromptSubmit) DO receive a real session_id though. Fix: the command body carries CAPTURE_SENTINEL (hooks/capture-sentinel.mjs); cursor-kb-recall.mjs/codex-kb-recall.mjs detect it in the submitted prompt and run kb-elicit.mjs --manual --session <real sid> themselves, injecting the result via the SAME additional_context/pending-capture channel already used for automatic-fire delivery. The command body's 'run this in the terminal' wording is kept as an explicit fallback for when the hook is disabled or fails - repair/repairAliases commands are untouched (UserCommand.hookInjected is capture-only, they need no session).\n- Codex's capture is NOT the same v5 trigger as Claude/Cursor: codex-kb-elicit.mjs does not import trigger.mjs at all and fires decision:block on every Stop that has new evidence, no arm/descent/score. This asymmetry predates 2026-08-06 and was not unified - flagged here, not fixed.\n- any change to this pipeline should be checked against the full matrix: 3 hosts x 2 roles (main/subagent) x 2 fire modes (automatic/manual) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133, plus the two 2026-08-06 fixes above)\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up to .coldstart/notebook), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist (PR #102 fixed a real case where a session that cd'd into ~/.claude/.../memory got those files recorded as if repo-local)\n- capture survives Claude Code /compact via the kb-elicit shrink guard (a transcript shorter than stored lineCount is reprocessed from its new start, not dropped) - PR #81 fixed evidence collection silently dying post-compact for the rest of a session\n- EMPIRICAL: descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - not a threshold problem. Root cause (PR #96): a 2026-07-21 edit reclassified synthesis turns as quiet (correct, feeds descent) but left the score's engagement term reading activeStops instead of ALL stops since fire, deleting the only score-growth term a pure-discussion session has. Fixed by splitting into two counters: score uses stopsSinceFire (has enough happened), quietRun uses only non-active stops (has it wound down)\n- every worklist/marker write in this pipeline is deliberately best-effort (try/catch, 'capture must never fail because these could not be written') - correct for not blocking the agent, but means write failures are silent by design. There is no repair/reconciliation command today that checks marker state against worklist-file existence the way `kb repair` checks note shape against the sidecar - a hand-deleted .worklist-<sid>-<aid>.{json,md} stays gone forever for those files, UNLESS it is a captured read-only file, which is recovered by manual capture (see the 2026-08-06 fix below)\n- any change to this pipeline should be checked against the full matrix: 3 hosts (Claude/Cursor/Codex) x 2 roles (main/subagent) x 2 fire modes (automatic score-based / manual on-demand) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133, plus the 2026-08-06 fixes below)\n- 2026-08-06 FIX: a captured READ-ONLY file whose durable worklist artifact (.worklist-<sid>-<aid>.json) is missing - hand-deleted, or the write itself failed - is now re-included by manual capture even though captured=true, because there is no other live copy of that checklist anywhere. Checked via a fresh existsSync(worklistJsonPath(...)) at manual-capture time (hooks/kb-elicit.mjs), NOT via any change to trigger.mjs or automatic firing - deliberately narrow scope to avoid yet another regression cycle. Automatic firing does NOT self-heal a lost worklist; running /capture-notes (now working correctly on all 3 hosts, see below) is the recovery path\n- 2026-08-06 MAJOR FIX, previously undiscovered: `/capture-notes` for ALL THREE HOSTS always ran the SAME shared hooks/kb-elicit.mjs --manual (src/init.ts's invocation is host-agnostic), which reads/writes tmpdir()/coldstart-kb-<sid>-<aid>.json. But Cursor's and Codex's OWN automatic Stop hooks (cursor-kb-elicit.mjs, codex-kb-elicit.mjs) wrote to DIFFERENT, host-prefixed marker files (coldstart-cursor-kb-*, coldstart-codex-kb-*) that the shared script's regex/glob never matched. Net effect: manual capture on Cursor/Codex could NEVER see evidence gathered by their own automatic Stop hooks - it always hit 'no notebook-capture evidence yet', even after the prior session's soleMarkerUnderRoot fallback, because there was nothing under the searched prefix to find. Every existing manual-capture test (this repo's own, before this fix) hand-seeded a coldstart-kb-* marker directly and so never caught it. FIXED by unifying all three hosts onto ONE marker prefix (coldstart-kb-) - src/kb/write-guide.ts's flowEvidenceCount already treated the three prefixes as one logical union by design, which is what made this discoverable: it was already assuming host-agnostic evidence that the marker filenames didn't actually deliver\n- 2026-08-06 FIX: Cursor/Codex commands have no way to pass a real session id INTO the command body the way Claude's `!`-expansion does (confirmed via official docs, not just transcripts - no ! expansion in .cursor/commands/*.md, no session var on Codex skill bodies). Their own pre-prompt hooks (beforeSubmitPrompt / UserPromptSubmit) DO receive a real session_id though. Fix: the command body carries CAPTURE_SENTINEL (hooks/capture-sentinel.mjs); cursor-kb-recall.mjs/codex-kb-recall.mjs detect it in the submitted prompt and run kb-elicit.mjs --manual --session <real sid> themselves, injecting the result via the SAME additional_context/pending-capture channel already used for automatic-fire delivery. The command body's 'run this in the terminal' wording is kept as an explicit fallback for when the hook is disabled or fails - repair/repairAliases commands are untouched (UserCommand.hookInjected is capture-only, they need no session)\n- Codex's capture is NOT the same v5 trigger as Claude/Cursor: codex-kb-elicit.mjs does not import trigger.mjs at all and fires decision:block on every Stop that has new evidence, no arm/descent/score. This asymmetry predates 2026-08-06 and was not unified - flagged here, not fixed\n- 2026-08-06 FIX: the static instructions half of the capture payload (DECIDE-FIRST/per-note/FLOWS/WRITE rules) is now generated ONCE per repo into the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (hooks/capture-payload.mjs ensureCaptureInstructions/shippedInstructionsTemplate), version-tagged so a future edit to the template self-heals a stale on-disk copy instead of silently drifting. This is a pure disk-I/O simplification (USER's own proposal, deferred to after the prior PR merged) - it does NOT change what the agent reads on any given fire (buildCapturePayload's return value still inlines the full instructions every time) and does NOT touch the worklist-deletion recovery fix above (that protects the per-session JSON half - files/tier/needsNote - which must stay per-session and deletable; only the static prose half moved to a permanent file). The per-session .worklist-<sid>-<aid>.md shrank from a full ~10KB duplicate to a ~400-byte worklist+pointer","backlinks":["src-init-ts-a867acfe"],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","hooks-capture-sentinel-mjs-944d6bea","hooks-codex-kb-elicit-mjs-9cb55b18","hooks-codex-kb-recall-mjs-cd4df13f","hooks-cursor-kb-elicit-mjs-151bef1e"]},{"id":"hooks-capture-payload-mjs-9f99e00d","type":"file","character":"single","title":"hooks/capture-payload.mjs","aliases":["rule 7","under capture","capture coverage denominator","worklist manifest tmpdir","inline spec shapes","checklist override","worklist scope rule","envelope","capture instructions","capture-instructions.md","permanent instructions file","shipped instructions template"],"status":"active","updated":"2026-08-06T11:16:13.455Z","edits":27,"anchors":[{"path":"hooks/capture-payload.mjs","symbols":["buildCapturePayload","recordWorklistManifest","worklistManifestPath","worklistLines","loadChecklistOverride"],"hash":"sha256:cb889f7d6a57","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"Builds the capture prompt (v5) for every host. 2026-08-06: the static DECIDE-FIRST/per-note/FLOWS/WRITE instructions (~150 lines, byte-identical every fire) no longer get duplicated onto disk per session. shippedInstructionsTemplate() is written ONCE to the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (ensureCaptureInstructions — version-tagged via INSTRUCTIONS_VERSION so a future template change self-heals a stale on-disk copy instead of drifting silently). renderCapturePayload substitutes {{CLI}}/{{ROOT}}/{{SID}}/{{AID}}/{{WORKLIST}} into that permanent body — the SAME placeholder mechanism the pre-existing `.coldstart/checklist.md` user-override path already used (loadChecklistOverride now takes precedence, ensureCaptureInstructions is the fallback; both paths share one substitution pass now instead of two near-duplicate branches). The per-session `.worklist-<sid>-<aid>.md` (writeDurableWorklist/renderDurableMd) is now SMALL — just the worklist + a pointer to the permanent file — instead of the full rendered payload. Nothing changes for the CURRENT fire: buildCapturePayload's return value (what the agent actually reads this turn) still inlines the complete instructions text every time; only what gets persisted to disk for a LATER re-Read shrank (~10KB -> ~400 bytes per session). This does not touch the worklist-deletion recovery fix from the same week (see the flow note) — that's about the JSON half (files/tier/needsNote), which must stay per-session and deletable; this split only concerns the static prose half.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — renders the compact shapes inline into the capture prompt","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","src-kb-search-ts-272e86f3","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"hooks-capture-sentinel-mjs-944d6bea","type":"file","character":"single","title":"hooks/capture-sentinel.mjs","aliases":["capture sentinel","capture-notes marker string","hook-injected command detection"],"status":"active","updated":"2026-08-06T09:53:32.824Z","edits":1,"anchors":[{"path":"hooks/capture-sentinel.mjs","symbols":["CAPTURE_SENTINEL"],"hash":"sha256:9ec243a69ec0","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Exports the single literal string CAPTURE_SENTINEL (<!-- coldstart:capture-notes -->) that src/init.ts embeds in the Cursor/Codex /capture-notes command body and that cursor-kb-recall.mjs/codex-kb-recall.mjs grep the submitted prompt for, so a host's pre-prompt recall hook can recognize its own capture command and run it with a real session id instead of leaving the agent to type one blind.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"why-a-file-note-s-extra-anchors-can-never-carry-symbols","type":"flow","character":null,"title":"why a file note's extra anchors can never carry symbols","aliases":["one addressable anchor per file note","verified creates anchors","anchor fill targets wrong note","repair pass never converges","symbols land on another note"],"status":"active","updated":"2026-08-03T04:18:58.898Z","edits":1,"anchors":[{"path":"src/kb/write.ts","hash":"sha256:d14c1dd5b965","state":"changed"},{"path":"src/kb/repair.ts","hash":"sha256:5f6602bab1c5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"A file note can accumulate anchors it is structurally incapable of ever filling: every path listed in a write's `verified` becomes an anchor, but only ONE of them — the anchor whose path derives the note id — is addressable by a later write. kbWrite routes a file note by spec.path and overwrites the record's anchors with a single entry at that path, so there is no spec that attaches symbols to a secondary anchor; a write aimed at one lands on whatever note that path derives to instead. Any code that walks a note's anchors and tries to fill them one by one is therefore writing to the wrong note and never converging, which is exactly how the keeper's auto-backfill disabled itself. Observed live 2026-08-03: a note written with verified:[src/alpha.ts, src/beta.ts] gained two anchors, and only the alpha one could ever be given symbols.\n\n## Steps\n\n1. `src/kb/write.ts` (`kbWrite`) — routes a file note by spec.path (fileNoteId) and overwrites record.anchors with one entry at that path — the constraint everything else inherits\n2. `src/kb/raw-log.ts` — stamps an anchor for every path in `verified`, which is how secondary anchors appear at all (observed via behaviour this session, file not read)\n3. `src/kb/repair.ts` (`mechanicalSymbolRepair`) — the consumer that must respect it — fills only the anchor whose path derives the note id, skipping the rest\n\n## Invariants\n\n- exactly one anchor per file note is addressable by a write: the one where fileNoteId(anchor.path) === note.id\n- a fill loop over note.anchors must skip every other anchor or it writes to a different note and re-fires forever","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked","src-kb-repair-ts-a197bcce","src-kb-write-ts-d5968d80","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"tests-kb-repair-test-ts-35dbd7b5","type":"file","character":"single","title":"tests/kb-repair.test.ts","aliases":["repair tests","lesson scope terms rejected","retract needs target","hub facet symbols","kbWrite call shape","repair writes nothing","kb repair tests","seedSidecar helper","backfill regression tests","secondary anchor test","convergence assertion"],"status":"active","updated":"2026-08-03T04:18:38.158Z","edits":3,"anchors":[{"path":"tests/kb-repair.test.ts","symbols":["planRepairs","repairWorklist","rawSnapshot","seedSidecar"],"hash":"sha256:71771b79bc32","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers kb repair: planRepairs/repairWorklist (pure, never writes) and mechanicalSymbolRepair (the one writing path). Verified 2026-08-03: the mechanical block seeds a fake sidecar directly via saveKbNotesIndex, so no real code index is needed. Two tests added for the wrong-note backfill bug — one asserts a secondary anchor (created by listing a second path in `verified`) is skipped, no note is conjured at its path, and a second pass fixes nothing; the other asserts a note already carrying aliasesVerified stays out of planAliasRepair after a backfill. The convergence assertion is the load-bearing one: a non-converging pass is what trips the keeper's streak cap.","backlinks":[],"anchorLinks":[]},{"id":"src-kb-write-ts-d5968d80","type":"file","character":"single","title":"src/kb/write.ts","aliases":["verified auto stamp","note freshness reset by edit","file note id from path","two-phase write gate","kb write validation","anchors overwritten on file note","file IS the anchor","secondary anchor unwritable","spec.path addresses the note","extra anchors dropped silently","symbols went to the wrong path"],"status":"active","updated":"2026-08-03T04:18:16.605Z","edits":4,"anchors":[{"path":"src/kb/write.ts","symbols":["kbWrite","WriteSpec","WriteOptions","WriteResult","WriteCandidate","exactAddressCandidates","pathWarnings"],"hash":"sha256:d14c1dd5b965","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"Validates and routes a kb write spec, then hands a record to the raw log. Two non-obvious rules live in the file-note branch. (1) It auto-fills `verified` with the anchor path, which makes raw-log stamp the file's live hash and reset freshness — conditional since 2026-07-30 on the spec carrying knowledge implying a read (summary, facets, body), so a metadata-only edit stamps nothing; an explicit `verified` is always honoured. (2) Verified 2026-08-03: the same branch OVERWRITES record.anchors with a single entry at spec.path and reads symbols only from spec.anchors[0] — so a file note's extra anchors are unwritable through this path. Secondary anchors exist (raw-log stamps one per `verified` path) but can never be given symbols, and a spec whose anchors[0] is not spec.path has those symbols silently attributed to spec.path instead. File-note ids derive from the path (never supplied); the two-phase candidate gate runs only for non-file notes.","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked","why-a-file-note-s-extra-anchors-can-never-carry-symbols","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"src-kb-repair-ts-a197bcce","type":"file","character":"single","title":"src/kb/repair.ts","aliases":["notes not findable","missing aliases","unfindable notes","repair worklist","Nothing to repair here","flow steps unanchored","repair prompt wording","preloadedSidecar param","anchor symbol backfill","mechanicalSymbolRepair","own anchor only","SYMBOL_BACKFILL_CAP","backfill wrote to wrong note","auto-backfill stopped firing","streak 3/3 disabled","secondary anchor never filled","repair never converges"],"status":"active","updated":"2026-08-03T04:18:16.473Z","edits":5,"anchors":[{"path":"src/kb/repair.ts","symbols":["planRepairs","repairWorklist","RepairFinding","RepairReport","subjectPaths","mechanicalSymbolRepair","SYMBOL_BACKFILL_CAP"],"hash":"sha256:5f6602bab1c5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"kb repair: detection worklist + the one mechanical exception, mechanicalSymbolRepair, which backfills anchors[].symbols on single-character file notes from the kb-notes-index sidecar (hub notes excluded, never overrides existing symbols, capped at SYMBOL_BACKFILL_CAP=15). Takes an optional preloadedSidecar so the keeper skips a redundant disk read. 2026-08-03: it can only ever fill the note's OWN anchor — the one whose path derives the note id (fileNoteId). It used to loop every anchor and re-put each under ITS own path; because kbWrite addresses a file note by spec.path, a secondary anchor's record landed on a different note, the real anchor stayed empty, and the pass re-fired every watcher cycle until the keeper's streak cap tripped and disabled auto-backfill permanently. It also now carries aliasesVerified forward when the note was already verified at its current edit, so a machine write does not push edits past aliasesVerifiedAtEdit and resurface the note in kb repair-aliases.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — runs missingInNote over the folded notebook","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-file-note-s-extra-anchors-can-never-carry-symbols"]},{"id":"src-kb-alias-repair-ts-f079a186","type":"file","character":"single","title":"src/kb/alias-repair.ts","aliases":["planAliasRepair","aliasRepairWorklist","hiddenIdentityAliases","pagination offset limit","aliasesVerifiedAtEdit stamp","stopping point","resume contract","offset advance unsafe","notes repeat forever","same note every run","pagination skips notes","offset skips notes after marking"],"status":"active","updated":"2026-08-02T18:21:55.330Z","edits":3,"anchors":[{"path":"src/kb/alias-repair.ts","symbols":["planAliasRepair","aliasRepairWorklist"],"hash":"sha256:78de3ecf8f3c","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"kb repair-aliases' engine. Distinct from kb repair's missing-identity-aliases check (that one catches notes with NO aliases; this is for aliases that EXIST but no longer describe the file/flow). planAliasRepair(root, offset, limit) paginates every active file/flow note, computing hiddenIdentityAliases via {capIdentity:false} so an agent sees what a blind retract would resurface. 2026-08-02 FIX: the command had no memory of 'already reviewed' — a note judged still-accurate reappeared on every future run forever, since that judgment left no trace (unlike kb repair's mechanical checks). Fixed with FoldedNote.aliasesVerifiedAtEdit (fold.ts): eligible now excludes a note where nothing has changed since its stamp. USER caught the real trap before this shipped: naively filtering that way breaks pagination, because `eligible` shrinks as notes get marked verified, so continuing to advance --offset by the page size (the OLD documented flow) silently skips whatever slides into that position next. Fix changed the RESUME CONTRACT, not the slicing: mark a batch verified, then re-run with offset 0 (default) — reviewed notes are simply gone from the list. offset/nextOffset still work for read-only browsing, just are no longer how you advance through a reconciling pass. Verified end to end same session: backfilled aliasesVerified:true onto all 53 notes this repo had already reconciled; kb repair-aliases now correctly reports 'No file/flow notes to reconcile.'","backlinks":[],"anchorLinks":[]},{"id":"src-init-ts-a867acfe","type":"file","character":"single","title":"src/init.ts","aliases":["repair-notes command","slash command wiring","capture-notes command","wireClaudeCommand","codex skill frontmatter","cursor no bang expansion","REPAIR_COMMAND","USER_COMMANDS table","repair-aliases command","already imports @coldstart.md","aliasesVerified instructions","no offset resume"],"status":"active","updated":"2026-08-02T18:21:55.074Z","edits":11,"anchors":[{"path":"src/init.ts","symbols":["wireClaudeImport","ensureColdstartignore","captureInvocation","wireClaudeCaptureCommand","wireCursorCaptureCommand","wireCodexCaptureSkill","USER_COMMANDS","REPAIR_COMMAND","CAPTURE_COMMAND","wireClaudeCommand","wireCursorCommand","wireCodexSkill","writeOwnedFile","installRoot","coldstartMd"],"hash":"sha256:d89dfee0ae35","state":"changed"}],"freshness":"changed","dir":"src","outLinks":["how-notebook-capture-fires-v5-trigger-timed"],"body":"init.ts owns coldstart init/setup for all three hosts. USER_COMMANDS is the single source of truth for every user-invoked slash-command/skill (capture-notes, repair-notes, repair-aliases): one row (invocation/description/skillDescription/instructions) per command, rendered by wireClaudeCommand/wireCursorCommand/wireCodexSkill into each host's own format. Deliberately thin `instructions`: the actual guidance lives in the command's own worklist output, never restated here. init's main flow also calls mechanicalSymbolRepair once on the upgrade path. 2026-08-02: USER_COMMANDS.repairAliases.instructions rewritten — it used to tell the agent to advance --offset across calls, which silently skips notes once repair-aliases starts excluding reviewed ones (the eligible list shrinks under a fixed offset). Now says: mark the batch aliasesVerified:true, then re-run with NO offset.\n\n## Facets\n\n- **wireClaudeImport** — BUG live in 2.2.0 (fix open in PR #80): presence check is substring includes(), so a CLAUDE.md that merely MENTIONS @coldstart.md in backticked prose (coldstart's own repo does) makes init report 'already imports' and skip writing the real import line — and Claude Code does not resolve imports inside code spans, so the guidance never loads. Fix = standalone-line check, symmetric with unwire's line-based strip.\n- **ensureColdstartignore** — Writes .coldstart/.coldstartignore (comments-only template; defaults live in hooks/ignore.mjs) and ensures a sibling .coldstart/.gitignore carries the .coldstartignore line so the file stays personal even in shared-notebook repos.\n- **captureInvocation** — bakes ONLY the absolute install path (resolveHooksDir) into the capture command - never a repo path. The hook defaults --root to cwd, so one identical invocation works for every host and every repo, and npm updates are picked up automatically. — [[how-notebook-capture-fires-v5-trigger-timed]]\n- **wireClaudeCaptureCommand** — writes .claude/commands/capture-notes.md. Uses Claude's leading-! expansion so the checklist is injected into the prompt at submit time rather than the agent having to run it. Fully-owned file, overwritten every init.\n- **wireCursorCaptureCommand** — writes .cursor/commands/capture-notes.md as a PLAIN prompt template - Cursor commands have no ! expansion, so the body must ask the agent to run the command itself.\n- **wireCodexCaptureSkill** — writes .agents/skills/capture-notes/SKILL.md, NOT a Codex prompt: Codex custom prompts live in global ~/.codex/prompts and are deprecated, so they cannot carry repo-scoped wiring. Skills are repo-scoped (walked up to the repo root) and REQUIRE name + description frontmatter.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"src-kb-fold-ts-cc536263","type":"file","character":"single","title":"src/kb/fold.ts","aliases":["note ordering","union never trims","alias cap","where did my aliases go","fold options","capIdentity flag","uncapped alias union","notebook merge conflict","raw log fold","aliasesVerified flag","aliasesVerifiedAtEdit stamp","post-increment edits check"],"status":"active","updated":"2026-08-02T18:21:54.944Z","edits":13,"anchors":[{"path":"src/kb/fold.ts","symbols":["fold","applyPut","applyRetract","capAliases","ALIAS_MAX","ALIAS_MAX_WORDS","stableStringify","FoldResult","PUT_KEYS"],"hash":"sha256:fe634a6ddd04","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"The fold — render is a fold, and the fold IS the merge. identityAliases union-forever + capped (capAliases, ALIAS_MAX=12); incidentAliases replaced wholesale by any write carrying summary/body. fold() takes an optional {capIdentity:false} to skip the cap and return the FULL historical union — the one consumer is kb repair-aliases, which needs to show an agent what's hidden past the render cap before it retracts anything. 2026-08-02: a put carrying aliasesVerified:true stamps note.aliasesVerifiedAtEdit = note.edits, set in the MAIN fold loop AFTER the edits++ increment (not inside applyPut, which still sees the pre-increment count) — this is the signal kb repair-aliases uses to stop resurfacing a note nothing has changed on since it was reviewed. 'aliasesVerified' is added to PUT_KEYS purely so it is not dumped into note.extra; it carries no stored content of its own.","backlinks":[],"anchorLinks":[]},{"id":"why-a-note-cannot-be-found-by-the-symbol-it-is-about","type":"flow","character":null,"title":"why a note cannot be found by the symbol it is about","aliases":["empty anchor symbols","kb search misses symbol","file-single shape","note not findable by name","lane 2 tool mode only","sidecar symbol inventory"],"status":"active","updated":"2026-08-02T18:19:44.673Z","edits":10,"anchors":[{"path":"src/kb/write-guide.ts","hash":"sha256:ea58bd486a3b","state":"changed"},{"path":"src/kb/search.ts","hash":"sha256:51e1afe7535c","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:c29235b37e62","state":"changed"},{"path":"tests/kb-shape-parity.test.ts","hash":"sha256:ab4a2402accd","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:a98db0290d25","state":"changed"},{"path":"src/kb/write.ts","hash":"sha256:38e7ca9a095a","state":"changed"},{"path":"src/kb/notes-index.ts","symbols":["buildKbNotesIndex","loadKbNotesIndex","saveKbNotesIndex","kbNotesIndexPath","KbNotesIndex","KB_NOTES_INDEX_VERSION","deriveRenames","stampCoversTerms"],"hash":"sha256:751df4c238dc","state":"fresh"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"CORRECTED 2026-08-01 (second pass — the first version of this note got the mechanism wrong; trust this paragraph over anything above it). A note's stored anchor symbols matter in HOOK mode only. Verified by running kbSearch both ways on `cmdSearch context` and reading carriers: lane 2 (resolveTermToSymbolFiles over the keeper's kb-notes.json sidecar, which holds a per-anchored-file symbol inventory — 35 of 47 files here, and it does contain cmdSearch for src/kb/cli.ts) is ENABLED in tool mode and DISABLED in hook mode at search.ts:488, because enabling it there produced false implants. So `kb search` can match a symbol a note never stored, while hook recall cannot. The shape gap was still real — file-single published no symbols field, so 2 of 44 notes stored any, and hook mode had nothing — but the earlier claim that the anchor channel is empty CORPUS-WIDE was wrong for tool mode. Beware attributing rank changes to this: after storing symbols on src/kb/cli.ts its note went from rank 2 to rank 1 in BOTH modes, but the summary was rewritten in the same write, so the cause is not isolated. Aliases have no such fallback in either mode: nothing derives them, so a note without them is reachable only by its exact title, and the capture prompt's inlined copy of the flow shape had silently lost the field.\n\n## Steps\n\n1. `src/kb/write-guide.ts` (`WRITE_GUIDE_SHAPES`, `missingFieldsWarning`) — canonical shapes + the post-write report naming what is missing\n2. `hooks/capture-payload.mjs` (`buildCapturePayload`) — the inlined SECOND copy agents actually read — where the drift happened\n3. `src/kb/write.ts` (`kbWrite`) — accepts and unions anchors[{path,symbols}] on file specs — capability was never the constraint\n4. `src/kb/search.ts` (`kbSearch`) — weights the anchor channel x2 for exactly these terms, and found it empty\n5. `tests/kb-shape-parity.test.ts` (`REQUIRED`) — pins the two copies so the drift cannot recur\n\n## Invariants\n\n- The anchor channel can only hold what the spec shape asks for — a matcher change cannot recover a field agents were never told to write.\n- file-single is the default and ~97% of volume, so anything missing from ITS shape is missing from the corpus.\n- Tool-mode (kb search) quality is invisible in the inject log: cli.ts logs inject-log only when flags.hook, so tool hits have never been recorded — one tool-source query exists in the entire history, a miss.\n- Two copies of a shape drift silently; the parity test is the only thing that makes it loud.\n- Findability checks REPORT, never reject: the capture prompt chains writes with && so a non-zero exit silences every note behind the failing one.\n- Tool-mode (kb search) quality is still invisible in the inject log: cli.ts logs it only when flags.hook, so tool hits have never been recorded.\n- Lane 2 (sidecar symbol inventory) is tool-mode ONLY — search.ts:488. Stored anchor symbols are the only symbol evidence hook mode has.\n- Aliases have no derived fallback anywhere; a note without them is reachable only by its exact title.\n- Two copies of a shape drift silently; tests/kb-shape-parity.test.ts is what makes it loud.","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","src-kb-search-ts-272e86f3","what-counts-as-the-query-for-notebook-recall","hooks-capture-payload-mjs-9f99e00d","src-kb-cli-ts-99b5d5ba"]},{"id":"where-the-required-note-shape-is-defined-and-how-it-reaches","type":"flow","character":null,"title":"where the required note shape is defined, and how it reaches every surface","aliases":["one note shape table","note-shape.mjs","required note fields","shape drift","hooks cannot import dist","NOTE_CHECKS","missingInSpec missingInNote","add a note requirement"],"status":"active","updated":"2026-08-02T18:19:44.664Z","edits":5,"anchors":[{"path":"hooks/note-shape.mjs","hash":"sha256:c42cfbd8820f","state":"changed"},{"path":"src/kb/write-guide.ts","hash":"sha256:bfd678a3e8b5","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:eff608418ff7","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:427809766ada","state":"changed"},{"path":"src/kb/repair.ts","hash":"sha256:ce2b42070900","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:a5bb3cf1046d","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"There is exactly ONE definition of what a note must contain — hooks/note-shape.mjs — and it lives in hooks/ rather than src/ because the capture hooks are plain .mjs that run straight from the package and never import from dist/; the TypeScript side reaches INTO hooks/ instead (the pattern lint.ts already uses with ignore.mjs), which is what lets one file serve the hook, the CLI and the MCP server. Adding a requirement is one NOTE_CHECKS entry and it reaches all five consumers at once: the write guide, the capture prompt's inlined shapes, the MCP kb_write description, the write-time warning, and kb repair's detection. Each entry carries TWO predicates on purpose — missingInSpec reads the JSON an agent just sent, missingInNote reads the folded note on disk; they cannot be collapsed, so they sit adjacent and a change to what 'missing' means has to be made in both, in view of each other. Verified this session: tsc's rootDir does NOT reject the cross-directory import (a .d.mts beside the .mjs supplies the types), and vitest imports the same file from both TS and .mjs test code.\n\n## Steps\n\n1. `hooks/note-shape.mjs` (`SPEC_SHAPES`, `NOTE_CHECKS`, `shapesBlock`, `requiredFieldsLine`, `checksForSpec`, `checksForNote`, `unanchoredSteps`, `stepsMissingAfterWrite`) — the single table plus its renderers\n2. `src/kb/write-guide.ts` (`WRITE_GUIDE_SHAPES`, `missingFieldsWarning`, `flowStepsWarning`) — renders the guide and the write-time warning from checksForSpec\n3. `hooks/capture-payload.mjs` (`buildCapturePayload`) — renders shapesBlock({compact:true}) inline — the copy that used to drift\n4. `src/server/mcp.ts` (`TOOL_DEFINITIONS`) — kb_write description injects requiredFieldsLine(); this copy never said aliases at all\n5. `src/kb/repair.ts` (`planRepairs`, `repairWorklist`) — runs missingInNote over the folded notebook\n\n## Invariants\n\n- Hooks NEVER import from dist/ — a shared table must live in hooks/ or the capture prompt cannot see it.\n- Renderings may differ in prose (compact drops it) but never in fields; tests/kb-shape-parity.test.ts asserts every required field appears in the example an agent copies.\n- A shipped `check` id is never removed — kb repair --json consumers filter by it; retire one by making its predicate always false.\n- missingInSpec and missingInNote read different shapes and cannot be merged; both live in the same entry so neither is edited alone.\n- Every write-time WARN is judged against the FOLDED note, never the record just sent — `op: put` appends and the fold merges, so a partial update omits fields it still has. Both call sites (src/kb/cli.ts and src/server/mcp.ts) load the folded note and must pass it to every warning; a warning that takes only the spec will misfire on updates.","backlinks":["hooks-capture-payload-mjs-9f99e00d","hooks-note-shape-mjs-d85ce294","src-kb-cli-ts-99b5d5ba","src-kb-repair-ts-a197bcce","src-kb-write-guide-ts-c9053885","src-server-mcp-ts-18031783"],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","hooks-capture-payload-mjs-9f99e00d","hooks-note-shape-mjs-d85ce294","how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","src-kb-cli-ts-99b5d5ba"]},{"id":"what-counts-as-the-query-for-notebook-recall","type":"flow","character":null,"title":"what counts as \"the query\" for notebook recall","aliases":["why was this note injected","note about a file I never mentioned","path match boost","harness telemetry in the prompt","grep pattern became the query","my shell command got injected"],"status":"active","updated":"2026-08-02T18:19:44.656Z","edits":5,"anchors":[{"path":"src/kb/search.ts","hash":"sha256:0f8e8b280da3","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:c2ff1ee17d47","state":"changed"},{"path":"hooks/kb-recall.mjs","hash":"sha256:a82ef1040d11","state":"changed"},{"path":"hooks/recall-query.mjs","hash":"sha256:4a146b7ec842","state":"fresh"},{"path":"hooks/preguard-handler.mjs","hash":"sha256:f136ff422137","state":"fresh"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"The text the recall matcher scores is NOT what the user typed. Two distinct feeds prove it. (1) Every host wraps the user's words in editor/subagent telemetry, which is file- and symbol-rich and hijacks the path-name override in search.ts (+100, bypassing the rarity and suppression gates) — fixed 2026-07-29 in the HOOKS via recall-query.mjs, never in search.ts, because the override is opts.strongOnly-gated and tool-mode kb search must keep trusting a path the user typed literally. (2) OBSERVED 2026-07-29 in inject-log.jsonl: the PostToolUse nudge path also drives kb search --hook, so an AGENT's raw grep pattern lands in the log as a query and can inject — the record at 17:01:29Z has query 'rareCount |let rare = false' (a shell grep pattern, not a prompt) with implant:true against hooks-capture-payload-mjs. So an agent-term recall channel already exists in partial form; anyone measuring 'should we add grep terms as a signal' must subtract what the nudge already does.\n\n## Steps\n\n1. `hooks/kb-recall.mjs` (`recallQuery`) — UserPromptSubmit feed — strips harness wrappers BEFORE the 2000-char slice\n2. `hooks/recall-query.mjs` (`stripHarnessWrappers`) — shared prompt hygiene for all three hosts; named tags only, so real questions survive\n3. `hooks/preguard-handler.mjs` (`canonicalFindKey`) — the OTHER feed — wired on every Bash call, and the nudge path puts tool-call text into recall\n4. `src/kb/cli.ts` — --hook: strongOnly search, writes every decision to inject-log.jsonl (the evidence for both feeds)\n5. `src/kb/search.ts` (`kbSearch`) — scores whatever arrives; the path override treats any contained anchor path as the user naming that file\n\n## Invariants\n\n- inject-log.jsonl query strings are NOT all user prompts — some are agent tool-call text, so any corpus study over it must classify the feed first\n- stripping belongs in the hooks; search.ts stays feed-agnostic so tool mode keeps honouring literally-typed paths","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-kb-recall-mjs-bb2f72e8","hooks-preguard-handler-mjs-e53f8b7b","hooks-recall-query-mjs-6503796e","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"tests-kb-shape-parity-test-ts-afd06d3a","type":"file","character":"single","title":"tests/kb-shape-parity.test.ts","aliases":["anchors come from steps","TOOL_DEFINITIONS","required note fields","spec shape drift","note shape drift test","every surface renders from table","warning folded note test","write time warning contract","requiredFieldsLine assertion","repair-aliases drift guard","identityAliases field name pin","pagination contract test","repair-aliases text drift","kb_repair_aliases description mismatch"],"status":"active","updated":"2026-08-02T18:19:44.646Z","edits":5,"anchors":[{"path":"tests/kb-shape-parity.test.ts","symbols":["shapeBlock","REQUIRED","SPEC_SHAPES","NOTE_CHECKS","checksForSpec","requiredFieldsLine","missingFieldsWarning","flowStepsWarning","unanchoredSteps","shapesBlock","TOOL_DEFINITIONS","aliasRepairWorklist","USER_COMMANDS","REPAIR_ALIASES_COMMAND"],"hash":"sha256:614e291ace82","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Pins every consumer to hooks/note-shape.mjs so a required field cannot go missing from one surface again: each spec example must contain the fields its own checksForSpec demands, the write guide and capture prompt must both carry every example verbatim, the MCP kb_write description must contain requiredFieldsLine(), and a dedicated suite asserts no surface says a flow's anchors come from its steps. It also carries the write-time warning contracts (flowStepsWarning/missingFieldsWarning judge the fold, not the spec). A newer describe block, 'kb repair-aliases surfaces agree with each other and with the frozen field name', extends the same drift-guard idea to a field note-shape.mjs's SPEC_SHAPES never covers directly: identityAliases only appears in the repair-aliases worklist/MCP tool/USER_COMMANDS text, not in any spec an agent writes, so it pins those three surfaces to each other by hand (the exact 'identityAliases' string, the empty-notebook sentinel 'No file/flow notes to reconcile.', the offset/limit MCP schema props, and the 'no aliases at all' line distinguishing it from kb repair's own missing-identity-aliases check) rather than deriving them from a table the way SPEC_SHAPES lets the rest of this file do.","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"tests-kb-search-write-test-ts-0c3c0c6d","type":"file","character":"single","title":"tests/kb-search-write.test.ts","aliases":["ranking contract test","stale outranks fresh","superseded hard tier","kb search unit tests","metadata write test","verified stamp test","kb write unit tests"],"status":"active","updated":"2026-08-02T18:19:44.638Z","edits":4,"anchors":[{"path":"tests/kb-search-write.test.ts","symbols":["kbSearch","kbWrite","renderCompactPage","fakeIndex","writeRepoFile","seedLesson","strongOnly"],"hash":"sha256:96be90d6f342","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Unit tests for kb search ranking and kb write. Holds two contract regressions worth knowing before editing either area: 'staleness LABELS but does not rank' asserts a stale note covering every query term outranks a fresher note covering fewer while a superseded note stays last (this test asserted the OPPOSITE order until 2026-07-30, so an inverted expectation here means freshness has crept back into the sort); and 'a metadata-only write does NOT re-verify the anchor' asserts a title-only write records an empty `verified` and no hash, while a write carrying a summary re-stamps. Both fixtures write real files and drift them, so they exercise live hashing rather than mocked anchor state.","backlinks":[],"anchorLinks":[]},{"id":"tests-kb-retrieval-live-test-ts-f5d387f6","type":"file","character":"single","title":"tests/kb-retrieval-live.test.ts","aliases":["retrieval regression tests","injection floor tests","calibration tests","single carrier exemptions","tier number assertion","retrieval test without notesIndex","admission contract test"],"status":"active","updated":"2026-08-02T18:19:44.629Z","edits":6,"anchors":[{"path":"tests/kb-retrieval-live.test.ts","symbols":["kbSearch","notesIndex","seedCorpus","touch","noteLine","strongOnly"],"hash":"sha256:1ecfff69d579","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Live retrieval tests over a real seeded notebook — the hook-mode admission contracts live here, so this is the file that tells you whether a ranking change is intentional or a regression. Two things to know before editing. First, most tests here call kbSearch WITHOUT notesIndex, which means convergence cannot fire and every hit is name-channel-only; a change that penalises name-only hits will fail tests that look unrelated (stemming, matcher repairs) for that reason alone rather than because stemming broke. Second, 'convergence stands alone only when the term is also rare' asserted the OPPOSITE contract until 2026-07-31 — it was named 'convergence bypasses the suppression gate' and its setup deliberately pushes a term out of the rare band with six body-only decoy notes so that convergence is the only thing that could admit it. That exact shape is now the junk case, so the test asserts both halves: common+converged stays suppressed, rare+converged still injects on a single carrier. If you are relaxing the rarity requirement, this test is the one that should stop you.","backlinks":[],"anchorLinks":[]},{"id":"tests-kb-fold-test-ts-363d2ac8","type":"file","character":"single","title":"tests/kb-fold.test.ts","aliases":["fold determinism test","alias cap regression","shuffled records fold identically","capIdentity test"],"status":"active","updated":"2026-08-02T18:19:44.612Z","edits":4,"anchors":[{"path":"tests/kb-fold.test.ts","symbols":["fold","stableStringify","capAliases","ALIAS_MAX","ALIAS_MAX_WORDS","put"],"hash":"sha256:8e41124f3672","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"fold.ts unit tests. Added a case for fold(..., {capIdentity:false}): asserts the uncapped result is a strict superset of the capped one and includes aliases the cap would have dropped (reuses the same 5-write/30-alias fixture the existing cap test already builds).","backlinks":[],"anchorLinks":[]},{"id":"src-watcher-ts-0eb096ed","type":"file","character":"single","title":"src/watcher.ts","aliases":["watcher loop","keeper self-write loop","excluded dir watcher"],"status":"active","updated":"2026-08-02T18:19:44.604Z","edits":6,"anchors":[{"path":"src/watcher.ts","symbols":["startWatcher","isUnderExcludedDir","EXTENSION_TO_LANGUAGE","onNotebookRaw","BatchHandler"],"hash":"sha256:a2b29ceb0b4d","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Debounced (400ms) recursive fs.watch wrapper that feeds the keeper two separate routes: notebook .raw/*.jsonl events go to onNotebookRaw, everything else is filtered to indexed extensions and goes to the code batch. The non-obvious hazard, verified here: .html and .md ARE both present in EXTENSION_TO_LANGUAGE, so the keeper's own writes under .coldstart/ (it regenerates notebook/index.html and re-renders derived .md on every notes refresh) used to clear the extension filter and re-enter the code batch as 'repo changed' - a self-feeding loop that re-saved the cache and regenerated the view about every 5s. Fixed in #92 by the isUnderExcludedDir guard, which mirrors the walker's hidden/excluded-dir rules and is shared with patch so the rule cannot drift. The .raw/*.jsonl route is checked BEFORE the extension filter, which is why real note writes still refresh the view.","backlinks":[],"anchorLinks":[]},{"id":"src-unwire-ts-aab82fa6","type":"file","character":"single","title":"src/unwire.ts","aliases":["unwire","deinit","leftover wiring","uninstall","repair-notes removal","init unwire symmetry","rmEmptyDirs","strip slash commands","no unwire tests","repair-aliases sweep"],"status":"active","updated":"2026-08-02T18:19:44.595Z","edits":4,"anchors":[{"path":"src/unwire.ts","symbols":["runUnwire","stripHooksConfig","unwireJsonMcp","removeFile","rmEmptyDirs"],"hash":"sha256:292d6038573c","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"The explicit reverse of init. Now sweeps THREE user-invoked commands (capture-notes, repair-notes, repair-aliases) across all three hosts using the same REPAIR_ALIASES_COMMAND constant init.ts exports — symmetric with how init writes them, verified live (init writes 2 command files per host, unwire removes both and prunes the now-empty skill dir).","backlinks":[],"anchorLinks":[]},{"id":"src-kb-write-guide-ts-c9053885","type":"file","character":"single","title":"src/kb/write-guide.ts","aliases":["symbols missing from file notes","empty anchor symbols","write guide shapes","missing aliases warning","under-indexed note","required note fields","symbols in file note","put is not overwrite","warning judges folded note","kb write guide","mcp cli parity","flow evidence warning"],"status":"active","updated":"2026-08-02T18:19:44.544Z","edits":14,"anchors":[{"path":"src/kb/write-guide.ts","symbols":["WRITE_GUIDE_SHAPES","flowEvidenceWarning","flowStepsWarning","writeGuideCli","writeGuideMcp","missingFieldsWarning","flowEvidenceCount"],"hash":"sha256:bfd678a3e8b5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"Single source for the kb write spec guide and every write-time WARN, shared by the CLI (kb write, no spec -> guide) and MCP kb_write (parity: identical semantics, only the howto tail differs). flowEvidenceCount scans tmpdir capture markers from ALL THREE hosts (coldstart-kb-/coldstart-cursor-kb-/coldstart-codex-kb- prefixes) for the session's content-read set. This file NO LONGER OWNS THE SHAPES: WRITE_GUIDE_SHAPES is shapesBlock() from hooks/note-shape.mjs and missingFieldsWarning is a loop over checksForSpec(type), so what warns here and what kb repair detects on disk cannot disagree. THE RULE EVERY WARN HERE MUST FOLLOW, learned twice: judge the FOLDED note, never the record just sent. `op: put` appends a record and the note is the fold of the whole log (aliases/anchors union, summary/steps LWW), so a partial update legitimately omits fields it is not changing. flowStepsWarning was fixed for this first — it takes the folded note and delegates to stepsMissingAfterWrite. missingFieldsWarning had the identical defect four lines down and was fixed 2026-08-01: it now takes an optional `after` and a field counts as missing only when missingInSpec(spec) AND missingInNote(after). The AND matters — swapping outright to missingInNote would make the repair-only checks (flow-no-steps, flow-steps-unanchored, both missingInSpec:()=>false) start firing at write time and duplicate flowStepsWarning. With no `after` it falls back to the spec, which is exact for a create.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — renders the guide and the write-time warning from the table","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"src-kb-session-worklist-ts-dc6104ba","type":"file","character":"single","title":"src/kb/session-worklist.ts","aliases":["capture coverage","under-capture reporting","worklist manifest reader","coverage denominator fresh notes","flow does not count as file note"],"status":"active","updated":"2026-08-02T18:19:44.526Z","edits":4,"anchors":[{"path":"src/kb/session-worklist.ts","symbols":["noteCoverage","specPaths","manifestPath","load"],"hash":"sha256:4e1e7af12a3b","state":"missing"}],"freshness":"missing","dir":"src/kb","outLinks":[],"body":"Reads the session worklist manifest that hooks/capture-payload.mjs drops in tmpdir and turns it into the coverage line `kb write` prints. noteCoverage(sid, spec) appends this write's paths to the manifest's `wrote` array, then reports done/outstanding. Two deliberate arithmetic choices: files whose note is already fresh are EXCLUDED from the denominator (counting them makes full coverage unreachable and the ratio meaningless, though they are still reported as 'N more already had a fresh note'), and specPaths() credits only file-single/file-hub — a flow does NOT count as a note for its step files, because a flow is not the per-file note rule 5 asks for. Everything is best-effort: no session, no manifest, a malformed one, or one older than 24h (a resumed session) all return null rather than throwing. The manifest lives in tmpdir and never in the repo, so it cannot be committed and needs no ignore rule; it is scratch state for one session, not a record, and nothing about it leaves the machine.","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured"]},{"id":"src-kb-search-ts-272e86f3","type":"file","character":"single","title":"src/kb/search.ts","aliases":["lane 2 anchor admission phantom evidence","tool mode vs hook mode search gates","notebook search precision","domain word rarity","anchor channel inflates df","hook mode rarity gate","ecommerce domain noun problem","rareMax vs minority threshold","hardEvidence flag"],"status":"active","updated":"2026-08-02T18:19:44.517Z","edits":19,"anchors":[{"path":"src/kb/search.ts","symbols":["kbSearch","KbSearchOptions","KbSearchHit","KbSearchResult","strongOnly","HOOK_MIN_CARRIERS","NAME_ONLY_MIN_DENSITY","rarityMax","isCodeShaped","wordHit","hookNameNorm","haystacksFor","resolveTermToAnchors","resolveTermToSymbolFiles","symbolTokens","absenceVerdict","renderSearchPage","renderCompactPage","gistLines","shouldImplantTop","stem","renderResultsPage"],"hash":"sha256:51e1afe7535c","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:cd323aa5c322","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"The notebook search engine, in two modes chosen by strongOnly (hook = precision-first admission gates; tool = BM25, no gates). HOOK-MODE RARITY (separate from the tool-mode lane-2 phantom evidence already noted here): df at L430 is document frequency across name+anchor+body COMBINED, so a term that is a widely-declared anchor symbol inflates its own df even when it never appears in prose. Two different thresholds use it: eligibility (`minority`, L510, df*2<=notes.length, ~50%) drops a term from scoring entirely if it fails; hardEvidence (`rareMax=ceil(N/10)`, L178/516/543) requires the stricter top-10% band before a symbol-convergence hit can admit a note alone, UNLESS the term is code-shaped (isCodeShaped, L278) which bypasses rarity outright. Risk: in a domain-concentrated codebase a real entity name (e.g. an ecommerce Order/Shipment declared as an anchor symbol on many file notes) can fail hardEvidence's rarity band via the SAME mechanism that correctly suppresses generic filler (run/status/write) -- notebook-wide df does not distinguish 'generic English' from 'domain-central but frequent'. Untested on this repo's own notebook (too small/self-referential); needs a real domain-heavy notebook (e.g. ARCHES) to size.","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","what-counts-as-the-query-for-notebook-recall","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-kb-raw-log-ts-ba590d64","type":"file","character":"single","title":"src/kb/raw-log.ts","aliases":["anchor hash written here","appendRecord","raw log append","verified triggers hashing","note provenance stamp"],"status":"active","updated":"2026-08-02T18:19:44.501Z","edits":3,"anchors":[{"path":"src/kb/raw-log.ts","symbols":["appendRecord","readLog","listIds","rawPath","rawDir","notebookDir","KB_RAW_VERSION","AppendOptions","ReadLogResult"],"hash":"sha256:0815f155b48a","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"Appends one JSON line per note record and is the ONLY producer of anchor hashes: for every path listed in a record's `verified`, appendRecord hashes that file at append time and writes the hash into the record's anchor (creating the anchor if absent). Agents never author hashes. It also stamps `v`, `ts`, and the git `head` as provenance, overriding any agent-supplied head. A record with an empty or absent `verified` carries no hash at all, which is what lets the fold keep a note's earlier verification intact.","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked"]},{"id":"src-kb-freshness-ts-8278f01b","type":"file","character":"single","title":"src/kb/freshness.ts","aliases":["evidence changed","note freshness","stale note","is a note still valid","does freshness depend on git","branch switch note freshness"],"status":"active","updated":"2026-08-02T18:19:44.492Z","edits":3,"anchors":[{"path":"src/kb/freshness.ts","symbols":["hashFile","stampAnchors","freshnessLine","anchorsAllMissing","RenameMap"],"hash":"sha256:7a81ff09fde6","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"The hash tripwire behind [fresh]/[evidence changed]. Verified 2026-07-24: freshness has NO git dependency whatsoever — grepping this file for 'head' returns zero matches. hashFile is a whole-file raw-byte SHA-256 (first 12 hex, never per-symbol) and stampAnchors compares each anchor's stored hash against the live file NOW, so an anchor's recorded `head` commit is never consulted here. Consequence worth knowing before assuming otherwise: note freshness is content-addressed, not commit-addressed, and therefore survives branch switches and would survive notes living outside git entirely. A missing file resolves through the keeper's rename map only when the destination's live content still equals the recorded hash, so a stale rename hint can never resurrect a note wrongly.","backlinks":[],"anchorLinks":[]},{"id":"src-kb-cli-ts-99b5d5ba","type":"file","character":"single","title":"src/kb/cli.ts","aliases":["flow decision one call","kb write decision flag","coverage line kb write","N of M files noted","warnings never fail write","exit code 3 candidates","kb verb dispatcher","exit code 3","kb write warnings order","repair-aliases verb","offset limit flags"],"status":"active","updated":"2026-08-02T18:19:44.475Z","edits":15,"anchors":[{"path":"src/kb/cli.ts","symbols":["cmdWrite","cmdSearch","runKb","recordFlowDecision","parseKbArgs","cmdLookup","cmdLint","requireNotebook","USAGE","missingFieldsWarning","flowStepsWarning"],"hash":"sha256:57f5ef7e46af","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"The kb verb dispatcher. New verb `repair-aliases [--offset N] [--limit 10] [--json]` calls planAliasRepair/aliasRepairWorklist from alias-repair.ts — pure read, paginated, never writes. Like `repair`, it deliberately does not call ensureKeeper (reads only the folded notebook).\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — exposes repair detection as a CLI verb","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured","what-counts-as-the-query-for-notebook-recall","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"site-index-html-f8b5f3ae","type":"file","character":"single","title":"site/index.html","aliases":["meta keywords","JSON-LD structured data","og image","landing page marketing site","blog cards","featured posts","article-card","SEO"],"status":"active","updated":"2026-08-02T18:19:44.416Z","edits":10,"anchors":[{"path":"site/index.html","hash":"sha256:405d3b4d0b9b","state":"changed"}],"freshness":"changed","dir":"site","outLinks":[],"body":"The #blog section near the end features exactly TWO hand-picked article cards linking into site/blog/; they are hardcoded and do not read from blog.html, so adding or renaming a post silently leaves stale links here. Those cards are styled by .article-card in the sibling styles.css, NOT by docs.css which the blog pages themselves use.","backlinks":[],"anchorLinks":[]},{"id":"site-docs-css-54e94142","type":"file","character":"single","title":"site/docs.css","aliases":["ch unit measure bug","essay column alignment","figure wider than text","diagram overflows the column","svg figure","hand drawn diagram","feTurbulence","sketch style","figcaption monospace","prefers-color-scheme","measure","dark mode"],"status":"active","updated":"2026-08-02T18:19:44.406Z","edits":11,"anchors":[{"path":"site/docs.css","hash":"sha256:8b82bb1e4718","state":"changed"}],"freshness":"changed","dir":"site","outLinks":[],"body":"The shared stylesheet for BOTH non-landing surfaces: docs.html (sidebar reference layout, body.docs-page) and every blog page (body.essay-page). The landing page uses styles.css instead, so .article-card on index.html is NOT styled here. The blog section at the end scopes its OWN theme tokens to body.essay-page: light by default with a prefers-color-scheme dark override, which is why docs.html stays dark while the blog follows the reader's OS. --measure MUST stay an absolute length (680px) and never ch: ch resolves against each element's own font-size, so a 46px h1 and a 19px p computed different widths and margin-inline:auto then centred every child of .essay-article on a different left edge (fixed in #105). Two widths govern essay layout and they differ on purpose: `.essay-article > *` constrains every child to --measure, while `.essay-article > .wide` opts out to min(920px,100%) — that 240px gap is why figures visibly overhang the prose column. The FIGURES block (added #111) styles inline-SVG diagrams: the hand-drawn look is a seeded feTurbulence displacement applied per figure, and the filtered <g> must contain ONLY shapes because displaced text is unreadable. It also overrides `.essay-article figcaption`, whose base rule sets font-family:var(--mono) and rendered diagram captions as code comments.","backlinks":[],"anchorLinks":[]},{"id":"scripts-replay-recall-gates-mjs-6f8d13d2","type":"file","character":"single","title":"scripts/replay-recall-gates.mjs","aliases":["recall replay harness","measure recall outside coldstart","compare two builds","hook mode assertion","tool mode replay","noMissLog replay"],"status":"active","updated":"2026-08-02T18:19:44.397Z","edits":3,"anchors":[{"path":"scripts/replay-recall-gates.mjs","symbols":["kbSearch","loadKbNotesIndex","loadAll","arg","strongOnly","noMissLog","notesIndex"],"hash":"sha256:923c50687d2a","state":"changed"}],"freshness":"changed","dir":"scripts","outLinks":[],"body":"Replays a notebook's logged prompts through kbSearch and diffs two builds, so a recall change can be measured on a notebook that is NOT this repo's — the reason it exists is that coldstart's own notebook is ~44 notes about coldstart, where the junk cause the gates target barely occurs. Used by humans only: nothing imports it, it is invoked as `node scripts/replay-recall-gates.mjs --root <repo> --dist <coldstart>/dist [--mode hook|tool] [--out f.json]`, then `--compare before.json after.json`. Its reason for printing the options it used is a real incident: KbSearchOptions has NO `hook` field, so {hook:true} silently runs TOOL mode with convergence off, which voided an entire measurement — the header line is the assertion that the run is the mode you think. `--mode tool` exists because every admission gate in kbSearch is wrapped in `if (opts.strongOnly)` while the fold runs upstream of both modes, so an alias-side change can move `kb search` results while looking invisible in hook mode. Read-only on the target repo: it passes noMissLog so the replay does not pollute that repo's metrics.","backlinks":[],"anchorLinks":[]},{"id":"how-an-agent-finds-out-it-under-captured","type":"flow","character":null,"title":"how an agent finds out it under-captured","aliases":["capture coverage","under-capture reporting","N of M files noted","worklist manifest","capture coverage line"],"status":"active","updated":"2026-08-02T18:19:44.379Z","edits":5,"anchors":[{"path":"hooks/capture-payload.mjs","hash":"sha256:ea825a4f366c","state":"changed"},{"path":"src/kb/session-worklist.ts","hash":"sha256:4e1e7af12a3b","state":"missing"},{"path":"src/kb/cli.ts","hash":"sha256:0e915261a609","state":"changed"}],"freshness":"missing","dir":"hooks","outLinks":[],"body":"An agent's own note count is the one thing it cannot check while writing, because kb write sees one spec at a time and never saw the worklist — so the worklist is handed forward out-of-band, through a tmpdir file keyed by session id, and comes back as a ratio printed with each write. The import graph cannot see this link at all: hooks/capture-payload.mjs (an .mjs hook) and src/kb/session-worklist.ts (the TS CLI) never import each other and agree only on a filename template, tmpdir/coldstart-kb-worklist-<sid>.json. Change the name or the record shape on one side and coverage silently stops printing — there is no error, because every read is best-effort by design.\n\n## Steps\n\n1. `hooks/capture-payload.mjs` (`buildCapturePayload`, `recordWorklistManifest`, `worklistManifestPath`) — the one point every host passes through — writes the manifest (path, tier, needsNote) as a side effect of building the prompt\n2. `src/kb/session-worklist.ts` (`noteCoverage`, `specPaths`) — reads it back, records this write, computes done vs outstanding\n3. `src/kb/cli.ts` (`cmdWrite`) — prints the line under the write's own output, so it lands mid-Bash-block while the agent is still writing\n\n## Invariants\n\n- The manifest filename and record shape are a contract between an .mjs hook and TS source that never import each other — change both sides together.\n- The session id the agent passes to `kb write --session` must be the same sid the capture prompt was built with, or there is no manifest and coverage is silent.\n- Silence is a valid outcome (no session, no manifest, stale, malformed) — coverage must never fail a write.\n- The denominator counts only files that needed a note; already-fresh files are excluded so full coverage stays reachable.","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","how-notebook-capture-fires-v5-trigger-timed","src-kb-cli-ts-99b5d5ba","src-kb-search-ts-272e86f3","src-kb-session-worklist-ts-dc6104ba","what-counts-as-the-query-for-notebook-recall"]},{"id":"how-a-note-s-freshness-gets-claimed-and-checked","type":"flow","character":null,"title":"how a note's freshness gets claimed and checked","aliases":["freshness stamping","evidence changed label","anchor hash","verified field","note marked fresh wrongly"],"status":"active","updated":"2026-08-02T18:19:44.371Z","edits":2,"anchors":[{"path":"src/kb/write.ts","hash":"sha256:38e7ca9a095a","state":"changed"},{"path":"src/kb/raw-log.ts","hash":"sha256:0815f155b48a","state":"fresh"},{"path":"src/kb/search.ts","hash":"sha256:7de67121ff4b","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"A note's freshness is a CLAIM the writer makes, not something derived from the note's content: `verified` in a write spec is what causes a file's live hash to be recorded, and read time only compares that recorded hash against the file now. Nothing re-reads the file to decide if a note is still true, so whoever writes decides what counts as verified — which is why a write that carries no knowledge must not stamp.\n\n## Steps\n\n1. `src/kb/write.ts` (`kbWrite`) — decides what goes in `verified` — the anchor path is added only when the spec carries knowledge implying a read (summary/facets/body); an explicit `verified` from the agent always wins\n2. `src/kb/raw-log.ts` (`appendRecord`) — the only place a hash is produced: for each `verified` path it hashes the file NOW and writes it into the record's anchor. The agent never writes hashes itself\n3. `src/kb/search.ts` (`kbSearch`) — read time — stampAnchors compares each stored anchor hash against the live file and labels the result; since 2026-07-30 that label does not affect rank\n\n## Invariants\n\n- a record with no `verified` carries no hash, and the fold preserves the note's previous hash — so a metadata-only edit cannot reset freshness\n- freshness has no git dependency: the comparison is hash-vs-file, and `head` is provenance only","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","src-kb-raw-log-ts-ba590d64","src-kb-search-ts-272e86f3","src-kb-write-ts-d5968d80","what-counts-as-the-query-for-notebook-recall","why-a-file-note-s-extra-anchors-can-never-carry-symbols"]},{"id":"hooks-trigger-mjs-36ac51eb","type":"file","character":"single","title":"hooks/trigger.mjs","aliases":["arm threshold","descent one quiet stop","synthesis counts as quiet","surge removed","cap fires inject","T_ARM","MIN_FILES","score threshold","arming","fresh note discount","arm threshold too high","T_ARM unreachable","only fires on commit","head-drift starves descent","armed false forever","quiet stops no capture","stop hook firing rate low","why no notes captured"],"status":"active","updated":"2026-08-02T18:19:44.362Z","edits":23,"anchors":[{"path":"hooks/trigger.mjs","symbols":["step","initialState","T_ARM","T_CAP","MIN_FILES","MIN_FILES_ARM","DESCENT_QUIET","SETTLE_ACTIVE_STOPS","MAX_CAPTURE_FILES"],"hash":"sha256:d5d41f6fd44c","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Pure capture state machine, no I/O or clock. score = uncaptured files x1 + settled edits x2 + ALL stops since the last fire; arm at T_ARM=10 requiring >=1 active stop and >=1 uncaptured file (MIN_FILES_ARM); fires descent (1 quiet stop, INJECT), cap@20 (INJECT), or headDrift (BLOCK) - the last two keep the >=2-file MIN_FILES floor. CORRECTION 2026-07-24: this note previously blamed T_ARM=10 being 'out of range for normal session size'. That diagnosis was WRONG and is retracted. The real cause of descent never firing (104 stops / 24 fires / 0 descent) was a regression - the score's stop term read activeStops, and once synthesis turns were reclassified as quiet they no longer incremented it, so a discussion session had NO score-growth term at all and froze at ~4. T_ARM=10 is reachable and unchanged. Two other tempting fixes are also replay-falsified: stopping head-drift from resetting activeStops (still 0 descent fires), and lowering T_ARM.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-recall-seen-mjs-27dd2674","type":"file","character":"single","title":"hooks/recall-seen.mjs","aliases":["recall dedup state","seen ids file","pointer page id parsing","recall dedup","seen note ids","dedup state file","kb search --seen","same note injected twice","repeated note injection","compaction resets recall","compaction reset","transcript shrink detection","tmpdir not slash tmp"],"status":"active","updated":"2026-08-02T18:19:44.354Z","edits":11,"anchors":[{"path":"hooks/recall-seen.mjs","symbols":["readSeen","writeSeen","idsInPage","seenArgs","seenPath","transcriptSize"],"hash":"sha256:5797d3a94eb2","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Per-session recall dedup state shared by all three recall hooks (kb-recall.mjs, cursor-kb-recall.mjs, codex-kb-recall.mjs each import readSeen/writeSeen/idsInPage/seenArgs) so their behaviour cannot drift; created 2026-07-30 after the dedup shipped Claude-only and Cursor/Codex kept re-showing notes. State lives at os.tmpdir()/coldstart-recall-seen-<sid>.json — deliberately NOT literal /tmp, which is reserved for the find_nudge state file the nudge handler reads back by an agreed literal path. The seen set resets when the transcript file SHRINKS (a compact) rather than on a clock, because after a compact the session id is unchanged but the context is gone, so a previously-shown note is genuinely absent again; a host that exposes no transcript path (ephemeral Codex runs) simply never resets, which is the safe direction. idsInPage parses ids back out of the RENDERED pointer page via the '-> open: .../<id>.md' line, so the hooks need no structured output from the CLI. Every function is fail-open: any error leaves dedup off rather than blocking recall. Verified E2E on all three hooks this session: inject -> silent -> transcript shrinks -> inject, and inject -> silent with no transcript path.","backlinks":[],"anchorLinks":[]},{"id":"hooks-recall-query-mjs-6503796e","type":"file","character":"single","title":"hooks/recall-query.mjs","aliases":["harness boilerplate in the query","inject-log truncates the query"],"status":"active","updated":"2026-08-02T18:19:44.346Z","edits":14,"anchors":[{"path":"hooks/recall-query.mjs","symbols":["recallQuery","stripHarnessWrappers","HARNESS_TAGS"],"hash":"sha256:4a146b7ec842","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Shared prompt->query hygiene for all three recall hooks: stripHarnessWrappers removes HARNESS_TAGS (system-reminder, ide_opened_file, ide_selection, ide_diagnostics, task-notification, local-command-caveat/stdout/stderr, command-name/message/args, user-prompt-submit-hook, browser_instruction, environment_context, user_instructions) as well-formed pairs (4 nested passes) plus leftover lone tags, and recallQuery strips BEFORE slicing to maxChars so a 1.5KB <ide_selection> cannot eat the budget ahead of the real question. Only the NAMED tag set is stripped; user-pasted XML is left alone; fail-open returns the raw text. CORRECTION 2026-08-02: this note previously said the file HAD NEVER RUN IN PRODUCTION because the wired hook pointed at an npm install with no recall-query.mjs - that is now FALSE; the published @cstart/coldstart 2.2.11 install ships hooks/recall-query.mjs, so the stripping is live. The measured finding behind it still stands: with the caveat block left in, the word 'commands' from the boilerplate 'while running local commands' added +7.9 to src/init.ts and promoted it rank 4 -> rank 2, via the path-name override in src/kb/search.ts. Still true for analysis: the inject-log stores only query.slice(0,200), so replays of logged queries score a CLEANER string than production used and measured junk rates understate the live rate.","backlinks":[],"anchorLinks":["what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-preguard-handler-mjs-e53f8b7b","type":"file","character":"single","title":"hooks/preguard-handler.mjs","aliases":["preguard does not block grep","PreToolUse hook produces no output on Bash","matcher widened but handler narrow"],"status":"active","updated":"2026-08-02T18:19:44.337Z","edits":5,"anchors":[{"path":"hooks/preguard-handler.mjs","symbols":["handle"],"hash":"sha256:f136ff422137","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"PreToolUse handler wired by init.ts with matcher `Bash|mcp__coldstart__find`, so it runs on EVERY Bash call — but it is only a dedup guard for `coldstart find`, not an anti-grep mechanism: canonicalFindKey(cmd) returns null for any non-find command and the handler returns null immediately, so grep/rg/git-grep/find shell through untouched with no output. Anti-grep spiral coverage lives in the PostToolUse nudge-handler.mjs instead (fires on tool===\"Grep\" or Bash matching SEARCH_RE), i.e. coldstart reacts AFTER the grep is paid for, never before. Denies only an exact repeat of a term-set+flags already run successfully this session (state in /tmp/find_nudge_{sid}_{aid}.json, written by the PostToolUse hook); fail-open on any error.","backlinks":[],"anchorLinks":["what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-note-shape-mjs-d85ce294","type":"file","character":"single","title":"hooks/note-shape.mjs","aliases":["one note shape table","required note fields","NOTE_CHECKS","SPEC_SHAPES","shapesBlock","requiredFieldsLine","shape drift","hooks cannot import dist","add a note requirement","missingInSpec missingInNote"],"status":"active","updated":"2026-08-02T18:19:44.328Z","edits":2,"anchors":[{"path":"hooks/note-shape.mjs","symbols":["SPEC_SHAPES","NOTE_CHECKS","shapesBlock","requiredFieldsLine","checksForSpec","checksForNote","unanchoredSteps","stepsMissingAfterWrite","REPAIR_CONTRACT_VERSION"],"hash":"sha256:c42cfbd8820f","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"THE frozen definition of what a notebook note must carry to be findable, and the only place the spec shapes are written down. SPEC_SHAPES holds one example string per spec type (file-single/file-hub/flow/lesson) rendered by shapesBlock({compact}) — compact drops the prose for the capture prompt, both emit the SAME examples. NOTE_CHECKS holds one entry per way a note ends up unfindable, each with TWO predicates: missingInSpec (the JSON just written) and missingInNote (the folded note). It lives in hooks/ and not src/ because the capture hooks never import from dist/; the TS side imports it across directories and tsc's rootDir does NOT object (types come from note-shape.d.mts beside it). Template literals here open with a newline so dedent() can strip the common prefix and keep RELATIVE indentation — that is what makes a JSON example's continuation lines line up under it.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — the table every other surface renders from","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"hooks-kb-recall-mjs-bb2f72e8","type":"file","character":"single","title":"hooks/kb-recall.mjs","aliases":["recall dedup","recall hook claude","UserPromptSubmit recall","pointer page injection","pending capture first","same note injected twice","seen ids file","compaction resets recall","transcript shrink detection","cursor codex no dedup","seen ids"],"status":"active","updated":"2026-08-02T18:19:44.318Z","edits":11,"anchors":[{"path":"hooks/kb-recall.mjs","symbols":["recallQuery","takePendingCapture","readSeen","writeSeen","idsInPage","seenArgs"],"hash":"sha256:a82ef1040d11","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"UserPromptSubmit recall hook for Claude Code: shells out to `kb search --hook --max 3`, delivers any pending capture FIRST, and injects a pointer page (title + gist + path) as hookSpecificOutput.additionalContext. It reads input.transcript_path and passes it with the session id to the shared dedup helpers, harvesting shown ids back out of the RENDERED page so no structured output is needed. CORRECTS this note's own earlier claims (same day): the dedup state handling NO LONGER lives here — it moved to hooks/recall-seen.mjs so the three recall hooks cannot drift — and dedup is NO LONGER Claude-only; cursor-kb-recall.mjs and codex-kb-recall.mjs were ported in the same PR and verified to behave identically.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-ignore-mjs-1a07e730","type":"file","character":"single","title":"hooks/ignore.mjs","aliases":["coldstartignore","ignored files still in find","files that never get notes"],"status":"active","updated":"2026-08-02T18:19:44.300Z","edits":3,"anchors":[{"path":"hooks/ignore.mjs","symbols":["loadIgnore","compileIgnore","DEFAULT_IGNORES","patternToRegex"],"hash":"sha256:6b5fde7d5dc4","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"The .coldstartignore matcher: shipped DEFAULTS (json, lockfiles, build output, .env*, binaries) live here in code; the user file at .coldstart/.coldstartignore (personal — gitignored via a committed .coldstart/.gitignore) only adds or negates on top. Scope is notebook-only PERMANENTLY (owner decision 2026-07-17): it filters capture evidence and note surfacing, NEVER find/gs navigation.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-cursor-kb-elicit-mjs-151bef1e","type":"file","character":"single","title":"hooks/cursor-kb-elicit.mjs","aliases":["cursor capture","followup_message","loop_count guard"],"status":"active","updated":"2026-08-02T18:19:44.273Z","edits":3,"anchors":[{"path":"hooks/cursor-kb-elicit.mjs","symbols":["extractCursorEvidence","segmentStatsCursor","step","initialState","writePendingCapture","buildCapturePayload","worklistEntries","cursorRoot","loadIgnore","freshNotedSet","gitHead","logCaptureEvent"],"hash":"sha256:5d466a726425","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Cursor stop/subagentStop capture — the FULL v5 trigger port. Processes only loop_count===0 turns (followup_message re-fires stop); blocking channel is {followup_message}; non-blocking fires write the same pending file that cursor-kb-recall delivers via beforeSubmitPrompt additional_context. LIVE-UNTESTED as of 2.2.0 — validated against stored real transcripts and hook-level tests only.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-codex-kb-recall-mjs-cd4df13f","type":"file","character":"single","title":"hooks/codex-kb-recall.mjs","aliases":["codex recall hook","recall hooks differ","per host verification","ephemeral codex no transcript","session id binding"],"status":"active","updated":"2026-08-02T18:19:44.263Z","edits":4,"anchors":[{"path":"hooks/codex-kb-recall.mjs","symbols":["recallQuery","readSeen","writeSeen","idsInPage","seenArgs"],"hash":"sha256:bf6aec34f7cd","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Codex recall hook. Verified this session: its handler body is structurally DIFFERENT from kb-recall.mjs and cursor-kb-recall.mjs even though all three share recallQuery and recall-seen — it early-exits when there is no notebook, has no pending-capture delivery, and wraps its search call in a plain try rather than the nested-if the other two use. A scripted edit written against the Claude/Cursor shape silently no-ops here (that happened this session: the shared-import patch applied, the call-site patch did not, and only a grep caught it). Verify per-host after any change that touches all three. The sanitized session id is bound once at the top of the handler and reused by both the dedup call and the find_nudge arming block, which previously re-derived its own unsanitized copy. Codex ephemeral runs expose no rollout path, so transcript_path is often absent and the compaction reset simply never fires.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-codex-kb-elicit-mjs-9cb55b18","type":"file","character":"single","title":"hooks/codex-kb-elicit.mjs","aliases":["codex capture one shot","stop fires at exit","codex hook trust re-prompt"],"status":"active","updated":"2026-08-02T18:19:44.253Z","edits":3,"anchors":[{"path":"hooks/codex-kb-elicit.mjs","symbols":["extractCodexEvidence","buildCapturePayload","worklistEntries","logCaptureEvent","loadIgnore"],"hash":"sha256:28f2f4216da9","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Codex capture is deliberately ONE-SHOT v5, not the trigger machine: Codex's Stop fires once at session exit (TUI) or by construction (codex exec), so there is nothing to time and no next prompt for pending delivery — blocking {decision:block} at the single Stop, with a session-cumulative offered-set marker for resumed threads. Updating shipped hook files changes their hash, so Codex re-prompts its trust gate once after every coldstart update. LIVE-UNTESTED as of 2.2.0.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"github-workflows-npm-publish-yml-af3dbc50","type":"file","character":"single","title":".github/workflows/npm-publish.yml","aliases":["npm publish workflow","release trigger","publish to npm ci"],"status":"active","updated":"2026-08-02T18:19:44.232Z","edits":2,"anchors":[{"path":".github/workflows/npm-publish.yml","hash":"sha256:cccb7702c319","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"Publishes the package to npm. Triggers on `release: types: [created]` — NOT on a push or a tag by itself, so a `gh release create` (or the GitHub UI 'create release' action) is what actually fires it, not `git push --tags` alone. It does NOT run the test suite before publishing (no `npm test` step) — checkout, `npm ci`, `npm run build`, then `npm publish --provenance --access public` reading `NODE_AUTH_TOKEN` from the `NPM_TOKEN` secret. `--access public` is required alongside `--provenance` or npm refuses to generate provenance for what it would otherwise create as a private/restricted scoped package.","backlinks":[],"anchorLinks":[]},{"id":"dockerfile-6651ddff","type":"file","character":"single","title":"Dockerfile","aliases":["docker build sandbox","ripgrep postinstall download","ignore-scripts"],"status":"active","updated":"2026-08-02T18:19:44.221Z","edits":8,"anchors":[{"path":"Dockerfile","hash":"sha256:6a07ad14a17d","state":"fresh"}],"freshness":"fresh","dir":".","outLinks":[],"body":"Exists ONLY so MCP directory build sandboxes (Glama) can boot the server and run the introspection exchange — it is not a supported way to run coldstart, which is repo-local and needs a repository a container does not have. Two deliberate choices that look like mistakes: `npm ci --ignore-scripts` is there because the sole postinstall in the tree is @vscode/ripgrep downloading a prebuilt binary from GitHub, which network-restricted sandboxes may block — coldstart resolves a searcher at runtime and degrades to git grep/grep/Node scan, and this session confirmed a clean install leaves @vscode/ripgrep with no bin/ directory while the server still builds and answers; and `.dockerignore` excludes node_modules so the later `COPY . .` cannot clobber the modules from the npm ci layer. `npm prune --omit=dev` after the build was verified safe (53 packages dropped, all six tools still returned).","backlinks":[],"anchorLinks":[]}]};</script>
+<script>const DB = {"summary":{"total":135,"byType":{"flow":26,"file":109},"byFreshness":{"fresh":76,"changed":52,"missing":7},"repo":"coldstart","generated":"2026-09-06"},"notes":[{"id":"site-astro-has-two-independent-stylesheets-that-must-be-hand","type":"flow","character":null,"title":"site-astro has two independent stylesheets that must be hand-kept in sync","aliases":["landing.css docs.css split","site-astro design system","two stylesheet architecture","how.css ride-on pattern","third stylesheet","unscoped root tokens","nav layout dimension drift","backdrop.css shared visual","page-wide background definition","stylesheet token drift","shared text ramp","grey text hard to read","low contrast body copy","token fixed on one page only","navbar narrower than body"],"status":"active","updated":"2026-09-06T17:35:49.709Z","edits":9,"anchors":[{"path":"site-astro/src/pages/index.astro","hash":"sha256:73ddc5b0a45e","state":"fresh"},{"path":"site-astro/src/styles/landing.css","hash":"sha256:2c51f1372cf9","state":"fresh"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:5c6dfd9b8f8f","state":"fresh"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:131c8ebc9124","state":"fresh"},{"path":"site-astro/src/pages/blog/index.astro","hash":"sha256:ad1a1743e444","state":"fresh"},{"path":"site-astro/src/layouts/BlogPostLayout.astro","hash":"sha256:9b42858ab2ab","state":"fresh"},{"path":"site-astro/src/styles/how.css","hash":"sha256:02bdedbf0f63","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","state":"fresh"},{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:35ff4c406dd2","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages","outLinks":[],"body":"site-astro has three page-level stylesheets that redefine the same things independently, and what is shared versus duplicated has MOVED: the text ramp is now centralised, everything else still is not. landing.css (home) and docs.css (docs, blog, and the base how.css rides on) each still define --frost/--ember/--line/--void and the whole nav and footer layout independently, so a change to one leaves the other silently stale. But --text/--muted/--faint/--ink/--prose are now defined ONLY in styles/backdrop.css, which every page shell imports last. That move was forced by a real drift: body.essay-page had been repaired to a readable --prose with a comment reading 'was #8b9ab2 at 6.9:1', so the blog got fixed while docs and the landing page kept a grey that measured 4.30:1 - below the AA floor - once the background field changed what text sat on. The same class of drift is still live for the container width: .docs was 1200px/24px while .nav-in and .wrap are 1120px/28px, which put the docs content edge 44px left of the nav's until it was fixed this session. backdrop.css is the pattern to copy for anything that must not drift; how.css is the other good pattern - zero tokens of its own, riding docs.css.\n\n## Steps\n\n1. `site-astro/src/styles/backdrop.css` (`:root`, `body::before`) — the ONE shared definition - background field AND text ramp; imported last by every shell so its :root wins\n2. `site-astro/src/styles/landing.css` (`:root`, `.wrap`, `.hero`) — home tokens and nav layout; no longer defines the text ramp, still owns --frost/--ember/--line and its own nav rules\n3. `site-astro/src/styles/docs.css` (`:root`, `.docs`, `body.essay-page`) — docs+blog; redefines the same accent tokens and nav dimensions independently; .docs must stay 1120/28 to match .wrap\n4. `site-astro/src/styles/how.css` (`body.how-page`) — the good pattern - scoped overrides only, no tokens or nav rules of its own\n5. `site-astro/src/pages/index.astro` — imports landing.css then backdrop.css - the required order\n\n## Invariants\n\n- Nav.astro and Footer.astro are shared components styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component itself\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently (this already happened once: docs.css still had a pre-redesign SF Mono/system-ui font stack after landing.css was fully re-themed to Newsreader/IBM Plex Sans/JetBrains Mono)\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently\n- Nav.astro and Footer.astro are styled purely through CSS custom properties — changing their look for one page family means editing that family's stylesheet, never the component\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void; a palette change in one needs the matching edit by hand or the dark palette diverges silently\n- how.css declares no token of its own and must stay that way — its only local definitions are --paper/--paper-ink/--paper-line/--faint/--ember-dim under body.how-page, which docs.css does not define\n- anything added to how.css must stay scoped under .how-page or it leaks into docs and blog, which load the same docs.css\n- docs.css's palette sits on a bare :root — a new page family gets the dark theme by importing it under ANY body class; only body.essay-page re-scopes to light\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void — a palette change in one needs the matching edit by hand or the dark palette diverges silently\n- landing.css and docs.css ALSO independently duplicate nav layout dimensions (nav-in height/gap, z-index, .nav-mobile top offset, .side sticky top) — verified this session: docs.css's nav had drifted to 60px height/20px gap/z-index 30 while landing.css was 64px/28px/50, so the header visibly resized crossing from home to /docs/. Fixed by making docs.css's nav block byte-identical to landing.css's again (including .side's sticky top/max-height, which must track the nav height too)\n- how.css declares no token or nav rule of its own and must stay that way\n- docs.css's palette and nav rules sit on bare selectors (:root, nav) with no body-class qualifier — a new page family gets them just by importing docs.css\n- backdrop.css is the ONLY place a page-wide background may be defined. A per-section or per-page background (a section on --ink-1, a .hero::before glow) paints over the shared field and re-bands the page — that is what it replaced.\n- backdrop.css is the ONLY place a page-wide background may be defined. A per-section or per-page background (a section on --ink-1, a .hero::before glow) paints over the shared field and re-bands the page - that is what it replaced, and DESIGN.md 5 now names the field as the site's one signature device.\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void - if landing.css's palette changes, docs.css needs the matching edit by hand or the dark palette diverges silently\n- A shared component's chrome rules live in BOTH stylesheets, so deleting one (as with the .tl dots) means deleting it twice\n- Nav.astro and Footer.astro are shared components styled purely through CSS custom properties - changing their look for one page family means editing that family's stylesheet, never the component itself\n- The text ramp (--text/--muted/--faint/--ink/--prose) is defined ONLY in backdrop.css. Redefining any of them in a page stylesheet reintroduces the drift that made the blog readable and the docs not.\n- backdrop.css is also the ONLY place a page-wide background may be defined. A per-section background paints over the shared field and re-bands the page.\n- landing.css and docs.css intentionally share identical hex values for --frost/--ember/--line/--void - a palette change in one needs the matching edit in the other by hand.\n- Every content container is 1120px with 28px padding (.wrap, .nav-in, .docs). A container with its own width misaligns against the nav.\n- A shared component's chrome rules live in BOTH stylesheets, so deleting one (as with the .tl traffic-light dots) means deleting it twice.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-src-pages-blog-index-astro-eeb82beb","site-astro-src-pages-docs-astro-d1cf6fe9","site-astro-src-pages-how-it-works-notebook-astro-7be582fd","site-astro-src-pages-index-astro-08d662bc","site-astro-src-styles-backdrop-css-590ddcf8"]},{"id":"how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","type":"flow","character":null,"title":"how a new site-astro page acquires nav, footer and SVG defs","aliases":["new site-astro page","page chrome wiring","nav footer styling","SvgDefs filter defs","docs sidebar component pattern","backdrop import requirement","page has no background field","page text unreadable grey","missing backdrop import"],"status":"active","updated":"2026-09-06T17:35:49.658Z","edits":4,"anchors":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","hash":"sha256:ac83d3352f95","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/navigation.astro","hash":"sha256:fe084da82216","state":"changed"},{"path":"site-astro/src/components/Nav.astro","hash":"sha256:47409c440654","state":"fresh"},{"path":"site-astro/src/components/Footer.astro","hash":"sha256:f67267f5bf38","state":"fresh"},{"path":"site-astro/src/components/SvgDefs.astro","hash":"sha256:855fadd756ae","state":"fresh"},{"path":"site-astro/src/styles/docs.css","hash":"sha256:cabd593fda98","state":"changed"},{"path":"site-astro/src/styles/how.css","hash":"sha256:518ebee8e16f","state":"changed"},{"path":"site-astro/src/components/DocsSidebar.astro","hash":"sha256:8044650fa72f","state":"changed"},{"path":"site-astro/src/pages/docs/navigation.astro","hash":"sha256:d43204e50261","state":"changed"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","hash":"sha256:a7ffe7021ad0","state":"changed"},{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:1e4be26bcb26","state":"fresh"},{"path":"site-astro/src/pages/live/index.astro","hash":"sha256:47f92ca46b8a","state":"fresh"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:46674c8a42cf","state":"changed"},{"path":"site-astro/src/styles/backdrop.css","hash":"sha256:35ff4c406dd2","state":"fresh"}],"freshness":"changed","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"A new page needs THREE imports, not one, and each fails silently on its own: its page-level stylesheet (landing.css or docs.css) because Nav.astro/Footer.astro/SvgDefs.astro carry no styling of their own; <SvgDefs /> in the markup or every url(#rough)/url(#glow) reference silently resolves to nothing; and styles/backdrop.css, which is NO LONGER OPTIONAL. backdrop.css used to be just the background field, so forgetting it only cost a gradient. It now also defines the text ramp (--text/--muted/--faint, plus --ink and --prose aliases), so a page that omits it gets no field AND falls back to whatever greys its stylesheet still happens to define. That is not hypothetical: pages/live/index.astro shipped without the backdrop import and was the one page on the site with no field at all until it was fixed this session. backdrop.css must also be imported LAST, after landing.css/docs.css, because its :root is what overrides theirs.\n\n## Steps\n\n1. `site-astro/src/styles/backdrop.css` (`:root`, `body::before`) — REQUIRED third import - the background field and the text ramp; must come last so its :root wins\n2. `site-astro/src/pages/demo/index.astro` (`readOut`) — a correct example: tailwind + landing.css + backdrop.css, then Nav/Footer/SvgDefs\n3. `site-astro/src/pages/live/index.astro` — the counter-example - shipped without the backdrop import and silently had no field; fixed this session\n4. `site-astro/src/components/Nav.astro` (`Props`, `nav-drop`, `nav-drop-menu`) — markup only; variant prop picks which link is active\n5. `site-astro/src/components/Footer.astro` (`Props`, `taglines`) — markup only; variant keys into a taglines map\n\n## Invariants\n\n- Nav/Footer/SvgDefs are unstyled markup — their appearance comes entirely from the page's stylesheet, never from the component\n- url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter\n- Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined\n- Nav/Footer/SvgDefs are unstyled markup — appearance comes entirely from the page's stylesheet\n- url(#rough) on a page that does not render <SvgDefs /> fails silently\n- DocsSidebar.astro is the one component so far that DOES ship its own scoped <style> — see its own note for why (a docs.css global rule it must locally override)\n- Nav and Footer each declare their own variant union and Footer keys a taglines map off it — adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined (both were widened together this session for the new 'live' variant)\n- Nav's dropdown submenu is markup+classes only too — its active-state styling lives in the page stylesheet's '.nav-drop-menu a.active' rule, and the SITE-WIDE '.nav-links a.active::after' underline rule must be scoped with a direct-child combinator ('.nav-links>a.active') or it leaks onto nested dropdown items, drawing an unwanted full-width underline under whichever submenu item happens to be active\n- Three imports, all silent on failure: page stylesheet, <SvgDefs />, and backdrop.css. Nothing errors when one is missing.\n- backdrop.css must be imported AFTER landing.css/docs.css - same :root specificity, so source order decides, and it is the one meant to win.\n- Nav/Footer/SvgDefs are unstyled markup - their appearance comes entirely from the page's stylesheet, never from the component.\n- url(#rough) on a page that does not render <SvgDefs /> fails silently: no error, the element just draws without the filter.\n- Nav and Footer each declare their own variant union and Footer keys a taglines map off it - adding a page family means widening BOTH unions and adding the taglines key, or the tagline lookup returns undefined.\n- DocsSidebar.astro is the one component that ships its own scoped <style> - see its own note for why.\n- The site-wide '.nav-links a.active::after' underline rule must be scoped with a direct-child combinator ('.nav-links>a.active') or it leaks onto nested dropdown items.","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-src-components-docssidebar-astro-93ed0ec3","site-astro-src-components-footer-astro-98a77858","site-astro-src-components-nav-astro-9dfe3071","site-astro-src-pages-demo-index-astro-2e0c6d23","site-astro-src-pages-docs-navigation-astro-e37c5fa9"]},{"id":"terminal-output-in-an-astro-template-breaks-the-build-two-di","type":"flow","character":null,"title":"Terminal output in an .astro template breaks the build two different ways","aliases":["astro template literal trap","astro brace expression trap","terminal output in astro","readOut frontmatter pattern","token is not defined","Expected } but found await","astro build fails on terminal output","astro strips newlines","white-space pre not working"],"status":"active","updated":"2026-09-06T17:34:02.877Z","edits":1,"anchors":[{"path":"site-astro/src/pages/demo/index.astro","hash":"sha256:1e4be26bcb26","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/demo","outLinks":[],"body":"An .astro file's whole template is compiled to a JS template literal AND its markup braces are Astro expressions, so pasting real command or source output into the markup fails the build twice over. (1) `${...}` is interpolated - a line like `redis.set(`sess:${token}`...)` fails with 'token is not defined'. (2) `{...}` is parsed as an expression - `JSON.stringify({ uid: user.id })` fails with 'Expected } but found await'. HTML-entity escaping does NOT fix either one: `&#36;{token}` is decoded back to `${token}` before the literal is emitted. The fix that works is to put the output in a frontmatter array of plain strings and map over it - frontmatter strings are immune to both - which is what `readOut` in demo/index.astro does. A THIRD, separate trap in the same territory: Astro also collapses template newlines, so a transcript written as one text block under white-space:pre renders as a single wrapped line; each line needs its own element. All three were found by building and rendering, never by reading the markup.\n\n## Steps\n\n1. `site-astro/src/pages/demo/index.astro` (`readOut`, `.ob`) — carries the fix - terminal output as a frontmatter string array, mapped into one div per line\n2. `site-astro/src/pages/docs.astro` (`term-body`) — also renders terminal blocks; same rules apply to any output pasted here\n\n## Invariants\n\n- Never paste raw command or source output straight into an .astro template. If it contains `$` followed by a brace, or any `{`, the build fails.\n- HTML entities do not escape either construct - the entity is decoded before the template literal is emitted.\n- One element per output line, because Astro collapses template newlines and white-space:pre alone will not save it.\n- The output box needs its own overflow-x:auto so long lines scroll inside the box instead of overflowing the page on mobile.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-src-pages-demo-index-astro-2e0c6d23"]},{"id":"site-astro-src-pages-demo-index-astro-2e0c6d23","type":"file","character":"single","title":"site-astro/src/pages/demo/index.astro","aliases":["demo page","live session demo","recall timeline","keynote callout","term live terminal","claude code panel replica","cold and warm session panels","static demo transcript","auth demo","demo not relatable","zero tool calls claim","demo page overclaims","demo animation removed"],"status":"active","updated":"2026-09-06T17:33:53.824Z","edits":4,"anchors":[{"path":"site-astro/src/pages/demo/index.astro","symbols":["title","description",".cc",".cc-body",".cc-bar",".cc-in",".turn",".tool",".ob",".note",".cap",".chip",".prose",".dsec",".dhead",".dclose","readOut",".tally",".disclaim"],"hash":"sha256:1e4be26bcb26","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/demo","outLinks":[],"body":"The /demo/ page: two static Claude Code panel replicas, fully rendered on load - no typing effect, no scroll triggers, zero opacity:0, works with JS off. The scenario is 'how does authentication work in this codebase?' on an INVENTED Node/Express API, and the page says so in a line under the hero: the repo and its output are made up, only the command shapes and output format are real. It was previously a real captured session about coldstart's own co-change internals, which only demonstrates the tool to someone who already uses it. COLD panel: no note, one `coldstart find`, one `coldstart gs`, then the answer (Redis sessions, not JWTs, despite the variable being named token). WARM panel: a note arrives with the prompt, and the agent then runs ONE Read against the file the note named before answering. That read is deliberate and must not be removed - an earlier version claimed 'Zero tool calls, no reads', which is false about how agents behave and contradicts the freshness story on the same page. The honest framing the copy now uses is 'one read instead of a search'. The panel keeps its own neutral #1f1f1f ground rather than the site's field, because it is a replica.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","terminal-output-in-an-astro-template-breaks-the-build-two-di"]},{"id":"site-astro-src-styles-docs-css-e5e1acf9","type":"file","character":"single","title":"site-astro/src/styles/docs.css","aliases":["blog styles","documentation CSS","docs stylesheet","blog stylesheet","nav-wrap bug","essay card grid","docs.css bare root","chrome stylesheet","dark token source","essay page styles","docs container width","blog post styles","navbar not as wide as body","docs page asymmetric","sidebar misaligned with logo","content edge mismatch"],"status":"active","updated":"2026-09-06T17:33:53.814Z","edits":7,"anchors":[{"path":"site-astro/src/styles/docs.css","symbols":[":root",".side",".term","@media (max-width: 768px)",".nav-burger",".nav-mobile","body.essay-page","footer",".foot-in","nav",".nav-in",".side a.active",".chip",".term-body .ln",".docs",".term-bar"],"hash":"sha256:5c6dfd9b8f8f","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/styles","outLinks":[],"body":"Stylesheet for the docs pages, the blog index and blog posts (body.essay-page), and the base that how.css rides on. It no longer defines --ink/--prose/--muted/--faint: those come from backdrop.css, which every page shell imports after this one. It still owns --bg/--surface/--frost/--ember/--line and, independently of landing.css, the same nav and footer layout rules - that duplication is deliberate but unguarded, so a nav change here needs the matching edit in landing.css by hand. The .docs container is 1120px with 28px padding, which MATTERS: it was 1200/24, which put the docs content edge at 144px against the nav's 188px, so the logo read as indented against the sidebar. 1120/28 is what .nav-in and landing.css's .wrap use, and any new container should match it rather than invent its own width.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-styles-backdrop-css-590ddcf8","type":"file","character":"single","title":"site-astro/src/styles/backdrop.css","aliases":["backdrop stylesheet","page background field","frost ember gradient","body before background","shared page visual","text ramp","shared token source","contrast tokens","grey text hard to read","low contrast body copy","washed out text","tokens drifted between stylesheets","dot grid background","page has no background field"],"status":"active","updated":"2026-09-06T17:33:53.788Z","edits":2,"anchors":[{"path":"site-astro/src/styles/backdrop.css","symbols":["body::before",":root","--text","--muted","--faint","--ink","--prose"],"hash":"sha256:35ff4c406dd2","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/styles","outLinks":[],"body":"The site's single source for TWO page-wide things, and it is imported LAST by every page shell so its :root wins over landing.css/docs.css/how.css. (1) The background field: one fixed body::before carrying a 90deg frost-to-ember ramp, rotating to 180deg below 900px. It replaced a 30px dot grid, because a tiled background is the most common generated-site tell. (2) The TEXT RAMP - --text #eef2f8, --muted #c3c8d0, --faint #a3a9b2, plus --ink and --prose as aliases for the names docs.css and the essay pages use. The ramp moved here because it had been hand-copied into three stylesheets and had already drifted: body.essay-page carried a repaired --prose at 12.8:1 with a comment reading 'was #8b9ab2 at 6.9:1', so the blog was fixed and docs and the landing page were left behind. The old values were measured as FAILING: against the composited ground (the field changes what text sits on, costing ~24% of the contrast ratio) --muted fell to 5.28:1 and --faint to 4.30:1, which is below the 4.5 AA floor for normal text. Both also carried an R-B spread near 40, which DESIGN.md 11 identified as the real cause of the washed-out look - a blue-grey on a blue-black ground has too little hue separation from its own background. The new values are 13.4 / 9.0 / 6.4 on the worst ground with R-B spreads of 10 / 13 / 15.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-pages-index-astro-08d662bc","type":"file","character":"single","title":"site-astro/src/pages/index.astro","aliases":["index page","hero section","landing page","landing page astro","home page astro","faq section","faq json-ld source","how-it-works entry links","two column homepage","col-a col-b sections","hero install terminal","faqs array","two column homepage reverted","homepage layout rejected","traffic light dots removed"],"status":"active","updated":"2026-09-04T09:19:10.061Z","edits":10,"anchors":[{"path":"site-astro/src/pages/index.astro","symbols":["class hero","class commands-grid","class notebook","class philosophy","section#notebook","section#flow","section#philosophy","section#install","faqs","faqJsonLd","Head title","class kicker","section#faq","softwareAppJsonLd","how-link","class two","class col-a","class col-b","class term-bar"],"hash":"sha256:5b1f210cd987","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"Homepage. Section order: hero -> notebook -> flow (index) -> philosophy -> FAQ. The single `faqs` array is the source for BOTH the rendered <details> list and the FAQPage JSON-LD, so adding a question means editing that one array only. Layout is the ORIGINAL centred, single-column, stacked one: the .two/.col-a/.col-b two-column conversion an earlier version of this note described was reverted wholesale in 0867280 after USER rejected it and measurement contradicted it. The copy was never touched by that experiment or its revert. The only change that survives here is that the three <span class=\"tl\"> traffic-light dots were removed from the hero terminal's .term-bar, part of a sitewide removal of 39 such spans across five pages.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-styles-landing-css-cc3a29d9","type":"file","character":"single","title":"site-astro/src/styles/landing.css","aliases":["faq section styling","how-link button","raised not recessed","brand tinted button","note card dark theme","recall timeline styles","two column spine","col-a col-b grid","sticky argument column","section hairline separator","homepage tokens","no section background rule","two column spine reverted","col-a col-b removed","landing layout too narrow","prose measure too narrow","traffic light rules removed"],"status":"active","updated":"2026-09-04T09:19:10.049Z","edits":12,"anchors":[{"path":"site-astro/src/styles/landing.css","symbols":[":root",".hero",".commands-grid",".notebook","@media (max-width: 768px)",".nb-main",".nav-burger",".nav-mobile",".faq",".faq-head",".faq-list",".faq-item",".faq-q",".faq-a","@media (max-width: 640px)",".how-link",".nb-exhibit-label",".btn-ghost",".nav-cta",".card",".recall",".keynote",".time-gap",".nav-drop",".nav-drop-menu",".nav-links",".two",".col-a",".col-b",".hero-in",".navsec",".phil",".nb",".nb-intro",".nb-steps",".nb-exhibit",".wrap",".btn",".btn-primary"],"hash":"sha256:61c7ab27ec9a","state":"changed"}],"freshness":"changed","dir":"site-astro/src/styles","outLinks":[],"body":"Homepage stylesheet and token source of truth (--display Newsreader, --sans IBM Plex Sans, --mono JetBrains Mono; --frost/--ember palette); also styles nav, footer, the .faq block and the shared .card note-card. Layout is STACKED, FULL-WIDTH, CENTRED sections - the .two/.col-a/.col-b two-column spine described by an earlier version of this note was reverted in 0867280 and no longer exists. It was reverted because a DOM probe across six dev-tool landing pages found that nextjs.org, vercel.com and railway.com use ZERO two-column grids, nobody repeats an asymmetric split as a page spine, and 5 of 6 centre some text; the spine also ran ~375px / ~44 chars per line, below the measured 429-550px band. What DID survive the revert is the removal of every per-section background: .navsec/.phil/.faq no longer sit on --ink-1, .nb no longer has its warm ground plus two radial blobs, and .hero::before's glow is gone, because backdrop.css now paints one continuous field under the whole page and sections are divided by a hairline instead of a band of colour. The .tl traffic-light rules were also deleted here (and in docs.css) when the dots were removed sitewide.","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"tests-freshness-b3b7-test-ts-b97853e9","type":"file","character":"single","title":"tests/freshness-b3b7.test.ts","aliases":["freshness tests","keeper wait tests","status rendering tests","dead keeper test"],"status":"active","updated":"2026-08-31T18:33:10.457Z","edits":1,"anchors":[{"path":"tests/freshness-b3b7.test.ts","symbols":["waitForCacheHead","runStatus","updateKeeperState"],"hash":"sha256:58997c46995a","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers reconcile, invariants, keeper-state, constants, the keeper waits, status rendering, and disk-cache generations. What is worth knowing before editing: the dead-keeper rule is asserted on BOTH sides of the contract — 'waitForCacheHead: a rebuild stamp from a DEAD keeper is ignored' for the reader path, and 'status rendering' for the renderer, which was added only after a killed keeper was found reporting 'IN PROGRESS' forever. Both fabricate a dead process with pid 0x7ffffff0. The status block isolates via COLDSTART_HOME + a temp root and captures output by swapping process.stdout.write, and its live-keeper case is a deliberate positive control so a fix cannot pass by simply never printing the line.","backlinks":[],"anchorLinks":[]},{"id":"tests-inflight-test-ts-d7fdaaff","type":"file","character":"single","title":"tests/inflight.test.ts","aliases":["inflight tests","markInflight test","parse attribution test"],"status":"active","updated":"2026-08-31T18:33:10.447Z","edits":1,"anchors":[{"path":"tests/inflight.test.ts","symbols":["markInflight","readStaleInflight","parseFile"],"hash":"sha256:48bcad00c654","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers the inflight record end to end, and its load-bearing test is the last one: parseFile must announce work AFTER its awaits, because the first version of the feature marked at the call site and — verified against a real hang — reported an innocent file while a different one span the CPU. The dead-pid cases build their fixture by writing a record and then rewriting its pid to 0x7ffffff0 (above any real pid on either platform), the same trick the keeper-wait tests use. Isolation is by COLDSTART_HOME pointed at a temp dir, restored in afterEach, which works because constants.coldstartHome() resolves per call rather than at import.","backlinks":[],"anchorLinks":[]},{"id":"src-index-ts-c5fb8502","type":"file","character":"hub","title":"src/index.ts","aliases":["command hangs","unknown command","MCP reader boots unexpectedly","command dispatch","graph building","index accumulation","keeper startup"],"status":"active","updated":"2026-08-31T18:33:10.436Z","edits":6,"anchors":[{"path":"src/index.ts","symbols":["main","buildIndex","runKeeper"],"hash":"sha256:69f50f897b4f","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":["how-a-hung-index-build-names-the-file-that-hung-it"],"body":"## Facets\n\n- **main** — Dispatch order is load-bearing, not stylistic. Everything past the subcommand block is treated as a flag-driven invocation (--daemon / --no-daemon / --probe / the default stdio MCP reader), and the unknown-command guard deliberately rejects only a first arg that does NOT start with '-'. So any bare flag falls through and BOOTS THE MCP READER. Fixed by handling --version/-v and --help/-h first by exact match.\n- **buildIndex** — allSymbolEdgesBuilt = buildSymbolEdges() accumulates into a symbolEdges array assigned to CodebaseIndex.symbolEdges; isBarrel is set on TS/JS files (reexportRatio > 0.5 && importedByCount > 1 && exports.length > 0), then the domain map is cleaned and transitiveImportedByCount computed. These are cycle-guard structures: isBarrel + reexportRatio + transitiveImportedByCount are load-bearing for traversal that must bypass re-export hubs. It also marks each phase (walk/parse/resolve/graph) in the inflight record and hands parseFile a per-file mark, then clears the record before returning — a record surviving that clear means the process died mid-build. — [[how-a-hung-index-build-names-the-file-that-hung-it]]\n- **runKeeper** — At startup, before any build, it reads the inflight record left by a PREVIOUS process and — if that pid is gone — logs a WARNING naming the file as prime suspect and appends `died-in-progress` to repair.jsonl. This has to happen here because keeper start is the last moment that evidence exists: the build about to run overwrites it. — [[how-a-hung-index-build-names-the-file-that-hung-it]]","backlinks":[],"anchorLinks":["how-a-hung-index-build-names-the-file-that-hung-it","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-status-ts-8c69c9ca","type":"file","character":"single","title":"src/status.ts","aliases":["npm update didn't take","update not picked up","keeper running old version","install health","wired hook path missing","version drift","moves-together not derived","coldstart status command","keeper freshness output","IN PROGRESS stamp","LAST SEEN line","status shows stale in progress","status cannot explain a hang"],"status":"active","updated":"2026-08-31T18:33:10.424Z","edits":7,"anchors":[{"path":"src/status.ts","symbols":["runStatus","wiredHookPaths","indexFreshness","deriveRoot","relativeAge","fileSize","renderStatus","stampLine"],"hash":"sha256:6e76b0cf5c91","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Renders keeper liveness/freshness per root from keeper-state.json + repair.jsonl + the inflight record beside the cache. Two pid-liveness rules live here and both were added after being wrong: the inProgress stamp is gated on isDaemonAlive(state.pid), because KeeperWork's contract in keeper-state.ts says a stamp outliving its keeper is harmless only if readers check the pid first (waitForCacheHead did; this renderer did not, so a killed keeper reported 'IN PROGRESS' forever); and the inflight line reads the opposite way on purpose — a live pid prints `working on: <phase> <file>`, while a record whose pid is GONE prints `LAST SEEN: PID N died during <phase> <file>`, which is the whole diagnostic for a build that hung and had to be killed.","backlinks":[],"anchorLinks":["how-a-hung-index-build-names-the-file-that-hung-it"]},{"id":"src-keeper-state-ts-cc715659","type":"file","character":"single","title":"src/keeper-state.ts","aliases":["keeper state file","repair log","KeeperWork contract","inProgress stamp"],"status":"active","updated":"2026-08-31T18:33:10.414Z","edits":1,"anchors":[{"path":"src/keeper-state.ts","symbols":["KeeperState","KeeperWork","RepairEvent","updateKeeperState","readKeeperState","appendRepairLog"],"hash":"sha256:b3c119bd07c6","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Holds keeper-state.json (pid, startedAt, inProgress, last reconcile/patch/rebuild/save) and repair.jsonl beside the cache, all writes best-effort so observability can never take the keeper down. The load-bearing contract is on KeeperWork: a lingering inProgress stamp from a keeper that died mid-rebuild is declared harmless BECAUSE readers check the pid is alive before believing it — a rule waitForCacheHead honoured while status.ts did not, which is how a killed keeper produced a permanent 'IN PROGRESS'. RepairEvent's event union is closed and gained `died-in-progress` for a previous indexer that vanished mid-work (see the inflight flow).","backlinks":[],"anchorLinks":[]},{"id":"src-indexer-parser-ts-ddced573","type":"file","character":"single","title":"src/indexer/parser.ts","aliases":["parseFile onWork","parser sync section","batch parse attribution","inflight names wrong file","mark set at call site"],"status":"active","updated":"2026-08-31T18:33:10.403Z","edits":1,"anchors":[{"path":"src/indexer/parser.ts","symbols":["parseFile","parseByLanguage"],"hash":"sha256:81674e6509c7","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"parseFile takes an optional `onWork` callback that it invokes immediately before each synchronous section (the tree-sitter parse and the content-token extraction), and it MUST be invoked here rather than at the call site. Verified this session by reproducing a real hang: parseFile awaits a grammar load and a file read, while the caller runs a batch of 100 through Promise.all, so every file in the batch gets past the call site before any of them reaches the CPU-bound work — a mark set out there named an innocent file while a different one span at 100% CPU. The rule the signature depends on is that no await may sit between an onWork call and the work it announces.","backlinks":[],"anchorLinks":["how-a-hung-index-build-names-the-file-that-hung-it"]},{"id":"src-inflight-ts-668f1959","type":"file","character":"single","title":"src/inflight.ts","aliases":["inflight record","current file being parsed","markInflight","stale inflight","hung build names no file","silent index hang"],"status":"active","updated":"2026-08-31T18:33:10.393Z","edits":1,"anchors":[{"path":"src/inflight.ts","symbols":["markInflight","clearInflight","readInflight","readStaleInflight","describeInflight","inflightPath"],"hash":"sha256:79d91d4f62ce","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Records what the indexer is working on right now, as the one signal that survives a synchronous CPU spin: markInflight does a synchronous writeFileSync BEFORE each unit of work, because once a pathological input blocks the event loop no timer, signal handler, or async flush can ever run to report it. The record is overwritten in place (it answers 'what now', not 'what happened') and cleared by clearInflight on clean completion, which is what makes readStaleInflight meaningful — a record whose pid is no longer alive names the exact unit of work that killed the process. Per-file granularity was a measured choice: ~0.04ms/file, 86ms across a 2000-file build, under 3% of a build that takes seconds, in exchange for the exact path instead of a 100-file window to bisect by hand.","backlinks":[],"anchorLinks":["how-a-hung-index-build-names-the-file-that-hung-it"]},{"id":"how-a-hung-index-build-names-the-file-that-hung-it","type":"flow","character":null,"title":"how a hung index build names the file that hung it","aliases":["hung build diagnosis","inflight record","stuck index file","died in progress","index build hangs silently","log stops at parsing files","which file is stuck"],"status":"active","updated":"2026-08-31T18:33:10.363Z","edits":1,"anchors":[{"path":"src/inflight.ts","hash":"sha256:79d91d4f62ce","state":"fresh"},{"path":"src/indexer/parser.ts","hash":"sha256:81674e6509c7","state":"fresh"},{"path":"src/index.ts","hash":"sha256:69f50f897b4f","state":"fresh"},{"path":"src/status.ts","hash":"sha256:6e76b0cf5c91","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"A build that spins the CPU inside one synchronous call cannot report anything through the normal channels — the event loop is dead, so a watchdog timer, a progress interval, a signal handler, and any async write are all permanently unable to run; the keeper log simply stops after its last phase line. The only thing that survives is a record written SYNCHRONOUSLY BEFORE the work starts, which is what markInflight does, and a record that outlives the process that wrote it is itself the diagnosis (readStaleInflight): the indexer began that unit of work and never finished it. The record is cleared on clean completion precisely so its presence means something. It is surfaced three ways — `coldstart status` prints `working on:` for a live pid and `LAST SEEN: ... died during ...` for a dead one, the next keeper logs a WARNING naming the prime suspect at startup, and that event is appended to repair.jsonl as `died-in-progress` because startup is the last moment the evidence exists before the next build overwrites it.\n\n## Steps\n\n1. `src/inflight.ts` (`markInflight`, `readStaleInflight`, `clearInflight`) — the record: synchronous write before work, cleared on completion, stale = died here\n2. `src/indexer/parser.ts` (`parseFile`) — invokes the mark AFTER its awaits, immediately before the synchronous work\n3. `src/index.ts` (`buildIndex`, `runKeeper`) — marks each phase + hands parseFile the per-file mark; detects and announces a stale record at keeper start\n4. `src/status.ts` — renders live work vs a record that outlived its process\n\n## Invariants\n\n- The mark is written synchronously (writeFileSync) — an async write may still be queued when the event loop stops, and queued means lost.\n- There must be NO await between a mark and the synchronous work it announces, or a concurrent file overwrites it and the record names an innocent file.\n- A record is cleared on clean completion, so its survival is what distinguishes a death from ordinary progress.","backlinks":["src-index-ts-c5fb8502"],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","src-index-ts-c5fb8502","src-indexer-parser-ts-ddced573","src-inflight-ts-668f1959","src-status-ts-8c69c9ca"]},{"id":"how-coldstart-gets-created-and-how-it-silently-never-does","type":"flow","character":null,"title":"how ~/.coldstart gets created, and how it silently never does","aliases":["coldstart home creation","coldstart cache directory","ensureKeeper spawn path","spawn lock","coldstart folder not recreated","index never builds","keeper never spawns"],"status":"active","updated":"2026-08-31T18:14:09.468Z","edits":1,"anchors":[{"path":"src/keeper.ts","hash":"sha256:dd3f5cc515f2","state":"fresh"},{"path":"src/daemon-lock.ts","hash":"sha256:4d06b20383c3","state":"fresh"},{"path":"src/init.ts","hash":"sha256:25e0376d8287","state":"fresh"},{"path":"src/constants.ts","hash":"sha256:db1ac57f315e","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"The coldstart home (~/.coldstart, or COLDSTART_HOME) is created lazily by READER processes only — there is no background service that recreates it, so after `rm -rf ~/.coldstart` it stays absent through any amount of editing, uninstalling, or reinstalling until a reader command runs. ensureKeeper is called from find/gs/index, non-hook kb commands, init, and MCP startup; the hooks that run during ordinary editing pass --hook and deliberately skip the spawn for latency, so normal work never recreates it. The actual mkdir happens inside tryAcquireSpawnLock (recursive, in the reader process) BEFORE the keeper is spawned, so the directory + daemon/ appear even when the keeper later dies or hangs. Two silent failure modes verified this session: (1) if the home path is not writable (EACCES — e.g. a root-owned remnant, or a coldstart previously run under sudo so homedir() differed), ensureKeeper swallows the error entirely at its catch-all and `find` still exits 0 with a normal-looking answer, the only trace being one `warn: could not save cache: EACCES ... mkdir` line, after which every run rebuilds in-process and persists nothing; (2) a leftover <root>.spawn lock file (reader killed between O_EXCL acquire and release) makes tryAcquireSpawnLock return null forever, so ensureKeeper returns at its `another reader is already spawning it` branch and NO keeper is ever spawned again — recovery is deleting that file, which nothing surfaces.\n\n## Steps\n\n1. `src/keeper.ts` (`ensureKeeper`) — entry: the only thing that spawns a keeper; swallows every failure best-effort\n2. `src/daemon-lock.ts` (`tryAcquireSpawnLock`, `daemonDir`, `isDaemonAlive`) — recursive-mkdirs the home, then O_EXCL spawn lock with no staleness check\n3. `src/init.ts` — calls ensureKeeper then blocks on waitForKeeperCache, so `init` warms the cache at setup\n4. `src/constants.ts` (`coldstartHome`) — resolves COLDSTART_HOME override else homedir()/.coldstart, per call\n\n## Invariants\n\n- Nothing recreates the coldstart home in the background — only a reader command does.\n- tryAcquireSpawnLock has no staleness check: a leftover .spawn file blocks keeper spawn permanently and silently.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed","src-init-ts-a867acfe"]},{"id":"tests-content-tokens-test-ts-1b6e539c","type":"file","character":"single","title":"tests/content-tokens.test.ts","aliases":["related section tests","content token tests","deriveRelatedFiles test","name echo test","isShapedToken tests"],"status":"active","updated":"2026-08-31T16:37:25.447Z","edits":2,"anchors":[{"path":"tests/content-tokens.test.ts","symbols":["makeIndex","TOKEN_IN_CODE","TOKEN_IN_STRING","deriveRelatedFiles","deriveNameEchoFiles","isShapedToken"],"hash":"sha256:0c148f866546","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers the content-token channel end to end: extractContentTokens, deriveRelatedFiles, deriveNameEchoFiles, and how handleGetStructure renders the Related section. The rendering block is the regression guard for two rules that were each broken once — Related must appear in every gs view (it was full-view-only, so `--view symbols` on a large file dropped the name-reference neighbours that view is used to find), and an import-edge neighbour must stay excluded even in a view that lists no importers, because the heading promises 'no import edge' and the imports/importers lists cannot back that promise when a narrow view leaves them empty. Both directions of the edge are asserted; the exclusion reads index.outEdges/inEdges, not the rendered lists. Also guards isShapedToken against catastrophic regex backtracking: an adversarial ~2000-char mixed-case run must resolve in well under 200ms, pinning the content-tokens.ts fix (see that file's note).","backlinks":[],"anchorLinks":[]},{"id":"src-indexer-content-tokens-ts-21b52eaf","type":"file","character":"single","title":"src/indexer/content-tokens.ts","aliases":["content token shape gate","isShapedToken","related files extraction","index rebuild hangs forever","coldstart index freezes","regex catastrophic backtracking"],"status":"active","updated":"2026-08-31T16:37:25.402Z","edits":1,"anchors":[{"path":"src/indexer/content-tokens.ts","symbols":["isShapedToken","SHAPE_SNAKE","SHAPE_CAMEL","SHAPE_ALL_CAPS","MAX_TOKEN_LENGTH"],"hash":"sha256:dcc9a76b95be","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Extracts identifier-shaped tokens from file bodies for the Related-files link channel via isShapedToken's SNAKE/CAMEL/PASCAL/ALL_CAPS shape gate. SHAPE_SNAKE/CAMEL/ALL_CAPS previously nested a quantified group inside a trailing `+` (e.g. `(?:[A-Z][a-zA-Z0-9]*)+$`), a catastrophic-backtracking shape that hung `coldstart index` indefinitely on any file containing one long mixed-case run (an embedded hash, base64 blob, or signature) — an 82-char adversarial token alone took 110+ seconds. Fixed by rewriting each as a single-quantifier regex plus a linear trailing-check/substring test (verified mathematically equivalent to the originals against the full test corpus), with MAX_TOKEN_LENGTH=100 kept on top as defense-in-depth; SHAPE_PASCAL was already safe (disjoint character classes) and untouched.","backlinks":[],"anchorLinks":[]},{"id":"src-kb-commit-ts-5df8452d","type":"file","character":"single","title":"src/kb/commit.ts","aliases":["kb commit","notebook publish","sanctioned git path notebook","notebook not committing","kb commit does nothing","gitignored notebook publish"],"status":"active","updated":"2026-08-26T19:53:19.361Z","edits":1,"anchors":[{"path":"src/kb/commit.ts","symbols":["kbCommit","publishPaths"],"hash":"sha256:af2da722de0e","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"kbCommit is the one sanctioned path for putting the notebook into git: it pathspec-stages and commits ONLY `.raw/` (the append-only source-of-truth logs), `okf.yaml`, and the notebook's own `.gitignore`, deliberately excluding the derived `notes/*.md` renders (gitignored, never publishable) and `.metrics/`. The pathspec'd `git commit -m msg -- <paths>` commits just those paths even when other work is staged, leaving that other staged work untouched. If the whole notebook is gitignored (a repo that opted out of sharing notes, as this repo's root .gitignore did until this session), `git add` fails with \"ignored by one of your .gitignore\" or \"did not match any files\" — kbCommit treats both as normal and returns kind:'nothing' rather than force-adding past the ignore rule.","backlinks":[],"anchorLinks":["how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p"]},{"id":"site-astro-src-pages-notebook-index-astro-89f6a4e8","type":"file","character":"single","title":"site-astro/src/pages/notebook/index.astro","aliases":["notebook site route","/notebook/ page","notebook-page.html import","notebook text mis-decoded","em dash garbled utf-8"],"status":"active","updated":"2026-08-26T19:53:19.352Z","edits":1,"anchors":[{"path":"site-astro/src/pages/notebook/index.astro","hash":"sha256:2fc00f50a339","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/notebook","outLinks":[],"body":"Serves /notebook/ by importing site-astro/src/notebook-page.html (generated by scripts/kb-viewer/build-site-page.mjs) via a `?raw` import and inlining it through a bare `<Fragment set:html>`, the same pattern as /graph/. It strips the generated file's own leading `<!doctype html>` since Astro emits its own ahead of the template. It also adds an explicit `<meta charset=\"utf-8\">` before the fragment that the graph route does not need: the kb-view template has no charset meta because it is designed to be opened as a local file (where browsers default to UTF-8), but served over HTTP without one the note text (em dashes etc.) gets mis-decoded as Latin-1 — a site-only fix, the generated template itself stays correct for its actual local-file use.","backlinks":[],"anchorLinks":[]},{"id":"scripts-graph-viewer-build-site-page-mjs-9bf323da","type":"file","character":"single","title":"scripts/graph-viewer/build-site-page.mjs","aliases":["site graph page generator","build-site-page","graph viewer site build","notebook privacy comment stale","notebook no longer private"],"status":"active","updated":"2026-08-26T19:53:19.342Z","edits":2,"anchors":[{"path":"scripts/graph-viewer/build-site-page.mjs","symbols":["OUT","distImport","GRAPH_TEMPLATE"],"hash":"sha256:ca2509b50b93","state":"fresh"}],"freshness":"fresh","dir":"scripts/graph-viewer","outLinks":[],"body":"Generates the site's copy of the graph viewer by importing the BUILT dist/ modules (loadCachedIndex, loadCoChange, buildGraphPayload, renderGraphHtml, GRAPH_TEMPLATE), so `npm run build` must run first or it fails with MODULE_NOT_FOUND. It always passes an empty notes array to buildGraphPayload — this is a permanent design choice (graph = code structure, notebook = a separate viewer; mixing them blurs what each page answers) that holds independent of the notebook's privacy status, NOT because the notebook used to be private (that rationale, in the old comment here, went stale once the notebook was committed to git this session). It also substitutes the home link into GRAPH_TEMPLATE BEFORE calling renderGraphHtml, since renderGraphHtml clears that slot for the standalone CLI page. Output is site-astro/src/graph-page.html, not public/, so an Astro route can serve /graph/ in dev.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when","how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p"]},{"id":"github-workflows-pages-yml-80c02bfb","type":"file","character":"single","title":".github/workflows/pages.yml","aliases":["pages deploy workflow","github pages build","site deploy ci","fetch-depth checkout","notebook graph regen ci","site notebook page stale","graph page out of date after push"],"status":"active","updated":"2026-08-26T19:53:19.331Z","edits":2,"anchors":[{"path":".github/workflows/pages.yml","symbols":["deploy"],"hash":"sha256:d4787cf44eab","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"Builds site-astro and deploys it to GitHub Pages. Beyond the site-astro build, the job now also builds the root coldstart package, runs `coldstart index --root .` to get a fresh code index for this checkout, and regenerates site-astro/src/{notebook,graph}-page.html (scripts/kb-viewer and scripts/graph-viewer build-site-page.mjs) BEFORE the astro build step, so every deploy bakes current notebook/graph content instead of relying on a manually-regenerated snapshot (see the how-the-sitemap-gets-its-lastmod-dates and how-the-site's-notebook-and-graph-pages-stay-fresh-after-a-push flows for why fetch-depth:0 and this ordering matter). The push trigger's `paths` filter was widened from just site-astro/** to also include src/**, .coldstart/notebook/**, scripts/kb-viewer/**, and scripts/graph-viewer/**, since a notebook-only or source-only push now changes deployed output too.","backlinks":[],"anchorLinks":["how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p","how-the-sitemap-gets-its-lastmod-dates"]},{"id":"how-a-standalone-generated-viewer-page-gets-a-back-link-when","type":"flow","character":null,"title":"how a standalone generated viewer page gets a back-link when embedded on the website","aliases":["home link placeholder","generated viewer back link","HOME_LINK substitution","notebook page no back link","graph page missing home link"],"status":"active","updated":"2026-08-26T19:53:19.320Z","edits":2,"anchors":[{"path":"src/graph/view-template.ts","hash":"sha256:1fce631954d2","state":"fresh"},{"path":"src/graph/view.ts","hash":"sha256:fc7d4eca1c94","state":"fresh"},{"path":"scripts/graph-viewer/build-site-page.mjs","hash":"sha256:ca2509b50b93","state":"fresh"},{"path":"src/kb/view-template.ts","hash":"sha256:b360b09a08c9","state":"changed"},{"path":"src/kb/view.ts","hash":"sha256:dfe46b1ff385","state":"fresh"},{"path":"scripts/kb-viewer/build-site-page.mjs","hash":"sha256:666bcaa58b10","state":"fresh"}],"freshness":"changed","dir":"src/graph","outLinks":[],"body":"coldstart graph and coldstart kb view each produce a single self-contained HTML file from a template carrying a <!--__HOME_LINK__--> placeholder; the CLI's own render call (renderGraphHtml / renderViewHtml) unconditionally clears that placeholder to '' because the standalone local file has nowhere to link back to, so the website build scripts (the only callers that want the link) must substitute the real <a id=\"home\"> anchor into the raw template BEFORE calling render — filling it in after render is a silent no-op.\n\n## Steps\n\n1. `src/graph/view-template.ts` (`GRAPH_TEMPLATE`) — defines the placeholder + #home CSS, original pattern\n2. `src/graph/view.ts` (`renderGraphHtml`) — clears the placeholder to '' unconditionally\n3. `scripts/graph-viewer/build-site-page.mjs` — substitutes the real home link into the template before calling renderGraphHtml; only its rationale COMMENT changed this session (notebook-privacy wording corrected), the substitution logic itself is untouched\n4. `src/kb/view-template.ts` (`VIEW_TEMPLATE`) — carries the same placeholder + #home CSS, mirroring the graph template\n5. `src/kb/view.ts` (`renderViewHtml`) — also clears the placeholder for the standalone CLI case\n6. `scripts/kb-viewer/build-site-page.mjs` — substitutes the real home link before calling renderViewHtml\n\n## Invariants\n\n- the placeholder must be filled on the TEMPLATE string before calling render() — render always clears it, so filling it in after is a no-op that silently ships a link-less page\n- both viewers use the identical anchor markup/id (#home) and CSS convention — a future third generated viewer should follow the same order","backlinks":[],"anchorLinks":["how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p","scripts-graph-viewer-build-site-page-mjs-9bf323da","scripts-kb-viewer-build-site-page-mjs-35d52445","src-graph-view-ts-9f9d75ac","src-kb-view-ts-1fba6747"]},{"id":"how-the-sitemap-gets-its-lastmod-dates","type":"flow","character":null,"title":"how the sitemap gets its lastmod dates","aliases":["sitemap lastmod","sitemap generation","fetch-depth shallow clone","astro sitemap serialize","uniform lastmod dates","identical timestamps sitemap","missing lastmod"],"status":"active","updated":"2026-08-26T19:53:19.308Z","edits":2,"anchors":[{"path":".github/workflows/pages.yml","hash":"sha256:d4787cf44eab","state":"fresh"},{"path":"site-astro/astro.config.mjs","hash":"sha256:268671d3ade6","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"The sitemap's <lastmod> values are not produced by Astro or by the deploy workflow alone — they come from git history read at build time, so the correctness of every date depends on a setting in a DIFFERENT file: actions/checkout's fetch-depth in .github/workflows/pages.yml. A shallow clone does not make git log fail; it answers every path with the single commit it has, so per-file dates come back uniform and wrong rather than absent. That is why astro.config.mjs probes `git rev-parse --is-shallow-repository` up front and emits NO lastmod at all when history is unusable: a wrong lastmod on every URL is worse than none, because it trains Google to ignore the field.\n\n## Steps\n\n1. `.github/workflows/pages.yml` (`deploy`) — fetch-depth: 0 makes full git history available to the build; removing it silently disables lastmod. Unrelated new steps (coldstart index + site-page regeneration) were added AFTER checkout this session and do not touch this setting\n2. `site-astro/astro.config.mjs` (`historyUsable`, `sourceFileForRoute`, `lastCommitDate`) — maps each route to its source file and stamps that file's last-commit date, guarded on clone depth\n\n## Invariants\n\n- fetch-depth: 0 in pages.yml is load-bearing for lastmod, not an optimisation\n- lastmod is omitted entirely rather than faked when git history is unusable\n- blog posts stamp from their markdown in src/content/blog, never from [slug].astro, so template edits do not restamp every post","backlinks":[],"anchorLinks":["github-workflows-pages-yml-80c02bfb","how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p","site-astro-astro-config-mjs-8801ef8e"]},{"id":"how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p","type":"flow","character":null,"title":"how the site's notebook and graph pages stay fresh after a push","aliases":["notebook site page deploy","graph site page deploy","coldstart index in CI","pages workflow regenerate","site notebook page stale","graph page out of date","pushed notebook update not live","manual regen forgotten"],"status":"active","updated":"2026-08-26T19:53:19.279Z","edits":1,"anchors":[{"path":".gitignore","hash":"sha256:4eca4b5cc0b9","state":"fresh"},{"path":"src/kb/commit.ts","hash":"sha256:af2da722de0e","state":"fresh"},{"path":"scripts/kb-viewer/build-site-page.mjs","hash":"sha256:666bcaa58b10","state":"fresh"},{"path":"scripts/graph-viewer/build-site-page.mjs","hash":"sha256:ca2509b50b93","state":"fresh"},{"path":".github/workflows/pages.yml","hash":"sha256:d4787cf44eab","state":"fresh"}],"freshness":"fresh","dir":".","outLinks":[],"body":"The /notebook/ and /graph/ site pages are baked HTML snapshots that CI now regenerates fresh on every relevant push (via `coldstart index` plus the two build-site-page.mjs scripts, run before the Astro build), which only works because this repo's own notebook — previously fully gitignored as private working memory — was committed to git via `kb commit` so a fresh CI checkout has notes to fold at all.\n\n## Steps\n\n1. `.gitignore` — narrowed from a blanket `.coldstart/` to `.coldstart/*` plus `!.coldstart/notebook`, the change that makes committing the notebook possible at all\n2. `src/kb/commit.ts` (`kbCommit`, `publishPaths`) — the sanctioned publish path; stages+commits only `.raw/` + okf.yaml + its own .gitignore, never the derived notes/*.md\n3. `scripts/kb-viewer/build-site-page.mjs` — folds the checked-out `.raw/` logs (buildViewData/loadAll) and bakes site-astro/src/notebook-page.html; needs dist/ built first\n4. `scripts/graph-viewer/build-site-page.mjs` — builds site-astro/src/graph-page.html from a freshly-built coldstart index plus git co-change history; always passes [] for notebook anchors\n5. `.github/workflows/pages.yml` — CI order: npm run build, then `coldstart index --root .`, then both generator scripts, then the site-astro build/deploy; push-trigger paths widened to src/**, .coldstart/notebook/**, and both generator script dirs so a notebook- or source-only push still redeploys\n\n## Invariants\n\n- the graph page always passes [] for notebook anchors — no note content ever appears in /graph/, independent of whether the notebook itself is committed\n- CI builds its OWN fresh index via `coldstart index --root .`; the developer's local .coldstart/cache stays gitignored and is never read by CI\n- kb commit only publishes .raw/ + okf.yaml + .gitignore — never derived notes/*.md — so the site build must fold notes itself rather than read pre-rendered markdown","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when","github-workflows-pages-yml-80c02bfb","gitignore-a5cc2925","how-the-sitemap-gets-its-lastmod-dates","scripts-graph-viewer-build-site-page-mjs-9bf323da","scripts-kb-viewer-build-site-page-mjs-35d52445","src-kb-commit-ts-5df8452d"]},{"id":"scripts-kb-viewer-build-site-page-mjs-35d52445","type":"file","character":"single","title":"scripts/kb-viewer/build-site-page.mjs","aliases":["notebook site page generator","kb view site build"],"status":"active","updated":"2026-08-26T19:36:28.412Z","edits":3,"anchors":[{"path":"scripts/kb-viewer/build-site-page.mjs","symbols":["HERE","ROOT","DIST","OUT","distImport","buildViewData","renderViewHtml","VIEW_TEMPLATE","template","generated","data","html"],"hash":"sha256:666bcaa58b10","state":"fresh"}],"freshness":"fresh","dir":"scripts/kb-viewer","outLinks":[],"body":"Generates `site-astro/src/notebook-page.html` — the same single-file viewer `coldstart kb view` produces, with this repo's own real notebook baked in. Mirrors `scripts/graph-viewer/build-site-page.mjs` exactly, including substituting the real `<a id=\"home\">` link into VIEW_TEMPLATE before calling renderViewHtml (renderViewHtml always clears the placeholder itself, so the substitution must happen on the template first — see the home-link-placeholder flow note). Requires `npm run build` first since it imports compiled `dist/kb/view.js` and `dist/kb/view-template.js` directly, not the TS source.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when","how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p"]},{"id":"site-astro-src-pages-live-index-astro-b8d46da1","type":"file","character":"single","title":"site-astro/src/pages/live/index.astro","aliases":["see it live hub","three cards demo graph notebook","live hub page"],"status":"active","updated":"2026-08-26T19:35:24.584Z","edits":2,"anchors":[{"path":"site-astro/src/pages/live/index.astro","symbols":["title","description","cards"],"hash":"sha256:0f3c6cc49e9d","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/live","outLinks":[],"body":"The /live/ hub page: three cards (Walkthrough → /demo/, Graph → /graph/, Notebook → /notebook/) so the homepage's CTA doesn't have to pick one of the three real-data pages for the visitor — it links here instead of straight to /graph/. Plain new-page chrome (landing.css + Nav/Footer/SvgDefs, `Nav variant=\"live\"`), no dependency beyond an inline `cards` array mapped to `.livecard` anchors.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"src-graph-view-ts-9f9d75ac","type":"file","character":"single","title":"src/graph/view.ts","aliases":["graph view writer","self-contained html output","open in browser","graph html placeholder substitution","home link placeholder","home link stripped","link back missing"],"status":"active","updated":"2026-08-26T19:35:24.045Z","edits":2,"anchors":[{"path":"src/graph/view.ts","symbols":["graphView","renderGraphHtml","noteAnchors","defaultGraphPath"],"hash":"sha256:fc7d4eca1c94","state":"fresh"}],"freshness":"fresh","dir":"src/graph","outLinks":[],"body":"The write-and-open half of `coldstart graph`: reads the notebook for note anchors, calls buildGraphPayload, bakes the result into GRAPH_TEMPLATE and writes a single self-contained HTML file, then opens it in the OS browser. `renderGraphHtml` substitutes `<!--__HOME_LINK__-->` with '' — the standalone CLI page has nowhere to link back to, so any caller that wants that link (the site build) must substitute it into the TEMPLATE before calling this. This exact mechanism was mirrored for the notebook viewer (`src/kb/view.ts` + `src/kb/view-template.ts`) this session — see the home-link-placeholder flow note for the full picture across both viewers.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-components-footer-astro-98a77858","type":"file","character":"single","title":"site-astro/src/components/Footer.astro","aliases":["footer component","footer tagline","home footer","footer variant","taglines map"],"status":"active","updated":"2026-08-26T19:35:24.024Z","edits":4,"anchors":[{"path":"site-astro/src/components/Footer.astro","symbols":["Props","taglines","tagline"],"hash":"sha256:f67267f5bf38","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Shared footer, markup only. The `variant` prop ('home'|'docs'|'blog'|'how'|'live') keys directly into a `taglines` object literal to pick the footer tagline text — so unlike Nav, widening Footer's variant union is NOT enough: a variant with no matching taglines key silently renders an undefined tagline. Widened again this session for the new 'live' hub page ('see it live · MIT').","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"src-kb-view-ts-1fba6747","type":"file","character":"single","title":"src/kb/view.ts","aliases":["notebook view rewritten","index.html mtime churn","notebook view","wikilink graph","note graph edges","buildViewData","notebook viewer data","note graph links","shared anchor links","kb view html","home link placeholder","empty note graph","notebook page no back link"],"status":"active","updated":"2026-08-26T19:35:24.015Z","edits":9,"anchors":[{"path":"src/kb/view.ts","symbols":["kbView","renderViewHtml","buildViewData","toClientNote","ignoreIndexHtml","openInBrowser","bodyMarkdown","ViewOptions","linkByAnchor"],"hash":"sha256:dfe46b1ff385","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":["wikilinks"],"body":"Builds the baked JSON for `kb view` and writes/opens the notebook's index.html. linkByAnchor draws graph edges between any two notes that anchor the same file (capped at 8/note), on top of hand-typed [[wikilinks]], because agents write almost no wikilinks on their own. `renderViewHtml` now also substitutes `<!--__HOME_LINK__-->` with '' this session, mirroring `src/graph/view.ts`'s `renderGraphHtml` — the standalone `kb view` CLI page has nowhere to link back to, so only the website build script (`scripts/kb-viewer/build-site-page.mjs`) fills the placeholder in, and only by substituting into the raw template BEFORE this function runs.","backlinks":[],"anchorLinks":["how-a-standalone-generated-viewer-page-gets-a-back-link-when"]},{"id":"site-astro-src-components-nav-astro-9dfe3071","type":"file","character":"single","title":"site-astro/src/components/Nav.astro","aliases":["nav component","site navigation","header nav","variant prop","active nav tab","nav variant union","how variant","demo dropdown","nav dropdown menu","dropdown active underline","thick blue line dropdown"],"status":"active","updated":"2026-08-26T19:35:23.964Z","edits":5,"anchors":[{"path":"site-astro/src/components/Nav.astro","symbols":["Props","nav-burger","nav-mobile","installHref","nav-links","nav-drop","nav-drop-menu","demoActive"],"hash":"sha256:47409c440654","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Shared nav component, markup only — all of its appearance comes from the page's stylesheet (landing.css for home/demo/live/notebook, docs.css everywhere else). The `variant` prop ('home'|'docs'|'blog'|'how'|'graph'|'demo'|'notebook'|'live', default 'docs') picks which link gets the `active` class. This session collapsed the separate Demo/Graph/Notebook links into one `.nav-drop` dropdown: the 'Demo' trigger still links straight to /demo/, `demoActive` (true for variant demo/graph/notebook/live) highlights the trigger, and a `.nav-drop-menu` lists all three with per-item descriptions. The npm link stays plain text; GitHub is icon-only on desktop but both render as plain text in the mobile menu (still not fixed).","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"hooks-evidence-mjs-147e7dd5","type":"file","character":"single","title":"hooks/evidence.mjs","aliases":["mention-only drop","grep hits not reads","sed -i is an edit","tool_result confirmation","cursor no tool results","codex cmd regex","inline script read detection","bashContentRead","bashEditTargets","shell write detection","heredoc tag arbitrary","cat redirect tiered as read","heredoc tag not recognized"],"status":"active","updated":"2026-08-25T18:54:16.712Z","edits":5,"anchors":[{"path":"hooks/evidence.mjs","symbols":["extractEvidence","extractCursorEvidence","extractCodexEvidence","classifyBash","codexCmdStrings","makeCollector","contentReadFiles","segmentStats","segmentStatsCursor","normRel","inlineScriptTier","bashContentRead","redirectTargets","bashEditTargets"],"hash":"sha256:9fbcfb9db13e","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Per-host transcript-to-evidence extractors with tier classification (edit/read/gs/mention), and the one table deciding what shell activity counts as reading or writing a file. Host gotchas verified on real transcripts: Cursor's conversation JSONL has NO tool_result records, so its extractor trusts calls and compensates with a stat-existence check on EVERY claim; Codex pairs custom_tool_call to output by call_id and its exec input embeds shell with the cmd key appearing BOTH quoted and unquoted across rollout versions. Default-deny: an unknown bash verb contributes at most a mention. Reading through the SHELL counts as reading (read verbs, plus inline scripts in any language matched on the file-open call in their body); writing through the shell counts as writing (bashEditTargets: redirect, tee, sed -i, literal write arg). A heredoc tag is an ARBITRARY identifier — the old EOF/PY/JS whitelist missed PATCH, TS and MSG and made those scripts invisible to both surfaces. redirectTargets overrides the verb table so `cat > x <<EOF` is an edit, not a read. Measured while building this: attributing a whole command would over-tier 50.6% of inline reads; output VOLUME does not separate reads from searches (cat's median is 18 lines vs an inline script's 10); and the deterministic write rules cover 89.2% of shell writes, so the single-literal guess for computed paths was rejected at 5.8% marginal gain.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"hooks-cochange-nudge-mjs-2fa94d26","type":"file","character":"single","title":"hooks/cochange-nudge.mjs","aliases":["co-change edit nudge","edit list per task","cochange sidecar reader","resetEditTrack","mirrored cache dir","shell edit detection","editedFiles list","nudge silent on sed edits","heredoc edit not counted"],"status":"active","updated":"2026-08-25T18:54:16.701Z","edits":2,"anchors":[{"path":"hooks/cochange-nudge.mjs","symbols":["coChangeNudge","resetEditTrack","coChangePath","suggest","render","loadState","editedPath","EDIT_TOOLS","MIN_RATIO","ORPHAN_MS","editedFiles","SHELL_TOOLS"],"hash":"sha256:33dd367fbc19","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Detector (7) of the PostToolUse nudge: records each edited file per (session,agent) and, once a SECOND distinct file is edited, names the files git history says move with them. Three rules, all measured, none to re-derive: the list clears on every new user message; nothing fires below 2 distinct files (trivial one-file jobs); then it fires for any partner not already edited and not already named — those two exclusions are the whole quieting mechanism, no per-session cap is needed. An edit is an edit TOOL or a shell write: editedFiles() returns a LIST, because one command can write two files and reach the 2-file threshold by itself. Two things a future editor will get wrong: (a) the tmp sweep must match the exact key or `<sid>_<aid>`, NEVER a bare `<sid>` prefix, or it clears a different session whose id merely starts the same; (b) the cache-dir derivation is a hand-copy of getCacheDir/cacheKey because hooks cannot import dist/ — change one and tests/cochange-nudge.test.ts is the only thing that notices. Cursor is why EDIT_TOOLS carries `SearchReplace` and editedPath accepts `path` as well as `file_path`; that shape is verified against Cursor transcripts, NOT a live Cursor hook payload.","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","type":"flow","character":null,"title":"how the co-change signal reaches an agent that never runs gs","aliases":["co-change edit nudge","edited together injection","PostToolUse detector 7","unasked co-change","edit-time nudge","shell edits count as edits","sed heredoc edit nudge","nudge silent in auto mode","edited via script no nudge"],"status":"active","updated":"2026-08-25T18:54:16.648Z","edits":2,"anchors":[{"path":"hooks/cochange-nudge.mjs","hash":"sha256:33dd367fbc19","state":"fresh"},{"path":"hooks/nudge-handler.mjs","hash":"sha256:2eefdfc34529","state":"fresh"},{"path":"hooks/kb-recall.mjs","hash":"sha256:7a8923adf6e0","state":"fresh"},{"path":"src/indexer/cochange.ts","hash":"sha256:b77c94aa16f5","state":"fresh"},{"path":"hooks/evidence.mjs","hash":"sha256:9fbcfb9db13e","state":"fresh"},{"path":"tests/cochange-nudge.test.ts","hash":"sha256:bfb50fa6b9bd","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"The \"Edited together\" partners are delivered to the agent WITHOUT it asking, at the moment an edit lands, because agents do not reliably run `gs` before editing. What counts as \"an edit\" is the load-bearing part: an edit TOOL or a deterministic shell write (`>`/`>>`, `tee`, `sed -i`, or a write call naming a literal path, via bashEditTargets in hooks/evidence.mjs). Gating on tool names alone made the whole feature silent for an agent instructed to edit with sed/heredocs/scripts — which is the auto-mode default, so the agent that most needed the nudge was the one guaranteed never to get it. The delivery path shares NO code with the `gs` rendering path: it is detector (7) inside the PostToolUse nudge handler, it reads the keeper's `cochange.json` sidecar directly, and its gate is deliberately LOOSER than `gs` (ratio >= 0.3 of the seed's own commits, shared >= 2, top 5) because \"what am I forgetting\" is a recall question while the `gs` cut is tuned for precision. It needs no `init` wiring: PostToolUse is registered on all three hosts with a match-everything matcher, and cursor-nudge-handler delegates to the Codex one.\n\n## Steps\n\n1. `hooks/cochange-nudge.mjs` (`coChangeNudge`, `editedFiles`, `suggest`, `resetEditTrack`, `coChangePath`, `EDIT_TOOLS`, `SHELL_TOOLS`) — the whole feature: what counts as an edit, the per-task edit list, the gate, the message\n2. `hooks/evidence.mjs` (`bashEditTargets`, `redirectTargets`, `inlineScriptTier`) — decides which repo files a shell command WRITES — the shared table, so the nudge and the capture worklist cannot disagree\n3. `hooks/nudge-handler.mjs` (`handle`) — host entry — calls it as detector (7) at priority 3\n4. `tests/cochange-nudge.test.ts` — pins the shell-edit shapes and the deliberate silences\n\n## Invariants\n\n- UserPromptSubmit is the ONLY clearing signal. Elapsed time is the wrong shape for a task boundary — an auto-mode run edits for hours with no prompt, and a session id survives a resume days later. A settle clock, the session id, and a 30-min TTL were each tried and rejected as proxies for it. The 7-day sweep in resetEditTrack is garbage collection for abandoned files, never a boundary.\n- The nudge (PostToolUse) and the reset (UserPromptSubmit) are wired by SEPARATE init functions — wireClaudeHooks vs wireClaudeKbHooks — so a repo can have the nudge without the reset. There the list never clears; it degrades quietly rather than loudly, because each file is named at most once.\n- The edit list is its own tmp file, never folded into /tmp/find_nudge_<key>.json, which the search detectors and the preguard's deny-key depend on.\n- Hooks never import from dist/, so the hook MIRRORS getCacheDir/cacheKey. tests/cochange-nudge.test.ts asserts the two paths are equal — without it a rename on the TS side kills the feature silently.\n- only DETERMINISTIC shell writes count; a write to a computed path claims nothing. Measured: the deterministic rules cover 89.2% of real shell writes, and inferring the rest from 'the one source path in the script' added 5.8% while making it possible to name a file the script only READ\n- a heredoc tag is an arbitrary identifier (EOF, PATCH, TS, MSG) — never re-introduce a tag whitelist, it made whole scripts invisible\n- a redirect target is an edit even under a read verb, so `cat > x <<EOF` must not tier x as a read","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-notebook-capture-fires-v5-trigger-timed","hooks-cochange-nudge-mjs-2fa94d26","hooks-evidence-mjs-147e7dd5","hooks-kb-recall-mjs-bb2f72e8","hooks-nudge-handler-mjs-9ca0ef0b","how-the-moves-together-signal-reaches-gs-without-going-throu","src-indexer-cochange-ts-87067890"]},{"id":"hooks-codex-nudge-handler-mjs-f48031e6","type":"file","character":"single","title":"hooks/codex-nudge-handler.mjs","aliases":["codex nudge twin","duplicated detector logic","fix applied to one host only"],"status":"active","updated":"2026-08-25T18:44:33.078Z","edits":1,"anchors":[{"path":"hooks/codex-nudge-handler.mjs","symbols":["handle","resultText","grepPattern","kbSpiralHit"],"hash":"sha256:59c42aa2b899","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Codex's PostToolUse nudge. Verified this session by diffing it against hooks/nudge-handler.mjs: the two files are byte-identical apart from two header-comment lines (the filename and the name of the PreToolUse guard). It is a maintained copy, not a re-implementation, so any detector change must be applied to both in the same commit or Codex silently keeps the old behaviour. Cursor has no third copy — hooks/cursor-nudge-handler.mjs delegates here, so this file is the one that governs two of the three hosts.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap"]},{"id":"hooks-nudge-handler-mjs-9ca0ef0b","type":"file","character":"single","title":"hooks/nudge-handler.mjs","aliases":["postToolUse nudge detectors","grep spiral detector","seen_find_queries registration","cat treated as spiral","nudged while reading files"],"status":"active","updated":"2026-08-25T18:44:33.068Z","edits":1,"anchors":[{"path":"hooks/nudge-handler.mjs","symbols":["handle","resultText","grepPattern","kbSpiralHit","gitFingerprint","gitHead","matchAllGroup"],"hash":"sha256:2eefdfc34529","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Claude's PostToolUse nudge: 7 search-behaviour detectors over a per-(session,agent) /tmp state file, plus registration of every successful find's canonical key for the PreToolUse guard to deny against. What I verified this session is how it decides a call is a READ versus a SEARCH — it used to define a read as `tool === \"Read\"` and list `cat` inside SEARCH_RE, so an agent working through the shell (the auto-mode default) was told it was spiralling for reading files; three cats of three different files fired the anti-grep nudge. Read classification now comes from bashContentRead in evidence.mjs rather than from a regex here, so the nudge and the capture worklist cannot drift on what counts as reading. A command that both reads and searches (`cat x | grep y`) stays a search: the grep is the operative half.","backlinks":[],"anchorLinks":["how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"how-a-shell-mediated-file-read-reaches-the-nudge-and-the-cap","type":"flow","character":null,"title":"how a shell-mediated file read reaches the nudge and the capture worklist","aliases":["shell read classification","reading via bash","inline script read","intent vs attribution","cat counted as grep spiral","shell reads invisible to capture"],"status":"active","updated":"2026-08-25T18:44:33.030Z","edits":1,"anchors":[{"path":"hooks/evidence.mjs","hash":"sha256:d8b68b9a4e7f","state":"changed"},{"path":"hooks/nudge-handler.mjs","hash":"sha256:2eefdfc34529","state":"fresh"},{"path":"hooks/codex-nudge-handler.mjs","hash":"sha256:59c42aa2b899","state":"fresh"},{"path":"hooks/cursor-nudge-handler.mjs","hash":"sha256:745090ec3b11","state":"fresh"},{"path":"hooks/cursor-input.mjs","hash":"sha256:8fb374fcd6b4","state":"fresh"},{"path":"tests/shell-read-evidence.test.ts","hash":"sha256:233464173f1c","state":"fresh"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"One table in hooks/evidence.mjs decides what counts as reading a file, and it deliberately gives two different answers to two consumers: the PostToolUse nudge asks only whether content was put in front of the agent (bashContentRead), while the capture worklist asks which NAMED file was read (the tier attached to each path token). The same command can therefore clear the grep-spiral nudge while anchoring no note at all — `python3 -c 'print(open(sys.argv[1]).read())' src/cli.ts` is a real read with no literal path to attribute. Both surfaces reach that one table by three different host routes, so a fix applied to Claude's path alone leaves Codex and Cursor silently broken.\n\n## Steps\n\n1. `hooks/evidence.mjs` (`classifyBash`, `inlineScriptTier`, `bashContentRead`) — the single classification table: read verbs, inline-script file-open APIs, and per-token tier\n2. `hooks/nudge-handler.mjs` (`handle`) — Claude PostToolUse consumer — asks INTENT only, via bashContentRead\n3. `hooks/codex-nudge-handler.mjs` (`handle`) — Codex consumer, a verbatim twin of the Claude handler\n4. `hooks/cursor-nudge-handler.mjs` (`handle`) — Cursor consumer — delegates to the Codex handler through adaptCursorInput, so it inherits fixes without its own patch\n5. `hooks/cursor-input.mjs` (`adaptCursorInput`) — renames Cursor's Shell tool to Bash so the shared detectors match unchanged\n6. `tests/shell-read-evidence.test.ts` — pins all three hosts x both surfaces, because a one-host fix fails silently\n\n## Invariants\n\n- `cat` must never go back into SEARCH_RE in either nudge handler — it prints a whole file, which is a Read by another name\n- hooks/nudge-handler.mjs and hooks/codex-nudge-handler.mjs are verbatim twins apart from their header comment; patch both in the same change\n- inline scripts are classified BEFORE the segment split — the splitter cuts on `;`/`|` that are the script's own syntax, not shell operators\n- the read tier attaches only to the path named inside the read call; other path tokens in the same command stay mentions","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","hooks-codex-nudge-handler-mjs-f48031e6","hooks-evidence-mjs-147e7dd5","hooks-nudge-handler-mjs-9ca0ef0b","how-notebook-capture-fires-v5-trigger-timed"]},{"id":"src-cache-disk-cache-ts-1359262b","type":"file","character":"single","title":"src/cache/disk-cache.ts","aliases":["LoadProfile concept","cache segments","gs vs full profiles","disk persistence","cacheKey derivation","getCacheDir","cache path hash","mirrored by hooks","loadCachedIndex returned null","profile passed as second argument"],"status":"active","updated":"2026-08-25T18:18:29.577Z","edits":3,"anchors":[{"path":"src/cache/disk-cache.ts","symbols":["loadCachedIndex","saveCachedIndex","getCacheDir","cacheKey","LoadProfile"],"hash":"sha256:a309616de81d","state":"fresh"}],"freshness":"fresh","dir":"src/cache","outLinks":[],"body":"On-disk index cache with consumer-scoped segments and lazy loading. LoadProfile: 'find' loads table+core+graph (~200ms), 'gs' adds callgraph (500ms on warm cache), 'full' adds build data (keeper only). CLI readers use 'gs' to avoid keeper-only segments. Cache validity = version + gitHead + keeper watcher (no TTL). loadCachedIndex's SECOND positional parameter is baseCacheDir, not the profile — the profile is third, and passing it second silently yields a null cache that reads exactly like a cache miss. Verified 2026-08-25: cacheKey is `<basename>-<sha256(abs)[0:16]>` under coldstartHome()/indexes, and it now has a consumer the import graph cannot see — hooks/cochange-nudge.mjs HAND-COPIES that derivation, because hooks never import from dist/. tests/cochange-nudge.test.ts asserts the copy still agrees; renaming or rekeying here without running it silently breaks the edit-time nudge rather than failing a build.","backlinks":[],"anchorLinks":[]},{"id":"src-indexer-cochange-ts-87067890","type":"file","character":"single","title":"src/indexer/cochange.ts","aliases":["co-change derivation","git log name-status","rename carry forward","moves together pairs","canonicalizeRenames","co-edited partners","touched denominator","ratio denominator absent","no touched entry","denominator missing for file"],"status":"active","updated":"2026-08-25T18:18:29.565Z","edits":2,"anchors":[{"path":"src/indexer/cochange.ts","symbols":["deriveCoChange","canonicalizeRenames","parseCommits","coChangePartnersFor","loadCoChange","saveCoChange","CO_CHANGE_WINDOW","CO_CHANGE_K","coChangePath","CO_CHANGE_MIN_SUPPORT"],"hash":"sha256:b77c94aa16f5","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Derives \"which files move together\" by walking git log --name-status -M and counting files that change in the same commit; stores 8 partners per file, shows 3, min support 2, 12k-commit window (all measured, don't retune blind). The non-obvious part is canonicalizeRenames: -M labels ONLY the rename commit, so every older commit still records the old path and a renamed file silently splits into two half-histories whose older half is keyed to a path that no longer exists and can never be displayed. Because git log is newest-first, the fix is a single forward pass carrying an alias map — a rename old->new seen at commit i means every LATER entry in the stream (i.e. older commit) that says old means new — resolved transitively and only ever recorded backwards, so a path later reused by a different file keeps its own identity. Verified 2026-08-23 on arches: 12k commits in 596ms, 325KB sidecar. 2026-08-25, for consumers computing a RATIO: `touched` is NOT a count for every file in history — it is trimmed to `keep`, i.e. files that got a partner list plus those partners, so a file whose every pair fell below min-support has NO entry at all and any shared/touched calculation must read that absence as silence rather than a zero denominator. Every file that HAS partners does have its denominator, so a ratio gate needs no extra data.","backlinks":[],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","how-the-moves-together-signal-reaches-gs-without-going-throu"]},{"id":"github-workflows-ci-yml-899ce9c2","type":"file","character":"single","title":".github/workflows/ci.yml","aliases":["CI workflow","GitHub Actions permissions","workflow permissions block","missing workflow permissions","codeql workflow alert","actions permissions warning"],"status":"active","updated":"2026-08-25T16:34:51.684Z","edits":1,"anchors":[{"path":".github/workflows/ci.yml","hash":"sha256:c93991865d01","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"CI workflow running build+test on ubuntu-latest and windows-latest (matrix added in #159, after ubuntu-only CI hid months of Windows-only bugs). Requires an explicit top-level `permissions: contents: read` block — its absence trips CodeQL's actions/missing-workflow-permissions check; the workflow only checks out/builds/tests so read-only is correct, matching the same block in verify-149-windows-hide.yml.","backlinks":[],"anchorLinks":[]},{"id":"src-server-tools-ts-cb60011b","type":"file","character":"hub","title":"src/server/tools.ts","aliases":["gs handler","symbol lookup","file presence check","symbol page rendering","bidirectional edges","moves together rendering","gs page builder","handleGetStructure","gs view gating","related section"],"status":"active","updated":"2026-08-23T10:33:43.525Z","edits":6,"anchors":[{"path":"src/server/tools.ts","symbols":["handleGetStructure","findFileByPath","buildCallersForFile","renderSymbolSlice","compileMatchPredicate"],"hash":"sha256:53676513658f","state":"fresh"}],"freshness":"fresh","dir":"src/server","outLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu"],"body":"handleGetStructure builds the gs symbol page for one file. Uses findFileByPath to lookup file: returns [fileId, IndexedFile] if found, null if not indexed. Distinguishes two states: null → file not in index (untracked), [fileId, file with file.symbols=[]] → file indexed but has zero symbols (e.g., CSS). Handles match filtering, symbol slicing, imports/importers, callers per symbol. Critical for kb write reuse: can call loadCachedIndex('gs') then index.files.get(path) to check presence.\n\n## Facets\n\n- **handleGetStructure** — Builds the gs page. findFileByPath distinguishes two states: null = not indexed, [fileId, file with symbols=[]] = indexed but symbol-less (e.g. CSS). It is SYNCHRONOUS and takes the index only, which is why git-derived co-change arrives as an optional THIRD parameter loaded by each caller. The `view` param gates ONLY the sections describing this file — wantSymbols/wantImports/wantImporters/wantInlineCallers. The two cross-file sections, Edited together and Related, are deliberately ungated and render in every view; both were full-view-only once and both misses were found the same way, by a real session asking for `--view symbols` on a god-file. Related is still computed AFTER co-change so co-change's picks can join its excludeIds and a path never prints under two headings. — [[how-the-moves-together-signal-reaches-gs-without-going-throu]]\n- **buildCallersForFile** — Given fileId and file, returns { exportedSymbol, callers[] } by iterating ALL symbolEdges filtering type==='calls' and checking edge.to is exported in the target. No pre-built reverse index; an O(n) walk of symbolEdges per file lookup.\n- **renderSymbolSlice** — calleesOf(symId) walks symbolEdges filtering type==='calls' && from===symId for outgoing targets — bidirectional pattern: callers via incoming edges, callees via outgoing.\n- **compileMatchPredicate** — Compiles the match filter: /regex/, a|b for OR, else case-insensitive substring. Returns null when no filter was requested.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"how-the-moves-together-signal-reaches-gs-without-going-throu","type":"flow","character":null,"title":"how the edited-together signal reaches gs without going through the index","aliases":["co-change sidecar","moves together section","cochange.json","git history signal","co-edited files gs","how the moves-together signal reaches gs without going through the index","edited together section","section missing in view symbols","narrowed gs view drops a section"],"status":"active","updated":"2026-08-23T10:33:43.496Z","edits":4,"anchors":[{"path":"src/index-manager.ts","hash":"sha256:cb324edbaeb8","state":"changed"},{"path":"src/indexer/cochange.ts","hash":"sha256:b77c94aa16f5","state":"fresh"},{"path":"src/cli.ts","hash":"sha256:e863c8636403","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:3f63d980bc9b","state":"changed"},{"path":"src/server/tools.ts","hash":"sha256:53676513658f","state":"fresh"}],"freshness":"changed","dir":"src","outLinks":[],"body":"The \"Edited together\" pairs shown by gs are NOT part of the code index and never travel through the cache pipeline — they live in a separate keeper-written sidecar (cochange.json) that each reader loads itself and hands to handleGetStructure as a THIRD argument. This is why gs can show them at all: handleGetStructure is synchronous and takes only an index, so there was no way to reach git from inside it. Consequence for anyone adding a similar signal: don't try to hang it off CodebaseIndex — the cache is consumer-scoped and gzip-swept, and a reader that already has an index still needs a second explicit load. It also means a surface that forgets to pass the argument silently renders nothing rather than erroring. The section was called \"Moves together\" until 2026-08-23; the old name survives in identityAliases on purpose so a search for it still lands here.\n\n## Steps\n\n1. `src/index-manager.ts` (`refreshCoChange`, `startWatching`, `scheduleCacheSave`) — keeper derives it at watch start and whenever HEAD moves, then writes the sidecar\n2. `src/indexer/cochange.ts` (`deriveCoChange`, `saveCoChange`, `loadCoChange`, `coChangePartnersFor`) — the git walk, the sidecar read/write, and the render selector\n3. `src/cli.ts` (`runGs`) — CLI reader loads the sidecar and passes it as the third argument\n4. `src/server/mcp.ts` (`registerToolHandlers`) — MCP reader re-loads it per call, since the keeper rewrites it on branch switch\n5. `src/server/tools.ts` (`handleGetStructure`) — renders the section in EVERY view, excluding this file's import-graph neighbours (index.outEdges/inEdges) rather than whichever lists the current view happens to print\n\n## Invariants\n\n- Derivation is keyed on git HEAD, not on file edits — an uncommitted change never re-walks history.\n- Absent sidecar renders NO section at all, never an empty one: silence must not read as 'nothing moves with this file'.\n- The sidecar is plain JSON, not .gz — saveCachedIndex sweeps *.gz on every save and would delete it.\n- The section is full-view only; the narrowed gs views never show it.\n- The section renders in every gs view. It was full-view-only until 2026-08-23, and the first real session that could have used it asked for `--view symbols` on a god-file, so the channel was unreachable at exactly the moment it was wanted. Do not re-gate it on view.\n- The exclusion set is read from index.outEdges/inEdges, NOT from importsOut/importersShown. The heading claims these pairs carry no import edge, and that claim is only true if every graph neighbour is excluded — narrow views populate neither list, and full view's importer list is capped, so a view-scoped exclusion leaks importers into the section under a false heading.\n- Absent sidecar renders NO section at all, never an empty one: silence must not read as 'nothing was edited with this file'.\n- The user-facing name is 'Edited together' everywhere: the gs heading, the graph viewer's relation label, `status`, the site docs and the agent guidance in coldstart.md and templates/. The graph viewer's label lives in scripts/graph-viewer/sphere.template.html and reaches src/graph/view-template.ts only via build-template.mjs, so a rename that skips that script silently leaves the old word in the shipped viewer.\n- BOTH cross-file sections — Edited together and Related — render in every gs view. Each was full-view-only once, and each time the miss surfaced the same way: a real session asked for `--view symbols` on a god-file, which is exactly when the other-file channels matter most. Only the sections describing THIS file (symbols/imports/importers/callers) are view-gated. Do not re-gate either one.\n- Both sections build their exclusion set from index.outEdges/inEdges, NOT from importsOut/importersShown. Both headings claim the pair carries no import edge, and that is only true if every graph neighbour is excluded — narrow views populate neither list, and full view's importer list is capped at IMPORTERS_LIST_CAP.","backlinks":["src-server-tools-ts-cb60011b"],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","src-cli-ts-c443bc51","src-index-manager-ts-e298456b","src-indexer-cochange-ts-87067890","src-server-mcp-ts-18031783","src-server-tools-ts-cb60011b","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"site-astro-src-pages-graph-index-astro-797635e1","type":"file","character":"single","title":"site-astro/src/pages/graph/index.astro","aliases":["graph route","graph page astro","serve graph html","graph 404 in astro dev","public dir directory index 404"],"status":"active","updated":"2026-08-23T08:55:06.087Z","edits":1,"anchors":[{"path":"site-astro/src/pages/graph/index.astro","symbols":["html","raw"],"hash":"sha256:b3841695f407","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/graph","outLinks":[],"body":"Serves /graph/ by inlining site-astro/src/graph-page.html (a complete standalone document with its own head, CSS and canvas script) via a ?raw import into a bare <Fragment set:html>. It exists as a ROUTE rather than as public/graph/index.html because `astro dev` serves public/ by exact path with no directory-index fallback: the file answered /graph/index.html and 404'd on /graph/, the URL the nav links to, while production resolved it fine — a dev-only break invisible in CI. Being a route also puts /graph/ in the sitemap. It strips the generated file's leading doctype because Astro emits its own ahead of the template.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-components-docssidebar-astro-93ed0ec3","type":"file","character":"single","title":"site-astro/src/components/DocsSidebar.astro","aliases":["docs sidebar","progressive disclosure sidebar","active group prop","empty sidebar section headers","group header with no items"],"status":"active","updated":"2026-08-23T08:55:06.073Z","edits":2,"anchors":[{"path":"site-astro/src/components/DocsSidebar.astro","symbols":["Props","groups",".gh-link","gh-link","is-active"],"hash":"sha256:114a6d940ca0","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/components","outLinks":[],"body":"Reusable docs sidebar: an `active` prop ('getting-started'|'navigation'|'notebook'|'under-the-hood') selects which group expands its anchor sub-list; other groups collapse to a single link. Only the ACTIVE group's label carries the `gh` class (uppercase, tracked, muted — docs.css `.side-group .gh`). Every group used to carry it, so on any page the three inactive groups rendered as section headers with nothing beneath them: headings labelling nothing. The `.gh-link` scoped override still exists and is load-bearing for a different reason — it cancels docs.css's global `.side a.active` pill so the active group header is not double-highlighted on top of the active sub-link's own pill.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"tests-cochange-test-ts-09288f99","type":"file","character":"single","title":"tests/cochange.test.ts","aliases":["cochange tests","git fixture repo","moves together tests","moves together test","deriveCoChange test","flaky only in full suite","vitest timeout leaks fixture state"],"status":"active","updated":"2026-08-23T08:55:06.059Z","edits":2,"anchors":[{"path":"tests/cochange.test.ts","symbols":["git","commit","makeIndex","gsText"],"hash":"sha256:df9963d3865c","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Covers deriveCoChange (the git walk) and the gs rendering of the Moves together section. Two things a future editor needs: the helpers `git`/`commit` take the repo dir as an explicit parameter and must keep doing so — they once read a module-level `repo` that each scratch-repo test swapped and restored, and when the ~90-commit partner-cap test overran vitest's 5s default under full-suite load vitest moved on while the swap was live, so later tests silently ran against the wrong repo and the suite failed only under load. That test now carries an explicit 60s timeout for the same reason. The rendering block asserts co-change appears in EVERY gs view and that import-graph neighbours stay excluded even in a view that lists neither imports nor importers.","backlinks":[],"anchorLinks":[]},{"id":"src-graph-dump-ts-043aa709","type":"file","character":"single","title":"src/graph/dump.ts","aliases":["graph payload builder","directory band assignment","adaptive clustering","relation kinds","codebase sphere data"],"status":"active","updated":"2026-08-23T07:09:22.362Z","edits":1,"anchors":[{"path":"src/graph/dump.ts","symbols":["assignClusters","buildGraphPayload","REL_IMPORT","REL_CALLS","REL_COEDIT","REL_NOTE"],"hash":"sha256:b74220e57359","state":"changed"}],"freshness":"changed","dir":"src/graph","outLinks":[],"body":"Turns an already-built index (plus the co-change sidecar and note anchors handed in by the caller) into the compact payload `coldstart graph` draws. Two things here are load-bearing and were both arrived at by getting them wrong: directory bands are chosen ADAPTIVELY by assignClusters (split any band over 13% one segment deeper, then fold slivers into a terminal 'other' that is itself allowed to stay small), because a fixed depth-2 cut put 1093 of arches's 1615 files in one band; and the named verbs on call edges come from aggregating index.symbolEdges per FILE PAIR, because every edge in index.edges is a plain import and carries no verb. This module deliberately loads nothing — no index build, no notebook read — so it stays a pure function that tests can drive.","backlinks":[],"anchorLinks":[]},{"id":"src-server-mcp-ts-18031783","type":"file","character":"single","title":"src/server/mcp.ts","aliases":["required note fields","no-shell client notes","TOOL_DEFINITIONS","mcp cli parity","kb_repair_aliases tool","offset browsing only","aliasesVerified closing move","MCP wiring","tool registration","handler dispatch","tool schema","long-lived server stale read","mcp tool missing section","stale sidecar in mcp"],"status":"active","updated":"2026-08-22T19:02:26.308Z","edits":9,"anchors":[{"path":"src/server/mcp.ts","symbols":["TOOL_DEFINITIONS","registerToolHandlers","missingFieldsWarning","flowStepsWarning","kb_repair_aliases"],"hash":"sha256:3f63d980bc9b","state":"changed"}],"freshness":"changed","dir":"src/server","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"MCP server tool registration and handler dispatch. TOOL_DEFINITIONS declares every tool (name, description, inputSchema); the CallToolRequestSchema switch dispatches by name to handlers that call shared engines and wrap results as {__rawText} for text or JSON. Adding a query command = one TOOL_DEFINITIONS entry + one case + a shared engine; REMOVING one means both, and the tool description too, since the description is the only place an MCP client learns a section exists. Verified 2026-08-23: unlike the CLI, this server is long-lived, so a sidecar it reads (co-change) must be re-loaded per call — a copy cached at startup goes stale the moment the keeper rewrites it on a branch switch.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — kb_write description injects the required-fields line","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-cli-ts-c443bc51","type":"file","character":"single","title":"src/cli.ts","aliases":["CLI entry point","command routing","keeper spawning","cache read strategy","parseQueryArgs","reader loads sidecar"],"status":"active","updated":"2026-08-22T19:02:12.600Z","edits":3,"anchors":[{"path":"src/cli.ts","symbols":["runGs","runConsumers","getIndex","runFind","parseQueryArgs"],"hash":"sha256:e863c8636403","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"CLI command routing and execution — entry point for `find`, `gs`, `index`, `consumers`, and `kb`. Key pattern: runGs calls ensureKeeper before the cache load (keeps the index fresh for uncommitted edits) while runConsumers loads the cache directly with no keeper (pure read for capture hooks); the choice turns on whether the command needs live freshness. runGs also loads the co-change sidecar itself and passes it into handleGetStructure — reader-side, because handleGetStructure cannot reach disk. parseQueryArgs is a flat switch over every flag any subcommand accepts, so a flag added for one command is silently accepted by all of them; removing a command means removing its flags here too or they linger as dead accepted input.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-index-manager-ts-e298456b","type":"file","character":"single","title":"src/index-manager.ts","aliases":["keeper regenerates view","notes refresh HTML","kb-notes sidecar","auto mechanical symbol repair","mechanicalRepairStreak","auto symbol backfill keeper","MAX_AUTO_REPAIR_STREAK","sidecar refresh hook","autoMechanicalSymbolRepair","keeper sidecar refresh","refreshCoChange","co-change keyed on HEAD","auto repair silently off","keeper stopped backfilling"],"status":"active","updated":"2026-08-22T19:02:12.568Z","edits":6,"anchors":[{"path":"src/index-manager.ts","symbols":["IndexManager","refreshKbNotesIndex","regenerateKbViewIfPresent","handleNotebookRawBatch","handleBatch","triggerRebuild","scheduleCacheSave","auditFingerprints","startCacheWatcher","startWatching","scheduleRebuildRetry","IndexContext","autoMechanicalSymbolRepair","MAX_AUTO_REPAIR_STREAK","refreshCoChange"],"hash":"sha256:cb324edbaeb8","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"Keeper state machine: watch, patch-vs-rebuild, atomic cache save, plus the notebook sidecar refresh and (2026-08-23) the co-change sidecar refresh. autoMechanicalSymbolRepair fires right after every kb-notes-index rebuild and passes the just-built sidecar in memory; its MAX_AUTO_REPAIR_STREAK=3 guard is one-way — once the streak reaches the cap the method returns before running, so the pass that would reset it never happens and auto-backfill stays off for the keeper's lifetime (safe direction, now logged once naming `coldstart kb repair`). refreshCoChange is deliberately keyed on git HEAD rather than on the debounced file batch: history only changes when a commit lands, so re-walking on every patch would burn ~600ms for a byte-identical result. It is called from startWatching (seed) and from inside scheduleCacheSave's getGitHead().then, which is the one place the keeper already knows HEAD moved.","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu"]},{"id":"src-indexer-invariants-ts-7c3ad34a","type":"file","character":"single","title":"src/indexer/invariants.ts","aliases":["invariant lint","index corruption check","lintIndexInvariants","rebuild trigger","constant rebuilds","index keeps rebuilding"],"status":"active","updated":"2026-08-22T17:11:07.187Z","edits":1,"anchors":[{"path":"src/indexer/invariants.ts","symbols":["lintIndexInvariants","assertedFile"],"hash":"sha256:f1ad4a72cd14","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Post-patch structural lint whose output is a rebuild trigger, not a warning — so any check it fails must be fixable by rebuilding, or the keeper loops. assertedFile encodes that trade-off explicitly: bare extends/implements targets are exempt from the file-existence check because flagging them would make every repo with inheritance rebuild forever, and the same reasoning applies to any new edge kind whose endpoints are not guaranteed to be indexed files.","backlinks":[],"anchorLinks":["how-synthetic-edges-stay-alive-across-incremental-patches"]},{"id":"src-indexer-patch-ts-d18fe20b","type":"file","character":"single","title":"src/indexer/patch.ts","aliases":["incremental patch","patchIndex","index patching","changed file batch","stale edges after edit","synthetic edges missing after patch"],"status":"active","updated":"2026-08-22T17:11:07.177Z","edits":1,"anchors":[{"path":"src/indexer/patch.ts","symbols":["patchIndex"],"hash":"sha256:c7955d82d0b1","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Incremental index patcher: pre-plans delete/update/skip for the whole batch before mutating anything, so a parse failure never strips a file's existing state. Its synthetic-edge re-derivation at the end is language-gated — each family only re-runs when a file of its language changed — which is what keeps derived edges alive across edits and also what would silently skip a family driven by a non-source input.","backlinks":[],"anchorLinks":["how-synthetic-edges-stay-alive-across-incremental-patches"]},{"id":"how-synthetic-edges-stay-alive-across-incremental-patches","type":"flow","character":null,"title":"how synthetic edges stay alive across incremental patches","aliases":["synthetic edges","rails synthetic edges","edge re-derivation","patch symbol edges","changedLangs gate","edges disappear after edit","endless rebuild loop","edge points at deleted file"],"status":"active","updated":"2026-08-22T17:11:07.149Z","edits":1,"anchors":[{"path":"src/indexer/patch.ts","hash":"sha256:c7955d82d0b1","state":"fresh"},{"path":"src/indexer/invariants.ts","hash":"sha256:f1ad4a72cd14","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Synthetic edges are never stored in the index — they are re-derived from scratch on every build AND every incremental patch, which is the only reason they survive an edit at all, because patchIndex replaces a changed file's symbolEdges wholesale and strips both directions of its flat edges on delete. The re-derivation inside patch is gated on the CHANGED FILE'S LANGUAGE (changedLangs.has('ruby') etc.), so any future synthetic-edge family whose input is not a source file of that language — e.g. one derived from the notebook — would never be refreshed by an ordinary code edit and needs its own trigger. A synthetic edge whose endpoint file no longer exists is not merely ignored: lintIndexInvariants check 3 reports it and the keeper queues a full rebuild, and since a rebuild re-runs the same derivation, a derivation that keeps emitting a dead endpoint rebuilds forever. Derivations must therefore filter endpoints against index.files themselves.\n\n## Steps\n\n1. `src/indexer/patch.ts` (`patchIndex`) — replaces a changed file's symbol edges wholesale, then re-runs each synthetic-edge family gated on the changed languages\n2. `src/indexer/invariants.ts` (`lintIndexInvariants`, `assertedFile`) — flags any symbol edge whose asserted file side is absent from index.files; a violation makes the keeper rebuild\n\n## Invariants\n\n- Synthetic edges are a derivation, never persisted data — anything written into the index by hand is wiped on the next patch of that file.\n- Every synthetic-edge derivation must drop endpoints not present in index.files, or invariant check 3 turns into a rebuild loop.\n- assertedFile deliberately exempts bare extends/implements targets from the existence check; only refs carrying a '#' (and the exports edge's from-side) assert a file.","backlinks":[],"anchorLinks":["src-indexer-invariants-ts-7c3ad34a","src-indexer-patch-ts-d18fe20b"]},{"id":"src-kb-lookup-ts-772ecb1e","type":"file","character":"single","title":"src/kb/lookup.ts","aliases":["notebook query","kb lookup","flow step resolution","flow anchoring","flow-note bridging","anchor derivation"],"status":"active","updated":"2026-08-18T13:32:29.093Z","edits":1,"anchors":[{"path":"src/kb/lookup.ts","symbols":["kbLookup","LookupFlowHit"],"hash":"sha256:e38615ce2a2b","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"Query interface for the notebook at a specific file-or-symbol address. The `kbLookup` function returns everything anchored there: file notes (facets, features, character), flow notes with their step positions, and lessons—all with live freshness stamps. Flow note anchors are derived at query time from flow steps, so backlinks never go stale. Flow notes bridge files the code graph cannot connect (same tmpdir, hand-typed names, convention-only links), operationalizing the design rule that notebook is the source of truth for runtime/data/convention-only edges.","backlinks":[],"anchorLinks":[]},{"id":"how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","type":"flow","character":null,"title":"how to wire a new query command to both CLI and MCP surfaces","aliases":["add query command","CLI MCP wiring","dual-surface query pattern"],"status":"active","updated":"2026-08-18T13:26:14.581Z","edits":1,"anchors":[{"path":"src/cli.ts","hash":"sha256:98bdb7bfb4d0","state":"changed"},{"path":"src/server/tools.ts","hash":"sha256:5a3326747281","state":"changed"},{"path":"src/server/find.ts","hash":"sha256:ec1c7ebf22d1","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:f8995189f3a1","state":"changed"},{"path":"src/index.ts","hash":"sha256:d4b06f304d61","state":"changed"}],"freshness":"changed","dir":"src","outLinks":[],"body":"To add a new query command (e.g., `trace`), implement a shared engine returning {__rawText} that both CLI and MCP call through thin wrappers. The pattern: CLI registration in main() → parse args → load cache → call shared engine → emit __rawText; MCP registration in TOOL_DEFINITIONS + CallToolRequestSchema → parse params → call shared engine → wrap __rawText in MCP response. This ensures identical results on both surfaces from one implementation.\n\n## Steps\n\n1. `src/cli.ts` (`runFind`, `runGs`, `getIndex`) — CLI wrapper: parseQueryArgs, load cache, call shared engine, print __rawText\n2. `src/server/tools.ts` (`handleFind`, `handleGetStructure`) — MCP adapter: calls shared engines, wraps __rawText in response object\n3. `src/server/find.ts` (`buildRichPage`) — shared engine (find): business logic, returns __rawText\n4. `src/server/mcp.ts` (`TOOL_DEFINITIONS`, `registerToolHandlers`) — MCP registration: tool schema definition and CallToolRequestSchema case handler\n5. `src/index.ts` (`main`, `makeCacheReader`) — entry dispatch: subcommand check for CLI, cache reader factory for MCP\n\n## Invariants\n\n- Every query command's shared engine returns {__rawText: string} with optional {error: string}\n- CLI: emit __rawText directly to stdout; MCP: wrap unchanged in content[0].text\n- Cache loading: getIndex (CLI, per-query) vs makeCacheReader (MCP, long-lived with mtime polling)","backlinks":[],"anchorLinks":["how-the-moves-together-signal-reaches-gs-without-going-throu","how-a-hung-index-build-names-the-file-that-hung-it","src-cli-ts-c443bc51","src-index-ts-c5fb8502","src-server-find-ts-d168bf57","src-server-mcp-ts-18031783","src-server-tools-ts-cb60011b","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-server-find-ts-d168bf57","type":"file","character":"hub","title":"src/server/find.ts","aliases":["why does find not show my note","note exists but find did not surface it","buildNoteMap path keyed","find notebook lane","ranking algorithm","term scoring"],"status":"active","updated":"2026-08-18T13:25:59.595Z","edits":4,"anchors":[{"path":"src/server/find.ts","symbols":["buildNoteMap","noteLine","buildRichPage","convergencePreview","collectCoverage","firstSentence","parseTerms","pickSearcher","computeImportRelations","docFreq"],"hash":"sha256:ec1c7ebf22d1","state":"changed"}],"freshness":"changed","dir":"src/server","outLinks":[],"body":"find's notebook lane is PATH-KEYED, not query-keyed: buildNoteMap() iterates active notes and maps anchor path -> note, so a note can only ever surface if its anchor file ALREADY ranked in find's code-side results. The query terms are used solely to break ties on hub files that anchor several notes (the `hits` count on the note's title+aliases+facet symbols), never to admit a note. Consequence verified 2026-07-28: a note whose file find does not rank is invisible to find no matter how strongly the note matches -- measured on 16 relevant hook injections, 7 (44%) anchored to a file find did NOT rank on the same terms (e.g. prompt words 'images beyond text maybe increase' -> site/docs.css, which contains no matching code token). The prompt-time recall hook, not find, is what reaches those. noteLine() renders the inline 'Summary:' at the read-decision point deliberately (ruling recorded at find.ts:457) -- do not hoist notes into a header block.\n\n## Facets\n\n- **buildNoteMap** — PATH-KEYED: iterates active notes and maps anchor path -> note. A note can only surface if its anchor file ALREADY ranked in find's code-side results. Query terms used only to break ties on hub files (hits count on title+aliases+facet symbols), never to admit a note. Consequence: a file find does not rank is invisible to find no matter how strongly the note matches.\n- **buildRichPage** — Lines 553–932: Main entry point. Calls collectCoverage() for term matching (body+name+path), then score() to rank candidates. score() (lines 588–603) = (term_coverage_set.size × 3) + (separator-folded name/path match weight / maxIdf). Ranking: idf (BM25-style log rarity) weights symbol name matches (NAME_W=3) and path matches (PATH_W=2). Re-rankable for frontier traversal via idf(), docFreq(), term coverage sets, separator-folded matching (foldSep strips -_).\n- **collectCoverage** — Lines 260–321: Returns Map<fileId, Set<queryTerms>>. External searchers (rg/git grep/grep) for body-content matches (lines 271–292) + symbol name/path index matches (lines 304–319). Node fallback reads indexed files.\n- **convergencePreview** — Lines 379–456: Scores matched lines by rarity-weighted LOCAL CONVERGENCE—sum of 1/DF over distinct query terms within ±WINDOW lines. Import lines boosted (1.5×). Clusters kept hits by proximity, ranked by peak score. Returns line-level evidence for file preview.","backlinks":[],"anchorLinks":["how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces"]},{"id":"src-indexer-symbol-edges-ts-907b1d63","type":"file","character":"single","title":"src/indexer/symbol-edges.ts","aliases":["edge building","call resolution","symbol edge creation","bare-name edges dropped"],"status":"active","updated":"2026-08-18T13:25:59.561Z","edits":1,"anchors":[{"path":"src/indexer/symbol-edges.ts","symbols":["buildSymbolEdges"],"hash":"sha256:8c0cbcb23ac3","state":"fresh"}],"freshness":"fresh","dir":"src/indexer","outLinks":[],"body":"Builds symbol-level edges (calls/extends/implements/exports) by resolving call targets against imported files' exports. Critical: unresolvable bare-name 'calls' edges are dropped as noise (line 100–102) because query-time lookups use qualified symbolIds and bare names never match. Call resolution: Pass 1 tests direct export match; Pass 2 tests suffix match (Java 'Class.method', Ruby 'Module::Class') across qualified exports. Extends/implements bare names are kept (resolved at query time).","backlinks":[],"anchorLinks":[]},{"id":"src-types-ts-cdcae080","type":"file","character":"single","title":"src/types.ts","aliases":["edge types","SymbolEdge interface","IndexedFile structure","edge model"],"status":"active","updated":"2026-08-18T13:25:59.526Z","edits":1,"anchors":[{"path":"src/types.ts","symbols":["SymbolEdgeType","SymbolEdge","IndexedFile","CodebaseIndex"],"hash":"sha256:ad5ba9213feb","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Defines the edge types, SymbolEdge/Edge interfaces, and IndexedFile structure that all traversal and indexing logic builds on. SymbolEdge carries from/to (qualified symbolId or fileId), type (calls/extends/implements/exports), and optional line number. IndexedFile holds symbols, exports, isBarrel flag, reexportRatio, and importedByCount—these are load-bearing for cycle guards and barrier detection in graph traversal.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-pages-docs-under-the-hood-astro-9d2b1520","type":"file","character":"single","title":"site-astro/src/pages/docs/under-the-hood.astro","aliases":["under the hood docs page","supported languages section","lifecycle commands docs"],"status":"active","updated":"2026-08-16T16:51:41.613Z","edits":2,"anchors":[{"path":"site-astro/src/pages/docs/under-the-hood.astro","symbols":["#freshness","#lifecycle","#mcp","#languages"],"hash":"sha256:7eeb7e9309f7","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/docs","outLinks":[],"body":"One of the 4 docs sub-pages: covers index freshness (with the inline architecture SVG), lifecycle commands, MCP tool exposure, bring-your-own-semantics, and supported languages. The language chips (.langs/.chip) previously had a .chip.hot tier arbitrarily coloring some languages blue with no explanation — removed so all chips render uniformly. Its closing sidebar-highlight script is one of 4 duplicated copies, now scroll-position-based rather than IntersectionObserver-based (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-src-pages-docs-navigation-astro-e37c5fa9","type":"file","character":"single","title":"site-astro/src/pages/docs/navigation.astro","aliases":["docs navigation","find command reference","gs command reference","docs sub-page"],"status":"active","updated":"2026-08-16T16:51:41.602Z","edits":3,"anchors":[{"path":"site-astro/src/pages/docs/navigation.astro","symbols":["techArticleJsonLd"],"hash":"sha256:76baa0869608","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/docs","outLinks":[],"body":"Docs sub-page for coldstart find and gs commands. Follows docs.astro template: frontmatter imports (Head, SvgDefs, Nav, Footer, DocsSidebar), TechArticle JSON-LD, two doc sections (#find and #gs) with command signature, terminal examples, flags, and callouts. DocsSidebar uses active=\"navigation\". Its closing sidebar-highlight script is one of 4 duplicated copies, now scroll-position-based rather than IntersectionObserver-based (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-src-pages-docs-notebook-astro-474cc129","type":"file","character":"single","title":"site-astro/src/pages/docs/notebook.astro","aliases":["notebook docs","kb reference","docs sub-page template"],"status":"active","updated":"2026-08-16T16:51:41.586Z","edits":3,"anchors":[{"path":"site-astro/src/pages/docs/notebook.astro","symbols":["techArticleJsonLd"],"hash":"sha256:b28346763f30","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/docs","outLinks":[],"body":"Notebook reference page. Section ids (notebook, kb-search, kb-lookup, kb-write, kb-commit, kb-view, kb-maint, sharing) are linked by DocsSidebar and must be preserved. Trimmed this session: the 'why it can be trusted' bullet list, capture-internals detail (worklist lifecycle, per-agent keying), and a marketing callout were cut or condensed — that rationale now lives only at /how-it-works/notebook/, linked from this page instead of duplicated inline. The closing sidebar-highlight script is a scroll-position check, not IntersectionObserver — it's copied verbatim into 3 other docs pages (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script"]},{"id":"site-astro-src-pages-docs-astro-d1cf6fe9","type":"file","character":"single","title":"site-astro/src/pages/docs.astro","aliases":["docs page","structured data","brand terminology binding","docs landing page"],"status":"active","updated":"2026-08-16T16:51:41.575Z","edits":5,"anchors":[{"path":"site-astro/src/pages/docs.astro","symbols":["techArticleJsonLd","doc-sec#notebook","doc-sec#freshness","overview","install","flow","next"],"hash":"sha256:9faa0af4d67d","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"Docs landing page — sidebar reference layout on docs.css, with its own TechArticle JSON-LD and its own Google Fonts <link> block (not centralised in Head.astro). Sections are #overview, #install, #flow, #next; #next's fcards link out to the 3 docs sub-pages (navigation, notebook, under-the-hood) — there is no #notebook or #freshness section on this page itself, that content lives in the sub-pages now. Inline links in docs prose are styled per-link with style=\"color:var(--frost)\" — there is no link class in docs.css. Its closing sidebar-highlight script is one of 4 duplicated copies (see flow: docs pages share a hand-duplicated sidebar scrollspy script, not an import).","backlinks":[],"anchorLinks":["docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","type":"flow","character":null,"title":"docs pages share a hand-duplicated sidebar scrollspy script, not an import","aliases":["docs sidebar scrollspy script","sidebar active section highlight","duplicated docs script","docs sidebar highlight mechanism","last sidebar item never highlighted","sidebar highlight stuck wrong item","docs sidebar highlight bug"],"status":"active","updated":"2026-08-16T16:51:41.501Z","edits":1,"anchors":[{"path":"site-astro/src/pages/docs.astro","hash":"sha256:9faa0af4d67d","state":"changed"},{"path":"site-astro/src/pages/docs/navigation.astro","hash":"sha256:76baa0869608","state":"changed"},{"path":"site-astro/src/pages/docs/notebook.astro","hash":"sha256:b28346763f30","state":"changed"},{"path":"site-astro/src/pages/docs/under-the-hood.astro","hash":"sha256:7eeb7e9309f7","state":"fresh"}],"freshness":"changed","dir":"site-astro/src/pages","outLinks":[],"body":"The sidebar active-section highlight script on the 4 docs pages (docs.astro, docs/navigation.astro, docs/notebook.astro, docs/under-the-hood.astro) is copy-pasted verbatim into each page's own closing <script> block, not extracted into a shared component or module — so any behavior change or bug fix has to be hand-applied to all 4 files identically. Verified this session while fixing a bug where the previous IntersectionObserver version (rootMargin '-70px 0px -70% 0px', i.e. a trigger band covering only the top ~30% of the viewport) never highlighted the LAST section's sidebar link on normal/large screens: a short last section's heading could stop being scrolled toward (footer below it, or the user simply stopping once it's comfortably in view) before its top ever crossed into that narrow band. Replaced the mechanism in all 4 files with a scroll/resize-driven position check that walks sections top-to-bottom and marks active the last one whose top has crossed a fixed offset line (70px + 30% of viewport height) — same visual trigger point as before, but not dependent on an element re-entering a band, so the last section reliably activates once scrolled to, regardless of footer height or viewport size.\n\n## Steps\n\n1. `site-astro/src/pages/docs.astro` (`setActive`) — one of 4 duplicate copies of the scrollspy script\n2. `site-astro/src/pages/docs/navigation.astro` (`setActive`) — duplicate copy\n3. `site-astro/src/pages/docs/notebook.astro` (`setActive`) — duplicate copy\n4. `site-astro/src/pages/docs/under-the-hood.astro` (`setActive`) — duplicate copy\n\n## Invariants\n\n- The script is not shared via import or component — changing scrollspy behavior means editing all 4 files identically, or a future page will silently regress.\n- The offset (70px + 30% of viewport height) intentionally mirrors the old IntersectionObserver's visual crossing point, so the highlight timing feels unchanged even though the mechanism is now scroll-position-based, not intersection-based.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand","site-astro-src-pages-docs-astro-d1cf6fe9","site-astro-src-pages-docs-navigation-astro-e37c5fa9","site-astro-src-pages-docs-notebook-astro-474cc129","site-astro-src-pages-docs-under-the-hood-astro-9d2b1520"]},{"id":"scripts-win-repro-detachedlauncher-cs-2d8b5bf1","type":"file","character":"single","title":"scripts/win-repro/DetachedLauncher.cs","aliases":["DETACHED_PROCESS launcher","Win32 CreateProcess repro","hooks-shape console repro","hooks flash confirmed fixed","DETACHED_PROCESS resolves inconclusive repro"],"status":"active","updated":"2026-08-11T05:36:34.763Z","edits":1,"anchors":[{"path":"scripts/win-repro/DetachedLauncher.cs","symbols":["Main"],"hash":"sha256:e65597a5876f","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Replaces an earlier launcher (NoConsoleLauncher.cs, deleted) that used .NET's ProcessStartInfo.CreateNoWindow and produced an inconclusive A/B (no flash in either branch, since CreateNoWindow leaves a hidden-but-attached console that a grandchild process just reuses). This launcher calls Win32 CreateProcess directly with the real DETACHED_PROCESS flag (0x00000008), giving the launched node.exe genuinely no console object at all — the actual condition an Electron app's (Claude Code/Cursor) hooks/*.mjs child process runs under. Verified on real Windows 11 hardware: unpatched shows a new console window, patched shows nothing, confirmed by both the automated IsWindowVisible poll and direct visual observation.","backlinks":[],"anchorLinks":[]},{"id":"scripts-win-repro-watch-ps1-7c70124a","type":"file","character":"single","title":"scripts/win-repro/watch.ps1","aliases":["windowsHide repro driver","IsWindowVisible watcher","Run-Case"],"status":"active","updated":"2026-08-11T05:36:34.734Z","edits":3,"anchors":[{"path":"scripts/win-repro/watch.ps1","symbols":["Run-Case"],"hash":"sha256:f5632bae5e65","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"PowerShell driver for the #149 A/B repro flow: compiles DetachedLauncher.cs via csc.exe, then Run-Case runs 4 cases (unpatched/patched daemon-shape via orchestrator.mjs, unpatched/patched hooks-shape by launching DetachedLauncher.exe directly) and polls the real Win32 IsWindowVisible API. Both pairs now produce a confirmed flash/no-flash split — the earlier winexe+CreateNoWindow launcher (NoConsoleLauncher.cs/orchestrator-noconsole.mjs, both since deleted) gave an inconclusive result and was replaced by DetachedLauncher.cs, which uses the real Win32 DETACHED_PROCESS flag instead. See the flow note for the full root-cause story.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"github-workflows-verify-149-windows-hide-yml-9fbe00a7","type":"file","character":"single","title":".github/workflows/verify-149-windows-hide.yml","aliases":["#149 verification workflow","windows-latest repro job"],"status":"active","updated":"2026-08-11T05:36:34.722Z","edits":3,"anchors":[{"path":".github/workflows/verify-149-windows-hide.yml","hash":"sha256:50753c85a820","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"Windows-latest CI workflow driving the #149 windowsHide A/B repro (see flow note), shipped in PR #151 (merged into main). workflow_dispatch-only — a branch-scoped push trigger was used temporarily to iterate before this was on the default branch, and was removed once the PR was ready. Now carries an explicit `permissions: contents: read` block, added to resolve a CodeQL 'missing-workflow-permissions' finding raised on the PR (the job only checks out code and runs a local script, so read-only contents access is sufficient).","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"how-the-149-windowshide-a-b-repro-verifies-windows-console-f","type":"flow","character":null,"title":"how the #149 windowsHide A/B repro verifies Windows console-flash on CI and real hardware","aliases":["windowsHide repro","windows-latest A/B test","console flash verification","how the #149 windowsHide A/B repro verifies Windows console-flash on CI","DETACHED_PROCESS launcher","hooks flash confirmed fixed","CreateNoWindow false negative","DETACHED_PROCESS resolves inconclusive repro"],"status":"active","updated":"2026-08-11T05:36:34.697Z","edits":3,"anchors":[{"path":".github/workflows/verify-149-windows-hide.yml","hash":"sha256:50753c85a820","state":"fresh"},{"path":"scripts/win-repro/orchestrator.mjs","hash":"sha256:af1639e9fed1","state":"fresh"},{"path":"scripts/win-repro/harness.mjs","hash":"sha256:1186af440d49","state":"fresh"},{"path":"scripts/win-repro/watch.ps1","hash":"sha256:f5632bae5e65","state":"fresh"},{"path":"scripts/win-repro/orchestrator-noconsole.mjs","hash":"sha256:43cbb5390ab5","state":"missing"},{"path":"scripts/win-repro/NoConsoleLauncher.cs","hash":"sha256:c8b642b5d6de","state":"missing"}],"freshness":"missing","dir":".github/workflows","outLinks":[],"body":"A windows-latest CI workflow (workflow_dispatch-only, now with an explicit `permissions: contents: read` block) empirically confirms whether a child_process option shape flashes a visible console window by polling the real Win32 IsWindowVisible API, and this now works for BOTH shapes coldstart needed to prove: the daemon/CLI shape (Node's own detached:true spawn, matching keeper.js's self-relaunch) AND the hooks/*.mjs shape (a plain child of a console-less Electron host like Claude Code/Cursor). The hooks shape required two failed attempts before landing: a GUI-subsystem (winexe) launcher using .NET's ProcessStartInfo.CreateNoWindow gave the intermediate node.exe a HIDDEN-but-still-attached console rather than none, so its own child (ping.exe) just reused that hidden console regardless of windowsHide — an inconclusive A/B (no flash in either branch). The fix was DetachedLauncher.cs, which calls Win32 CreateProcess directly with the real DETACHED_PROCESS flag (0x8), giving the child genuinely no console object. Under that condition the split is exactly as expected: unpatched flashes, patched doesn't. Confirmed both by the automated IsWindowVisible poll and direct human visual observation on real Windows 11 hardware — this closes the 'hooks shape not independently proven' gap and the fix shipped as part of PR #151 (merged).\n\n## Steps\n\n1. `.github/workflows/verify-149-windows-hide.yml` — windows-latest job entry point; workflow_dispatch-only, now scoped to `permissions: contents: read` (added to address a CodeQL missing-workflow-permissions finding on PR #151)\n2. `scripts/win-repro/orchestrator.mjs` — spawns harness.mjs via Node's detached:true+stdio:'ignore' spawn, mirroring keeper.js's own self-relaunch shape — proven mechanism for the daemon-shape A/B\n3. `scripts/win-repro/harness.mjs` — runs execFileSync with the option shape under test, with or without windowsHide\n4. `scripts/win-repro/DetachedLauncher.cs` (`Main`) — replaces the earlier CreateNoWindow-based launcher; calls Win32 CreateProcess directly with DETACHED_PROCESS so the launched node.exe has genuinely no console object — the actual condition hooks/*.mjs runs under when spawned by a console-less GUI host. This is what finally produced a clean, confirmed flash/no-flash split for the hooks shape\n5. `scripts/win-repro/watch.ps1` (`Run-Case`) — compiles DetachedLauncher.cs via csc.exe, then polls Win32 IsWindowVisible before/after each of the 4 cases (2 daemon-shape via orchestrator.mjs + 2 hooks-shape via DetachedLauncher.exe directly)\n\n## Invariants\n\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction, confirmed via a live 404) — a temp verification workflow scoped to a feature branch must use `on: push: branches: [<branch>]` instead\n- the cleanup step between A/B cases must never Stop-Process match conhost/WindowsTerminal/OpenConsole broadly — those can back the runner's own pwsh session; killing them crashed the very next `node` invocation with a console-pipe error. Only kill the actual test straggler (e.g. ping.exe) by name\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction, confirmed via a live 404) — iterate with a branch-scoped push trigger pre-merge, then drop it once merged\n- a console-flash A/B test only proves something when the code under test is the FIRST thing to request a console in the whole ancestor chain — Node's detached:true spawn (used unpatched, held constant across the A/B pair) satisfies this for the daemon shape, but layering ANY additional console-suppression (CreateNoWindow=true on an intermediate hop, or just launching through an already-console-having process like pwsh) gives that intermediate process a console — hidden or inherited — which then absorbs any downstream child's console need regardless of that child's own windowsHide setting, making the A/B pair indistinguishable\n- workflow_dispatch only lets you trigger workflows already present on the default branch (GitHub platform restriction) — iterate with a branch-scoped push trigger pre-merge, then drop it once merged\n- a console-flash A/B test only proves something when the code under test is the FIRST thing to request a console in the whole ancestor chain — CreateNoWindow (.NET ProcessStartInfo) suppresses the WINDOW but still leaves a hidden console object attached, which downstream children silently reuse; only the raw Win32 DETACHED_PROCESS flag via CreateProcess gives a child genuinely zero console, which is the condition that makes the A/B pair distinguishable\n- run watch.ps1 with pwsh (PowerShell 7+), not Windows PowerShell 5.1 — the file is UTF-8 without a BOM (em-dashes in comments), and powershell.exe reads no-BOM files using the system codepage, mangling those bytes and breaking parsing","backlinks":[],"anchorLinks":["github-workflows-verify-149-windows-hide-yml-9fbe00a7","scripts-win-repro-harness-mjs-c2b8facb","scripts-win-repro-orchestrator-mjs-599e3c8d","scripts-win-repro-watch-ps1-7c70124a"]},{"id":"hooks-elicit-core-mjs-f3f159c1","type":"file","character":"single","title":"hooks/elicit-core.mjs","aliases":["shared elicit helpers","pending file handoff","worklist annotations","fail open annotation"],"status":"active","updated":"2026-08-11T04:28:44.606Z","edits":5,"anchors":[{"path":"hooks/elicit-core.mjs","symbols":["worklistEntries","noteAnnotations","consumerCounts","freshNotedSet","gitHead","logCaptureEvent","writePendingCapture","takePendingCapture","pendingPath","MAX_WORKLIST"],"hash":"sha256:cdd69e058357","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Host-neutral v5 capture helpers shared by all three elicit hooks AND the recall hooks: worklist annotation (kb status --json --paths + coldstart consumers --json, both fail-open to no-annotation), fresh-noted discount set, git-HEAD fingerprint, capture metrics (capture.jsonl), and the pending-capture handoff (writePendingCapture/takePendingCapture, one file per session id, 24h TTL). Consumed via relative import from sibling hook files — invisible to the TS import graph, which is why consumers reports zero for it. Re-read in full this session (unrelated task) and confirmed still accurate — re-stamping freshness only, no content change.","backlinks":[],"anchorLinks":[]},{"id":"claude-commands-capture-notes-md-3f9e019a","type":"file","character":"single","title":".claude/commands/capture-notes.md","aliases":["capture notes command","manual capture invocation"],"status":"active","updated":"2026-08-11T04:28:44.595Z","edits":1,"anchors":[{"path":".claude/commands/capture-notes.md","hash":"sha256:c2dbcaf67055","state":"changed"}],"freshness":"changed","dir":".claude/commands","outLinks":[],"body":"The /capture-notes command: its `!`-prefixed bash line passes ${CLAUDE_SESSION_ID} to kb-elicit.mjs --manual --session, which is the proof (used this session while building an unrelated plugin) that Claude Code substitutes a command's own session id into its bash execution body even though this isn't documented for slash commands generally — see the '${CLAUDE_SESSION_ID}' flow note.","backlinks":[],"anchorLinks":["how-commands-get-their-own-session-id-claude-session-id"]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-63c61af9","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/README.md","aliases":["plugin design caveats","clear boundary limitation","token tracker readme"],"status":"active","updated":"2026-08-11T04:28:44.584Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/README.md","hash":"sha256:dc6277333e9e","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker","outLinks":[],"body":"Documents the token-consumption-tracker plugin prototype's open caveats, verified this session by grepping real ~/.claude/projects/*.jsonl transcripts directly: /clear leaves no queryable trace inside the transcript JSONL (no SessionStart/clear record is ever written to the file, even though a SessionStart hook fires with source=\"clear\") even though it also confirmed /clear does not start a new transcript file — so v1 sums the whole session file rather than tracking a clear boundary, deferring a hook-based precision fix.","backlinks":[],"anchorLinks":[]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-72bc87ba","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","aliases":["token consumption command","slash command plugin"],"status":"active","updated":"2026-08-11T04:28:44.573Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","hash":"sha256:3c855346ac97","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands","outLinks":[],"body":"The /token-consumption slash command for the token-consumption-tracker plugin prototype. Its `!`-prefixed bash execution invokes scripts/usage.mjs with ${CLAUDE_SESSION_ID} and $(pwd) — see the '${CLAUDE_SESSION_ID}' flow note for why that substitution works despite not being documented for slash commands.","backlinks":[],"anchorLinks":["how-commands-get-their-own-session-id-claude-session-id"]},{"id":"claude-worktrees-token-consumption-tracker-token-consumption-4bc9d206","type":"file","character":"single","title":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts/usage.mjs","aliases":["token usage parser","transcript token counter","cwd path encoding"],"status":"active","updated":"2026-08-11T04:28:44.561Z","edits":1,"anchors":[{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts/usage.mjs","symbols":["encodeCwd","transcriptPathFor","main"],"hash":"sha256:84a8f33b46ed","state":"missing"}],"freshness":"missing","dir":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/scripts","outLinks":[],"body":"New Phase-0/1 spike for a standalone token-consumption-tracker plugin: stream-parses the current session's transcript JSONL (assistant records' message.usage) to sum real token counts, with a turn-level (not call-level) coldstart-attribution pass keyed on tool names starting with mcp__coldstart__. Derives its own transcript path deterministically — cwd-encoded (each \"/\" and \".\" replaced with \"-\", confirmed against a real ~/.claude/projects dir name) plus an exact session id passed in by the caller, never a \"most recently modified file\" guess. Validated this session: output matched a manual jq sum over this session's own live transcript exactly.","backlinks":[],"anchorLinks":[]},{"id":"how-commands-get-their-own-session-id-claude-session-id","type":"flow","character":null,"title":"how commands get their own session id (${CLAUDE_SESSION_ID})","aliases":["CLAUDE_SESSION_ID substitution","session id in commands","command bash execution"],"status":"active","updated":"2026-08-11T04:28:44.521Z","edits":1,"anchors":[{"path":".claude/commands/capture-notes.md","hash":"sha256:c2dbcaf67055","state":"changed"},{"path":".claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md","hash":"sha256:3c855346ac97","state":"missing"}],"freshness":"missing","dir":".claude/commands","outLinks":[],"body":"Claude Code substitutes ${CLAUDE_SESSION_ID} into a command markdown file's `!`-prefixed bash execution body, giving a slash command its own session id even though the official docs say hook-style stdin fields (session_id, transcript_path) are documented as available to hooks only, not slash commands — this repo has two independent, working proofs of the substitution.\n\n## Steps\n\n1. `.claude/commands/capture-notes.md` — first proof: passes ${CLAUDE_SESSION_ID} to kb-elicit.mjs --manual --session\n2. `.claude/worktrees/token-consumption-tracker/token-consumption-tracker/commands/token-consumption.md` — second independent proof: passes ${CLAUDE_SESSION_ID} to scripts/usage.mjs --session\n\n## Invariants\n\n- Not documented for slash commands by the official Claude Code docs (checked hooks.md) — only confirmed empirically via these two files' working behavior.\n- A companion gap: there is no equivalent substitution for a command's own transcript_path — it must be derived (cwd-encoding + session id), not read directly.","backlinks":[],"anchorLinks":["claude-commands-capture-notes-md-3f9e019a","claude-worktrees-token-consumption-tracker-token-consumption-72bc87ba"]},{"id":"scripts-win-repro-orchestrator-mjs-599e3c8d","type":"file","character":"single","title":"scripts/win-repro/orchestrator.mjs","aliases":["keeper spawn shape mirror"],"status":"active","updated":"2026-08-11T03:47:24.257Z","edits":2,"anchors":[{"path":"scripts/win-repro/orchestrator.mjs","symbols":["mode","dir","harness","child"],"hash":"sha256:af1639e9fed1","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Spawns harness.mjs detached with stdio:'ignore' and no windowsHide of its own, deliberately reproducing keeper.js's own self-relaunch shape so the repro tests child processes under the same no-console condition the real daemon runs under.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"scripts-win-repro-harness-mjs-c2b8facb","type":"file","character":"single","title":"scripts/win-repro/harness.mjs","aliases":["windowsHide option-shape harness"],"status":"active","updated":"2026-08-11T03:47:24.247Z","edits":2,"anchors":[{"path":"scripts/win-repro/harness.mjs","symbols":["mode","baseOpts","opts"],"hash":"sha256:1186af440d49","state":"fresh"}],"freshness":"fresh","dir":"scripts/win-repro","outLinks":[],"body":"Runs a single execFileSync call whose option shape matches either the unpatched src/indexer/git.ts call sites or the seven #149-patched sites, selected by a CLI arg ('windowsHide' | 'no-windowsHide'); swaps `ping` in for `git`/`rg` purely so the visibility poll in watch.ps1 has runtime to observe.","backlinks":[],"anchorLinks":["how-the-149-windowshide-a-b-repro-verifies-windows-console-f"]},{"id":"src-indexer-git-ts-398eed6c","type":"file","character":"single","title":"src/indexer/git.ts","aliases":["getGitHead","getGitChangedFiles","getGitExactRenames","getGitNewFiles","getGitDirtyFiles","windowsHide missing git.ts","console flash on reconcile","#149 unpatched gap"],"status":"active","updated":"2026-08-11T03:47:23.747Z","edits":1,"anchors":[{"path":"src/indexer/git.ts","symbols":["getGitHead","getGitChangedFiles","getGitExactRenames","getGitNewFiles","getGitDirtyFiles"],"hash":"sha256:7feccf2f2bb6","state":"changed"}],"freshness":"changed","dir":"src/indexer","outLinks":[],"body":"Four execFileAsync('git', ...) calls (getGitHead, getGitChangedFiles, getGitExactRenames, getGitNewFiles/getGitDirtyFiles) that omit windowsHide — confirmed via a real windows-latest CI repro (see the #149 flow note in scripts/win-repro/) that this exact option shape DOES flash a visible console window on Windows. getGitHead runs on every debounced keeper cache save and the others run on every keeper-start reconcile, so this is a live, high-frequency instance of issue #149's bug, left unpatched by the initial 7-site fix. Not yet fixed as of this note.","backlinks":[],"anchorLinks":[]},{"id":"gitignore-a5cc2925","type":"file","character":"single","title":".gitignore","aliases":["repo root gitignore","docs folder ignore pattern","new files missing from git status","untracked files silently excluded","gitignore matching wrong nested directory"],"status":"active","updated":"2026-08-10T18:51:51.993Z","edits":1,"anchors":[{"path":".gitignore","hash":"sha256:6fdc237ac252","state":"changed"}],"freshness":"changed","dir":".","outLinks":[],"body":"Repo-root gitignore. Line 9 was a bare `docs/` pattern intended only for the repo-root internal-docs folder, but an unanchored gitignore pattern matches a directory of that name ANYWHERE in the tree — it was silently excluding `site-astro/src/pages/docs/` from git too, so 3 new page files created there this session never showed up in `git status` and would have been dropped from the PR entirely. Fixed by anchoring it to `/docs/`.","backlinks":[],"anchorLinks":["how-the-site-s-notebook-and-graph-pages-stay-fresh-after-a-p"]},{"id":"site-astro-src-pages-how-it-works-notebook-astro-7be582fd","type":"file","character":"single","title":"site-astro/src/pages/how-it-works/notebook.astro","aliases":["how-it-works notebook page","notebook loop page","ring figure","freshness states page","notebook mock section","kb view recreation","wanted screenshot not image recreation"],"status":"active","updated":"2026-08-10T18:51:51.967Z","edits":2,"anchors":[{"path":"site-astro/src/pages/how-it-works/notebook.astro","symbols":["ring-svg","ring-card","loopGrad","state-grid","how-aside","nb-mock"],"hash":"sha256:ac83d3352f95","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"Concept-level explainer for the notebook loop: a four-station ring figure, then four cards for what happens to a note when its file changes (the [fresh]/[evidence changed]/[moved]/[anchor missing] strings are hand-copied from freshnessLine() in src/kb/freshness.ts and must be mirrored by hand). This session added a screenshot-free section right after the hero (.nb-mock, styled in how.css) — a built recreation of `kb view` showing a real note (src/server/tools.ts) from coldstart's own notebook, grounding the abstract loop explanation before it starts.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-styles-how-css-f5f7fefc","type":"file","character":"single","title":"site-astro/src/styles/how.css","aliases":["how-it-works stylesheet","how.css","ring figure styles","temperature figure styles","how-page scope","notebook mock styles"],"status":"active","updated":"2026-08-10T18:51:51.958Z","edits":2,"anchors":[{"path":"site-astro/src/styles/how.css","symbols":[".how-page .wrap",".how-sec",".how-sec-head",".ring-fig",".ring-card",".temp-fig",".temp-seam",".state-grid",".how-aside","@media (prefers-reduced-motion: reduce)",".nb-mock"],"hash":"sha256:518ebee8e16f","state":"changed"}],"freshness":"changed","dir":"site-astro/src/styles","outLinks":[],"body":"Stylesheet for the /how-it-works/ pages. Defines no design tokens of its own — rides docs.css's tokens/nav chrome, everything scoped under .how-page. Holds the two signature figures (.ring-* notebook loop, .temp-* index split) plus, added this session, .nb-mock — a hand-built HTML/CSS recreation of the notebook's `kb view` UI (top bar, file sidebar, note detail panel) used on the notebook how-it-works page instead of an embedded screenshot; it follows the same ride-on rule, using only --frost/--ember/--surface/--line from docs.css's bare :root.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"new-vs-comparison-pages-are-hand-linked-from-existing-conten","type":"flow","character":null,"title":"new /vs/ comparison pages are hand-linked from existing content, not from Nav","aliases":["vs page linking","comparison page discovery","vector rag page"],"status":"active","updated":"2026-08-10T18:44:42.033Z","edits":1,"anchors":[{"path":"site-astro/src/pages/vs/vector-rag.astro","hash":"sha256:8df78e50986b","state":"fresh"},{"path":"site-astro/src/pages/how-it-works/index.astro","hash":"sha256:19c4fdcc0bca","state":"fresh"},{"path":"site-astro/src/content/blog/why-coldstart-makes-zero-llm-calls.md","hash":"sha256:95f97d6898f5","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/vs","outLinks":[],"body":"A /vs/ page (e.g. vector-rag.astro) has no entry in Nav.astro or Footer.astro — discoverability is entirely from inline links placed in whichever existing pages already discuss the same tradeoff, not from a dedicated nav slot.\n\n## Steps\n\n1. `site-astro/src/pages/vs/vector-rag.astro` — the standalone comparison page itself, reuses how.css/docs.css chrome, no Nav/Footer entry\n2. `site-astro/src/pages/docs/under-the-hood.astro` — links to it from the 'Bring your own semantics' callout, next to the PHILOSOPHY.md link\n3. `site-astro/src/content/blog/why-coldstart-makes-zero-llm-calls.md` — links to it inline, at the sentence conceding RAG's fuzzy-conceptual-query advantage\n4. `site-astro/src/pages/how-it-works/index.astro` — links to it as a second ghost link in the closing CTA row, next to the blog link\n\n## Invariants\n\n- a new /vs/ page needs its own manual link-in placements chosen by content fit — there is no shared nav slot that auto-lists /vs/ pages","backlinks":[],"anchorLinks":[]},{"id":"site-astro-astro-config-mjs-8801ef8e","type":"file","character":"single","title":"site-astro/astro.config.mjs","aliases":["astro config","sitemap integration","coldstartmcp.dev domain","site url config","site canonical url","lastmod serialize hook","sitemap missing lastmod","uniform lastmod dates"],"status":"active","updated":"2026-08-09T17:41:18.452Z","edits":2,"anchors":[{"path":"site-astro/astro.config.mjs","symbols":["defineConfig","historyUsable","sourceFileForRoute","lastCommitDate"],"hash":"sha256:268671d3ade6","state":"fresh"}],"freshness":"fresh","dir":"site-astro","outLinks":[],"body":"Astro site config: sets canonical `site` to https://coldstartmcp.dev (consumed by @astrojs/sitemap for absolute URLs) and registers the @astrojs/sitemap + @astrojs/tailwind integrations. The sitemap is generated at build time from the site's routes — no hand-maintained sitemap file. It now passes a serialize() hook that stamps each URL's <lastmod> from its source file's last git commit date: sourceFileForRoute() maps a route back to src/pages/*.astro (or src/content/blog/<slug>.md for posts), and lastCommitDate() shells out to git log. historyUsable is computed ONCE at module load via `git rev-parse --is-shallow-repository` — this guard exists because git log does not fail in a shallow clone, it returns that clone's single commit date for every file, which would stamp all 16 URLs with the same wrong timestamp.","backlinks":[],"anchorLinks":["how-the-sitemap-gets-its-lastmod-dates"]},{"id":"site-astro-src-pages-how-it-works-navigation-astro-b7403337","type":"file","character":"single","title":"site-astro/src/pages/how-it-works/navigation.astro","aliases":["how-it-works navigation page","temperature figure","index explainer page","find gs explainer"],"status":"active","updated":"2026-08-09T10:05:32.780Z","edits":1,"anchors":[{"path":"site-astro/src/pages/how-it-works/navigation.astro","symbols":["temp-fig","temp-seam","temp-col","zoom","zpan"],"hash":"sha256:fe084da82216","state":"changed"}],"freshness":"changed","dir":"site-astro/src/pages/how-it-works","outLinks":[],"body":"Concept-level explainer for the navigation layer: a two-column 'temperature' figure splitting what the index keeps exact (paths, symbols, imports, calls) from what it leaves to the model, then three panels for the map, find and gs. The seam between the columns is a plain 1px gradient div, not an SVG stroke — a rough-filtered wavy stroke was tried first and read as a stray scratch at this size. Same page shell as its sibling: docs.css + how.css, SvgDefs, Nav/Footer variant 'how'.","backlinks":[],"anchorLinks":["how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs"]},{"id":"site-astro-scripts-generate-og-sh-37447c1d","type":"file","character":"single","title":"site-astro/scripts/generate-og.sh","aliases":["OG card generator","chrome-devtools screenshot","social card regeneration","og.png rebuild","chrome-devtools screenshot script","stale og card copied","screenshot failed silently","wrong fonts in og image"],"status":"active","updated":"2026-08-08T16:57:41.333Z","edits":3,"anchors":[{"path":"site-astro/scripts/generate-og.sh","symbols":["TEMPLATE_FILE","OUTPUT_FILE","TEMP_PNG","VIEWPORT","SCRIPT_DIR","REPO_ROOT"],"hash":"sha256:4eb03fafa437","state":"fresh"}],"freshness":"fresh","dir":"site-astro/scripts","outLinks":[],"body":"Regenerates public/og.png (the 1200x630 social card) from scripts/og.html by driving chrome-devtools-cli. Two environment constraints are the reason this is a script and not a one-liner: chrome-devtools REFUSES to write outside its allowed workspace roots, so the capture goes to a TMPDIR path and is copied into the repo afterwards; and resize_page silently does not apply, so the viewport must be set with 'emulate --viewport'. Rewritten this session after the first version could ship a stale card silently: it combined 'set -e' with '|| true' on every chrome-devtools call and used a FIXED temp path, so a failed capture left the previous run's PNG in place, passed the -f existence guard, and copied an old card into the repo while reporting success — which is also why 'ran it twice, identical output' was not evidence of reproducibility. Now uses a PID-unique temp path removed up-front and on EXIT via trap, no '|| true' swallowing, and hard failure if the viewport is not 1200x630 or the captured PNG is not 1200x630. It also awaits document.fonts.ready, without which the serif headline silently renders in a fallback face.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-public-llms-txt-0a80f88e","type":"file","character":"single","title":"site-astro/public/llms.txt","aliases":["llms.txt","LLM discovery file","agent-readable site summary","answer engine discovery","similarity score contrast lost"],"status":"active","updated":"2026-08-08T16:57:29.336Z","edits":3,"anchors":[{"path":"site-astro/public/llms.txt","hash":"sha256:7b4d30155654","state":"changed"}],"freshness":"changed","dir":"site-astro/public","outLinks":[],"body":"Machine-readable project summary for LLM crawlers/answer-engines, served at coldstartmcp.dev/llms.txt per the llms.txt convention. Its opening blockquote is a governed category slot and now leads 'coldstart is codebase memory for AI coding agents', where it previously led with navigation ('Codebase navigation and a codebase notebook'). When rewriting that line, keep the 'ranked with checkable evidence instead of a similarity score' contrast — it is the sharpest anti-embedding differentiator on the site and an earlier rewrite this session dropped it by accident before it was restored. Body lists core operations, doc links, and agent-facing usage notes; carries no numbers and no comparison language, consistent with the standing no-published-numbers and no-comparison-pages locks.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","type":"flow","character":null,"title":"site-astro coordinates SEO entity binding of 'coldstart' to 'codebase memory' across multiple surfaces","aliases":["coldstart brand positioning","codebase memory branding","SEO entity binding","site messaging consistency","category slot","codebase memory bigram","brand entity binding","memory led navigation second","memory plus navigation pair","generic memory wording"],"status":"active","updated":"2026-08-08T16:57:29.289Z","edits":2,"anchors":[{"path":"site-astro/src/components/Footer.astro","hash":"sha256:9dbf16ed662d","state":"changed"},{"path":"site-astro/src/pages/blog/index.astro","hash":"sha256:ad1a1743e444","state":"fresh"},{"path":"site-astro/public/llms.txt","hash":"sha256:7b4d30155654","state":"changed"},{"path":"site-astro/src/layouts/Head.astro","hash":"sha256:43e48691fd9a","state":"fresh"},{"path":"site-astro/src/pages/index.astro","hash":"sha256:d30a2555c5e0","state":"changed"},{"path":"site-astro/src/pages/docs.astro","hash":"sha256:28ef179f54d6","state":"changed"}],"freshness":"changed","dir":"site-astro/src/components","outLinks":[],"body":"The site distinguishes 'category slots' from body copy, and only category slots are governed: the title tag, hero kicker, footer tagline, llms.txt opening line, og.png kicker, and every meta/og/twitter description must carry the exact bigram 'codebase memory' and nothing may compete with it there. Positioning is memory-led with navigation second, so body copy is still free to describe navigation (the FAQ answer in index.astro says 'navigation and memory layer' and that is deliberate, not a miss). The phrase is applied to roughly six high-value slots ONLY — pushing it everywhere is keyword stuffing, which measurably reduces answer-engine visibility. Verified this session: the bigram was previously absent from every one of these slots because each generic surface pitched 'memory + navigation' as a co-equal pair, which is why npm/GitHub (one-sentence descriptions, forced to choose) were on-message while the site was not.\n\n## Steps\n\n1. `site-astro/src/pages/index.astro` (`Head title`, `class kicker`) — home title tag, hero kicker, and the three meta/og/twitter descriptions\n2. `site-astro/src/pages/docs.astro` — docs title/description/keywords — keywords must lead with the bigram, not generic 'agent memory'\n3. `site-astro/src/pages/blog/index.astro` — blog index title and descriptions\n4. `site-astro/src/components/Footer.astro` — home-variant tagline only; docs/blog taglines are not category slots\n5. `site-astro/public/llms.txt` — opening blockquote — the single highest-leverage line for answer engines\n6. `site-astro/src/layouts/Head.astro` — og:image:alt, which must match the og.png card text\n\n## Invariants\n\n- Brand string is lowercase 'coldstart' everywhere (matches npm, CLI, GitHub, wordmark) — title tags are category-first, brand last.\n- og:image:alt in Head.astro and the kicker baked into public/og.png must say the same thing; changing one means regenerating the other via scripts/generate-og.sh.","backlinks":[],"anchorLinks":["site-astro-has-two-independent-stylesheets-that-must-be-hand","how-a-new-site-astro-page-acquires-nav-footer-and-svg-defs","docs-pages-share-a-hand-duplicated-sidebar-scrollspy-script","site-astro-public-llms-txt-0a80f88e","site-astro-src-components-footer-astro-98a77858","site-astro-src-layouts-head-astro-41b37e1f","site-astro-src-pages-blog-index-astro-eeb82beb","site-astro-src-pages-docs-astro-d1cf6fe9"]},{"id":"site-astro-scripts-og-html-5839ef55","type":"file","character":"single","title":"site-astro/scripts/og.html","aliases":["OG social card","1200x630","social preview"],"status":"active","updated":"2026-08-08T16:44:45.217Z","edits":1,"anchors":[{"path":"site-astro/scripts/og.html","hash":"sha256:d5c456e784ea","state":"fresh"}],"freshness":"fresh","dir":"site-astro/scripts","outLinks":[],"body":"Self-contained HTML template that renders coldstart's 1200×630 social media preview card. The design combines Newsreader serif for the headline (48px), JetBrains Mono for the kicker (uppercase, cyan, letterspaced), and IBM Plex Sans for muted sub-lines. The headline uses dual accent colors — frost cyan (#4fbfe0) on 'scratch' and warm amber (#ef9448) on 'session' — matching the live homepage hero styling. The snowflake SVG mark is inlined from SvgDefs.astro's path definition but rendered in cyan (#4fbfe0). Fonts are loaded from Google Fonts over HTTPS; the container is exactly 1200×630 with dark background (#070a11) and a bottom gradient rule (cyan → amber). Rendered to PNG by generate-og.sh.","backlinks":[],"anchorLinks":[]},{"id":"site-astro-src-pages-blog-index-astro-eeb82beb","type":"file","character":"single","title":"site-astro/src/pages/blog/index.astro","aliases":["blog index page","blog listing","post collection"],"status":"active","updated":"2026-08-08T16:36:06.116Z","edits":2,"anchors":[{"path":"site-astro/src/pages/blog/index.astro","symbols":["posts","site","jsonLd"],"hash":"sha256:ad1a1743e444","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/pages/blog","outLinks":[],"body":"Blog index page. The <Head /> component props (title, description, ogDescription) contain SEO strings that bind 'coldstart' to 'codebase memory' as part of the site's coordinated brand-positioning strategy. These strings must stay in sync with corresponding strings in Footer.astro, public/llms.txt, and Head.astro when the brand messaging evolves. Note: this file also imports docs.css and duplicates the Google Fonts <link> block, tracked separately in the stylesheet-split flow.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co","site-astro-has-two-independent-stylesheets-that-must-be-hand"]},{"id":"site-astro-src-layouts-head-astro-41b37e1f","type":"file","character":"single","title":"site-astro/src/layouts/Head.astro","aliases":["Head layout","shared meta tags","og:image:alt"],"status":"active","updated":"2026-08-08T16:36:06.109Z","edits":2,"anchors":[{"path":"site-astro/src/layouts/Head.astro","symbols":["Props","site","canonical","ogImage"],"hash":"sha256:43e48691fd9a","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/layouts","outLinks":[],"body":"Shared head layout component defining meta tags for all pages. The og:image:alt content attribute ('coldstart — codebase memory for AI coding agents') binds the coldstart brand to 'codebase memory' for social sharing, part of a coordinated SEO entity binding across the site.","backlinks":[],"anchorLinks":["site-astro-coordinates-seo-entity-binding-of-coldstart-to-co"]},{"id":"site-astro-src-content-config-ts-72ba7b55","type":"file","character":"single","title":"site-astro/src/content/config.ts","aliases":["blog collection schema","content config","frontmatter schema","readingTime convention"],"status":"active","updated":"2026-08-08T11:38:56.256Z","edits":3,"anchors":[{"path":"site-astro/src/content/config.ts","symbols":["blog","collections"],"hash":"sha256:4508d7ae272e","state":"fresh"}],"freshness":"fresh","dir":"site-astro/src/content","outLinks":[],"body":"Declares the `blog` content collection's zod schema — the single source of truth for what frontmatter every post file must carry (title, description, lead, keywords, kicker, ogDescription, publishDate, readingTime, tags, next, optional wordCount). `publishDate` uses `z.coerce.date()` so a plain YAML date string parses to a real Date for sorting. `readingTime` is a free-text string with no computation or validation behind it — verified this session by computing word-count-vs-stated-minutes across all 10 posts, the unenforced convention in use is roughly 200-230 words/minute; a new post's value should be checked against a similar-length existing post, not eyeballed.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"site-astro-src-content-blog-how-your-own-benchmark-lies-to-y-196459c3","type":"file","character":"single","title":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","aliases":["benchmark methodology post","how your own benchmark lies","benchmark guardrails post","reading time too long","wrong minutes estimate"],"status":"active","updated":"2026-08-08T11:38:38.797Z","edits":1,"anchors":[{"path":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","hash":"sha256:8a4f613d59c4","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content/blog","outLinks":[],"body":"Companion post to the critique piece above, aimed at whoever is building a benchmark rather than reading one: one section per guardrail (answer-blind queries, one-variable-per-arm including sub-agent ground-truth corruption, environment/rules-file drift between arms, establishing a nondeterminism floor before trusting a delta), each grounded in a real past incident rather than invented for the post. The answer-blind-query anecdote's source repo is deliberately left unnamed for privacy. Its own `readingTime` was first set to 9 min (about 163 words/minute for its length), inconsistent with the ~200-230 wpm the rest of the site's posts use, and corrected to 8 min before publishing.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"site-astro-src-content-blog-why-most-token-savings-tools-lie-1fc86b94","type":"file","character":"single","title":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","aliases":["token savings critique post","why most token savings tools lie","benchmark honesty post"],"status":"active","updated":"2026-08-08T11:38:38.788Z","edits":1,"anchors":[{"path":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","hash":"sha256:308716b65de7","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content/blog","outLinks":[],"body":"The renamed and rewritten critique post (was `what-the-numbers-actually-say.md`), arguing a token-savings number is only honest when measured across a whole session's usage record, not one call — covers the ~90%-cache-read/2%-tool-output cost ratio and a prompt-caching-invalidation mechanism (rewriting earlier context converts cheap cache reads into full-price cache writes) before landing on coldstart's own Arches (-64%) / JMRI (-31%) sweep numbers as the worked example. Deliberately names no competitor tool or anecdote, and deliberately omits an old, since-rebuilt notebook-capture-cost figure — both scoped out on purpose, stated as open gaps in the post itself rather than silently left out.","backlinks":[],"anchorLinks":["blog-posts-chain-via-a-hand-maintained-circular-next-field"]},{"id":"blog-posts-chain-via-a-hand-maintained-circular-next-field","type":"flow","character":null,"title":"blog posts chain via a hand-maintained circular next field","aliases":["blog next field","post navigation chain","next post link"],"status":"active","updated":"2026-08-08T11:38:38.740Z","edits":1,"anchors":[{"path":"site-astro/src/content/config.ts","hash":"sha256:4508d7ae272e","state":"fresh"},{"path":"site-astro/src/content/blog/why-most-token-savings-tools-lie.md","hash":"sha256:308716b65de7","state":"changed"},{"path":"site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md","hash":"sha256:8a4f613d59c4","state":"changed"}],"freshness":"changed","dir":"site-astro/src/content","outLinks":[],"body":"Every blog post's `next` frontmatter field is a manually-authored pointer to another post's slug, and across the whole collection these links form exactly one closed loop (not derived from publishDate order, not validated at build time) that renders as the 'Next' link at the bottom of each post page.\n\n## Steps\n\n1. `site-astro/src/content/config.ts` — declares `next` as an optional plain string on the blog collection schema; nothing here checks that the value is a real, existing slug\n2. `site-astro/src/content/blog/why-most-token-savings-tools-lie.md` — one link in the loop; its `next` was repointed this session to splice a newly added post in after it, instead of straight to its old target\n3. `site-astro/src/content/blog/how-your-own-benchmark-lies-to-you-first.md` — new post spliced into the loop; its own `next` was set to the old target of the post before it, so the loop closes again with one more link\n\n## Invariants\n\n- the `next` chain across ALL posts must form exactly one closed loop with no missing or duplicate slug — inserting or removing a post means re-pointing the neighboring post(s) by hand, not just adding/deleting the one file\n- `next` values are raw slugs, unvalidated against real content-collection entries at build time — a stale slug after a rename or delete fails silently (a dead 'Next' link) rather than failing the build","backlinks":[],"anchorLinks":["site-astro-src-content-blog-how-your-own-benchmark-lies-to-y-196459c3","site-astro-src-content-blog-why-most-token-savings-tools-lie-1fc86b94","site-astro-src-content-config-ts-72ba7b55"]},{"id":"hooks-kb-elicit-mjs-08de0677","type":"file","character":"single","title":"hooks/kb-elicit.mjs","aliases":["findRepoRoot","frozen root marker","acompact","manual capture","baseline","nested subagent transcripts","kb-elicit","capture orchestrator","Stop hook","SubagentStop hook","manual capture entry point","soleMarkerUnderRoot","worklist deletion loses coverage forever","hand-deleted worklist file"],"status":"active","updated":"2026-08-06T12:54:32.329Z","edits":22,"anchors":[{"path":"hooks/kb-elicit.mjs","symbols":["findRepoRoot","freshestMarkerUnderRoot","resolveSubagentTranscript","markerMtime","argValue","readStdin"],"hash":"sha256:a6d2a6103578","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Claude Stop/SubagentStop capture orchestrator AND the shared --manual/on-demand entry point ALL THREE HOSTS invoke: reads the session marker, slices the transcript by stored lineCount, filters evidence through .coldstartignore, and steps the trigger state machine; most stops tick silently. Resume hazards handled: /compact shrinkage (stored lineCount > current lines -> reset) and a fresh marker meeting an already-large transcript (baseline, fire nothing). The repo root is FROZEN in the marker (state.root, via findRepoRoot walk-up to the nearest `.coldstart/notebook` ancestor) so a mid-session `cd` cannot admit a foreign absolute path into the worklist. --manual requires --session (2026-07-?? PR #133 tightened this — it no longer 'self-discovers the freshest marker', which guessed wrong across concurrent sessions), or falls back to `soleMarkerUnderRoot` when exactly one candidate marker exists under --root (refuses on 2+, ambiguous) — this is what lets Cursor/Codex's hook-injected /capture-notes work without a real --session on their command surface. --manual marks LISTED files captured while leaving armed/activeStops/stopsSinceFire/quietRun untouched, so it cannot change WHEN automatic capture next fires. 2026-08-06 FIX: the manual branch now also checks `worklistLost = !existsSync(worklistJsonPath(root, sid, 'main'))` (imported from hooks/capture-payload.mjs) and includes a captured READ-ONLY file in the listing when true — previously, hand-deleting `.worklist-<sid>-<aid>.json` left those files permanently invisible to manual capture even though they still needed a note, since captured=true was otherwise treated as done.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"how-notebook-capture-fires-v5-trigger-timed","type":"flow","character":null,"title":"how notebook capture fires (v5 trigger-timed)","aliases":["capture-notes","manual capture","capture on demand","fire capture now","durable worklist","worklist","capture sentinel","unified marker","cross-host session id","capture instructions","capture-instructions.md","permanent instructions file"],"status":"active","updated":"2026-08-06T11:17:53.830Z","edits":15,"anchors":[{"path":"hooks/kb-elicit.mjs","hash":"sha256:a6d2a6103578","state":"fresh"},{"path":"hooks/evidence.mjs","hash":"sha256:de7c023db93c","state":"changed"},{"path":"hooks/ignore.mjs","hash":"sha256:6b5fde7d5dc4","state":"fresh"},{"path":"hooks/trigger.mjs","hash":"sha256:d5d41f6fd44c","state":"fresh"},{"path":"hooks/capture-payload.mjs","hash":"sha256:cb889f7d6a57","state":"changed"},{"path":"hooks/kb-recall.mjs","hash":"sha256:41cc77ff40a0","state":"changed"},{"path":"hooks/cursor-kb-recall.mjs","hash":"sha256:81eb647451fe","state":"changed"},{"path":"hooks/codex-kb-recall.mjs","hash":"sha256:bfee03e28713","state":"changed"},{"path":"hooks/cursor-kb-elicit.mjs","hash":"sha256:4e5bdaa79e39","state":"fresh"},{"path":"hooks/codex-kb-elicit.mjs","hash":"sha256:b3f62e471f3f","state":"fresh"},{"path":"hooks/capture-sentinel.mjs","hash":"sha256:9ec243a69ec0","state":"fresh"},{"path":"src/init.ts","hash":"sha256:667ecf980a53","state":"changed"},{"path":"src/kb/write-guide.ts","hash":"sha256:9a8d307fce87","state":"fresh"},{"path":"src/kb/durable-worklist.ts","hash":"sha256:f3458ced167c","state":"fresh"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Capture is trigger-timed, not per-stop: every Stop silently updates per-file evidence and a score, and only when the trigger fires is the checklist payload delivered - the stop itself is never blocked; only git-HEAD drift blocks. Writing a note is really THREE decoupled writes (trigger-state marker, durable worklist file, notebook note) across 3 hosts x 2 agent roles x 2 fire modes, and this pipeline has regressed a different cell of that matrix on almost every past fix. As of 2026-08-06 all three hosts share ONE marker namespace, manual /capture-notes on Cursor/Codex is hook-injected with the real session id rather than typed by the agent, and the static instructions half of the payload lives in one permanent file instead of being duplicated per session - see Invariants for the full incident list before changing anything here.\n\n## Steps\n\n1. `hooks/kb-elicit.mjs` — (`step`, `soleMarkerUnderRoot`) — Claude's Stop/SubagentStop orchestrator AND the shared --manual/on-demand entry point ALL THREE HOSTS invoke (src/init.ts's USER_COMMANDS.capture.invocation is host-agnostic - it always shells out to this one file, never a host-specific elicit script). --manual requires --session, or falls back to soleMarkerUnderRoot when exactly one candidate marker exists under --root, refusing when 2+ are ambiguous.\n2. `hooks/evidence.mjs` — tiered evidence (edit/read/gs; mentions never count) for Claude's transcript format\n3. `hooks/ignore.mjs` — filters ignored files out of evidence at the root\n4. `hooks/trigger.mjs` — (`step`) — pure state machine (Claude/Cursor only - Codex does NOT import this, see cursor-kb-elicit.mjs/codex-kb-elicit.mjs below): score = uncaptured files + 2x settled edits + ALL stops since last fire; arm at 10; fire on descent, cap, or headDrift. A fire is ONE-SHOT: marks offered files captured=true and resets counters in the same call kb-elicit.mjs persists to the marker UNCONDITIONALLY, regardless of whether the worklist write below succeeds.\n5. `hooks/capture-payload.mjs` — (`writeDurableWorklist`, `buildCapturePayload`, `ensureCaptureInstructions`) — renders the FULL checklist for THIS turn (unchanged: always inlines the complete instructions text) and best-effort writes the durable pair .worklist-<sid>-<aid>.{json,md}. If that write is lost (hand-deleted, disk error), the marker still believes those files were offered, so nothing regenerates the pair short of a fresh edit. 2026-08-06: the static DECIDE-FIRST/per-note/FLOWS/WRITE instructions (~150 lines, byte-identical every fire) are no longer duplicated into every session's .md. They live ONCE in the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (shippedInstructionsTemplate, version-tagged via INSTRUCTIONS_VERSION so a future template edit self-heals a stale on-disk copy). renderCapturePayload substitutes {{CLI}}/{{ROOT}}/{{SID}}/{{AID}}/{{WORKLIST}} into that permanent body - the same placeholder mechanism the pre-existing `.coldstart/checklist.md` user-override already used; loadChecklistOverride still takes precedence when present. The per-session .worklist-<sid>-<aid>.md shrank to just the worklist + a pointer at the permanent file (~10KB -> ~400 bytes); the JSON half (files/tier/needsNote - what the worklist-deletion fix above actually protects) is untouched.\n6. `src/kb/durable-worklist.ts` — TS contract twin of the worklist writer/shape; kb write reads it to credit/trim/clear coverage on finalize\n7. `hooks/kb-recall.mjs` — Claude's UserPromptSubmit: consumes the pending file and injects capture FIRST\n8. `hooks/cursor-kb-elicit.mjs` — (`marker`) — Cursor's OWN Stop/SubagentStop capture logic (does not use trigger.mjs at all - has its own inline evidence/fire logic). As of 2026-08-06 writes its session-state marker to the SAME path kb-elicit.mjs's --manual reads: tmpdir()/coldstart-kb-<sid>-<aid>.json (previously coldstart-cursor-kb-<sid>-<aid>.json, a DIFFERENT file --manual could never see - see Invariants). The per-turn dedupe file (coldstart-cursor-kb-turn-<tid>-<aid>.done) is unrelated and keeps its own cursor-specific prefix.\n9. `hooks/codex-kb-elicit.mjs` — (`marker`) — Codex's OWN Stop/SubagentStop capture logic - also does not import trigger.mjs; ALWAYS fires decision:block on evidence (no arm/descent threshold at all, unlike Claude/Cursor's v5 trigger - a real asymmetry, not yet unified). As of 2026-08-06 writes to the same unified tmpdir()/coldstart-kb-<sid>-<aid>.json marker (previously coldstart-codex-kb-<sid>-<aid>.json).\n10. `hooks/capture-sentinel.mjs` — (`CAPTURE_SENTINEL`) — the literal string `<!-- coldstart:capture-notes -->` embedded in the Cursor/Codex capture command body (src/init.ts wireCursorCommand/wireCodexSkill, gated on UserCommand.hookInjected) so a host's own pre-prompt recall hook can recognize the submitted prompt IS /capture-notes and act on it.\n11. `hooks/cursor-kb-recall.mjs` — Cursor's beforeSubmitPrompt: when the submitted prompt contains CAPTURE_SENTINEL and a real session_id is present (which this hook always has, unlike the command surface itself), it runs `kb-elicit.mjs --manual --session <real sid> --root <root>` itself and injects the output via the existing additional_context/pending channel - deterministic, no LLM has to type a correct --session. Falls back to the command's own 'run this in the terminal' wording if the hook is disabled/fails.\n12. `hooks/codex-kb-recall.mjs` — Codex's UserPromptSubmit: same CAPTURE_SENTINEL detection and self-run of kb-elicit.mjs --manual, injected via hookSpecificOutput.additionalContext. Every early-exit (no notebook yet, empty query, search failed, no recall hits) falls back to delivering the manual-capture text alone via deliverManualOnlyAndExit, instead of exiting silently and swallowing an explicit /capture-notes.\n13. `src/init.ts` — (`wireCursorCommand`, `wireCodexSkill`, `UserCommand`) — UserCommand gained hookInjected?:boolean (true only for the capture command, not repair/repairAliases which need no session). When set, the Cursor/Codex command body opens with CAPTURE_SENTINEL and reworded fallback text instead of unconditionally telling the agent to run the terminal command.\n14. `src/kb/write-guide.ts` — (`MARKER_PREFIXES`, `flowEvidenceCount`) — the flow-evidence check that unions markers across a session's agents. Simplified 2026-08-06 from 3 per-host prefixes to the one unified prefix now that all hosts write the same marker file.\n\n## Invariants\n\n- mentions (grep hits, bare path tokens) never enter evidence — content tiers only\n- cap fires INJECT not block — validated spec deviation: dense sessions starve descent and repeated cap-blocks re-create the v4 agitation\n- pending file = tmpdir coldstart-kb-pending-<sid>.json, 24h TTL, consumed (deleted) on delivery\n- capture survives Claude Code /compact: a transcript shorter than the stored lineCount is reprocessed from its new start rather than dropping evidence (kb-elicit shrink guard)\n- manual capture is READ-ONLY on the session marker, so an on-demand capture can never perturb automatic firing\n- the manual path prints the payload directly - it does NOT write a pending file and does not go through kb-recall\n- manual self-discovers the session (no hook stdin): freshest tmpdir marker whose recorded relative files still resolve under --root\n- mentions (grep hits, bare path tokens) never enter evidence - content tiers only\n- cap fires INJECT not block - dense sessions starve descent and repeated cap-blocks re-create v4 agitation\n- pending file = tmpdir coldstart-kb-pending-<sid>.json, 24h TTL, consumed on delivery\n- capture survives Claude Code /compact via the kb-elicit shrink guard\n- manual capture is READ-ONLY on the session marker, so it cannot perturb automatic firing\n- the manual path prints the payload directly - no pending file, no kb-recall\n- manual self-discovers the session: freshest tmpdir marker whose recorded files resolve under --root\n- EMPIRICAL: descent has never fired in this repo; head-drift (commits) and cap (huge sessions) are the only automatic paths\n- score counts ALL stops since the last fire (engagement); quietRun counts only non-active stops (wind-down) - two different questions, two different counters\n- MIN_FILES_ARM=1 governs arming and descent (non-blocking); MIN_FILES=2 still governs head-drift and cap, because a one-file BLOCKING prompt is the v4 agitation the design exists to kill\n- a session that touches ZERO files never fires, however long it runs\n- manual capture marks the files it LISTED as captured, but leaves armed/activeStops/stopsSinceFire/quietRun untouched - it cannot change WHEN automatic capture fires, only what is still outstanding\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up to .coldstart/notebook), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist\n- capture survives Claude Code /compact via the kb-elicit shrink guard (a transcript shorter than stored lineCount is reprocessed from its new start, not dropped) - PR #81 fixed this after evidence collection silently died post-compact for the rest of a session\n- manual capture does NOT call trigger.step() and does not touch armed/activeStops/stopsSinceFire/quietRun - it only reads the marker and lists/marks worklist files, so it cannot change WHEN automatic capture next fires, only what is still outstanding\n- manual capture requires --session (or exactly one unambiguous marker under --root via soleMarkerUnderRoot); it no longer 'self-discovers the freshest marker' - that guessed wrong when multiple sessions had evidence, which PR #133 closed\n- EMPIRICAL: descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - not a threshold problem. Root cause (PR #96): a 2026-07-21 edit reclassified synthesis turns as quiet (correct, feeds descent) but left the score's engagement term reading activeStops instead of ALL stops since fire, deleting the only score-growth term a pure-discussion session has. Fixed by splitting into two counters: score uses stopsSinceFire (has enough happened), quietRun uses only non-active stops (has it wound down).\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist - PR #102 fixed a real case where a session that `cd`'d into ~/.claude/.../memory got those files recorded as if repo-local\n- captured=true means OFFERED by a fire, not WRITTEN by kb write - the manual path used to filter out every captured file, which silently dropped a session's own just-edited/new files from /capture-notes (PR #113); do not conflate the two states when touching either path\n- SubagentStop's capture prompt runs as the subagent's OWN turn, and a subagent's return value to its coordinator IS its last message - blocking a SubagentStop for the notebook step overwrote the actual deliverable until a subagent-only 'restate your result last' tail was added (PR #61); any new SubagentStop-blocking behavior needs the same tail or it will re-break this\n- the flow-note gate is a precision/recall knob that has swung to both extremes on the SAME axis with no automated test: PR #70 tightened it after a 32% junk-flow rate, then PR #100 found it had overcorrected to a hard zero (0 new flows in 6 days, every flow write folding into one pre-existing flow) six weeks later - only caught by eyeballing capture.jsonl rates by hand each time\n- concurrency identity: the durable worklist and the tmpdir evidence marker MUST share the exact key <sid>-<aid> (aid defaults to 'main'), never sid alone and never root alone - a subagent shares its parent's session id, so a looser key lets a subagent's capture clobber the main agent's list (PR #127 -> re-keyed by PR #133)\n- every worklist/marker write in this pipeline is deliberately best-effort (try/catch, 'capture must never fail because these could not be written') - correct for not blocking the agent, but means write failures are silent by design. There is no repair/reconciliation command today that checks marker state against worklist-file existence the way `kb repair` checks note shape against the sidecar - a hand-deleted .worklist-<sid>-<aid>.{json,md} stays gone forever for those files.\n- any change to this pipeline should be checked against the full matrix: 3 hosts (Claude/Cursor/Codex) x 2 roles (main/subagent) x 2 fire modes (automatic score-based / manual on-demand) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133)\n- capture survives Claude Code /compact via the kb-elicit shrink guard - PR #81 fixed evidence collection silently dying post-compact for the rest of a session\n- manual capture does NOT call trigger.step() and cannot change WHEN automatic capture next fires, only what is still outstanding\n- manual capture requires --session (or exactly one unambiguous marker under --root via soleMarkerUnderRoot)\n- EMPIRICAL (Claude/Cursor only): descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - PR #96 fixed a wrong score counter (activeStops instead of stopsSinceFire)\n- MIN_FILES_ARM=1 governs arming and descent (non-blocking); MIN_FILES=2 still governs head-drift and cap\n- a session that touches ZERO files never fires, however long it runs (Claude/Cursor)\n- evidence is attributed to the FROZEN repo root, so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist (PR #102)\n- captured=true means OFFERED by a fire, not WRITTEN by kb write - manual used to filter out every captured file, silently dropping a session's own just-edited/new files (PR #113 fixed this for edits)\n- 2026-08-06 FIX: a captured READ-ONLY file whose durable worklist artifact (.worklist-<sid>-<aid>.json) is missing - hand-deleted, or the write itself failed - is now re-included by manual capture even though captured=true, because there is no other live copy of that checklist anywhere. Checked via a fresh existsSync(worklistJsonPath(...)) at manual-capture time (hooks/kb-elicit.mjs), NOT via any change to trigger.mjs or automatic firing - deliberately narrow scope to avoid yet another regression cycle. Automatic firing does NOT self-heal a lost worklist; running /capture-notes (now working correctly on all 3 hosts, see below) is the recovery path.\n- SubagentStop's capture prompt runs as the subagent's OWN turn and IS its last message to the coordinator - blocking it for the notebook step overwrote the actual deliverable until a subagent-only 'restate your result last' tail was added (PR #61)\n- the flow-note gate is a precision/recall knob that has swung to both extremes on the SAME axis with no automated test: PR #70 tightened it (32% junk), PR #100 found it had overcorrected to zero six weeks later\n- concurrency identity: the durable worklist and the tmpdir evidence marker MUST share the exact key <sid>-<aid> (aid defaults to 'main'), never sid alone and never root alone (PR #127 -> re-keyed by PR #133)\n- 2026-08-06 MAJOR FIX, previously undiscovered: `/capture-notes` for ALL THREE HOSTS always ran the SAME shared hooks/kb-elicit.mjs --manual (src/init.ts's invocation is host-agnostic), which reads/writes tmpdir()/coldstart-kb-<sid>-<aid>.json. But Cursor's and Codex's OWN automatic Stop hooks (cursor-kb-elicit.mjs, codex-kb-elicit.mjs) wrote to DIFFERENT, host-prefixed marker files (coldstart-cursor-kb-*, coldstart-codex-kb-*) that the shared script's regex/glob never matched. Net effect: manual capture on Cursor/Codex could NEVER see evidence gathered by their own automatic Stop hooks - it always hit 'no notebook-capture evidence yet', even after last session's soleMarkerUnderRoot fallback, because there was nothing under the searched prefix to find. Every existing manual-capture test (this repo's own, before this fix) hand-seeded a coldstart-kb-* marker directly and so never caught it. FIXED by unifying all three hosts onto ONE marker prefix (coldstart-kb-) - src/kb/write-guide.ts's flowEvidenceCount already treated the three prefixes as one logical union by design, which is what made this discoverable: it was already assuming host-agnostic evidence that the marker filenames didn't actually deliver.\n- 2026-08-06 FIX: Cursor/Codex commands have no way to pass a real session id INTO the command body the way Claude's `!`-expansion does (confirmed via official docs, not just transcripts - no ! expansion in .cursor/commands/*.md, no session var on Codex skill bodies). Their own pre-prompt hooks (beforeSubmitPrompt / UserPromptSubmit) DO receive a real session_id though. Fix: the command body carries CAPTURE_SENTINEL (hooks/capture-sentinel.mjs); cursor-kb-recall.mjs/codex-kb-recall.mjs detect it in the submitted prompt and run kb-elicit.mjs --manual --session <real sid> themselves, injecting the result via the SAME additional_context/pending-capture channel already used for automatic-fire delivery. The command body's 'run this in the terminal' wording is kept as an explicit fallback for when the hook is disabled or fails - repair/repairAliases commands are untouched (UserCommand.hookInjected is capture-only, they need no session).\n- Codex's capture is NOT the same v5 trigger as Claude/Cursor: codex-kb-elicit.mjs does not import trigger.mjs at all and fires decision:block on every Stop that has new evidence, no arm/descent/score. This asymmetry predates 2026-08-06 and was not unified - flagged here, not fixed.\n- any change to this pipeline should be checked against the full matrix: 3 hosts x 2 roles (main/subagent) x 2 fire modes (automatic/manual) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133, plus the two 2026-08-06 fixes above)\n- evidence is attributed to the FROZEN repo root (marker state.root, derived once via findRepoRoot walk-up to .coldstart/notebook), so a mid-session `cd` out of the repo cannot admit a foreign absolute path into the worklist (PR #102 fixed a real case where a session that cd'd into ~/.claude/.../memory got those files recorded as if repo-local)\n- capture survives Claude Code /compact via the kb-elicit shrink guard (a transcript shorter than stored lineCount is reprocessed from its new start, not dropped) - PR #81 fixed evidence collection silently dying post-compact for the rest of a session\n- EMPIRICAL: descent had NEVER fired in this repo for 6 weeks (104 stops/24 fires, all head-drift or cap) - not a threshold problem. Root cause (PR #96): a 2026-07-21 edit reclassified synthesis turns as quiet (correct, feeds descent) but left the score's engagement term reading activeStops instead of ALL stops since fire, deleting the only score-growth term a pure-discussion session has. Fixed by splitting into two counters: score uses stopsSinceFire (has enough happened), quietRun uses only non-active stops (has it wound down)\n- every worklist/marker write in this pipeline is deliberately best-effort (try/catch, 'capture must never fail because these could not be written') - correct for not blocking the agent, but means write failures are silent by design. There is no repair/reconciliation command today that checks marker state against worklist-file existence the way `kb repair` checks note shape against the sidecar - a hand-deleted .worklist-<sid>-<aid>.{json,md} stays gone forever for those files, UNLESS it is a captured read-only file, which is recovered by manual capture (see the 2026-08-06 fix below)\n- any change to this pipeline should be checked against the full matrix: 3 hosts (Claude/Cursor/Codex) x 2 roles (main/subagent) x 2 fire modes (automatic score-based / manual on-demand) - a fix scoped to one cell has regressed a different cell almost every time in this file's history (PRs #61, #64, #70, #81, #85, #96, #100, #102, #113, #127, #133, plus the 2026-08-06 fixes below)\n- 2026-08-06 FIX: a captured READ-ONLY file whose durable worklist artifact (.worklist-<sid>-<aid>.json) is missing - hand-deleted, or the write itself failed - is now re-included by manual capture even though captured=true, because there is no other live copy of that checklist anywhere. Checked via a fresh existsSync(worklistJsonPath(...)) at manual-capture time (hooks/kb-elicit.mjs), NOT via any change to trigger.mjs or automatic firing - deliberately narrow scope to avoid yet another regression cycle. Automatic firing does NOT self-heal a lost worklist; running /capture-notes (now working correctly on all 3 hosts, see below) is the recovery path\n- 2026-08-06 MAJOR FIX, previously undiscovered: `/capture-notes` for ALL THREE HOSTS always ran the SAME shared hooks/kb-elicit.mjs --manual (src/init.ts's invocation is host-agnostic), which reads/writes tmpdir()/coldstart-kb-<sid>-<aid>.json. But Cursor's and Codex's OWN automatic Stop hooks (cursor-kb-elicit.mjs, codex-kb-elicit.mjs) wrote to DIFFERENT, host-prefixed marker files (coldstart-cursor-kb-*, coldstart-codex-kb-*) that the shared script's regex/glob never matched. Net effect: manual capture on Cursor/Codex could NEVER see evidence gathered by their own automatic Stop hooks - it always hit 'no notebook-capture evidence yet', even after the prior session's soleMarkerUnderRoot fallback, because there was nothing under the searched prefix to find. Every existing manual-capture test (this repo's own, before this fix) hand-seeded a coldstart-kb-* marker directly and so never caught it. FIXED by unifying all three hosts onto ONE marker prefix (coldstart-kb-) - src/kb/write-guide.ts's flowEvidenceCount already treated the three prefixes as one logical union by design, which is what made this discoverable: it was already assuming host-agnostic evidence that the marker filenames didn't actually deliver\n- 2026-08-06 FIX: Cursor/Codex commands have no way to pass a real session id INTO the command body the way Claude's `!`-expansion does (confirmed via official docs, not just transcripts - no ! expansion in .cursor/commands/*.md, no session var on Codex skill bodies). Their own pre-prompt hooks (beforeSubmitPrompt / UserPromptSubmit) DO receive a real session_id though. Fix: the command body carries CAPTURE_SENTINEL (hooks/capture-sentinel.mjs); cursor-kb-recall.mjs/codex-kb-recall.mjs detect it in the submitted prompt and run kb-elicit.mjs --manual --session <real sid> themselves, injecting the result via the SAME additional_context/pending-capture channel already used for automatic-fire delivery. The command body's 'run this in the terminal' wording is kept as an explicit fallback for when the hook is disabled or fails - repair/repairAliases commands are untouched (UserCommand.hookInjected is capture-only, they need no session)\n- Codex's capture is NOT the same v5 trigger as Claude/Cursor: codex-kb-elicit.mjs does not import trigger.mjs at all and fires decision:block on every Stop that has new evidence, no arm/descent/score. This asymmetry predates 2026-08-06 and was not unified - flagged here, not fixed\n- 2026-08-06 FIX: the static instructions half of the capture payload (DECIDE-FIRST/per-note/FLOWS/WRITE rules) is now generated ONCE per repo into the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (hooks/capture-payload.mjs ensureCaptureInstructions/shippedInstructionsTemplate), version-tagged so a future edit to the template self-heals a stale on-disk copy instead of silently drifting. This is a pure disk-I/O simplification (USER's own proposal, deferred to after the prior PR merged) - it does NOT change what the agent reads on any given fire (buildCapturePayload's return value still inlines the full instructions every time) and does NOT touch the worklist-deletion recovery fix above (that protects the per-session JSON half - files/tier/needsNote - which must stay per-session and deletable; only the static prose half moved to a permanent file). The per-session .worklist-<sid>-<aid>.md shrank from a full ~10KB duplicate to a ~400-byte worklist+pointer","backlinks":["src-init-ts-a867acfe"],"anchorLinks":["how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","hooks-capture-sentinel-mjs-944d6bea","hooks-codex-kb-elicit-mjs-9cb55b18","hooks-codex-kb-recall-mjs-cd4df13f","hooks-cursor-kb-elicit-mjs-151bef1e"]},{"id":"hooks-capture-payload-mjs-9f99e00d","type":"file","character":"single","title":"hooks/capture-payload.mjs","aliases":["rule 7","under capture","capture coverage denominator","worklist manifest tmpdir","inline spec shapes","checklist override","worklist scope rule","envelope","capture instructions","capture-instructions.md","permanent instructions file","shipped instructions template"],"status":"active","updated":"2026-08-06T11:16:13.455Z","edits":27,"anchors":[{"path":"hooks/capture-payload.mjs","symbols":["buildCapturePayload","recordWorklistManifest","worklistManifestPath","worklistLines","loadChecklistOverride"],"hash":"sha256:cb889f7d6a57","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"Builds the capture prompt (v5) for every host. 2026-08-06: the static DECIDE-FIRST/per-note/FLOWS/WRITE instructions (~150 lines, byte-identical every fire) no longer get duplicated onto disk per session. shippedInstructionsTemplate() is written ONCE to the permanent, gitignored `.coldstart/notebook/.capture-instructions.md` (ensureCaptureInstructions — version-tagged via INSTRUCTIONS_VERSION so a future template change self-heals a stale on-disk copy instead of drifting silently). renderCapturePayload substitutes {{CLI}}/{{ROOT}}/{{SID}}/{{AID}}/{{WORKLIST}} into that permanent body — the SAME placeholder mechanism the pre-existing `.coldstart/checklist.md` user-override path already used (loadChecklistOverride now takes precedence, ensureCaptureInstructions is the fallback; both paths share one substitution pass now instead of two near-duplicate branches). The per-session `.worklist-<sid>-<aid>.md` (writeDurableWorklist/renderDurableMd) is now SMALL — just the worklist + a pointer to the permanent file — instead of the full rendered payload. Nothing changes for the CURRENT fire: buildCapturePayload's return value (what the agent actually reads this turn) still inlines the complete instructions text every time; only what gets persisted to disk for a LATER re-Read shrank (~10KB -> ~400 bytes per session). This does not touch the worklist-deletion recovery fix from the same week (see the flow note) — that's about the JSON half (files/tier/needsNote), which must stay per-session and deletable; this split only concerns the static prose half.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — renders the compact shapes inline into the capture prompt","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","src-kb-search-ts-272e86f3","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"hooks-capture-sentinel-mjs-944d6bea","type":"file","character":"single","title":"hooks/capture-sentinel.mjs","aliases":["capture sentinel","capture-notes marker string","hook-injected command detection"],"status":"active","updated":"2026-08-06T09:53:32.824Z","edits":1,"anchors":[{"path":"hooks/capture-sentinel.mjs","symbols":["CAPTURE_SENTINEL"],"hash":"sha256:9ec243a69ec0","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Exports the single literal string CAPTURE_SENTINEL (<!-- coldstart:capture-notes -->) that src/init.ts embeds in the Cursor/Codex /capture-notes command body and that cursor-kb-recall.mjs/codex-kb-recall.mjs grep the submitted prompt for, so a host's pre-prompt recall hook can recognize its own capture command and run it with a real session id instead of leaving the agent to type one blind.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"why-a-file-note-s-extra-anchors-can-never-carry-symbols","type":"flow","character":null,"title":"why a file note's extra anchors can never carry symbols","aliases":["one addressable anchor per file note","verified creates anchors","anchor fill targets wrong note","repair pass never converges","symbols land on another note"],"status":"active","updated":"2026-08-03T04:18:58.898Z","edits":1,"anchors":[{"path":"src/kb/write.ts","hash":"sha256:d14c1dd5b965","state":"changed"},{"path":"src/kb/repair.ts","hash":"sha256:5f6602bab1c5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"A file note can accumulate anchors it is structurally incapable of ever filling: every path listed in a write's `verified` becomes an anchor, but only ONE of them — the anchor whose path derives the note id — is addressable by a later write. kbWrite routes a file note by spec.path and overwrites the record's anchors with a single entry at that path, so there is no spec that attaches symbols to a secondary anchor; a write aimed at one lands on whatever note that path derives to instead. Any code that walks a note's anchors and tries to fill them one by one is therefore writing to the wrong note and never converging, which is exactly how the keeper's auto-backfill disabled itself. Observed live 2026-08-03: a note written with verified:[src/alpha.ts, src/beta.ts] gained two anchors, and only the alpha one could ever be given symbols.\n\n## Steps\n\n1. `src/kb/write.ts` (`kbWrite`) — routes a file note by spec.path (fileNoteId) and overwrites record.anchors with one entry at that path — the constraint everything else inherits\n2. `src/kb/raw-log.ts` — stamps an anchor for every path in `verified`, which is how secondary anchors appear at all (observed via behaviour this session, file not read)\n3. `src/kb/repair.ts` (`mechanicalSymbolRepair`) — the consumer that must respect it — fills only the anchor whose path derives the note id, skipping the rest\n\n## Invariants\n\n- exactly one anchor per file note is addressable by a write: the one where fileNoteId(anchor.path) === note.id\n- a fill loop over note.anchors must skip every other anchor or it writes to a different note and re-fires forever","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked","src-kb-repair-ts-a197bcce","src-kb-write-ts-d5968d80","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"tests-kb-repair-test-ts-35dbd7b5","type":"file","character":"single","title":"tests/kb-repair.test.ts","aliases":["repair tests","lesson scope terms rejected","retract needs target","hub facet symbols","kbWrite call shape","repair writes nothing","kb repair tests","seedSidecar helper","backfill regression tests","secondary anchor test","convergence assertion"],"status":"active","updated":"2026-08-03T04:18:38.158Z","edits":3,"anchors":[{"path":"tests/kb-repair.test.ts","symbols":["planRepairs","repairWorklist","rawSnapshot","seedSidecar"],"hash":"sha256:71771b79bc32","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Covers kb repair: planRepairs/repairWorklist (pure, never writes) and mechanicalSymbolRepair (the one writing path). Verified 2026-08-03: the mechanical block seeds a fake sidecar directly via saveKbNotesIndex, so no real code index is needed. Two tests added for the wrong-note backfill bug — one asserts a secondary anchor (created by listing a second path in `verified`) is skipped, no note is conjured at its path, and a second pass fixes nothing; the other asserts a note already carrying aliasesVerified stays out of planAliasRepair after a backfill. The convergence assertion is the load-bearing one: a non-converging pass is what trips the keeper's streak cap.","backlinks":[],"anchorLinks":[]},{"id":"src-kb-write-ts-d5968d80","type":"file","character":"single","title":"src/kb/write.ts","aliases":["verified auto stamp","note freshness reset by edit","file note id from path","two-phase write gate","kb write validation","anchors overwritten on file note","file IS the anchor","secondary anchor unwritable","spec.path addresses the note","extra anchors dropped silently","symbols went to the wrong path"],"status":"active","updated":"2026-08-03T04:18:16.605Z","edits":4,"anchors":[{"path":"src/kb/write.ts","symbols":["kbWrite","WriteSpec","WriteOptions","WriteResult","WriteCandidate","exactAddressCandidates","pathWarnings"],"hash":"sha256:d14c1dd5b965","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"Validates and routes a kb write spec, then hands a record to the raw log. Two non-obvious rules live in the file-note branch. (1) It auto-fills `verified` with the anchor path, which makes raw-log stamp the file's live hash and reset freshness — conditional since 2026-07-30 on the spec carrying knowledge implying a read (summary, facets, body), so a metadata-only edit stamps nothing; an explicit `verified` is always honoured. (2) Verified 2026-08-03: the same branch OVERWRITES record.anchors with a single entry at spec.path and reads symbols only from spec.anchors[0] — so a file note's extra anchors are unwritable through this path. Secondary anchors exist (raw-log stamps one per `verified` path) but can never be given symbols, and a spec whose anchors[0] is not spec.path has those symbols silently attributed to spec.path instead. File-note ids derive from the path (never supplied); the two-phase candidate gate runs only for non-file notes.","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked","why-a-file-note-s-extra-anchors-can-never-carry-symbols","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"src-kb-repair-ts-a197bcce","type":"file","character":"single","title":"src/kb/repair.ts","aliases":["notes not findable","missing aliases","unfindable notes","repair worklist","Nothing to repair here","flow steps unanchored","repair prompt wording","preloadedSidecar param","anchor symbol backfill","mechanicalSymbolRepair","own anchor only","SYMBOL_BACKFILL_CAP","backfill wrote to wrong note","auto-backfill stopped firing","streak 3/3 disabled","secondary anchor never filled","repair never converges"],"status":"active","updated":"2026-08-03T04:18:16.473Z","edits":5,"anchors":[{"path":"src/kb/repair.ts","symbols":["planRepairs","repairWorklist","RepairFinding","RepairReport","subjectPaths","mechanicalSymbolRepair","SYMBOL_BACKFILL_CAP"],"hash":"sha256:5f6602bab1c5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"kb repair: detection worklist + the one mechanical exception, mechanicalSymbolRepair, which backfills anchors[].symbols on single-character file notes from the kb-notes-index sidecar (hub notes excluded, never overrides existing symbols, capped at SYMBOL_BACKFILL_CAP=15). Takes an optional preloadedSidecar so the keeper skips a redundant disk read. 2026-08-03: it can only ever fill the note's OWN anchor — the one whose path derives the note id (fileNoteId). It used to loop every anchor and re-put each under ITS own path; because kbWrite addresses a file note by spec.path, a secondary anchor's record landed on a different note, the real anchor stayed empty, and the pass re-fired every watcher cycle until the keeper's streak cap tripped and disabled auto-backfill permanently. It also now carries aliasesVerified forward when the note was already verified at its current edit, so a machine write does not push edits past aliasesVerifiedAtEdit and resurface the note in kb repair-aliases.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — runs missingInNote over the folded notebook","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-file-note-s-extra-anchors-can-never-carry-symbols"]},{"id":"src-kb-alias-repair-ts-f079a186","type":"file","character":"single","title":"src/kb/alias-repair.ts","aliases":["planAliasRepair","aliasRepairWorklist","hiddenIdentityAliases","pagination offset limit","aliasesVerifiedAtEdit stamp","stopping point","resume contract","offset advance unsafe","notes repeat forever","same note every run","pagination skips notes","offset skips notes after marking"],"status":"active","updated":"2026-08-02T18:21:55.330Z","edits":3,"anchors":[{"path":"src/kb/alias-repair.ts","symbols":["planAliasRepair","aliasRepairWorklist"],"hash":"sha256:78de3ecf8f3c","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"kb repair-aliases' engine. Distinct from kb repair's missing-identity-aliases check (that one catches notes with NO aliases; this is for aliases that EXIST but no longer describe the file/flow). planAliasRepair(root, offset, limit) paginates every active file/flow note, computing hiddenIdentityAliases via {capIdentity:false} so an agent sees what a blind retract would resurface. 2026-08-02 FIX: the command had no memory of 'already reviewed' — a note judged still-accurate reappeared on every future run forever, since that judgment left no trace (unlike kb repair's mechanical checks). Fixed with FoldedNote.aliasesVerifiedAtEdit (fold.ts): eligible now excludes a note where nothing has changed since its stamp. USER caught the real trap before this shipped: naively filtering that way breaks pagination, because `eligible` shrinks as notes get marked verified, so continuing to advance --offset by the page size (the OLD documented flow) silently skips whatever slides into that position next. Fix changed the RESUME CONTRACT, not the slicing: mark a batch verified, then re-run with offset 0 (default) — reviewed notes are simply gone from the list. offset/nextOffset still work for read-only browsing, just are no longer how you advance through a reconciling pass. Verified end to end same session: backfilled aliasesVerified:true onto all 53 notes this repo had already reconciled; kb repair-aliases now correctly reports 'No file/flow notes to reconcile.'","backlinks":[],"anchorLinks":[]},{"id":"src-init-ts-a867acfe","type":"file","character":"single","title":"src/init.ts","aliases":["repair-notes command","slash command wiring","capture-notes command","wireClaudeCommand","codex skill frontmatter","cursor no bang expansion","REPAIR_COMMAND","USER_COMMANDS table","repair-aliases command","already imports @coldstart.md","aliasesVerified instructions","no offset resume"],"status":"active","updated":"2026-08-02T18:21:55.074Z","edits":11,"anchors":[{"path":"src/init.ts","symbols":["wireClaudeImport","ensureColdstartignore","captureInvocation","wireClaudeCaptureCommand","wireCursorCaptureCommand","wireCodexCaptureSkill","USER_COMMANDS","REPAIR_COMMAND","CAPTURE_COMMAND","wireClaudeCommand","wireCursorCommand","wireCodexSkill","writeOwnedFile","installRoot","coldstartMd"],"hash":"sha256:d89dfee0ae35","state":"changed"}],"freshness":"changed","dir":"src","outLinks":["how-notebook-capture-fires-v5-trigger-timed"],"body":"init.ts owns coldstart init/setup for all three hosts. USER_COMMANDS is the single source of truth for every user-invoked slash-command/skill (capture-notes, repair-notes, repair-aliases): one row (invocation/description/skillDescription/instructions) per command, rendered by wireClaudeCommand/wireCursorCommand/wireCodexSkill into each host's own format. Deliberately thin `instructions`: the actual guidance lives in the command's own worklist output, never restated here. init's main flow also calls mechanicalSymbolRepair once on the upgrade path. 2026-08-02: USER_COMMANDS.repairAliases.instructions rewritten — it used to tell the agent to advance --offset across calls, which silently skips notes once repair-aliases starts excluding reviewed ones (the eligible list shrinks under a fixed offset). Now says: mark the batch aliasesVerified:true, then re-run with NO offset.\n\n## Facets\n\n- **wireClaudeImport** — BUG live in 2.2.0 (fix open in PR #80): presence check is substring includes(), so a CLAUDE.md that merely MENTIONS @coldstart.md in backticked prose (coldstart's own repo does) makes init report 'already imports' and skip writing the real import line — and Claude Code does not resolve imports inside code spans, so the guidance never loads. Fix = standalone-line check, symmetric with unwire's line-based strip.\n- **ensureColdstartignore** — Writes .coldstart/.coldstartignore (comments-only template; defaults live in hooks/ignore.mjs) and ensures a sibling .coldstart/.gitignore carries the .coldstartignore line so the file stays personal even in shared-notebook repos.\n- **captureInvocation** — bakes ONLY the absolute install path (resolveHooksDir) into the capture command - never a repo path. The hook defaults --root to cwd, so one identical invocation works for every host and every repo, and npm updates are picked up automatically. — [[how-notebook-capture-fires-v5-trigger-timed]]\n- **wireClaudeCaptureCommand** — writes .claude/commands/capture-notes.md. Uses Claude's leading-! expansion so the checklist is injected into the prompt at submit time rather than the agent having to run it. Fully-owned file, overwritten every init.\n- **wireCursorCaptureCommand** — writes .cursor/commands/capture-notes.md as a PLAIN prompt template - Cursor commands have no ! expansion, so the body must ask the agent to run the command itself.\n- **wireCodexCaptureSkill** — writes .agents/skills/capture-notes/SKILL.md, NOT a Codex prompt: Codex custom prompts live in global ~/.codex/prompts and are deprecated, so they cannot carry repo-scoped wiring. Skills are repo-scoped (walked up to the repo root) and REQUIRE name + description frontmatter.","backlinks":[],"anchorLinks":["how-coldstart-gets-created-and-how-it-silently-never-does","how-notebook-capture-fires-v5-trigger-timed"]},{"id":"src-kb-fold-ts-cc536263","type":"file","character":"single","title":"src/kb/fold.ts","aliases":["note ordering","union never trims","alias cap","where did my aliases go","fold options","capIdentity flag","uncapped alias union","notebook merge conflict","raw log fold","aliasesVerified flag","aliasesVerifiedAtEdit stamp","post-increment edits check"],"status":"active","updated":"2026-08-02T18:21:54.944Z","edits":13,"anchors":[{"path":"src/kb/fold.ts","symbols":["fold","applyPut","applyRetract","capAliases","ALIAS_MAX","ALIAS_MAX_WORDS","stableStringify","FoldResult","PUT_KEYS"],"hash":"sha256:fe634a6ddd04","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"The fold — render is a fold, and the fold IS the merge. identityAliases union-forever + capped (capAliases, ALIAS_MAX=12); incidentAliases replaced wholesale by any write carrying summary/body. fold() takes an optional {capIdentity:false} to skip the cap and return the FULL historical union — the one consumer is kb repair-aliases, which needs to show an agent what's hidden past the render cap before it retracts anything. 2026-08-02: a put carrying aliasesVerified:true stamps note.aliasesVerifiedAtEdit = note.edits, set in the MAIN fold loop AFTER the edits++ increment (not inside applyPut, which still sees the pre-increment count) — this is the signal kb repair-aliases uses to stop resurfacing a note nothing has changed on since it was reviewed. 'aliasesVerified' is added to PUT_KEYS purely so it is not dumped into note.extra; it carries no stored content of its own.","backlinks":[],"anchorLinks":[]},{"id":"why-a-note-cannot-be-found-by-the-symbol-it-is-about","type":"flow","character":null,"title":"why a note cannot be found by the symbol it is about","aliases":["empty anchor symbols","kb search misses symbol","file-single shape","note not findable by name","lane 2 tool mode only","sidecar symbol inventory"],"status":"active","updated":"2026-08-02T18:19:44.673Z","edits":10,"anchors":[{"path":"src/kb/write-guide.ts","hash":"sha256:ea58bd486a3b","state":"changed"},{"path":"src/kb/search.ts","hash":"sha256:51e1afe7535c","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:c29235b37e62","state":"changed"},{"path":"tests/kb-shape-parity.test.ts","hash":"sha256:ab4a2402accd","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:a98db0290d25","state":"changed"},{"path":"src/kb/write.ts","hash":"sha256:38e7ca9a095a","state":"changed"},{"path":"src/kb/notes-index.ts","symbols":["buildKbNotesIndex","loadKbNotesIndex","saveKbNotesIndex","kbNotesIndexPath","KbNotesIndex","KB_NOTES_INDEX_VERSION","deriveRenames","stampCoversTerms"],"hash":"sha256:751df4c238dc","state":"fresh"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"CORRECTED 2026-08-01 (second pass — the first version of this note got the mechanism wrong; trust this paragraph over anything above it). A note's stored anchor symbols matter in HOOK mode only. Verified by running kbSearch both ways on `cmdSearch context` and reading carriers: lane 2 (resolveTermToSymbolFiles over the keeper's kb-notes.json sidecar, which holds a per-anchored-file symbol inventory — 35 of 47 files here, and it does contain cmdSearch for src/kb/cli.ts) is ENABLED in tool mode and DISABLED in hook mode at search.ts:488, because enabling it there produced false implants. So `kb search` can match a symbol a note never stored, while hook recall cannot. The shape gap was still real — file-single published no symbols field, so 2 of 44 notes stored any, and hook mode had nothing — but the earlier claim that the anchor channel is empty CORPUS-WIDE was wrong for tool mode. Beware attributing rank changes to this: after storing symbols on src/kb/cli.ts its note went from rank 2 to rank 1 in BOTH modes, but the summary was rewritten in the same write, so the cause is not isolated. Aliases have no such fallback in either mode: nothing derives them, so a note without them is reachable only by its exact title, and the capture prompt's inlined copy of the flow shape had silently lost the field.\n\n## Steps\n\n1. `src/kb/write-guide.ts` (`WRITE_GUIDE_SHAPES`, `missingFieldsWarning`) — canonical shapes + the post-write report naming what is missing\n2. `hooks/capture-payload.mjs` (`buildCapturePayload`) — the inlined SECOND copy agents actually read — where the drift happened\n3. `src/kb/write.ts` (`kbWrite`) — accepts and unions anchors[{path,symbols}] on file specs — capability was never the constraint\n4. `src/kb/search.ts` (`kbSearch`) — weights the anchor channel x2 for exactly these terms, and found it empty\n5. `tests/kb-shape-parity.test.ts` (`REQUIRED`) — pins the two copies so the drift cannot recur\n\n## Invariants\n\n- The anchor channel can only hold what the spec shape asks for — a matcher change cannot recover a field agents were never told to write.\n- file-single is the default and ~97% of volume, so anything missing from ITS shape is missing from the corpus.\n- Tool-mode (kb search) quality is invisible in the inject log: cli.ts logs inject-log only when flags.hook, so tool hits have never been recorded — one tool-source query exists in the entire history, a miss.\n- Two copies of a shape drift silently; the parity test is the only thing that makes it loud.\n- Findability checks REPORT, never reject: the capture prompt chains writes with && so a non-zero exit silences every note behind the failing one.\n- Tool-mode (kb search) quality is still invisible in the inject log: cli.ts logs it only when flags.hook, so tool hits have never been recorded.\n- Lane 2 (sidecar symbol inventory) is tool-mode ONLY — search.ts:488. Stored anchor symbols are the only symbol evidence hook mode has.\n- Aliases have no derived fallback anywhere; a note without them is reachable only by its exact title.\n- Two copies of a shape drift silently; tests/kb-shape-parity.test.ts is what makes it loud.","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","src-kb-search-ts-272e86f3","what-counts-as-the-query-for-notebook-recall","hooks-capture-payload-mjs-9f99e00d","src-kb-cli-ts-99b5d5ba"]},{"id":"where-the-required-note-shape-is-defined-and-how-it-reaches","type":"flow","character":null,"title":"where the required note shape is defined, and how it reaches every surface","aliases":["one note shape table","note-shape.mjs","required note fields","shape drift","hooks cannot import dist","NOTE_CHECKS","missingInSpec missingInNote","add a note requirement"],"status":"active","updated":"2026-08-02T18:19:44.664Z","edits":5,"anchors":[{"path":"hooks/note-shape.mjs","hash":"sha256:c42cfbd8820f","state":"changed"},{"path":"src/kb/write-guide.ts","hash":"sha256:bfd678a3e8b5","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:eff608418ff7","state":"changed"},{"path":"src/server/mcp.ts","hash":"sha256:427809766ada","state":"changed"},{"path":"src/kb/repair.ts","hash":"sha256:ce2b42070900","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:a5bb3cf1046d","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"There is exactly ONE definition of what a note must contain — hooks/note-shape.mjs — and it lives in hooks/ rather than src/ because the capture hooks are plain .mjs that run straight from the package and never import from dist/; the TypeScript side reaches INTO hooks/ instead (the pattern lint.ts already uses with ignore.mjs), which is what lets one file serve the hook, the CLI and the MCP server. Adding a requirement is one NOTE_CHECKS entry and it reaches all five consumers at once: the write guide, the capture prompt's inlined shapes, the MCP kb_write description, the write-time warning, and kb repair's detection. Each entry carries TWO predicates on purpose — missingInSpec reads the JSON an agent just sent, missingInNote reads the folded note on disk; they cannot be collapsed, so they sit adjacent and a change to what 'missing' means has to be made in both, in view of each other. Verified this session: tsc's rootDir does NOT reject the cross-directory import (a .d.mts beside the .mjs supplies the types), and vitest imports the same file from both TS and .mjs test code.\n\n## Steps\n\n1. `hooks/note-shape.mjs` (`SPEC_SHAPES`, `NOTE_CHECKS`, `shapesBlock`, `requiredFieldsLine`, `checksForSpec`, `checksForNote`, `unanchoredSteps`, `stepsMissingAfterWrite`) — the single table plus its renderers\n2. `src/kb/write-guide.ts` (`WRITE_GUIDE_SHAPES`, `missingFieldsWarning`, `flowStepsWarning`) — renders the guide and the write-time warning from checksForSpec\n3. `hooks/capture-payload.mjs` (`buildCapturePayload`) — renders shapesBlock({compact:true}) inline — the copy that used to drift\n4. `src/server/mcp.ts` (`TOOL_DEFINITIONS`) — kb_write description injects requiredFieldsLine(); this copy never said aliases at all\n5. `src/kb/repair.ts` (`planRepairs`, `repairWorklist`) — runs missingInNote over the folded notebook\n\n## Invariants\n\n- Hooks NEVER import from dist/ — a shared table must live in hooks/ or the capture prompt cannot see it.\n- Renderings may differ in prose (compact drops it) but never in fields; tests/kb-shape-parity.test.ts asserts every required field appears in the example an agent copies.\n- A shipped `check` id is never removed — kb repair --json consumers filter by it; retire one by making its predicate always false.\n- missingInSpec and missingInNote read different shapes and cannot be merged; both live in the same entry so neither is edited alone.\n- Every write-time WARN is judged against the FOLDED note, never the record just sent — `op: put` appends and the fold merges, so a partial update omits fields it still has. Both call sites (src/kb/cli.ts and src/server/mcp.ts) load the folded note and must pass it to every warning; a warning that takes only the spec will misfire on updates.","backlinks":["hooks-capture-payload-mjs-9f99e00d","hooks-note-shape-mjs-d85ce294","src-kb-cli-ts-99b5d5ba","src-kb-repair-ts-a197bcce","src-kb-write-guide-ts-c9053885","src-server-mcp-ts-18031783"],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","hooks-capture-payload-mjs-9f99e00d","hooks-note-shape-mjs-d85ce294","how-the-moves-together-signal-reaches-gs-without-going-throu","how-to-wire-a-new-query-command-to-both-cli-and-mcp-surfaces","src-kb-cli-ts-99b5d5ba"]},{"id":"what-counts-as-the-query-for-notebook-recall","type":"flow","character":null,"title":"what counts as \"the query\" for notebook recall","aliases":["why was this note injected","note about a file I never mentioned","path match boost","harness telemetry in the prompt","grep pattern became the query","my shell command got injected"],"status":"active","updated":"2026-08-02T18:19:44.656Z","edits":5,"anchors":[{"path":"src/kb/search.ts","hash":"sha256:0f8e8b280da3","state":"changed"},{"path":"src/kb/cli.ts","hash":"sha256:c2ff1ee17d47","state":"changed"},{"path":"hooks/kb-recall.mjs","hash":"sha256:a82ef1040d11","state":"changed"},{"path":"hooks/recall-query.mjs","hash":"sha256:4a146b7ec842","state":"fresh"},{"path":"hooks/preguard-handler.mjs","hash":"sha256:f136ff422137","state":"fresh"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"The text the recall matcher scores is NOT what the user typed. Two distinct feeds prove it. (1) Every host wraps the user's words in editor/subagent telemetry, which is file- and symbol-rich and hijacks the path-name override in search.ts (+100, bypassing the rarity and suppression gates) — fixed 2026-07-29 in the HOOKS via recall-query.mjs, never in search.ts, because the override is opts.strongOnly-gated and tool-mode kb search must keep trusting a path the user typed literally. (2) OBSERVED 2026-07-29 in inject-log.jsonl: the PostToolUse nudge path also drives kb search --hook, so an AGENT's raw grep pattern lands in the log as a query and can inject — the record at 17:01:29Z has query 'rareCount |let rare = false' (a shell grep pattern, not a prompt) with implant:true against hooks-capture-payload-mjs. So an agent-term recall channel already exists in partial form; anyone measuring 'should we add grep terms as a signal' must subtract what the nudge already does.\n\n## Steps\n\n1. `hooks/kb-recall.mjs` (`recallQuery`) — UserPromptSubmit feed — strips harness wrappers BEFORE the 2000-char slice\n2. `hooks/recall-query.mjs` (`stripHarnessWrappers`) — shared prompt hygiene for all three hosts; named tags only, so real questions survive\n3. `hooks/preguard-handler.mjs` (`canonicalFindKey`) — the OTHER feed — wired on every Bash call, and the nudge path puts tool-call text into recall\n4. `src/kb/cli.ts` — --hook: strongOnly search, writes every decision to inject-log.jsonl (the evidence for both feeds)\n5. `src/kb/search.ts` (`kbSearch`) — scores whatever arrives; the path override treats any contained anchor path as the user naming that file\n\n## Invariants\n\n- inject-log.jsonl query strings are NOT all user prompts — some are agent tool-call text, so any corpus study over it must classify the feed first\n- stripping belongs in the hooks; search.ts stays feed-agnostic so tool mode keeps honouring literally-typed paths","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-kb-recall-mjs-bb2f72e8","hooks-preguard-handler-mjs-e53f8b7b","hooks-recall-query-mjs-6503796e","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs"]},{"id":"tests-kb-shape-parity-test-ts-afd06d3a","type":"file","character":"single","title":"tests/kb-shape-parity.test.ts","aliases":["anchors come from steps","TOOL_DEFINITIONS","required note fields","spec shape drift","note shape drift test","every surface renders from table","warning folded note test","write time warning contract","requiredFieldsLine assertion","repair-aliases drift guard","identityAliases field name pin","pagination contract test","repair-aliases text drift","kb_repair_aliases description mismatch"],"status":"active","updated":"2026-08-02T18:19:44.646Z","edits":5,"anchors":[{"path":"tests/kb-shape-parity.test.ts","symbols":["shapeBlock","REQUIRED","SPEC_SHAPES","NOTE_CHECKS","checksForSpec","requiredFieldsLine","missingFieldsWarning","flowStepsWarning","unanchoredSteps","shapesBlock","TOOL_DEFINITIONS","aliasRepairWorklist","USER_COMMANDS","REPAIR_ALIASES_COMMAND"],"hash":"sha256:614e291ace82","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"Pins every consumer to hooks/note-shape.mjs so a required field cannot go missing from one surface again: each spec example must contain the fields its own checksForSpec demands, the write guide and capture prompt must both carry every example verbatim, the MCP kb_write description must contain requiredFieldsLine(), and a dedicated suite asserts no surface says a flow's anchors come from its steps. It also carries the write-time warning contracts (flowStepsWarning/missingFieldsWarning judge the fold, not the spec). A newer describe block, 'kb repair-aliases surfaces agree with each other and with the frozen field name', extends the same drift-guard idea to a field note-shape.mjs's SPEC_SHAPES never covers directly: identityAliases only appears in the repair-aliases worklist/MCP tool/USER_COMMANDS text, not in any spec an agent writes, so it pins those three surfaces to each other by hand (the exact 'identityAliases' string, the empty-notebook sentinel 'No file/flow notes to reconcile.', the offset/limit MCP schema props, and the 'no aliases at all' line distinguishing it from kb repair's own missing-identity-aliases check) rather than deriving them from a table the way SPEC_SHAPES lets the rest of this file do.","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"tests-kb-search-write-test-ts-0c3c0c6d","type":"file","character":"single","title":"tests/kb-search-write.test.ts","aliases":["ranking contract test","stale outranks fresh","superseded hard tier","kb search unit tests","metadata write test","verified stamp test","kb write unit tests"],"status":"active","updated":"2026-08-02T18:19:44.638Z","edits":4,"anchors":[{"path":"tests/kb-search-write.test.ts","symbols":["kbSearch","kbWrite","renderCompactPage","fakeIndex","writeRepoFile","seedLesson","strongOnly"],"hash":"sha256:96be90d6f342","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Unit tests for kb search ranking and kb write. Holds two contract regressions worth knowing before editing either area: 'staleness LABELS but does not rank' asserts a stale note covering every query term outranks a fresher note covering fewer while a superseded note stays last (this test asserted the OPPOSITE order until 2026-07-30, so an inverted expectation here means freshness has crept back into the sort); and 'a metadata-only write does NOT re-verify the anchor' asserts a title-only write records an empty `verified` and no hash, while a write carrying a summary re-stamps. Both fixtures write real files and drift them, so they exercise live hashing rather than mocked anchor state.","backlinks":[],"anchorLinks":[]},{"id":"tests-kb-retrieval-live-test-ts-f5d387f6","type":"file","character":"single","title":"tests/kb-retrieval-live.test.ts","aliases":["retrieval regression tests","injection floor tests","calibration tests","single carrier exemptions","tier number assertion","retrieval test without notesIndex","admission contract test"],"status":"active","updated":"2026-08-02T18:19:44.629Z","edits":6,"anchors":[{"path":"tests/kb-retrieval-live.test.ts","symbols":["kbSearch","notesIndex","seedCorpus","touch","noteLine","strongOnly"],"hash":"sha256:1ecfff69d579","state":"changed"}],"freshness":"changed","dir":"tests","outLinks":[],"body":"Live retrieval tests over a real seeded notebook — the hook-mode admission contracts live here, so this is the file that tells you whether a ranking change is intentional or a regression. Two things to know before editing. First, most tests here call kbSearch WITHOUT notesIndex, which means convergence cannot fire and every hit is name-channel-only; a change that penalises name-only hits will fail tests that look unrelated (stemming, matcher repairs) for that reason alone rather than because stemming broke. Second, 'convergence stands alone only when the term is also rare' asserted the OPPOSITE contract until 2026-07-31 — it was named 'convergence bypasses the suppression gate' and its setup deliberately pushes a term out of the rare band with six body-only decoy notes so that convergence is the only thing that could admit it. That exact shape is now the junk case, so the test asserts both halves: common+converged stays suppressed, rare+converged still injects on a single carrier. If you are relaxing the rarity requirement, this test is the one that should stop you.","backlinks":[],"anchorLinks":[]},{"id":"tests-kb-fold-test-ts-363d2ac8","type":"file","character":"single","title":"tests/kb-fold.test.ts","aliases":["fold determinism test","alias cap regression","shuffled records fold identically","capIdentity test"],"status":"active","updated":"2026-08-02T18:19:44.612Z","edits":4,"anchors":[{"path":"tests/kb-fold.test.ts","symbols":["fold","stableStringify","capAliases","ALIAS_MAX","ALIAS_MAX_WORDS","put"],"hash":"sha256:8e41124f3672","state":"fresh"}],"freshness":"fresh","dir":"tests","outLinks":[],"body":"fold.ts unit tests. Added a case for fold(..., {capIdentity:false}): asserts the uncapped result is a strict superset of the capped one and includes aliases the cap would have dropped (reuses the same 5-write/30-alias fixture the existing cap test already builds).","backlinks":[],"anchorLinks":[]},{"id":"src-watcher-ts-0eb096ed","type":"file","character":"single","title":"src/watcher.ts","aliases":["watcher loop","keeper self-write loop","excluded dir watcher"],"status":"active","updated":"2026-08-02T18:19:44.604Z","edits":6,"anchors":[{"path":"src/watcher.ts","symbols":["startWatcher","isUnderExcludedDir","EXTENSION_TO_LANGUAGE","onNotebookRaw","BatchHandler"],"hash":"sha256:a2b29ceb0b4d","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"Debounced (400ms) recursive fs.watch wrapper that feeds the keeper two separate routes: notebook .raw/*.jsonl events go to onNotebookRaw, everything else is filtered to indexed extensions and goes to the code batch. The non-obvious hazard, verified here: .html and .md ARE both present in EXTENSION_TO_LANGUAGE, so the keeper's own writes under .coldstart/ (it regenerates notebook/index.html and re-renders derived .md on every notes refresh) used to clear the extension filter and re-enter the code batch as 'repo changed' - a self-feeding loop that re-saved the cache and regenerated the view about every 5s. Fixed in #92 by the isUnderExcludedDir guard, which mirrors the walker's hidden/excluded-dir rules and is shared with patch so the rule cannot drift. The .raw/*.jsonl route is checked BEFORE the extension filter, which is why real note writes still refresh the view.","backlinks":[],"anchorLinks":[]},{"id":"src-unwire-ts-aab82fa6","type":"file","character":"single","title":"src/unwire.ts","aliases":["unwire","deinit","leftover wiring","uninstall","repair-notes removal","init unwire symmetry","rmEmptyDirs","strip slash commands","no unwire tests","repair-aliases sweep"],"status":"active","updated":"2026-08-02T18:19:44.595Z","edits":4,"anchors":[{"path":"src/unwire.ts","symbols":["runUnwire","stripHooksConfig","unwireJsonMcp","removeFile","rmEmptyDirs"],"hash":"sha256:292d6038573c","state":"fresh"}],"freshness":"fresh","dir":"src","outLinks":[],"body":"The explicit reverse of init. Now sweeps THREE user-invoked commands (capture-notes, repair-notes, repair-aliases) across all three hosts using the same REPAIR_ALIASES_COMMAND constant init.ts exports — symmetric with how init writes them, verified live (init writes 2 command files per host, unwire removes both and prunes the now-empty skill dir).","backlinks":[],"anchorLinks":[]},{"id":"src-kb-write-guide-ts-c9053885","type":"file","character":"single","title":"src/kb/write-guide.ts","aliases":["symbols missing from file notes","empty anchor symbols","write guide shapes","missing aliases warning","under-indexed note","required note fields","symbols in file note","put is not overwrite","warning judges folded note","kb write guide","mcp cli parity","flow evidence warning"],"status":"active","updated":"2026-08-02T18:19:44.544Z","edits":14,"anchors":[{"path":"src/kb/write-guide.ts","symbols":["WRITE_GUIDE_SHAPES","flowEvidenceWarning","flowStepsWarning","writeGuideCli","writeGuideMcp","missingFieldsWarning","flowEvidenceCount"],"hash":"sha256:bfd678a3e8b5","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"Single source for the kb write spec guide and every write-time WARN, shared by the CLI (kb write, no spec -> guide) and MCP kb_write (parity: identical semantics, only the howto tail differs). flowEvidenceCount scans tmpdir capture markers from ALL THREE hosts (coldstart-kb-/coldstart-cursor-kb-/coldstart-codex-kb- prefixes) for the session's content-read set. This file NO LONGER OWNS THE SHAPES: WRITE_GUIDE_SHAPES is shapesBlock() from hooks/note-shape.mjs and missingFieldsWarning is a loop over checksForSpec(type), so what warns here and what kb repair detects on disk cannot disagree. THE RULE EVERY WARN HERE MUST FOLLOW, learned twice: judge the FOLDED note, never the record just sent. `op: put` appends a record and the note is the fold of the whole log (aliases/anchors union, summary/steps LWW), so a partial update legitimately omits fields it is not changing. flowStepsWarning was fixed for this first — it takes the folded note and delegates to stepsMissingAfterWrite. missingFieldsWarning had the identical defect four lines down and was fixed 2026-08-01: it now takes an optional `after` and a field counts as missing only when missingInSpec(spec) AND missingInNote(after). The AND matters — swapping outright to missingInNote would make the repair-only checks (flow-no-steps, flow-steps-unanchored, both missingInSpec:()=>false) start firing at write time and duplicate flowStepsWarning. With no `after` it falls back to the spec, which is exact for a create.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — renders the guide and the write-time warning from the table","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"src-kb-session-worklist-ts-dc6104ba","type":"file","character":"single","title":"src/kb/session-worklist.ts","aliases":["capture coverage","under-capture reporting","worklist manifest reader","coverage denominator fresh notes","flow does not count as file note"],"status":"active","updated":"2026-08-02T18:19:44.526Z","edits":4,"anchors":[{"path":"src/kb/session-worklist.ts","symbols":["noteCoverage","specPaths","manifestPath","load"],"hash":"sha256:4e1e7af12a3b","state":"missing"}],"freshness":"missing","dir":"src/kb","outLinks":[],"body":"Reads the session worklist manifest that hooks/capture-payload.mjs drops in tmpdir and turns it into the coverage line `kb write` prints. noteCoverage(sid, spec) appends this write's paths to the manifest's `wrote` array, then reports done/outstanding. Two deliberate arithmetic choices: files whose note is already fresh are EXCLUDED from the denominator (counting them makes full coverage unreachable and the ratio meaningless, though they are still reported as 'N more already had a fresh note'), and specPaths() credits only file-single/file-hub — a flow does NOT count as a note for its step files, because a flow is not the per-file note rule 5 asks for. Everything is best-effort: no session, no manifest, a malformed one, or one older than 24h (a resumed session) all return null rather than throwing. The manifest lives in tmpdir and never in the repo, so it cannot be committed and needs no ignore rule; it is scratch state for one session, not a record, and nothing about it leaves the machine.","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured"]},{"id":"src-kb-search-ts-272e86f3","type":"file","character":"single","title":"src/kb/search.ts","aliases":["lane 2 anchor admission phantom evidence","tool mode vs hook mode search gates","notebook search precision","domain word rarity","anchor channel inflates df","hook mode rarity gate","ecommerce domain noun problem","rareMax vs minority threshold","hardEvidence flag"],"status":"active","updated":"2026-08-02T18:19:44.517Z","edits":19,"anchors":[{"path":"src/kb/search.ts","symbols":["kbSearch","KbSearchOptions","KbSearchHit","KbSearchResult","strongOnly","HOOK_MIN_CARRIERS","NAME_ONLY_MIN_DENSITY","rarityMax","isCodeShaped","wordHit","hookNameNorm","haystacksFor","resolveTermToAnchors","resolveTermToSymbolFiles","symbolTokens","absenceVerdict","renderSearchPage","renderCompactPage","gistLines","shouldImplantTop","stem","renderResultsPage"],"hash":"sha256:51e1afe7535c","state":"changed"},{"path":"hooks/capture-payload.mjs","hash":"sha256:cd323aa5c322","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"The notebook search engine, in two modes chosen by strongOnly (hook = precision-first admission gates; tool = BM25, no gates). HOOK-MODE RARITY (separate from the tool-mode lane-2 phantom evidence already noted here): df at L430 is document frequency across name+anchor+body COMBINED, so a term that is a widely-declared anchor symbol inflates its own df even when it never appears in prose. Two different thresholds use it: eligibility (`minority`, L510, df*2<=notes.length, ~50%) drops a term from scoring entirely if it fails; hardEvidence (`rareMax=ceil(N/10)`, L178/516/543) requires the stricter top-10% band before a symbol-convergence hit can admit a note alone, UNLESS the term is code-shaped (isCodeShaped, L278) which bypasses rarity outright. Risk: in a domain-concentrated codebase a real entity name (e.g. an ecommerce Order/Shipment declared as an anchor symbol on many file notes) can fail hardEvidence's rarity band via the SAME mechanism that correctly suppresses generic filler (run/status/write) -- notebook-wide df does not distinguish 'generic English' from 'domain-central but frequent'. Untested on this repo's own notebook (too small/self-referential); needs a real domain-heavy notebook (e.g. ARCHES) to size.","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","how-a-note-s-freshness-gets-claimed-and-checked","how-an-agent-finds-out-it-under-captured","how-notebook-capture-fires-v5-trigger-timed","what-counts-as-the-query-for-notebook-recall","where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"src-kb-raw-log-ts-ba590d64","type":"file","character":"single","title":"src/kb/raw-log.ts","aliases":["anchor hash written here","appendRecord","raw log append","verified triggers hashing","note provenance stamp"],"status":"active","updated":"2026-08-02T18:19:44.501Z","edits":3,"anchors":[{"path":"src/kb/raw-log.ts","symbols":["appendRecord","readLog","listIds","rawPath","rawDir","notebookDir","KB_RAW_VERSION","AppendOptions","ReadLogResult"],"hash":"sha256:0815f155b48a","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"Appends one JSON line per note record and is the ONLY producer of anchor hashes: for every path listed in a record's `verified`, appendRecord hashes that file at append time and writes the hash into the record's anchor (creating the anchor if absent). Agents never author hashes. It also stamps `v`, `ts`, and the git `head` as provenance, overriding any agent-supplied head. A record with an empty or absent `verified` carries no hash at all, which is what lets the fold keep a note's earlier verification intact.","backlinks":[],"anchorLinks":["how-a-note-s-freshness-gets-claimed-and-checked"]},{"id":"src-kb-freshness-ts-8278f01b","type":"file","character":"single","title":"src/kb/freshness.ts","aliases":["evidence changed","note freshness","stale note","is a note still valid","does freshness depend on git","branch switch note freshness"],"status":"active","updated":"2026-08-02T18:19:44.492Z","edits":3,"anchors":[{"path":"src/kb/freshness.ts","symbols":["hashFile","stampAnchors","freshnessLine","anchorsAllMissing","RenameMap"],"hash":"sha256:7a81ff09fde6","state":"fresh"}],"freshness":"fresh","dir":"src/kb","outLinks":[],"body":"The hash tripwire behind [fresh]/[evidence changed]. Verified 2026-07-24: freshness has NO git dependency whatsoever — grepping this file for 'head' returns zero matches. hashFile is a whole-file raw-byte SHA-256 (first 12 hex, never per-symbol) and stampAnchors compares each anchor's stored hash against the live file NOW, so an anchor's recorded `head` commit is never consulted here. Consequence worth knowing before assuming otherwise: note freshness is content-addressed, not commit-addressed, and therefore survives branch switches and would survive notes living outside git entirely. A missing file resolves through the keeper's rename map only when the destination's live content still equals the recorded hash, so a stale rename hint can never resurrect a note wrongly.","backlinks":[],"anchorLinks":[]},{"id":"src-kb-cli-ts-99b5d5ba","type":"file","character":"single","title":"src/kb/cli.ts","aliases":["flow decision one call","kb write decision flag","coverage line kb write","N of M files noted","warnings never fail write","exit code 3 candidates","kb verb dispatcher","exit code 3","kb write warnings order","repair-aliases verb","offset limit flags"],"status":"active","updated":"2026-08-02T18:19:44.475Z","edits":15,"anchors":[{"path":"src/kb/cli.ts","symbols":["cmdWrite","cmdSearch","runKb","recordFlowDecision","parseKbArgs","cmdLookup","cmdLint","requireNotebook","USAGE","missingFieldsWarning","flowStepsWarning"],"hash":"sha256:57f5ef7e46af","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"The kb verb dispatcher. New verb `repair-aliases [--offset N] [--limit 10] [--json]` calls planAliasRepair/aliasRepairWorklist from alias-repair.ts — pure read, paginated, never writes. Like `repair`, it deliberately does not call ensureKeeper (reads only the folded notebook).\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — exposes repair detection as a CLI verb","backlinks":[],"anchorLinks":["how-an-agent-finds-out-it-under-captured","what-counts-as-the-query-for-notebook-recall","where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about"]},{"id":"site-index-html-f8b5f3ae","type":"file","character":"single","title":"site/index.html","aliases":["meta keywords","JSON-LD structured data","og image","landing page marketing site","blog cards","featured posts","article-card","SEO"],"status":"active","updated":"2026-08-02T18:19:44.416Z","edits":10,"anchors":[{"path":"site/index.html","hash":"sha256:405d3b4d0b9b","state":"changed"}],"freshness":"changed","dir":"site","outLinks":[],"body":"The #blog section near the end features exactly TWO hand-picked article cards linking into site/blog/; they are hardcoded and do not read from blog.html, so adding or renaming a post silently leaves stale links here. Those cards are styled by .article-card in the sibling styles.css, NOT by docs.css which the blog pages themselves use.","backlinks":[],"anchorLinks":[]},{"id":"site-docs-css-54e94142","type":"file","character":"single","title":"site/docs.css","aliases":["ch unit measure bug","essay column alignment","figure wider than text","diagram overflows the column","svg figure","hand drawn diagram","feTurbulence","sketch style","figcaption monospace","prefers-color-scheme","measure","dark mode"],"status":"active","updated":"2026-08-02T18:19:44.406Z","edits":11,"anchors":[{"path":"site/docs.css","hash":"sha256:8b82bb1e4718","state":"changed"}],"freshness":"changed","dir":"site","outLinks":[],"body":"The shared stylesheet for BOTH non-landing surfaces: docs.html (sidebar reference layout, body.docs-page) and every blog page (body.essay-page). The landing page uses styles.css instead, so .article-card on index.html is NOT styled here. The blog section at the end scopes its OWN theme tokens to body.essay-page: light by default with a prefers-color-scheme dark override, which is why docs.html stays dark while the blog follows the reader's OS. --measure MUST stay an absolute length (680px) and never ch: ch resolves against each element's own font-size, so a 46px h1 and a 19px p computed different widths and margin-inline:auto then centred every child of .essay-article on a different left edge (fixed in #105). Two widths govern essay layout and they differ on purpose: `.essay-article > *` constrains every child to --measure, while `.essay-article > .wide` opts out to min(920px,100%) — that 240px gap is why figures visibly overhang the prose column. The FIGURES block (added #111) styles inline-SVG diagrams: the hand-drawn look is a seeded feTurbulence displacement applied per figure, and the filtered <g> must contain ONLY shapes because displaced text is unreadable. It also overrides `.essay-article figcaption`, whose base rule sets font-family:var(--mono) and rendered diagram captions as code comments.","backlinks":[],"anchorLinks":[]},{"id":"scripts-replay-recall-gates-mjs-6f8d13d2","type":"file","character":"single","title":"scripts/replay-recall-gates.mjs","aliases":["recall replay harness","measure recall outside coldstart","compare two builds","hook mode assertion","tool mode replay","noMissLog replay"],"status":"active","updated":"2026-08-02T18:19:44.397Z","edits":3,"anchors":[{"path":"scripts/replay-recall-gates.mjs","symbols":["kbSearch","loadKbNotesIndex","loadAll","arg","strongOnly","noMissLog","notesIndex"],"hash":"sha256:923c50687d2a","state":"changed"}],"freshness":"changed","dir":"scripts","outLinks":[],"body":"Replays a notebook's logged prompts through kbSearch and diffs two builds, so a recall change can be measured on a notebook that is NOT this repo's — the reason it exists is that coldstart's own notebook is ~44 notes about coldstart, where the junk cause the gates target barely occurs. Used by humans only: nothing imports it, it is invoked as `node scripts/replay-recall-gates.mjs --root <repo> --dist <coldstart>/dist [--mode hook|tool] [--out f.json]`, then `--compare before.json after.json`. Its reason for printing the options it used is a real incident: KbSearchOptions has NO `hook` field, so {hook:true} silently runs TOOL mode with convergence off, which voided an entire measurement — the header line is the assertion that the run is the mode you think. `--mode tool` exists because every admission gate in kbSearch is wrapped in `if (opts.strongOnly)` while the fold runs upstream of both modes, so an alias-side change can move `kb search` results while looking invisible in hook mode. Read-only on the target repo: it passes noMissLog so the replay does not pollute that repo's metrics.","backlinks":[],"anchorLinks":[]},{"id":"how-an-agent-finds-out-it-under-captured","type":"flow","character":null,"title":"how an agent finds out it under-captured","aliases":["capture coverage","under-capture reporting","N of M files noted","worklist manifest","capture coverage line"],"status":"active","updated":"2026-08-02T18:19:44.379Z","edits":5,"anchors":[{"path":"hooks/capture-payload.mjs","hash":"sha256:ea825a4f366c","state":"changed"},{"path":"src/kb/session-worklist.ts","hash":"sha256:4e1e7af12a3b","state":"missing"},{"path":"src/kb/cli.ts","hash":"sha256:0e915261a609","state":"changed"}],"freshness":"missing","dir":"hooks","outLinks":[],"body":"An agent's own note count is the one thing it cannot check while writing, because kb write sees one spec at a time and never saw the worklist — so the worklist is handed forward out-of-band, through a tmpdir file keyed by session id, and comes back as a ratio printed with each write. The import graph cannot see this link at all: hooks/capture-payload.mjs (an .mjs hook) and src/kb/session-worklist.ts (the TS CLI) never import each other and agree only on a filename template, tmpdir/coldstart-kb-worklist-<sid>.json. Change the name or the record shape on one side and coverage silently stops printing — there is no error, because every read is best-effort by design.\n\n## Steps\n\n1. `hooks/capture-payload.mjs` (`buildCapturePayload`, `recordWorklistManifest`, `worklistManifestPath`) — the one point every host passes through — writes the manifest (path, tier, needsNote) as a side effect of building the prompt\n2. `src/kb/session-worklist.ts` (`noteCoverage`, `specPaths`) — reads it back, records this write, computes done vs outstanding\n3. `src/kb/cli.ts` (`cmdWrite`) — prints the line under the write's own output, so it lands mid-Bash-block while the agent is still writing\n\n## Invariants\n\n- The manifest filename and record shape are a contract between an .mjs hook and TS source that never import each other — change both sides together.\n- The session id the agent passes to `kb write --session` must be the same sid the capture prompt was built with, or there is no manifest and coverage is silent.\n- Silence is a valid outcome (no session, no manifest, stale, malformed) — coverage must never fail a write.\n- The denominator counts only files that needed a note; already-fresh files are excluded so full coverage stays reachable.","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches","why-a-note-cannot-be-found-by-the-symbol-it-is-about","hooks-capture-payload-mjs-9f99e00d","how-notebook-capture-fires-v5-trigger-timed","src-kb-cli-ts-99b5d5ba","src-kb-search-ts-272e86f3","src-kb-session-worklist-ts-dc6104ba","what-counts-as-the-query-for-notebook-recall"]},{"id":"how-a-note-s-freshness-gets-claimed-and-checked","type":"flow","character":null,"title":"how a note's freshness gets claimed and checked","aliases":["freshness stamping","evidence changed label","anchor hash","verified field","note marked fresh wrongly"],"status":"active","updated":"2026-08-02T18:19:44.371Z","edits":2,"anchors":[{"path":"src/kb/write.ts","hash":"sha256:38e7ca9a095a","state":"changed"},{"path":"src/kb/raw-log.ts","hash":"sha256:0815f155b48a","state":"fresh"},{"path":"src/kb/search.ts","hash":"sha256:7de67121ff4b","state":"changed"}],"freshness":"changed","dir":"src/kb","outLinks":[],"body":"A note's freshness is a CLAIM the writer makes, not something derived from the note's content: `verified` in a write spec is what causes a file's live hash to be recorded, and read time only compares that recorded hash against the file now. Nothing re-reads the file to decide if a note is still true, so whoever writes decides what counts as verified — which is why a write that carries no knowledge must not stamp.\n\n## Steps\n\n1. `src/kb/write.ts` (`kbWrite`) — decides what goes in `verified` — the anchor path is added only when the spec carries knowledge implying a read (summary/facets/body); an explicit `verified` from the agent always wins\n2. `src/kb/raw-log.ts` (`appendRecord`) — the only place a hash is produced: for each `verified` path it hashes the file NOW and writes it into the record's anchor. The agent never writes hashes itself\n3. `src/kb/search.ts` (`kbSearch`) — read time — stampAnchors compares each stored anchor hash against the live file and labels the result; since 2026-07-30 that label does not affect rank\n\n## Invariants\n\n- a record with no `verified` carries no hash, and the fold preserves the note's previous hash — so a metadata-only edit cannot reset freshness\n- freshness has no git dependency: the comparison is hash-vs-file, and `head` is provenance only","backlinks":[],"anchorLinks":["why-a-note-cannot-be-found-by-the-symbol-it-is-about","src-kb-raw-log-ts-ba590d64","src-kb-search-ts-272e86f3","src-kb-write-ts-d5968d80","what-counts-as-the-query-for-notebook-recall","why-a-file-note-s-extra-anchors-can-never-carry-symbols"]},{"id":"hooks-trigger-mjs-36ac51eb","type":"file","character":"single","title":"hooks/trigger.mjs","aliases":["arm threshold","descent one quiet stop","synthesis counts as quiet","surge removed","cap fires inject","T_ARM","MIN_FILES","score threshold","arming","fresh note discount","arm threshold too high","T_ARM unreachable","only fires on commit","head-drift starves descent","armed false forever","quiet stops no capture","stop hook firing rate low","why no notes captured"],"status":"active","updated":"2026-08-02T18:19:44.362Z","edits":23,"anchors":[{"path":"hooks/trigger.mjs","symbols":["step","initialState","T_ARM","T_CAP","MIN_FILES","MIN_FILES_ARM","DESCENT_QUIET","SETTLE_ACTIVE_STOPS","MAX_CAPTURE_FILES"],"hash":"sha256:d5d41f6fd44c","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Pure capture state machine, no I/O or clock. score = uncaptured files x1 + settled edits x2 + ALL stops since the last fire; arm at T_ARM=10 requiring >=1 active stop and >=1 uncaptured file (MIN_FILES_ARM); fires descent (1 quiet stop, INJECT), cap@20 (INJECT), or headDrift (BLOCK) - the last two keep the >=2-file MIN_FILES floor. CORRECTION 2026-07-24: this note previously blamed T_ARM=10 being 'out of range for normal session size'. That diagnosis was WRONG and is retracted. The real cause of descent never firing (104 stops / 24 fires / 0 descent) was a regression - the score's stop term read activeStops, and once synthesis turns were reclassified as quiet they no longer incremented it, so a discussion session had NO score-growth term at all and froze at ~4. T_ARM=10 is reachable and unchanged. Two other tempting fixes are also replay-falsified: stopping head-drift from resetting activeStops (still 0 descent fires), and lowering T_ARM.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-recall-seen-mjs-27dd2674","type":"file","character":"single","title":"hooks/recall-seen.mjs","aliases":["recall dedup state","seen ids file","pointer page id parsing","recall dedup","seen note ids","dedup state file","kb search --seen","same note injected twice","repeated note injection","compaction resets recall","compaction reset","transcript shrink detection","tmpdir not slash tmp"],"status":"active","updated":"2026-08-02T18:19:44.354Z","edits":11,"anchors":[{"path":"hooks/recall-seen.mjs","symbols":["readSeen","writeSeen","idsInPage","seenArgs","seenPath","transcriptSize"],"hash":"sha256:5797d3a94eb2","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Per-session recall dedup state shared by all three recall hooks (kb-recall.mjs, cursor-kb-recall.mjs, codex-kb-recall.mjs each import readSeen/writeSeen/idsInPage/seenArgs) so their behaviour cannot drift; created 2026-07-30 after the dedup shipped Claude-only and Cursor/Codex kept re-showing notes. State lives at os.tmpdir()/coldstart-recall-seen-<sid>.json — deliberately NOT literal /tmp, which is reserved for the find_nudge state file the nudge handler reads back by an agreed literal path. The seen set resets when the transcript file SHRINKS (a compact) rather than on a clock, because after a compact the session id is unchanged but the context is gone, so a previously-shown note is genuinely absent again; a host that exposes no transcript path (ephemeral Codex runs) simply never resets, which is the safe direction. idsInPage parses ids back out of the RENDERED pointer page via the '-> open: .../<id>.md' line, so the hooks need no structured output from the CLI. Every function is fail-open: any error leaves dedup off rather than blocking recall. Verified E2E on all three hooks this session: inject -> silent -> transcript shrinks -> inject, and inject -> silent with no transcript path.","backlinks":[],"anchorLinks":[]},{"id":"hooks-recall-query-mjs-6503796e","type":"file","character":"single","title":"hooks/recall-query.mjs","aliases":["harness boilerplate in the query","inject-log truncates the query"],"status":"active","updated":"2026-08-02T18:19:44.346Z","edits":14,"anchors":[{"path":"hooks/recall-query.mjs","symbols":["recallQuery","stripHarnessWrappers","HARNESS_TAGS"],"hash":"sha256:4a146b7ec842","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"Shared prompt->query hygiene for all three recall hooks: stripHarnessWrappers removes HARNESS_TAGS (system-reminder, ide_opened_file, ide_selection, ide_diagnostics, task-notification, local-command-caveat/stdout/stderr, command-name/message/args, user-prompt-submit-hook, browser_instruction, environment_context, user_instructions) as well-formed pairs (4 nested passes) plus leftover lone tags, and recallQuery strips BEFORE slicing to maxChars so a 1.5KB <ide_selection> cannot eat the budget ahead of the real question. Only the NAMED tag set is stripped; user-pasted XML is left alone; fail-open returns the raw text. CORRECTION 2026-08-02: this note previously said the file HAD NEVER RUN IN PRODUCTION because the wired hook pointed at an npm install with no recall-query.mjs - that is now FALSE; the published @cstart/coldstart 2.2.11 install ships hooks/recall-query.mjs, so the stripping is live. The measured finding behind it still stands: with the caveat block left in, the word 'commands' from the boilerplate 'while running local commands' added +7.9 to src/init.ts and promoted it rank 4 -> rank 2, via the path-name override in src/kb/search.ts. Still true for analysis: the inject-log stores only query.slice(0,200), so replays of logged queries score a CLEANER string than production used and measured junk rates understate the live rate.","backlinks":[],"anchorLinks":["what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-preguard-handler-mjs-e53f8b7b","type":"file","character":"single","title":"hooks/preguard-handler.mjs","aliases":["preguard does not block grep","PreToolUse hook produces no output on Bash","matcher widened but handler narrow"],"status":"active","updated":"2026-08-02T18:19:44.337Z","edits":5,"anchors":[{"path":"hooks/preguard-handler.mjs","symbols":["handle"],"hash":"sha256:f136ff422137","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"PreToolUse handler wired by init.ts with matcher `Bash|mcp__coldstart__find`, so it runs on EVERY Bash call — but it is only a dedup guard for `coldstart find`, not an anti-grep mechanism: canonicalFindKey(cmd) returns null for any non-find command and the handler returns null immediately, so grep/rg/git-grep/find shell through untouched with no output. Anti-grep spiral coverage lives in the PostToolUse nudge-handler.mjs instead (fires on tool===\"Grep\" or Bash matching SEARCH_RE), i.e. coldstart reacts AFTER the grep is paid for, never before. Denies only an exact repeat of a term-set+flags already run successfully this session (state in /tmp/find_nudge_{sid}_{aid}.json, written by the PostToolUse hook); fail-open on any error.","backlinks":[],"anchorLinks":["what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-note-shape-mjs-d85ce294","type":"file","character":"single","title":"hooks/note-shape.mjs","aliases":["one note shape table","required note fields","NOTE_CHECKS","SPEC_SHAPES","shapesBlock","requiredFieldsLine","shape drift","hooks cannot import dist","add a note requirement","missingInSpec missingInNote"],"status":"active","updated":"2026-08-02T18:19:44.328Z","edits":2,"anchors":[{"path":"hooks/note-shape.mjs","symbols":["SPEC_SHAPES","NOTE_CHECKS","shapesBlock","requiredFieldsLine","checksForSpec","checksForNote","unanchoredSteps","stepsMissingAfterWrite","REPAIR_CONTRACT_VERSION"],"hash":"sha256:c42cfbd8820f","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"],"body":"THE frozen definition of what a notebook note must carry to be findable, and the only place the spec shapes are written down. SPEC_SHAPES holds one example string per spec type (file-single/file-hub/flow/lesson) rendered by shapesBlock({compact}) — compact drops the prose for the capture prompt, both emit the SAME examples. NOTE_CHECKS holds one entry per way a note ends up unfindable, each with TWO predicates: missingInSpec (the JSON just written) and missingInNote (the folded note). It lives in hooks/ and not src/ because the capture hooks never import from dist/; the TS side imports it across directories and tsc's rootDir does NOT object (types come from note-shape.d.mts beside it). Template literals here open with a newline so dedent() can strip the common prefix and keep RELATIVE indentation — that is what makes a JSON example's continuation lines line up under it.\n\n## Part of\n\n- [[where-the-required-note-shape-is-defined-and-how-it-reaches]] — the table every other surface renders from","backlinks":[],"anchorLinks":["where-the-required-note-shape-is-defined-and-how-it-reaches"]},{"id":"hooks-kb-recall-mjs-bb2f72e8","type":"file","character":"single","title":"hooks/kb-recall.mjs","aliases":["recall dedup","recall hook claude","UserPromptSubmit recall","pointer page injection","pending capture first","same note injected twice","seen ids file","compaction resets recall","transcript shrink detection","cursor codex no dedup","seen ids"],"status":"active","updated":"2026-08-02T18:19:44.318Z","edits":11,"anchors":[{"path":"hooks/kb-recall.mjs","symbols":["recallQuery","takePendingCapture","readSeen","writeSeen","idsInPage","seenArgs"],"hash":"sha256:a82ef1040d11","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"UserPromptSubmit recall hook for Claude Code: shells out to `kb search --hook --max 3`, delivers any pending capture FIRST, and injects a pointer page (title + gist + path) as hookSpecificOutput.additionalContext. It reads input.transcript_path and passes it with the session id to the shared dedup helpers, harvesting shown ids back out of the RENDERED page so no structured output is needed. CORRECTS this note's own earlier claims (same day): the dedup state handling NO LONGER lives here — it moved to hooks/recall-seen.mjs so the three recall hooks cannot drift — and dedup is NO LONGER Claude-only; cursor-kb-recall.mjs and codex-kb-recall.mjs were ported in the same PR and verified to behave identically.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed","how-the-co-change-signal-reaches-an-agent-that-never-runs-gs","what-counts-as-the-query-for-notebook-recall"]},{"id":"hooks-ignore-mjs-1a07e730","type":"file","character":"single","title":"hooks/ignore.mjs","aliases":["coldstartignore","ignored files still in find","files that never get notes"],"status":"active","updated":"2026-08-02T18:19:44.300Z","edits":3,"anchors":[{"path":"hooks/ignore.mjs","symbols":["loadIgnore","compileIgnore","DEFAULT_IGNORES","patternToRegex"],"hash":"sha256:6b5fde7d5dc4","state":"fresh"}],"freshness":"fresh","dir":"hooks","outLinks":[],"body":"The .coldstartignore matcher: shipped DEFAULTS (json, lockfiles, build output, .env*, binaries) live here in code; the user file at .coldstart/.coldstartignore (personal — gitignored via a committed .coldstart/.gitignore) only adds or negates on top. Scope is notebook-only PERMANENTLY (owner decision 2026-07-17): it filters capture evidence and note surfacing, NEVER find/gs navigation.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-cursor-kb-elicit-mjs-151bef1e","type":"file","character":"single","title":"hooks/cursor-kb-elicit.mjs","aliases":["cursor capture","followup_message","loop_count guard"],"status":"active","updated":"2026-08-02T18:19:44.273Z","edits":3,"anchors":[{"path":"hooks/cursor-kb-elicit.mjs","symbols":["extractCursorEvidence","segmentStatsCursor","step","initialState","writePendingCapture","buildCapturePayload","worklistEntries","cursorRoot","loadIgnore","freshNotedSet","gitHead","logCaptureEvent"],"hash":"sha256:5d466a726425","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Cursor stop/subagentStop capture — the FULL v5 trigger port. Processes only loop_count===0 turns (followup_message re-fires stop); blocking channel is {followup_message}; non-blocking fires write the same pending file that cursor-kb-recall delivers via beforeSubmitPrompt additional_context. LIVE-UNTESTED as of 2.2.0 — validated against stored real transcripts and hook-level tests only.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-codex-kb-recall-mjs-cd4df13f","type":"file","character":"single","title":"hooks/codex-kb-recall.mjs","aliases":["codex recall hook","recall hooks differ","per host verification","ephemeral codex no transcript","session id binding"],"status":"active","updated":"2026-08-02T18:19:44.263Z","edits":4,"anchors":[{"path":"hooks/codex-kb-recall.mjs","symbols":["recallQuery","readSeen","writeSeen","idsInPage","seenArgs"],"hash":"sha256:bf6aec34f7cd","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Codex recall hook. Verified this session: its handler body is structurally DIFFERENT from kb-recall.mjs and cursor-kb-recall.mjs even though all three share recallQuery and recall-seen — it early-exits when there is no notebook, has no pending-capture delivery, and wraps its search call in a plain try rather than the nested-if the other two use. A scripted edit written against the Claude/Cursor shape silently no-ops here (that happened this session: the shared-import patch applied, the call-site patch did not, and only a grep caught it). Verify per-host after any change that touches all three. The sanitized session id is bound once at the top of the handler and reused by both the dedup call and the find_nudge arming block, which previously re-derived its own unsanitized copy. Codex ephemeral runs expose no rollout path, so transcript_path is often absent and the compaction reset simply never fires.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"hooks-codex-kb-elicit-mjs-9cb55b18","type":"file","character":"single","title":"hooks/codex-kb-elicit.mjs","aliases":["codex capture one shot","stop fires at exit","codex hook trust re-prompt"],"status":"active","updated":"2026-08-02T18:19:44.253Z","edits":3,"anchors":[{"path":"hooks/codex-kb-elicit.mjs","symbols":["extractCodexEvidence","buildCapturePayload","worklistEntries","logCaptureEvent","loadIgnore"],"hash":"sha256:28f2f4216da9","state":"changed"}],"freshness":"changed","dir":"hooks","outLinks":[],"body":"Codex capture is deliberately ONE-SHOT v5, not the trigger machine: Codex's Stop fires once at session exit (TUI) or by construction (codex exec), so there is nothing to time and no next prompt for pending delivery — blocking {decision:block} at the single Stop, with a session-cumulative offered-set marker for resumed threads. Updating shipped hook files changes their hash, so Codex re-prompts its trust gate once after every coldstart update. LIVE-UNTESTED as of 2.2.0.","backlinks":[],"anchorLinks":["how-notebook-capture-fires-v5-trigger-timed"]},{"id":"github-workflows-npm-publish-yml-af3dbc50","type":"file","character":"single","title":".github/workflows/npm-publish.yml","aliases":["npm publish workflow","release trigger","publish to npm ci"],"status":"active","updated":"2026-08-02T18:19:44.232Z","edits":2,"anchors":[{"path":".github/workflows/npm-publish.yml","hash":"sha256:cccb7702c319","state":"fresh"}],"freshness":"fresh","dir":".github/workflows","outLinks":[],"body":"Publishes the package to npm. Triggers on `release: types: [created]` — NOT on a push or a tag by itself, so a `gh release create` (or the GitHub UI 'create release' action) is what actually fires it, not `git push --tags` alone. It does NOT run the test suite before publishing (no `npm test` step) — checkout, `npm ci`, `npm run build`, then `npm publish --provenance --access public` reading `NODE_AUTH_TOKEN` from the `NPM_TOKEN` secret. `--access public` is required alongside `--provenance` or npm refuses to generate provenance for what it would otherwise create as a private/restricted scoped package.","backlinks":[],"anchorLinks":[]},{"id":"dockerfile-6651ddff","type":"file","character":"single","title":"Dockerfile","aliases":["docker build sandbox","ripgrep postinstall download","ignore-scripts"],"status":"active","updated":"2026-08-02T18:19:44.221Z","edits":8,"anchors":[{"path":"Dockerfile","hash":"sha256:6a07ad14a17d","state":"fresh"}],"freshness":"fresh","dir":".","outLinks":[],"body":"Exists ONLY so MCP directory build sandboxes (Glama) can boot the server and run the introspection exchange — it is not a supported way to run coldstart, which is repo-local and needs a repository a container does not have. Two deliberate choices that look like mistakes: `npm ci --ignore-scripts` is there because the sole postinstall in the tree is @vscode/ripgrep downloading a prebuilt binary from GitHub, which network-restricted sandboxes may block — coldstart resolves a searcher at runtime and degrades to git grep/grep/Node scan, and this session confirmed a clean install leaves @vscode/ripgrep with no bin/ directory while the server still builds and answers; and `.dockerignore` excludes node_modules so the later `COPY . .` cannot clobber the modules from the npm ci layer. `npm prune --omit=dev` after the build was verified safe (53 packages dropped, all six tools still returned).","backlinks":[],"anchorLinks":[]}]};</script>
 <script>
 (function(){
   "use strict";
@@ -697,12 +706,12 @@ <h1 class="note-title">${esc(n.title)}</h1>
     ctx.clearRect(0,0,W,H);
     for(const [a,b,k] of G.E){const A=G.nodes[a],B=G.nodes[b],[ax,ay]=T(A.x,A.y),[bx,by]=T(B.x,B.y);
       const on=hover>-1&&(a===hover||b===hover);
-      ctx.strokeStyle=on?'rgba(31,79,216,.55)':'rgba(105,116,138,.20)';ctx.lineWidth=on?1.8:1;
+      ctx.strokeStyle=on?'rgba(15,111,140,.55)':'rgba(90,102,116,.20)';ctx.lineWidth=on?1.8:1;
       ctx.setLineDash(k?[4,4]:[]);
       ctx.beginPath();ctx.moveTo(ax,ay);ctx.lineTo(bx,by);ctx.stroke();}
     ctx.setLineDash([]);
     const cs=getComputedStyle(document.documentElement);
-    const cFile=cs.getPropertyValue('--file').trim(),cFlow=cs.getPropertyValue('--flow').trim();
+    const cFile=cs.getPropertyValue('--file-node').trim(),cFlow=cs.getPropertyValue('--flow-node').trim();
     G.nodes.forEach((n,i)=>{const[x,y]=T(n.x,n.y),r=Math.max(4,Math.min(13,4+n.deg*1.6)),isH=i===hover;
       ctx.beginPath();ctx.arc(x,y,r+(isH?2:0),0,7);ctx.fillStyle=n.type==='flow'?cFlow:cFile;
       ctx.globalAlpha=hover>-1&&!isH&&!G.E.some(([a,b])=>(a===hover&&b===i)||(b===hover&&a===i))?0.35:1;
diff --git a/site-astro/src/pages/blog/index.astro b/site-astro/src/pages/blog/index.astro
index bd3d936..ba11bfc 100644
--- a/site-astro/src/pages/blog/index.astro
+++ b/site-astro/src/pages/blog/index.astro
@@ -5,8 +5,8 @@ import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
-import '../../styles/backdrop.css';
 
 const posts = (await getCollection('blog')).sort(
   (a, b) => b.data.publishDate.valueOf() - a.data.publishDate.valueOf()
@@ -28,6 +28,11 @@ const jsonLd = {
     author: { '@type': 'Person', name: 'Akash Goenka' },
   })),
 };
+
+// Kicker temperature. The site colours the notebook/memory layer ember and the
+// index/measurement layer frost; the blog index was the last surface where the
+// topic was rendered in one colour regardless of what the post was about.
+const warmKickers = new Set(['Memory', 'Codebase memory', 'Codebase notes', 'Design']);
 ---
 <html lang="en">
 <head>
@@ -58,7 +63,7 @@ const jsonLd = {
   <section class="essay-list" aria-label="Blog">
     {posts.map((post) => (
       <a class="essay-card" href={`/blog/${post.slug}/`}>
-        <span class="essay-meta">{post.data.kicker} <span class="sep">·</span> <time datetime={post.data.publishDate.toISOString().slice(0,10)}>{post.data.publishDate.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' })}</time> <span class="sep">·</span> <span class="rt">{post.data.readingTime}</span></span>
+        <span class="essay-meta"><span class={warmKickers.has(post.data.kicker) ? "k warm" : "k"}>{post.data.kicker}</span> <span class="sep">·</span> <time datetime={post.data.publishDate.toISOString().slice(0,10)}>{post.data.publishDate.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', year: 'numeric' })}</time></span>
         <h2>{post.data.title}</h2>
         <p>{post.data.description}</p>
       </a>
diff --git a/site-astro/src/pages/demo/index.astro b/site-astro/src/pages/demo/index.astro
index fa70c81..6609f58 100644
--- a/site-astro/src/pages/demo/index.astro
+++ b/site-astro/src/pages/demo/index.astro
@@ -3,11 +3,27 @@ import Head from '../../layouts/Head.astro';
 import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
+import '../../styles/tokens.css';
 import '../../styles/landing.css';
+import '../../styles/backdrop.css';
 
-const title = 'Demo — one real session, this repo | coldstart';
+const title = 'Demo — a visual walkthrough of how coldstart works | coldstart';
 const description =
-  'A single continuous session against coldstart\'s own codebase: an agent with no note yet runs find and gs to answer a question, writes what it learned, then a later prompt gets the same answer for zero tool calls.';
+  "Watch the same question run twice on one repo: once by an agent that has to go looking for the file, and once by an agent that starts at the right one because a past session wrote it down.";
+// Terminal output lives here, not in the markup: Astro parses `{...}` in the
+// template as an expression and `${...}` as interpolation, so real source text
+// breaks the build. Frontmatter strings are immune to both.
+const readOut = [
+  "  14  const SESSION_TTL = 60 * 60 * 24 * 7;",
+  "  16  const COOKIE_NAME = 'sid';",
+  "  ..",
+  "  24  export async function createSession(user: User) {",
+  "  29    const token = randomBytes(32).toString('hex');",
+  "  31    await redis.set('sess:' + token, JSON.stringify({ uid: user.id }),",
+  "  32                    'EX', SESSION_TTL);",
+  "  35    return { name: COOKIE_NAME, value: token, httpOnly: true };",
+  "  36  }",
+];
 ---
 <html lang="en">
 <head>
@@ -17,8 +33,8 @@ const description =
     keywords="coldstart demo, coldstart find, coldstart gs, notebook recall, codebase memory demo, AI coding agent navigation"
     canonicalPath="/demo/"
     ogType="website"
-    ogTitle="Demo — one real session, this repo"
-    ogDescription="find + gs answer a question with no note yet. Later, the same question costs zero tool calls. One real session, not a mockup."
+    ogTitle="Demo — a visual walkthrough of how coldstart works"
+    ogDescription="The first session goes looking. The second starts at the right file. A walkthrough of what coldstart changes inside a real agent session."
     themeColor="#070a11"
   />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -29,254 +45,227 @@ const description =
 <SvgDefs />
 <Nav variant="demo" />
 
-<header class="hero" style="padding-bottom:24px;">
+<header class="hero demo-hero">
   <div class="wrap hero-in">
-    <div class="kicker">Demo — one real session, captured from this repo</div>
-    <h1 class="title" style="font-size:clamp(32px,5vw,52px);">The first time, it looks things up.<br>The second time, it already knows.</h1>
-    <p class="hero-sub">One continuous session against coldstart's own codebase. Every command, every note, every answer below is real — same repo, same day. Scroll to watch it happen.</p>
+    <h1 class="title">What coldstart changes,<br>inside the session</h1>
+    <p class="hero-sub">Below is a walkthrough of one agent answering the same question twice on the same example repo, three days apart. The commands and the output format are the real ones.</p>
   </div>
 </header>
 
-<!-- ===================== PART 1 — FIRST TIME ===================== -->
-<section id="first-time">
+<!-- ============================ COLD ============================ -->
+<section class="dsec">
   <div class="wrap">
-    <div class="rise in">
-      <div class="eyebrow">01 · first time</div>
-      <h2>No note yet. The agent goes and looks.</h2>
-      <p class="lead">A real question, asked cold. Nothing's been written down about it yet, so the agent reaches for <code>find</code>, then <code>gs</code>, then answers from what it just read.</p>
+    <div class="dhead">
+      <div class="eyebrow">Monday · nobody has written this down</div>
+      <h2>It has to go and find out.</h2>
     </div>
 
-    <div class="recall reveal">
-      <div class="rprompt" data-t="0"><span class="who">you</span><span class="q">"why does <code>gs</code> show files edited together — is that from the import graph?"</span></div>
-
-      <div class="rflow" data-t="400"><span class="glyph">→</span><span class="rlab"><b>UserPromptSubmit</b> <span class="sub">fires · kb search runs against the notebook</span></span></div>
-      <div class="rflow" data-t="350"><span class="glyph">·</span><span class="rlab"><b>no match</b> <span class="sub">nothing written about this yet — nothing injected</span></span></div>
-      <div class="rflow think" data-t="400"><span class="glyph think"><span class="pdot"></span></span><span class="rlab"><b>Thinking…</b> <span class="sub">no note for this — check the code directly</span></span></div>
-
-      <div class="term live" data-t="2400" role="img" aria-label="Terminal output of coldstart find edited together cochange sidecar handleGetStructure">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="term-title">coldstart-mcp</span></div>
-        <div class="term-body">
-<span class="l cmdline"><span class="p-prompt">$&nbsp;</span><span class="typed" data-cmd="coldstart find edited together cochange sidecar"></span><span class="type-cursor"></span></span>
-<div class="out">
-<span class="l" data-t="100"><span class="p-dim">[coldstart] cache hit (19ms, 421 files)</span></span>
-<span class="gap" data-t="0"></span>
-<span class="l" data-t="140"><span class="p-frost">▸ src/server/tools.ts</span>  <span class="p-hit">[4/5]</span></span>
-<span class="l" data-t="90">   <span class="p-ember">Role:</span>  <span class="p-dim">defines</span> symbol, handleGetStructure</span>
-<span class="l" data-t="90">   <span class="p-dim">co-change arrives as an optional</span> <b>third parameter</b><span class="p-dim">, loaded by each caller</span></span>
-<span class="gap" data-t="0"></span>
-<span class="l" data-t="140"><span class="p-frost">▸ src/cli.ts</span>  <span class="p-hit">[5/5]</span></span>
-<span class="l" data-t="90">   <span class="p-ember">Wired:</span>  <span class="p-dim">imports</span> handleGetStructure <span class="p-dim">(from tools.ts)</span></span>
-<span class="l" data-t="90">   <span class="p-dim">in</span> function runGs <span class="p-dim">[L166-191]:</span> <span class="p-dim">loadCoChange(root) → passed as 3rd arg</span><span class="cursor"></span></span>
-</div>
-        </div>
-      </div>
+    <div class="cc">
+      <div class="cc-bar"><span class="cc-file">acme-api</span><span class="cc-badge">Claude Code</span></div>
+      <div class="cc-body">
 
-      <div class="rflow" data-t="400"><span class="glyph">→</span><span class="rlab"><b>cli.ts</b> <span class="sub">is where it's wired — confirm with a targeted <code>gs</code></span></span></div>
-
-      <div class="term live" data-t="1900" role="img" aria-label="Terminal output of coldstart gs src/cli.ts --match cochange">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="term-title">coldstart-mcp</span></div>
-        <div class="term-body">
-<span class="l cmdline"><span class="p-prompt">$&nbsp;</span><span class="typed" data-cmd="coldstart gs src/cli.ts --match cochange"></span><span class="type-cursor"></span></span>
-<div class="out">
-<span class="l" data-t="120"><span class="p-dim">2 content matches in 1 method (in-tool grep → method body)</span></span>
-<span class="gap" data-t="0"></span>
-<span class="l" data-t="120"><span class="p-ember">function runGs</span> <span class="p-dim">[L166-191]</span></span>
-<span class="l" data-t="100">  180  <span class="p-dim">const</span> &#123; loadCoChange &#125; = <span class="p-dim">await import(</span><span class="p-file">'./indexer/cochange.js'</span><span class="p-dim">)</span></span>
-<span class="l" data-t="100">  186  &#125;, <span class="p-frost">loadCoChange(root, flags.cacheDir)</span>) <span class="p-dim">as HandlerResult;</span><span class="cursor"></span></span>
-</div>
+        <div class="turn">
+          <div class="g">IN</div>
+          <div class="c"><div class="chip">how does authentication work in this codebase?</div></div>
         </div>
-      </div>
-
-      <div class="rtag" data-t="400"><span class="d"></span>answered — cites <code>src/server/tools.ts</code> + <code>src/cli.ts</code>, 2 tool calls</div>
 
-      <blockquote class="rquote" data-t="300">"Not the import graph — <code>gs</code> takes co-change as an optional third argument, lazily loaded from <code>cochange.json</code> and passed in by whichever reader is running (<code>cli.ts</code>'s <code>runGs</code> here). No index rebuild involved."</blockquote>
-
-      <div class="rflow" data-t="450"><span class="glyph">→</span><span class="rlab"><b>Stop hook</b> <span class="sub">fires · worklist: 2 files read this turn, both note-worthy</span></span></div>
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="prose think">Nothing written down about auth here. I'll locate the files first.</div></div>
+        </div>
 
-      <div class="card captured" data-t="350">
-        <div class="card-top">
-          <div class="kick"><span class="pill-t">Flow note</span><span class="pill fresh"><span class="d"></span>captured</span></div>
-          <div class="card-title">how the edited-together signal reaches gs without going through the index</div>
+        <div class="turn">
+          <div class="g">OUT</div>
+          <div class="c">
+            <div class="tool">
+              <div class="th"><span class="dot ok"></span><b>Bash</b> <span class="arg">coldstart find auth session login middleware</span></div>
+              <div class="ob"><div>find: auth session login middleware  (4 terms, 112 candidate files)</div><div>&nbsp;</div><div>▸ src/auth/session.ts   [4/4]</div><div>   Role:  defines `session`, `login`; imports `auth`</div><div>   Read:  createSession [L24-58], verifySession [L62-91]</div><div>   Wired: used by `requireAuth.ts`, `login.ts` · near `User.ts`</div><div>   near L31:</div><div>     L29: const token = randomBytes(32).toString('hex');</div><div>     L31: await redis.set('sess:' + token, ..., 'EX', SESSION_TTL);</div><div>&nbsp;</div><div>▸ src/middleware/requireAuth.ts   [3/4]</div><div>   Role:  defines `middleware`, `auth`</div><div>   Wired: uses `session.ts` · used by 14 route files</div><div>&nbsp;</div><div>▸ src/routes/login.ts   [3/4]</div><div>   Role:  defines `login`; imports `session`, `auth`</div><div class="el">… +21 lines</div></div>
+            </div>
+          </div>
         </div>
-        <div class="card-body">
-          <p>The "Edited together" pairs <code>gs</code> shows are <b>not part of the code index</b> and never travel through the cache pipeline — they live in a separate keeper-written sidecar (<code>cochange.json</code>) that each reader loads itself and hands to the symbol-page builder as a third argument.</p>
-          <div class="anchors">
-            <div class="lbl">Anchors</div>
-            <div class="arow">
-              <span class="anc fresh"><span class="d"></span>src/index-manager.ts</span>
-              <span class="anc fresh"><span class="d"></span>src/cli.ts</span>
-              <span class="anc fresh"><span class="d"></span>+1 more</span>
+
+        <div class="turn">
+          <div class="g">OUT</div>
+          <div class="c">
+            <div class="tool">
+              <div class="th"><span class="dot ok"></span><b>Bash</b> <span class="arg">coldstart gs src/auth/session.ts</span></div>
+              <div class="ob"><div>src/auth/session.ts (108 lines, importedBy: 6)</div><div>&nbsp;</div><div>Symbols:</div><div>constant SESSION_TTL [L14]</div><div>constant COOKIE_NAME [L16]</div><div>function createSession  [L24-58]  ← src/routes/login.ts:41</div><div>function verifySession  [L62-91]  ← src/middleware/requireAuth.ts:18</div><div>function destroySession [L95-108] ← src/routes/logout.ts:12</div><div>&nbsp;</div><div>Imports:</div><div>src/db/redis.ts</div><div>src/models/User.ts</div><div>&nbsp;</div><div>Importers (6):</div><div>  Source (4):</div><div>    src/middleware/requireAuth.ts</div><div>    src/routes/login.ts</div><div>    src/routes/logout.ts</div><div>    src/routes/refresh.ts</div><div>  Tests (2):</div><div>    tests/auth.test.ts</div><div>&nbsp;</div><div>Edited together (git history, not a dependency):</div><div>  src/middleware/requireAuth.ts — 14 commits</div><div>  tests/auth.test.ts — 11 commits</div></div>
             </div>
           </div>
         </div>
-      </div>
-    </div>
 
-    <div class="keynote rise in">
-      <span class="kk">This turn</span>
-      <p><b>2 tool calls</b> to answer — <code>find</code>, then <code>gs</code> — and one note written down, unasked, so the next agent doesn't repeat the trip.</p>
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="prose">Sessions, not JWTs — despite the variable being called <code>token</code>.<br><br><b>Login:</b> <code>src/routes/login.ts:41</code> checks the password, then calls <code>createSession</code>, which writes a random 32-byte token to Redis under <code>sess:&lt;token&gt;</code> with a 7-day TTL and returns it as an httpOnly cookie.<br><br><b>Every protected route:</b> <code>requireAuth</code> pulls that cookie and calls <code>verifySession</code>, which is a single Redis lookup. Nothing is signed and nothing is decoded — if the key is gone from Redis, the session is over.<br><br><b>Logout:</b> <code>destroySession</code> deletes the key. There is no revocation list because there is nothing to revoke.</div></div>
+        </div>
+
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="hook"><span class="hl">Stop hook</span> the agent writes this down — the files, the symbols, and the thing that would mislead the next reader — checked against a content hash so it expires when the code moves.</div></div>
+        </div>
+
+      </div>
+      <div class="cc-in"><span>Reply to Claude…</span><span class="send">↑</span></div>
     </div>
   </div>
 </section>
 
-<!-- ===================== PART 2 — SECOND TIME ===================== -->
-<section id="second-time" style="background:var(--ink-1);border-top:1px solid var(--line);border-bottom:1px solid var(--line);">
+<!-- ============================ WARM ============================ -->
+<section class="dsec warm">
   <div class="wrap">
-    <div class="rise in">
-      <div class="eyebrow warm">02 · second time</div>
-      <h2>Same question. Zero tool calls.</h2>
-      <p class="lead">A different session, maybe a different contributor. The note from last time is still there, still checked against the code — so this time the answer doesn't need <code>find</code> or <code>gs</code> at all.</p>
+    <div class="dhead">
+      <div class="eyebrow">Thursday · a different session, a different person</div>
+      <h2>It starts at the right file.</h2>
     </div>
 
-    <div class="recall reveal">
-      <div class="rprompt" data-t="0"><span class="who">you</span><span class="q">"does <code>gs</code>'s 'edited together' come from the import graph?"</span></div>
+    <div class="cc">
+      <div class="cc-bar"><span class="cc-file">acme-api</span><span class="cc-badge">Claude Code</span></div>
+      <div class="cc-body">
 
-      <div class="rflow" data-t="500"><span class="glyph">→</span><span class="rlab"><b>UserPromptSubmit</b> <span class="sub">fires before the agent ever sees this message</span></span></div>
-      <div class="rflow" data-t="450"><span class="glyph">→</span><span class="rlab"><b>kb search</b> <span class="sub">ranks notebook notes against the prompt — no embeddings, term + title match</span></span></div>
-      <div class="rflow" data-t="450"><span class="glyph">✓</span><span class="rlab"><b>match found</b> <span class="sub">[fresh] · injected as context, unasked</span></span></div>
+        <div class="turn">
+          <div class="g">IN</div>
+          <div class="c"><div class="chip">are we using JWTs for login, or something else?</div></div>
+        </div>
+
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c">
+            <div class="note">
+              <div class="nh"><span class="nlbl">From the notebook</span><span class="fresh">fresh</span></div>
+              <div class="nt">Auth is session cookies in Redis, not JWTs</div>
+              <div class="nb2"><code>createSession</code> writes a random 32-byte token to Redis under <code>sess:&lt;token&gt;</code> with a 7-day TTL and returns an httpOnly cookie. <code>requireAuth</code> calls <code>verifySession</code>, a single Redis lookup, on every protected route. Nothing is signed or decoded. The variable is named <code>token</code>, which reads as a JWT and is not one — check Redis before assuming stateless auth.</div>
+              <div class="na">src/auth/session.ts · createSession, verifySession</div>
+            </div>
+          </div>
+        </div>
+
+        <p class="cap"><code>fresh</code> = <code>session.ts</code> has not changed a byte since this was written.</p>
 
-      <div class="card injected" data-t="400">
-        <div class="card-top">
-          <div class="kick"><span class="pill-t">Flow note</span><span class="pill inj"><span class="d"></span>injected</span></div>
-          <div class="card-title">how the edited-together signal reaches gs without going through the index</div>
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="prose think">The note names the file and the two functions. Opening it to confirm before I answer.</div></div>
         </div>
-        <div class="card-body">
-          <p>The "Edited together" pairs <code>gs</code> shows are <b>not part of the code index</b> and never travel through the cache pipeline — they live in a separate keeper-written sidecar (<code>cochange.json</code>) that each reader loads itself and hands to the symbol-page builder as a third argument.</p>
-          <div class="anchors">
-            <div class="lbl">Anchors</div>
-            <div class="arow">
-              <span class="anc fresh"><span class="d"></span>src/index-manager.ts</span>
-              <span class="anc fresh"><span class="d"></span>src/cli.ts</span>
-              <span class="anc fresh"><span class="d"></span>+1 more</span>
+
+        <div class="turn">
+          <div class="g">OUT</div>
+          <div class="c">
+            <div class="tool">
+              <div class="th"><span class="dot ok"></span><b>Read</b> <span class="arg">src/auth/session.ts</span></div>
+              <div class="ob">{readOut.map((l) => <div>{l}</div>)}<div class="el">… +72 lines</div></div>
             </div>
           </div>
         </div>
-      </div>
 
-      <div class="rflow think" data-t="700"><span class="glyph think"><span class="pdot"></span></span><span class="rlab"><b>Thinking…</b> <span class="sub">the gist already names the file and the mechanism — no search needed</span></span></div>
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="prose">Confirmed — not JWTs. Session cookies backed by Redis.<br><br>Login stores a random 32-byte token under <code>sess:&lt;token&gt;</code> with a 7-day TTL and sets it as an httpOnly cookie. <code>requireAuth</code> does one Redis lookup per request; nothing is signed or decoded. The <code>token</code> naming is misleading and has caught people out before.<br><br>Practically: sessions can be killed server-side by deleting the key, and auth stops working if Redis is down.</div></div>
+        </div>
 
-      <div class="rtag" data-t="600"><span class="d"></span>answered — cites <code>src/index-manager.ts</code> + <code>cochange.json</code>, zero tool calls</div>
+        <div class="turn">
+          <div class="g"></div>
+          <div class="c"><div class="tally"><b>One read instead of a search.</b> It still opened the file — it just knew which one, and it inherited the warning about the variable name.</div></div>
+        </div>
 
-      <blockquote class="rquote" data-t="400">"Not the import graph — <code>cochange.json</code> is a separate sidecar the keeper derives from <code>git log --name-status -M</code>, loaded straight into <code>gs</code>'s symbol-page builder. No index rebuild involved."</blockquote>
+      </div>
+      <div class="cc-in"><span>Reply to Claude…</span><span class="send">↑</span></div>
     </div>
 
-    <div class="keynote cool rise in">
-      <span class="kk">The flywheel</span>
-      <p><b>2 tool calls the first time, 0 the second.</b> The note carried the answer — checked against the code at the moment it was recalled, not trusted blindly.</p>
+    <div class="dclose">
+      <p class="big">Both sessions had the index. Only the second had the note.</p>
+      <p class="sm">Neither is free. What changes is how much of the work goes into finding the file rather than answering the question.</p>
+      <div class="cta"><a class="btn btn-primary" href="/docs/">Read the docs →</a><a class="btn btn-ghost" href="/docs/notebook/">How the notebook works</a></div>
     </div>
   </div>
 </section>
 
 <Footer />
+</body>
+</html>
 
-<style>
-.term.live .cmdline .typed{white-space:pre;}
-.term.live .type-cursor{display:inline-block;width:8px;height:15px;vertical-align:-2px;margin-left:2px;
-  background:var(--frost);animation:blink 1.05s steps(1) infinite;}
-.term.live .type-cursor.done{display:none;}
-.term.live .out .l,.term.live .out .gap{opacity:0;transform:translateY(2px);
-  transition:opacity .22s ease,transform .22s ease;}
-.term.live .out .l.in,.term.live .out .gap.in{opacity:1;transform:none;}
-@keyframes blink{50%{opacity:0;}}
-
-.recall{max-width:760px;margin:44px 0 0;}
-.recall.reveal>*{opacity:0;transform:translateY(5px);transition:opacity .32s ease,transform .32s ease;}
-.recall.reveal>*.in{opacity:1;transform:none;}
-.glyph.think{display:inline-flex;align-items:center;justify-content:center;width:13px;}
-.pdot{width:7px;height:7px;border-radius:50%;background:var(--frost);animation:pdot 1.1s ease-in-out infinite;}
-@keyframes pdot{0%,100%{opacity:.35;transform:scale(.85);}50%{opacity:1;transform:scale(1);}}
-.rquote{padding:16px 20px;border-left:2px solid var(--frost-dim);background:rgba(79,191,224,.05);
-  font-family:var(--display);font-style:italic;font-size:15.5px;line-height:1.65;color:var(--text);
-  border-radius:0 8px 8px 0;}
-.rquote code{font-family:var(--mono);font-style:normal;font-size:13.5px;color:var(--frost);}
-
-.time-gap{text-align:left;margin:0;font-family:var(--mono);font-size:12px;letter-spacing:.08em;
-  color:var(--faint);text-transform:uppercase;}
-.keynote{margin-top:40px;margin-bottom:0;}
-
-@media(prefers-reduced-motion:reduce){
-  .term.live .out .l,.term.live .out .gap{transition:none;}
-  .term.live .type-cursor{animation:none;}
-  .pdot{animation:none;}
-  .recall.reveal>*{transition:none;}
+<style is:global>
+/* ---------- demo page shell ---------- */
+.demo-hero{padding:44px 0 8px;}
+.demo-hero .title{font-size:clamp(30px,4.6vw,48px);}
+.dsec{padding:72px 0;border-top:1px solid var(--line);}
+.dsec.warm{border-top-color:var(--line-warm);}
+.dhead{max-width:640px;margin:0 auto 36px;text-align:center;}
+.dhead h2{margin-top:14px;}
+.dhead .lead{margin-top:16px;max-width:500px;margin-inline:auto;}
+
+/* ---------- the Claude Code panel — a replica, on its own neutral ground ---------- */
+.cc{max-width:880px;margin:0 auto;background:#1f1f1f;border:1px solid #2f2f2f;border-radius:10px;
+  overflow:hidden;text-align:left;box-shadow:0 24px 60px rgba(0,0,0,.42);}
+.cc-bar{display:flex;align-items:center;justify-content:space-between;gap:12px;
+  padding:11px 16px;background:#252525;border-bottom:1px solid #333;}
+.cc-file{font-family:var(--mono);font-size:12px;color:#8a8a8a;}
+.cc-badge{font-family:var(--mono);font-size:10.5px;letter-spacing:.09em;text-transform:uppercase;
+  color:#8a8a8a;border:1px solid #3a3a3a;border-radius:4px;padding:3px 7px;}
+.cc-body{padding:22px 20px 8px;}
+
+.turn{display:grid;grid-template-columns:34px 1fr;gap:14px;align-items:start;margin-bottom:18px;}
+.turn > .g{font-family:var(--mono);font-size:10px;letter-spacing:.08em;color:#6e6e6e;
+  text-align:right;padding-top:9px;}
+.turn > .c{min-width:0;}
+
+.chip{background:#2e2e2e;border-radius:6px;padding:10px 14px;color:#f2f2f2;font-size:13.5px;line-height:1.55;}
+.prose{color:#e3e3e3;font-size:13.5px;line-height:1.65;padding:2px 2px;}
+.prose.think{color:#9a9a9a;font-style:italic;}
+.cc code{font-family:var(--mono);font-size:12.5px;color:#d9a05b;
+  background:rgba(255,255,255,.06);border-radius:4px;padding:1px 5px;}
+
+.tool{border:1px solid #383838;border-radius:6px;background:#1a1a1a;overflow:hidden;}
+.th{display:flex;align-items:center;gap:8px;padding:9px 12px;border-bottom:1px solid #2c2c2c;
+  font-size:13px;color:#f2f2f2;flex-wrap:wrap;}
+.th b{font-weight:600;}
+.th .arg{font-family:var(--mono);font-size:12px;color:#8a8a8a;}
+.dot{width:7px;height:7px;border-radius:50%;flex:none;background:#6b6b6b;}
+.dot.ok{background:#7ec89a;}
+.ob{padding:11px 12px;font-family:var(--mono);font-size:12px;line-height:1.7;color:#cfcfcf;
+  overflow-x:auto;}
+.ob > div{white-space:pre;}
+.ob .el{color:#6e6e6e;}
+
+/* the note, as the recall hook hands it over */
+.note{border:1px solid rgba(239,148,72,.34);border-radius:6px;background:rgba(239,148,72,.05);padding:14px 15px;}
+.nh{display:flex;align-items:center;gap:10px;margin-bottom:9px;}
+.nlbl{font-family:var(--mono);font-size:10px;letter-spacing:.1em;text-transform:uppercase;color:#d9a05b;}
+.fresh{font-family:var(--mono);font-size:10px;letter-spacing:.06em;color:#7ec89a;
+  border:1px solid rgba(126,200,154,.4);border-radius:4px;padding:2px 6px;}
+.nt{font-family:var(--display);font-size:17px;color:#f2f2f2;margin-bottom:8px;}
+.nb2{font-size:13px;line-height:1.62;color:#cfcfcf;}
+.na{margin-top:10px;font-family:var(--mono);font-size:11px;color:#8a8a8a;}
+
+.hook{border-left:2px solid #7ec89a;padding:4px 0 4px 12px;font-size:12.5px;color:#9a9a9a;line-height:1.6;}
+.hook .hl{color:#7ec89a;font-family:var(--mono);font-size:11px;letter-spacing:.06em;
+  text-transform:uppercase;margin-right:8px;}
+.tally{border:1px dashed #3a3a3a;border-radius:6px;padding:11px 13px;font-size:13px;color:#cfcfcf;line-height:1.6;}
+.tally b{color:#f2f2f2;font-weight:600;}
+.tally em{color:#e3e3e3;font-style:italic;}
+
+.cc-in{display:flex;align-items:center;justify-content:space-between;margin:6px 16px 16px;
+  background:#242424;border:1px solid rgba(239,148,72,.45);border-radius:8px;padding:11px 13px;
+  font-size:13px;color:#6e6e6e;}
+.cc-in .send{width:22px;height:22px;border-radius:5px;background:#a8604a;color:#fff;
+  display:grid;place-items:center;font-size:12px;}
+
+/* captions sit outside the replica so the panel carries no marketing copy */
+.cap{max-width:600px;margin:-4px auto 20px;padding:0 4px;text-align:center;
+  font-size:12.5px;line-height:1.6;color:var(--faint);}
+.cap code{font-family:var(--mono);font-size:11.5px;color:var(--ember);background:none;padding:0;}
+
+/* The hero sub is the page's only framing line - it says the repo is an
+   example, so a reader does not take the terminal for captured output. */
+.demo-hero .hero-sub{max-width:600px;margin-inline:auto;}
+
+.dclose{max-width:660px;margin:56px auto 0;text-align:center;}
+.dclose .big{font-family:var(--display);font-size:clamp(20px,2.6vw,26px);color:var(--text);line-height:1.35;}
+.dclose .sm{margin-top:12px;font-size:15px;color:var(--muted);line-height:1.6;}
+.dclose .cta{margin-top:28px;justify-content:center;}
+
+@media(max-width:720px){
+  .cc-body{padding:18px 12px 6px;}
+  .turn{grid-template-columns:22px 1fr;gap:9px;}
+  .turn > .g{font-size:9px;}
+  .ob{font-size:11px;}
 }
 </style>
-
-<script>
-(function(){
-  var reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-
-  function typeCommand(term, done){
-    var typed = term.querySelector('.typed');
-    var cmd = typed.getAttribute('data-cmd') || '';
-    var i = 0;
-    (function tick(){
-      typed.textContent = cmd.slice(0, i);
-      i++;
-      if (i <= cmd.length) { setTimeout(tick, 14 + Math.random() * 16); } else { done(); }
-    })();
-  }
-
-  function revealTermInstantly(term){
-    var typed = term.querySelector('.typed');
-    typed.textContent = typed.getAttribute('data-cmd');
-    var cursor = term.querySelector('.type-cursor');
-    if (cursor) cursor.classList.add('done');
-    term.querySelectorAll('.out .l, .out .gap').forEach(function(el){ el.classList.add('in'); });
-  }
-
-  function revealTermOutput(term){
-    var lines = Array.prototype.slice.call(term.querySelectorAll('.out .l, .out .gap'));
-    var t = 0;
-    lines.forEach(function(el){
-      t += parseInt(el.getAttribute('data-t') || '0', 10) || 60;
-      setTimeout(function(){ el.classList.add('in'); }, t);
-    });
-  }
-
-  function runTerm(term){
-    if (term.dataset.ran) return;
-    term.dataset.ran = '1';
-    if (reduce) { revealTermInstantly(term); return; }
-    var cursor = term.querySelector('.type-cursor');
-    typeCommand(term, function(){
-      if (cursor) cursor.classList.add('done');
-      setTimeout(function(){ revealTermOutput(term); }, 240);
-    });
-  }
-
-  var timelines = Array.prototype.slice.call(document.querySelectorAll('.recall.reveal'));
-  if (!timelines.length) return;
-
-  function revealTimelineInstantly(el){
-    Array.prototype.slice.call(el.children).forEach(function(child){
-      child.classList.add('in');
-      if (child.classList.contains('term') && child.classList.contains('live')) revealTermInstantly(child);
-    });
-  }
-
-  function runTimeline(el){
-    if (reduce) { revealTimelineInstantly(el); return; }
-    var t = 0;
-    Array.prototype.slice.call(el.children).forEach(function(child){
-      t += parseInt(child.getAttribute('data-t') || '0', 10) || 0;
-      (function(child, t){
-        setTimeout(function(){
-          child.classList.add('in');
-          if (child.classList.contains('term') && child.classList.contains('live')) runTerm(child);
-        }, t);
-      })(child, t);
-    });
-  }
-
-  if (!('IntersectionObserver' in window)) { timelines.forEach(revealTimelineInstantly); return; }
-  var obs = new IntersectionObserver(function(entries){
-    entries.forEach(function(e){
-      if (e.isIntersecting) { runTimeline(e.target); obs.unobserve(e.target); }
-    });
-  }, { threshold: 0.2 });
-  timelines.forEach(function(el){ obs.observe(el); });
-})();
-</script>
-</body>
-</html>
diff --git a/site-astro/src/pages/docs.astro b/site-astro/src/pages/docs.astro
index f418df4..6a8e49e 100644
--- a/site-astro/src/pages/docs.astro
+++ b/site-astro/src/pages/docs.astro
@@ -5,8 +5,8 @@ import Nav from '../components/Nav.astro';
 import Footer from '../components/Footer.astro';
 import DocsSidebar from '../components/DocsSidebar.astro';
 import '../styles/tailwind.css';
+import '../styles/tokens.css';
 import '../styles/docs.css';
-import '../styles/backdrop.css';
 
 const techArticleJsonLd = {
   '@context': 'https://schema.org',
@@ -58,24 +58,40 @@ const techArticleJsonLd = {
       <h2>Install &amp; setup</h2>
       <p>Requires Node.js 18+. Install globally, then run <code>init</code> once per project.</p>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">your-project</span></div>
+        <div class="term-bar"><span class="title">your-project</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">npm install -g @cstart/coldstart</span></span>
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">cd</span> your-project</span>
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart init</span>   <span class="c-dim"># coldstart.md + client wiring + notebook + hooks + warm-up</span></span>
         </div>
       </div>
-      <p style="margin-top:22px"><code>init</code> asks two things — the <b>experience</b> (<code>cli</code>, recommended, or <code>mcp</code>) and the <b>client</b> (<code>claude</code> / <code>cursor</code> / <code>codex</code> / <code>other</code>) — then writes the coldstart guidance into the client's own rules file — imported via <code>coldstart.md</code> for Claude Code, inlined directly into <code>.cursor/rules/coldstart.mdc</code> (Cursor) and <code>AGENTS.md</code> (Codex) — and wires the client. It also creates the notebook and, for Claude Code / Codex / Cursor, registers the navigation and notebook hooks. Pass <code>--experience</code> / <code>--client</code> to skip the prompts; the client is never auto-detected. Finally it <b>indexes the repo and waits for that to finish</b> before exiting, so your very first <code>find</code> is instant rather than racing a half-built index — a few seconds once, at setup.</p>
+      <p style="margin-top:22px"><code>init</code> asks two things — the <b>experience</b> and the <b>client</b> — then writes the coldstart guidance where that client will read it, creates the notebook, and registers the navigation and notebook hooks. It indexes the repo before it exits, so your first <code>find</code> is instant instead of racing a half-built index. A few seconds, once.</p>
+
+      <h3>What it writes, per client</h3>
+      <div class="flags">
+        <div class="flag-row"><span class="fk">claude</span><span class="fv"><code>coldstart.md</code>, imported from <code>CLAUDE.md</code>, plus hooks in <code>.claude/settings.json</code>.</span></div>
+        <div class="flag-row"><span class="fk">cursor</span><span class="fv">The guidance inlined into <code>.cursor/rules/coldstart.mdc</code> — Cursor doesn't resolve file references in rules — plus <code>.cursor/hooks.json</code>.</span></div>
+        <div class="flag-row"><span class="fk">codex</span><span class="fv">The guidance inlined into a marked block in <code>AGENTS.md</code>, plus <code>.codex/hooks.json</code>.</span></div>
+        <div class="flag-row"><span class="fk">other</span><span class="fv"><code>coldstart.md</code> and printed wiring directions for anything else.</span></div>
+      </div>
+
+      <h3>Flags</h3>
       <div class="flags">
         <div class="flag-row"><span class="fk">--experience cli|mcp</span><span class="fv">The surface to wire. <b>cli</b> is the fast path; <b>mcp</b> also writes an MCP server entry.</span></div>
         <div class="flag-row"><span class="fk">--client NAME</span><span class="fv"><b>claude</b>, <b>cursor</b>, <b>codex</b>, or <b>other</b>. Determines which config files get wired.</span></div>
         <div class="flag-row"><span class="fk">--commit-notebook</span><span class="fv">Opt in to committing the notebook <code>.raw</code> logs so the team can share it. Private by default — see <a href="/docs/notebook/#sharing">Sharing</a>.</span></div>
       </div>
-      <div class="flags" style="margin-top:20px">
-        <div class="flag-row"><span class="fk">Upgrading</span><span class="fv"><code>npm install -g @cstart/coldstart@latest</code> — keepers detect the version bump and restart themselves. Re-run <code>init</code> only if a node/nvm change moved the global install; <code>coldstart status</code> flags that.</span></div>
-        <div class="flag-row"><span class="fk">Removing</span><span class="fv"><code>coldstart unwire</code> strips the per-repo wiring (notebook kept by default, <code>--purge</code> deletes it), then <code>npm uninstall -g @cstart/coldstart</code>.</span></div>
-        <div class="flag-row"><span class="fk">Codex hook trust</span><span class="fv">Codex requires approving hooks once — choose <em>"Trust all and continue"</em> when prompted, or launch <code>codex</code> from a terminal if it doesn't appear. Automated runs: pass <code>--dangerously-bypass-hook-trust</code>. Details: <a href="https://github.com/openai/codex/issues/21615">openai/codex#21615</a>.</span></div>
+      <h3>Upgrading and removing</h3>
+      <div class="term">
+        <div class="term-body">
+<span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">npm install -g @cstart/coldstart@latest</span>   <span class="c-dim"># upgrade</span></span>
+<span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart unwire</span>   <span class="c-dim"># unwire this repo, keeping the notebook</span></span>
+<span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">npm uninstall -g @cstart/coldstart</span></span>
+        </div>
       </div>
+      <p>On upgrade, running keepers notice the version bump and restart themselves. Re-run <code>init</code> only if a node or nvm change moved the global install — <code>coldstart status</code> tells you when that has happened. Unwiring keeps your notebook unless you pass <code>--purge</code>.</p>
+
+      <div class="callout"><span class="ct">Codex only</span>Codex asks you to approve hooks the first time — choose <b>Trust all and continue</b>, or launch <code>codex</code> from a terminal if the prompt never appears. For automated runs, pass <code>--dangerously-bypass-hook-trust</code>. <a href="https://github.com/openai/codex/issues/21615">openai/codex#21615</a> has the details.</div>
     </section>
 
     <section id="flow" class="doc-sec">
diff --git a/site-astro/src/pages/docs/navigation.astro b/site-astro/src/pages/docs/navigation.astro
index 314a4b9..e8c96f3 100644
--- a/site-astro/src/pages/docs/navigation.astro
+++ b/site-astro/src/pages/docs/navigation.astro
@@ -5,8 +5,8 @@ import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import DocsSidebar from '../../components/DocsSidebar.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
-import '../../styles/backdrop.css';
 
 const techArticleJsonLd = {
   '@context': 'https://schema.org',
@@ -58,7 +58,7 @@ const techArticleJsonLd = {
         <div class="desc"><b>Which files are about this?</b> Ranks files by how many of your query terms each covers — filenames, path segments, exported symbols, plus a repo-wide name-reference pass — and shows <em>why</em> each ranked: which terms it defines vs. imports.</div>
       </div>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart find</span></div>
+        <div class="term-bar"><span class="title">coldstart find</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart find</span> auth session cookie</span>
 <span class="gap"></span>
@@ -84,7 +84,7 @@ const techArticleJsonLd = {
         <div class="desc"><b>What is this file, and who uses it?</b> Returns the file's top-level symbols (with line ranges), its 1-hop internal imports, who imports it, and per-symbol cross-file callers — in one call. This is the answer to "who calls this?", not a grep.</div>
       </div>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart gs</span></div>
+        <div class="term-bar"><span class="title">coldstart gs</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart gs</span> src/auth/service.ts</span>
 <span class="ln"><span class="c-dim">symbols</span>  signCookie <span class="c-dim">L12</span> · verify <span class="c-dim">L34</span> · rotate <span class="c-dim">L61</span></span>
@@ -108,7 +108,7 @@ const techArticleJsonLd = {
       <h2><code>graph</code> — the same data, as a picture</h2>
       <p><code>find</code> and <code>gs</code> answer one question at a time, for an agent. <code>graph</code> is for you: it draws the whole repo as a sphere where every file is one point and latitude is the directory, then lets you click any point to walk the relations outward.</p>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart graph</span></div>
+        <div class="term-bar"><span class="title">coldstart graph</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart graph</span></span>
 <span class="ln"><span class="c-frost">.coldstart/graph.html</span></span>
diff --git a/site-astro/src/pages/docs/notebook.astro b/site-astro/src/pages/docs/notebook.astro
index 1262c3e..235ad1c 100644
--- a/site-astro/src/pages/docs/notebook.astro
+++ b/site-astro/src/pages/docs/notebook.astro
@@ -5,8 +5,8 @@ import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import DocsSidebar from '../../components/DocsSidebar.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
-import '../../styles/backdrop.css';
 
 const techArticleJsonLd = {
   '@context': 'https://schema.org',
@@ -84,7 +84,7 @@ const techArticleJsonLd = {
       <p>Sometimes you know a moment is worth recording before the automatic score crosses — a hard-won insight, a confirmed absence, a decision that didn't touch many files. <code>/capture-notes</code> fires the capture flow immediately, with the same worklist and gate. It never forces a write.</p>
       <p style="margin-top:12px"><code>coldstart init</code> wires it for your client: <b>Claude Code</b> and <b>Cursor</b> get a <code>/capture-notes</code> slash command; <b>Codex</b> gets a <code>capture-notes</code> skill. All three run the same one-liner, so it also works by hand:</p>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">capture on demand</span></div>
+        <div class="term-bar"><span class="title">capture on demand</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">node &lt;install&gt;/hooks/kb-elicit.mjs</span> <span class="c-flag">--manual</span>   <span class="c-dim"># prints the capture checklist for this session</span></span>
         </div>
@@ -93,7 +93,7 @@ const techArticleJsonLd = {
       <h4 class="subhead"><code>.coldstartignore</code> — files that never get notes</h4>
       <p><code>coldstart init</code> scaffolds <code>.coldstart/.coldstartignore</code> (gitignore syntax). Built-in defaults are <code>*.json</code>, lockfiles, <code>dist/</code>/<code>build/</code>/<code>coverage/</code>, minified files, binaries and images, and <code>.env*</code> (notes are committed; secrets must never enter them). Every collaborator gets that baseline; lines you add extend it on your machine.</p>
       <div class="term" style="margin-top:14px">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">.coldstart/.coldstartignore</span></div>
+        <div class="term-bar"><span class="title">.coldstart/.coldstartignore</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-dim"># add your own</span></span>
 <span class="ln">*.generated.ts</span>
@@ -112,7 +112,7 @@ const techArticleJsonLd = {
         <div class="desc">Search the notebook with plain task words, symbols, or file names. Returns ranked notes — the mid-task tool when your vocabulary shifts.</div>
       </div>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart kb search</span></div>
+        <div class="term-bar"><span class="title">coldstart kb search</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart kb search</span> tile save lifecycle</span>
 <span class="gap"></span>
@@ -129,7 +129,7 @@ const techArticleJsonLd = {
         <div class="desc">Everything known at one exact address. Run it before editing a file to pull the note (and per-symbol facets) that apply to exactly that path.</div>
       </div>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart kb lookup</span></div>
+        <div class="term-bar"><span class="title">coldstart kb lookup</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart kb lookup</span> src/models.py Tile</span>
         </div>
@@ -168,7 +168,7 @@ const techArticleJsonLd = {
         <div class="desc">Generate a single self-contained HTML browser of the whole notebook and open it in your default browser. No server — one file, freshness stamped at generation time.</div>
       </div>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">coldstart kb view</span></div>
+        <div class="term-bar"><span class="title">coldstart kb view</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart kb view</span></span>
 <span class="ln"><span class="c-hit">✓</span> <span class="c-dim">kb view: wrote .coldstart/notebook/index.html — opening in browser</span></span>
@@ -199,7 +199,7 @@ const techArticleJsonLd = {
       <h2>Sharing with a team</h2>
       <p>The notebook is <b>private by default</b> — <code>.coldstart/</code> is gitignored. Opt in to sharing and the whole team's agents contribute to one growing corpus.</p>
       <div class="term">
-        <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="title">share the notebook</span></div>
+        <div class="term-bar"><span class="title">share the notebook</span></div>
         <div class="term-body">
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart init</span> <span class="c-flag">--commit-notebook</span>   <span class="c-dim"># make .raw committable</span></span>
 <span class="ln"><span class="c-prompt">$</span> <span class="c-cmd">coldstart kb commit</span>              <span class="c-dim"># publish notes to git</span></span>
diff --git a/site-astro/src/pages/docs/under-the-hood.astro b/site-astro/src/pages/docs/under-the-hood.astro
index 8a5b182..733719f 100644
--- a/site-astro/src/pages/docs/under-the-hood.astro
+++ b/site-astro/src/pages/docs/under-the-hood.astro
@@ -5,8 +5,8 @@ import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import DocsSidebar from '../../components/DocsSidebar.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
-import '../../styles/backdrop.css';
 
 const techArticleJsonLd = {
   '@context': 'https://schema.org',
diff --git a/site-astro/src/pages/how-it-works/index.astro b/site-astro/src/pages/how-it-works/index.astro
index f594a39..08eb844 100644
--- a/site-astro/src/pages/how-it-works/index.astro
+++ b/site-astro/src/pages/how-it-works/index.astro
@@ -4,9 +4,9 @@ import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
 import '../../styles/how.css';
-import '../../styles/backdrop.css';
 
 const title = 'How coldstart works — codebase memory for AI coding agents | coldstart';
 const description =
diff --git a/site-astro/src/pages/how-it-works/navigation.astro b/site-astro/src/pages/how-it-works/navigation.astro
index dd3f98f..6810c80 100644
--- a/site-astro/src/pages/how-it-works/navigation.astro
+++ b/site-astro/src/pages/how-it-works/navigation.astro
@@ -4,9 +4,9 @@ import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
 import '../../styles/how.css';
-import '../../styles/backdrop.css';
 
 const title = 'How the navigation layer works — an exact map, no embeddings | coldstart';
 const description =
diff --git a/site-astro/src/pages/how-it-works/notebook.astro b/site-astro/src/pages/how-it-works/notebook.astro
index 487fdaa..0a6d9f3 100644
--- a/site-astro/src/pages/how-it-works/notebook.astro
+++ b/site-astro/src/pages/how-it-works/notebook.astro
@@ -4,9 +4,9 @@ import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
 import '../../styles/how.css';
-import '../../styles/backdrop.css';
 
 const title = 'How the notebook works — codebase memory that checks itself | coldstart';
 const description =
diff --git a/site-astro/src/pages/index.astro b/site-astro/src/pages/index.astro
index 3fced9e..8551e9c 100644
--- a/site-astro/src/pages/index.astro
+++ b/site-astro/src/pages/index.astro
@@ -4,8 +4,8 @@ import SvgDefs from '../components/SvgDefs.astro';
 import Nav from '../components/Nav.astro';
 import Footer from '../components/Footer.astro';
 import '../styles/tailwind.css';
+import '../styles/tokens.css';
 import '../styles/landing.css';
-import '../styles/backdrop.css';
 
 const softwareAppJsonLd = {
   '@context': 'https://schema.org',
@@ -92,7 +92,7 @@ const faqJsonLd = {
     <p class="hero-sub">coldstart gives it <b>persistent memory of your codebase</b> — a notebook it writes itself, so what one session figures out, the next already knows — plus an exact index to <b>find the right file without three wrong reads</b>. No embeddings, no API key: it runs on the model you already pay for.</p>
 
     <div class="term install-term">
-      <div class="term-bar"><span class="tl"></span><span class="tl"></span><span class="tl"></span><span class="term-title">your-project</span><button type="button" class="copy-btn" id="copy-install" data-copy="npm install -g @cstart/coldstart&#10;coldstart init" aria-label="Copy install commands">Copy</button></div>
+      <div class="term-bar"><span class="term-title">your-project</span><button type="button" class="copy-btn" id="copy-install" data-copy="npm install -g @cstart/coldstart&#10;coldstart init" aria-label="Copy install commands">Copy</button></div>
       <div class="term-body">
 <span class="l"><span class="p-prompt">$</span> <span class="p-cmd">npm install -g @cstart/coldstart</span></span>
 <span class="l"><span class="p-prompt">$</span> <span class="p-cmd">cd</span> your-project</span>
@@ -118,7 +118,7 @@ const faqJsonLd = {
     <div class="rise nb-intro">
       <div class="eyebrow warm">The notebook</div>
       <h2>The second time a question comes up, the answer is <span class="warm">already written down.</span></h2>
-      <p class="lead">An agent writes down what it learns while it works. The next one gets it for free, checked against the code so a stale note never passes as fact.</p>
+      <p class="lead">An agent writes down what it learns while it works. The next one starts where that one finished instead of searching for it again, checked against the code so a stale note never passes as fact.</p>
     </div>
 
     <div class="nb-main rise">
@@ -223,7 +223,7 @@ const faqJsonLd = {
       </div>
     </div>
 
-    <a class="how-link" href="/demo/" style="margin-top:8px;">See it run on a real repo, live <span class="ar" aria-hidden="true">→</span></a>
+    <a class="how-link" href="/demo/" style="margin-top:8px;">A visual representation of how it works <span class="ar" aria-hidden="true">→</span></a>
 
     <div class="keynote cool rise">
       <span class="kk">Measured, not promised</span>
diff --git a/site-astro/src/pages/live/index.astro b/site-astro/src/pages/live/index.astro
index 677c59a..c5bb0d4 100644
--- a/site-astro/src/pages/live/index.astro
+++ b/site-astro/src/pages/live/index.astro
@@ -3,7 +3,9 @@ import Head from '../../layouts/Head.astro';
 import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
+import '../../styles/tokens.css';
 import '../../styles/landing.css';
+import '../../styles/backdrop.css';
 
 const title = 'See it live — coldstart on its own repo';
 const description =
@@ -14,8 +16,8 @@ const cards = [
     href: '/demo/',
     kicker: 'Walkthrough',
     title: 'One real session',
-    body: 'A question asked cold, answered with find and gs — then asked again later and answered for free from a note.',
-    meta: '2 tool calls → 0',
+    body: 'A question asked cold, answered with find and gs — then asked again later, and answered straight from the right file because a note pointed at it.',
+    meta: 'a search, then one read',
   },
   {
     href: '/graph/',
@@ -27,6 +29,7 @@ const cards = [
   {
     href: '/notebook/',
     kicker: 'Notebook',
+    warm: true,
     title: "This repo's real notes",
     body: 'The actual notebook coldstart has written about its own code while working — not a mockup, the live thing.',
     meta: 'real notes, real code',
@@ -66,7 +69,7 @@ const cards = [
     <div class="livegrid">
       {cards.map(c => (
         <a class="livecard" href={c.href}>
-          <div class="lc-kicker">{c.kicker}</div>
+          <div class={c.warm ? "lc-kicker warm" : "lc-kicker"}>{c.kicker}</div>
           <h2>{c.title}</h2>
           <p>{c.body}</p>
           <div class="lc-foot">
@@ -91,6 +94,7 @@ const cards = [
 .livecard:hover{border-color:color-mix(in srgb,var(--frost) 40%,var(--line));
   transform:translateY(-3px);box-shadow:0 26px 54px -30px rgba(0,0,0,.75);}
 .lc-kicker{font-family:var(--mono);font-size:11px;letter-spacing:.12em;text-transform:uppercase;color:var(--frost);}
+.lc-kicker.warm{color:var(--ember);}
 .livecard h2{font-family:var(--display);font-weight:500;font-size:21px;letter-spacing:-.01em;margin:0;color:var(--text);}
 .livecard p{font-size:14px;line-height:1.65;color:var(--muted);margin:0;flex:1;}
 .lc-foot{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-top:4px;
diff --git a/site-astro/src/pages/specimen/index.astro b/site-astro/src/pages/specimen/index.astro
deleted file mode 100644
index cd1ff46..0000000
--- a/site-astro/src/pages/specimen/index.astro
+++ /dev/null
@@ -1,477 +0,0 @@
----
-// Specimen page for DESIGN.md. Self-contained on purpose: imports none of the
-// real stylesheets, so it can be approved or thrown away without touching the
-// live site. Not linked from nav; noindex.
-const findCmd = 'coldstart ' + 'find edited together cochange sidecar';
-const gsCmd = 'coldstart ' + 'gs src/cli.ts --match cochange';
----
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width,initial-scale=1" />
-<meta name="robots" content="noindex,nofollow" />
-<title>Specimen — coldstart design language</title>
-<link rel="preconnect" href="https://fonts.googleapis.com" />
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<link href="https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,400..700&family=IBM+Plex+Sans:wght@400;500;600&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet" />
-<style is:global>
-:root{
-  /* --- the field ------------------------------------------------------- */
-  --ground:#0b0e14;
-  --frost:#4fbfe0;
-  --ember:#ef9448;
-  --ok:#7ec89a;
-
-  /* --- text: prose is near-white. grey is labels only, never body copy. - */
-  --text:#eef3fa;
-  --muted:#a8b6c9;
-  --faint:#7f8da2;
-
-  /* --- surfaces are TRANSLUCENT so panels sit IN the field, not on it --- */
-  --surface:rgba(255,255,255,.035);
-  --line:rgba(255,255,255,.09);
-  --wash-frost:rgba(79,191,224,.07);
-  --wash-ember:rgba(239,148,72,.07);
-  --edge-ember:rgba(239,148,72,.22);
-
-  /* --- the Claude Code panel is a faithful replica: its own neutral ---- */
-  --cc-bg:#1f1f1f; --cc-raise:#2e2e2e; --cc-box:#1a1a1a;
-  --cc-line:#383838; --cc-text:#e3e3e3; --cc-dim:#8a8a8a;
-  --cc-code:#d9a05b; --cc-dot:#6b6b6b; --cc-tool:#7ec89a;
-
-  /* field controls — driven live by the dev panel at the bottom right */
-  --fa:.20;   /* frost alpha */
-  --ea:.19;   /* ember alpha */
-  --sp:78;    /* spread, in % of viewport width */
-  --field:
-    radial-gradient(calc(var(--sp) * 1%) 88% at  -6% 26%, rgba(79,191,224,var(--fa)), transparent 66%),
-    radial-gradient(calc(var(--sp) * 1%) 88% at 106% 74%, rgba(239,148,72,var(--ea)), transparent 66%),
-    linear-gradient(102deg,#0a1019 0%,#0b0e14 48%,#150f09 100%);
-
-  --seam:linear-gradient(180deg,var(--frost),var(--ember));
-  --display:"Archivo",system-ui,sans-serif;
-  --sans:"IBM Plex Sans",system-ui,sans-serif;
-  --mono:"JetBrains Mono",ui-monospace,Menlo,monospace;
-  --wrap:1120px;
-}
-*{box-sizing:border-box;}
-html{scroll-behavior:smooth;}
-body{margin:0;background:var(--ground);color:var(--text);font-family:var(--sans);
-  font-size:16px;line-height:1.7;-webkit-font-smoothing:antialiased;}
-
-/* THE FIELD — frost bleeding in from the left edge, ember from the right,
-   over a dark ramp. A fixed pseudo-element, not background-attachment:fixed
-   (which only paints one viewport and is unreliable on iOS Safari). */
-body::before{
-  content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
-  background:var(--field);
-}
-/* EDGE — colour only in the outer band, full height. The content area stays
-   neutral, so no artifact ever gets tinted. */
-html[data-shape="edge"]{
-  --sp:16;
-  --field:
-    linear-gradient( 90deg, rgba(79,191,224,var(--fa)) 0%, transparent calc(var(--sp) * 1%)),
-    linear-gradient(270deg, rgba(239,148,72,var(--ea)) 0%, transparent calc(var(--sp) * 1%)),
-    #0b0e14;
-}
-/* RAMP — no blobs at all: one flat left-to-right temperature ramp. */
-html[data-shape="ramp"]{
-  --field:
-    linear-gradient(90deg,
-      rgba(79,191,224,var(--fa)) 0%, transparent 42%,
-      transparent 58%, rgba(239,148,72,var(--ea)) 100%),
-    #0b0e14;
-}
-html[data-shape="off"]{ --field:#0b0e14; }
-
-h1,h2,h3{margin:0;font-family:var(--display);font-variation-settings:"wdth" 112;
-  font-weight:600;letter-spacing:-.015em;text-wrap:balance;color:var(--text);}
-h1{font-size:clamp(34px,4.6vw,56px);line-height:1.00;letter-spacing:-.02em;}
-h2{font-size:clamp(26px,3.2vw,38px);line-height:1.15;}
-h3{font-size:21px;line-height:1.3;letter-spacing:-.01em;}
-p{margin:0;}
-code{font-family:var(--mono);font-size:.9em;color:var(--ember);
-  background:rgba(239,148,72,.09);border-radius:4px;padding:1px 5px;}
-a{color:inherit;}
-:focus-visible{outline:none;box-shadow:0 0 0 2px var(--ground),0 0 0 4px var(--frost);border-radius:4px;}
-
-.wrap{max-width:var(--wrap);margin:0 auto;padding:0 28px;position:relative;}
-
-/* the vertical seam — the signature */
-.seam{position:fixed;top:0;bottom:0;width:1px;background:var(--seam);opacity:.34;
-  left:calc(50% - min(var(--wrap),100vw)/2 + 28px + (min(var(--wrap),100vw) - 56px) * 5 / 12 + 12px);
-  z-index:0;pointer-events:none;}
-.tick{position:absolute;top:-34px;
-  left:calc(28px + (100% - 56px) * 5 / 12 + 12px);
-  transform:translate(-100%,-50%);display:flex;align-items:center;gap:9px;
-  padding-right:9px;white-space:nowrap;z-index:2;}
-.tick i{display:block;width:11px;height:1px;background:var(--frost);opacity:.6;}
-.tick span{font-family:var(--mono);font-size:11.5px;letter-spacing:.16em;
-  text-transform:uppercase;color:var(--faint);}
-.tick .dot{position:absolute;right:-2.5px;top:50%;width:5px;height:5px;margin-top:-2.5px;
-  border-radius:50%;background:var(--frost);}
-
-/* the full-bleed separator, lifted from /how-it-works — a hairline edge to
-   edge. It marks the section boundary WITHOUT banding the background. */
-section{padding:84px 0;position:relative;}
-section + section{border-top:1px solid var(--line);}
-
-.label{font-family:var(--mono);font-size:11.5px;letter-spacing:.16em;
-  text-transform:uppercase;color:var(--faint);line-height:1.4;}
-/* Leads are TEXT, not muted grey. */
-.lead{margin-top:18px;font-size:18px;line-height:1.62;color:var(--text);max-width:66ch;}
-.note{margin-top:14px;font-family:var(--mono);font-size:12px;color:var(--faint);}
-
-.split{display:grid;grid-template-columns:repeat(12,1fr);gap:24px;}
-.split > .arg{grid-column:1 / span 5;}
-.split > .art{grid-column:6 / span 7;}
-@media(min-width:1024px){ .split > .arg{position:sticky;top:56px;align-self:start;} }
-.plain{display:grid;grid-template-columns:repeat(12,1fr);gap:24px;}
-.plain > *:not(.tick){grid-column:1 / span 8;}
-@media(max-width:860px){
-  .split,.plain{display:block;}
-  .seam,.tick{display:none;}
-  section{padding:64px 0;}
-  body::before{background:
-    radial-gradient(90% 42% at 50% -4%, rgba(79,191,224,.20), transparent 68%),
-    radial-gradient(90% 42% at 50% 104%, rgba(239,148,72,.19), transparent 68%),
-    linear-gradient(176deg,#0a1019 0%,#0b0e14 50%,#150f09 100%);}
-}
-
-/* --- swatches ---------------------------------------------------------- */
-.sw{display:grid;grid-template-columns:repeat(auto-fill,minmax(150px,1fr));gap:12px;}
-.chip{border:1px solid var(--line);border-radius:8px;overflow:hidden;background:var(--surface);}
-.chip .fill{height:52px;}
-.chip .meta{padding:8px 10px;font-family:var(--mono);font-size:11px;line-height:1.5;color:var(--muted);}
-.chip .meta b{display:block;color:var(--text);font-weight:500;}
-
-.scale{border-top:1px solid var(--line);}
-.row{display:grid;grid-template-columns:84px 1fr;gap:20px;align-items:baseline;
-  padding:15px 0;border-bottom:1px solid var(--line);}
-.tabular{font-variant-numeric:tabular-nums;}
-
-/* --- terminal: no traffic lights. The bar names the repo and branch. ---- */
-.term{background:var(--surface);border:1px solid var(--line);border-radius:10px;overflow:hidden;}
-.term-bar{display:flex;align-items:center;gap:10px;padding:9px 14px;
-  border-bottom:1px solid var(--line);font-family:var(--mono);font-size:11.5px;color:var(--faint);}
-.term-bar .br{color:var(--frost);}
-.term-body{padding:16px 18px 18px;font-family:var(--mono);font-size:13px;
-  line-height:1.8;color:var(--text);overflow-x:auto;}
-.term-body .l{white-space:pre;display:block;}
-.p-prompt{color:var(--ok);} .p-dim{color:var(--faint);}
-.p-frost{color:var(--frost);} .p-ember{color:var(--ember);} .p-hit{color:var(--ok);}
-
-/* --- note card: an ember WASH on the field, not paper. ------------------ */
-.card{background:var(--wash-ember);border:1px solid var(--edge-ember);
-  border-radius:10px;padding:15px 17px;}
-.card .k{font-family:var(--mono);font-size:10.5px;letter-spacing:.14em;
-  text-transform:uppercase;color:var(--ember);display:flex;align-items:center;gap:9px;}
-.card .k .fresh{color:var(--ok);}
-.card h3{margin-top:9px;font-size:19px;}
-.card p{margin-top:8px;font-size:15px;line-height:1.6;color:var(--text);}
-.card .anc{margin-top:12px;display:flex;flex-wrap:wrap;gap:6px;}
-.card .anc span{font-family:var(--mono);font-size:11px;background:rgba(255,255,255,.05);
-  border:1px solid var(--line);border-radius:4px;padding:2px 7px;color:var(--muted);}
-
-.stack{display:flex;flex-direction:column;gap:16px;}
-.callout{border:1px solid var(--line);border-left:2px solid var(--ember);
-  border-radius:0 8px 8px 0;background:var(--wash-ember);padding:13px 16px;margin-top:20px;}
-.callout .label{color:var(--ember);}
-.callout p{margin-top:6px;font-size:15px;}
-
-/* ======================================================================
-   CLAUDE CODE PANEL — a faithful replica, so it keeps its OWN neutral
-   ground rather than the site's field. It should read as the real thing
-   sitting on the page, not a themed imitation of it.
-   ====================================================================== */
-.cc{background:var(--cc-bg);border:1px solid var(--cc-line);border-radius:10px;
-  overflow:hidden;color:var(--cc-text);}
-.cc-head{padding:8px 14px;border-bottom:1px solid var(--cc-line);
-  font-family:var(--mono);font-size:11px;color:var(--cc-dim);display:flex;gap:9px;}
-.cc-body{padding:14px;}
-.cc-prompt{background:var(--cc-raise);border:1px solid rgba(255,255,255,.05);
-  border-radius:6px;padding:10px 14px;font-size:14px;color:#f2f2f2;line-height:1.5;}
-.cc-rail{margin-top:2px;}
-.cc-turn{display:grid;grid-template-columns:15px 1fr;gap:11px;align-items:start;
-  padding:9px 0;position:relative;}
-.cc-turn::before{content:"";position:absolute;left:7px;top:0;bottom:0;width:1px;background:var(--cc-line);}
-.cc-turn:first-child::before{top:14px;}
-.cc-turn:last-child::before{bottom:calc(100% - 14px);}
-.cc-turn .d{width:7px;height:7px;border-radius:50%;background:var(--cc-dot);
-  margin:6px 0 0 4px;position:relative;z-index:1;}
-.cc-turn.tool .d{background:var(--cc-tool);}
-.cc-turn .b{min-width:0;font-size:13.5px;line-height:1.6;}
-.cc-turn.think .b{color:var(--cc-dim);}
-.cc-turn .tname{font-weight:600;color:#f2f2f2;}
-.cc-turn .targ{font-family:var(--mono);font-size:12.5px;color:var(--cc-dim);margin-left:7px;}
-.cc-io{margin-top:8px;border:1px solid var(--cc-line);border-radius:6px;
-  background:var(--cc-box);overflow:hidden;}
-.cc-io .r{display:grid;grid-template-columns:34px 1fr;gap:8px;padding:8px 12px 8px 8px;
-  font-family:var(--mono);font-size:12px;line-height:1.65;}
-.cc-io .r + .r{border-top:1px solid var(--cc-line);}
-.cc-io .g{color:#6e6e6e;font-size:10px;letter-spacing:.1em;padding-top:3px;text-align:right;}
-.cc-io .v{color:#cfcfcf;white-space:pre-wrap;word-break:break-word;}
-.cc-io .v .more{color:#6e6e6e;}
-.cc code{font-family:var(--mono);font-size:12.5px;color:var(--cc-code);
-  background:rgba(255,255,255,.06);border-radius:4px;padding:1px 5px;}
-.cc-note{color:var(--cc-code);}
-.cc-foot{margin:12px 14px 14px;border:1px solid rgba(239,148,72,.45);border-radius:9px;
-  padding:9px 13px;display:flex;align-items:center;justify-content:space-between;
-  font-size:13px;color:#7d7d7d;background:#242424;}
-.cc-foot .rt{display:flex;align-items:center;gap:9px;font-family:var(--mono);font-size:11.5px;}
-.cc-foot .send{width:22px;height:22px;border-radius:6px;background:#a8604a;
-  display:grid;place-items:center;color:#f7ded4;font-size:12px;}
-@media(prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important;}}
-</style>
-</head>
-<body>
-<div class="seam"></div>
-
-<section id="field" style="padding-top:64px;">
-  <div class="wrap plain">
-    <div class="tick" aria-hidden="true"><span>field</span><i></i><em class="dot"></em></div>
-    <div>
-      <p class="label">Specimen · coldstart design language · v2</p>
-      <h1 style="margin-top:20px;">Frost on the left. Ember on the right. One field.</h1>
-      <p class="lead">The accents themselves light the page from opposite edges — not two black
-      grounds a shade apart, which is what the last pass shipped and you couldn't see. Every panel
-      below is <b>translucent</b>, so it sits inside this field rather than on top of it. That is
-      what makes a note match the background instead of punching out of it.</p>
-      <p class="note">Prose is near-white. Grey is for labels and captions only — never body copy.</p>
-    </div>
-  </div>
-</section>
-
-<section id="palette">
-  <div class="wrap split">
-    <div class="tick" aria-hidden="true"><span>palette</span><i></i><em class="dot"></em></div>
-    <div class="arg">
-      <p class="label">Palette</p>
-      <h2 style="margin-top:16px;">Two accents, no opaque surfaces.</h2>
-      <p class="lead">Frost is the exact index. Ember is the remembered note. There is no paper
-      stock and no solid card fill — a surface is a wash of white or accent at 3–7% over the field,
-      so the gradient shows through everything.</p>
-    </div>
-    <div class="art">
-      <div class="sw">
-        <div class="chip"><div class="fill" style="background:#4fbfe0;"></div><div class="meta"><b>--frost</b>#4fbfe0 · index</div></div>
-        <div class="chip"><div class="fill" style="background:#ef9448;"></div><div class="meta"><b>--ember</b>#ef9448 · notebook</div></div>
-        <div class="chip"><div class="fill" style="background:#7ec89a;"></div><div class="meta"><b>--ok</b>#7ec89a · state</div></div>
-        <div class="chip"><div class="fill" style="background:rgba(255,255,255,.035);"></div><div class="meta"><b>--surface</b>white 3.5%</div></div>
-        <div class="chip"><div class="fill" style="background:rgba(79,191,224,.07);"></div><div class="meta"><b>--wash-frost</b>frost 7%</div></div>
-        <div class="chip"><div class="fill" style="background:rgba(239,148,72,.07);"></div><div class="meta"><b>--wash-ember</b>ember 7%</div></div>
-      </div>
-      <div style="margin-top:16px;border:1px solid var(--line);border-radius:8px;padding:14px 16px;background:var(--surface);">
-        <p style="font-size:15px;">Body copy — <b>--text #eef3fa</b>, 17:1. This is what every paragraph uses now.</p>
-        <p style="color:var(--muted);font-size:14px;margin-top:7px;">Secondary metadata — --muted #a8b6c9, 9.5:1. Captions and asides only.</p>
-        <p class="label" style="margin-top:9px;">Labels — --faint #7f8da2, mono, never a sentence</p>
-      </div>
-    </div>
-  </div>
-</section>
-
-<section id="type">
-  <div class="wrap split">
-    <div class="tick" aria-hidden="true"><span>type</span><i></i><em class="dot"></em></div>
-    <div class="arg">
-      <p class="label">Typography</p>
-      <h2 style="margin-top:16px;">Archivo, not a serif.</h2>
-      <p class="lead">A serif display on near-black is the most recognizable marker of
-      AI-generated design right now, and coldstart's world is an instrument panel, not a magazine.
-      Archivo's width axis at <code>wdth 112</code> reads engineered. Body and mono are unchanged.</p>
-    </div>
-    <div class="art scale">
-      <div class="row"><span class="label">d1 · 56</span><span style="font-family:var(--display);font-variation-settings:'wdth' 112;font-weight:600;font-size:56px;line-height:1.00;letter-spacing:-.02em;">Two lookups, not three reads</span></div>
-      <div class="row"><span class="label">d2 · 38</span><span style="font-family:var(--display);font-variation-settings:'wdth' 112;font-weight:600;font-size:38px;line-height:1.15;letter-spacing:-.015em;">It already knows</span></div>
-      <div class="row"><span class="label">d3 · 21</span><span style="font-family:var(--display);font-variation-settings:'wdth' 112;font-weight:600;font-size:21px;">Edited together, not imported</span></div>
-      <div class="row"><span class="label">lead · 18</span><span style="font-size:18px;line-height:1.62;">An agent writes down what it learns while it works. The next one gets it for free.</span></div>
-      <div class="row"><span class="label">body · 16</span><span>Notes are anchored to real files and symbols, and re-checked against the live file every time they're read.</span></div>
-      <div class="row"><span class="label">mono · 13</span><span style="font-family:var(--mono);font-size:13px;">{gsCmd}</span></div>
-      <div class="row"><span class="label">data</span><span class="tabular" style="font-family:var(--mono);font-size:13px;">1,204 files · 19 ms · 421 indexed · −64% tokens</span></div>
-    </div>
-  </div>
-</section>
-
-<section id="split">
-  <div class="wrap split">
-    <div class="tick" aria-hidden="true"><span>split</span><i></i><em class="dot"></em></div>
-    <div class="arg">
-      <p class="label">Section type · split</p>
-      <h2 style="margin-top:16px;">Argument left. Artifact right.</h2>
-      <p class="lead">The default. 5 / 7 on a 12-column grid, and on desktop this left column is
-      <b>sticky</b> — the claim holds while the artifact scrolls past, which is what makes a long
-      terminal readable instead of exhausting.</p>
-      <p class="note">No traffic lights. The bar names the repo and branch, which is information.</p>
-    </div>
-    <div class="art stack">
-      <div class="term">
-        <div class="term-bar"><span>coldstart-mcp</span><span class="br">main</span></div>
-        <div class="term-body">
-<span class="l"><span class="p-prompt">$</span> {findCmd}</span>
-<span class="l"><span class="p-dim">[coldstart] cache hit (19ms, 421 files)</span></span>
-<span class="l"> </span>
-<span class="l"><span class="p-frost">▸ src/server/tools.ts</span>  <span class="p-hit">[4/5]</span></span>
-<span class="l">   <span class="p-ember">Role:</span>  <span class="p-dim">defines</span> handleGetStructure</span>
-<span class="l">   <span class="p-dim">co-change arrives as an optional third parameter</span></span>
-<span class="l"> </span>
-<span class="l"><span class="p-frost">▸ src/cli.ts</span>  <span class="p-hit">[5/5]</span></span>
-<span class="l">   <span class="p-ember">Wired:</span>  <span class="p-dim">imports</span> handleGetStructure</span>
-        </div>
-      </div>
-      <div class="card">
-        <div class="k"><span>Flow note</span><span class="fresh">● fresh</span></div>
-        <h3>How the edited-together signal reaches gs</h3>
-        <p>The pairs <code>gs</code> shows are not part of the code index and never travel through
-        the cache pipeline — they live in a keeper-written sidecar each reader loads itself.</p>
-        <div class="anc"><span>src/index-manager.ts</span><span>src/cli.ts</span><span>+1 more</span></div>
-      </div>
-      <p class="note">The note is an ember wash on the field — no paper, nothing punching forward.</p>
-    </div>
-  </div>
-</section>
-
-<section id="plain">
-  <div class="wrap plain">
-    <div class="tick" aria-hidden="true"><span>plain</span><i></i><em class="dot"></em></div>
-    <div>
-      <p class="label">Section type · plain</p>
-      <h2 style="margin-top:16px;">Columns 1–8. Still not centered.</h2>
-      <p class="lead">For FAQ, install, and the closing call to action. One column, same left rail,
-      and the right third stays open so the ember edge has somewhere to be. This is the change that
-      most affects how the landing page feels: nine screens of centered text become nine screens
-      with one consistent edge.</p>
-      <div class="callout">
-        <p class="label">Motion rule</p>
-        <p>Content is never hidden by default. Nothing here waits on JavaScript — which is exactly
-        what /demo/ and /how-it-works/ get wrong today.</p>
-      </div>
-    </div>
-  </div>
-</section>
-
-<section id="panel" style="padding-bottom:130px;">
-  <div class="wrap split">
-    <div class="tick" aria-hidden="true"><span>panel</span><i></i><em class="dot"></em></div>
-    <div class="arg">
-      <p class="label">Demo · Claude Code panel</p>
-      <h2 style="margin-top:16px;">The real chrome, rendered static.</h2>
-      <p class="lead">Built from your screenshots: neutral <code>#1f1f1f</code> ground, the prompt
-      as a raised chip, a dotted rail — <b>green for tool calls</b>, grey for thinking and prose —
-      and tool output in an <code>IN</code>/<code>OUT</code> gutter box.</p>
-      <p class="lead" style="margin-top:14px;">This panel keeps its own neutral ground on purpose.
-      It is a replica, so it should read as the real thing sitting on the page rather than a themed
-      imitation of it.</p>
-      <p class="note">Everything visible on load. No typing, no scroll triggers.</p>
-    </div>
-    <div class="art stack">
-      <div class="cc">
-        <div class="cc-head"><span>coldstart-mcp</span><span>—</span><span>no note yet</span></div>
-        <div class="cc-body">
-          <div class="cc-prompt">why does gs show files edited together — is that from the import graph?</div>
-          <div class="cc-rail">
-            <div class="cc-turn think"><span class="d"></span><span class="b">Thinking</span></div>
-            <div class="cc-turn tool"><span class="d"></span><span class="b">
-              <span class="tname">Bash</span><span class="targ">{findCmd}</span>
-              <div class="cc-io">
-                <div class="r"><span class="g">OUT</span><span class="v">▸ src/server/tools.ts  [4/5]
-   Role: defines handleGetStructure
-▸ src/cli.ts  [5/5]
-<span class="more">… +6 lines</span></span></div>
-              </div>
-            </span></div>
-            <div class="cc-turn tool"><span class="d"></span><span class="b">
-              <span class="tname">Bash</span><span class="targ">{gsCmd}</span>
-              <div class="cc-io">
-                <div class="r"><span class="g">OUT</span><span class="v">function runGs [L166-191]
-  180  const &#123; loadCoChange &#125; = await import('./indexer/cochange.js')
-<span class="more">… +1 line</span></span></div>
-              </div>
-            </span></div>
-            <div class="cc-turn"><span class="d"></span><span class="b">Not the import graph — <code>gs</code> takes co-change as an optional third argument, lazily loaded from <code>cochange.json</code> and passed in by whichever reader is running.</span></div>
-            <div class="cc-turn"><span class="d"></span><span class="b" style="color:var(--cc-dim);">Stop hook · wrote 1 note</span></div>
-          </div>
-        </div>
-        <div class="cc-foot"><span>⌘ Esc to focus or unfocus Claude</span><span class="rt"><span>Auto</span><span class="send">↑</span></span></div>
-      </div>
-
-      <div class="cc">
-        <div class="cc-head"><span>coldstart-mcp</span><span>—</span><span style="color:var(--cc-code);">note recalled</span></div>
-        <div class="cc-body">
-          <div class="cc-prompt">how does the edited-together section get its data?</div>
-          <div class="cc-rail">
-            <div class="cc-turn"><span class="d"></span><span class="b cc-note">notebook · how the edited-together signal reaches gs <span style="color:var(--cc-tool);">[fresh]</span></span></div>
-            <div class="cc-turn"><span class="d"></span><span class="b">From a keeper-written sidecar, not the index — each reader loads <code>cochange.json</code> and passes it in.</span></div>
-            <div class="cc-turn think"><span class="d"></span><span class="b">0 tool calls</span></div>
-          </div>
-        </div>
-        <div class="cc-foot"><span>⌘ Esc to focus or unfocus Claude</span><span class="rt"><span>Auto</span><span class="send">↑</span></span></div>
-      </div>
-    </div>
-  </div>
-</section>
-
-<!-- ============ DEV CONTROL — specimen only, never ships ============ -->
-<div id="fieldctl">
-  <button id="ctl-toggle" type="button" aria-expanded="true">field</button>
-  <div id="ctl-body">
-    <label>shape
-      <select id="c-shape">
-        <option value="glow">corner glow (current)</option>
-        <option value="edge">edge bleed</option>
-        <option value="ramp" selected>flat ramp</option>
-        <option value="off">off</option>
-      </select>
-    </label>
-    <label>frost <input id="c-fa" type="range" min="0" max="60" value="20"><output id="o-fa">.20</output></label>
-    <label>ember <input id="c-ea" type="range" min="0" max="60" value="19"><output id="o-ea">.19</output></label>
-    <label>spread <input id="c-sp" type="range" min="4" max="95" value="50"><output id="o-sp">50%</output></label>
-    <pre id="ctl-out"></pre>
-  </div>
-</div>
-<style>
-#fieldctl{position:fixed;right:16px;bottom:16px;z-index:99;width:250px;
-  background:rgba(14,18,26,.94);border:1px solid rgba(255,255,255,.14);border-radius:10px;
-  font-family:var(--mono);font-size:11px;color:#cfd8e6;backdrop-filter:blur(10px);}
-#ctl-toggle{width:100%;text-align:left;background:none;border:0;color:#7f8da2;cursor:pointer;
-  font-family:var(--mono);font-size:10px;letter-spacing:.16em;text-transform:uppercase;padding:9px 12px;}
-#ctl-body{padding:0 12px 12px;display:grid;gap:9px;}
-#fieldctl.closed #ctl-body{display:none;}
-#fieldctl label{display:grid;grid-template-columns:44px 1fr 38px;align-items:center;gap:8px;color:#7f8da2;}
-#fieldctl select{grid-column:2 / span 2;background:#131a26;color:#cfd8e6;border:1px solid rgba(255,255,255,.14);
-  border-radius:5px;padding:4px 6px;font-family:var(--mono);font-size:11px;}
-#fieldctl input[type=range]{width:100%;accent-color:#4fbfe0;}
-#fieldctl output{text-align:right;color:#cfd8e6;}
-#ctl-out{margin:2px 0 0;padding:8px;background:#0a0f18;border:1px solid rgba(255,255,255,.09);
-  border-radius:6px;font-size:10px;line-height:1.5;color:#8fb9c9;white-space:pre-wrap;word-break:break-all;}
-@media(max-width:860px){#fieldctl{display:none;}}
-</style>
-<script>
-(function(){
-  var r=document.documentElement, W=document.getElementById('fieldctl');
-  var sh=document.getElementById('c-shape'), fa=document.getElementById('c-fa'),
-      ea=document.getElementById('c-ea'), sp=document.getElementById('c-sp'),
-      out=document.getElementById('ctl-out');
-  var DEFAULT_SPREAD={glow:78,edge:16,ramp:50,off:50};
-  function apply(){
-    r.dataset.shape=sh.value;
-    r.style.setProperty('--fa',(fa.value/100).toFixed(2));
-    r.style.setProperty('--ea',(ea.value/100).toFixed(2));
-    r.style.setProperty('--sp',sp.value);
-    document.getElementById('o-fa').value='.'+String(fa.value).padStart(2,'0');
-    document.getElementById('o-ea').value='.'+String(ea.value).padStart(2,'0');
-    document.getElementById('o-sp').value=sp.value+'%';
-    out.textContent='shape: '+sh.value+'\n--fa: '+(fa.value/100).toFixed(2)
-      +'\n--ea: '+(ea.value/100).toFixed(2)+'\n--sp: '+sp.value;
-  }
-  sh.addEventListener('change',function(){ sp.value=DEFAULT_SPREAD[sh.value]; apply(); });
-  [fa,ea,sp].forEach(function(el){ el.addEventListener('input',apply); });
-  document.getElementById('ctl-toggle').addEventListener('click',function(){
-    W.classList.toggle('closed');
-    this.setAttribute('aria-expanded', String(!W.classList.contains('closed')));
-  });
-  apply();
-})();
-</script>
-</body>
-</html>
diff --git a/site-astro/src/pages/vs/vector-rag.astro b/site-astro/src/pages/vs/vector-rag.astro
index 5840f3e..7fc66a0 100644
--- a/site-astro/src/pages/vs/vector-rag.astro
+++ b/site-astro/src/pages/vs/vector-rag.astro
@@ -4,9 +4,9 @@ import SvgDefs from '../../components/SvgDefs.astro';
 import Nav from '../../components/Nav.astro';
 import Footer from '../../components/Footer.astro';
 import '../../styles/tailwind.css';
+import '../../styles/tokens.css';
 import '../../styles/docs.css';
 import '../../styles/how.css';
-import '../../styles/backdrop.css';
 
 const title = 'coldstart vs vector RAG for codebase memory | coldstart';
 const description =
diff --git a/site-astro/src/styles/backdrop.css b/site-astro/src/styles/backdrop.css
index 75aac7f..8faa50b 100644
--- a/site-astro/src/styles/backdrop.css
+++ b/site-astro/src/styles/backdrop.css
@@ -1,20 +1,76 @@
+/* The shared footer rides along here on purpose. Every page shell already
+   imports this file, and a per-page footer import would be a third thing a
+   new page can silently forget - /live/ shipped without this very file once.
+   footer.css defines no tokens, so being hoisted above the :root below is
+   harmless. */
+@import "./footer.css";
+
 /* ============================================================
-   Shared page backdrop — the fading dot grid.
+   Shared page backdrop — the frost→ember field.
    landing.css and docs.css are independent, hand-synced stylesheets
    (see notebook note "site-astro has two independent stylesheets
    that must be hand-kept in sync"). This file exists so a page-wide
    visual like the backdrop has ONE definition instead of two drifting
    copies — every page shell imports it directly, alongside whichever
    of landing.css/docs.css it uses for everything else.
+
+   One page-scale ramp: the cold index on the left edge, the warm
+   notebook on the right, meeting in the middle. It replaces the
+   per-section background bands, so the field runs continuously under
+   the whole document and sections are divided by a hairline instead
+   of by a change of colour.
+
+   This previously held a 30px dot grid. A repeating background
+   pattern is the most common generated-site tell on the web, and it
+   also fought the ramp for the same layer.
    ============================================================ */
+/* ------------------------------------------------------------
+   THE TEXT RAMP — defined here, and ONLY here.
+
+   This file is imported LAST by every page shell, so these :root
+   values win over landing.css / docs.css / how.css. They used to be
+   hand-copied into all three and drifted: the blog got a readable
+   --prose while docs and the landing page kept a 6.9:1 grey.
+
+   Measured against the composited ground (the field above changes
+   what text actually sits on — it cost ~24% of the contrast ratio
+   and the greys were never moved to compensate):
+
+                    frost side   ember side   R-B spread
+     --text          13.4          14.1        -10
+     --muted          9.0           9.4        -13
+     --faint          6.4           6.7        -15
+
+   The old values were --muted 5.3 / --faint 4.3 — and 4.3 is BELOW
+   the 4.5 AA floor for normal text. All three are near-neutral now:
+   DESIGN.md 11 measured that a blue-grey (R-B spread 39) on a
+   blue-black ground has too little hue separation from its own
+   background, which is what read as washed out.
+   ------------------------------------------------------------ */
+:root{
+  --text:#eef2f8;   /* prose. The default for a paragraph. */
+  --muted:#c3c8d0;  /* secondary prose, leads, list bodies */
+  --faint:#a3a9b2;  /* labels, captions, meta, axis ticks */
+  --ink:var(--text);    /* docs.css name for --text */
+  --prose:var(--muted); /* essay name for body prose */
+}
+
 body::before{
   content:"";
   position:fixed;
   inset:0;
   z-index:-1;
   pointer-events:none;
-  background-image:radial-gradient(rgba(255,255,255,.09) 1px,transparent 1.5px);
-  background-size:30px 30px;
-  -webkit-mask-image:radial-gradient(65% 55% at 50% 0%,#000,transparent 72%);
-  mask-image:radial-gradient(65% 55% at 50% 0%,#000,transparent 72%);
+  background:linear-gradient(90deg,
+    rgba(79,191,224,.17) 0%, transparent 42%,
+    transparent 58%, rgba(239,148,72,.16) 100%);
+}
+
+/* Below the two-column breakpoint the axis rotates: frost top, ember bottom. */
+@media(max-width:900px){
+  body::before{
+    background:linear-gradient(180deg,
+      rgba(79,191,224,.17) 0%, transparent 42%,
+      transparent 58%, rgba(239,148,72,.16) 100%);
+  }
 }
diff --git a/site-astro/src/styles/docs.css b/site-astro/src/styles/docs.css
index 0be0810..9ddde6c 100644
--- a/site-astro/src/styles/docs.css
+++ b/site-astro/src/styles/docs.css
@@ -1,30 +1,32 @@
 /* coldstart docs — dark design system, tokens matched to landing.css
    frost = navigation/index, ember = notebook/memory */
-
-:root {
-  --bg: #070a11;
-  --surface: #0f1826;
-  --surface-2: #0b111c;
-  --ink: #e7eef8;
-  --muted: #8b9ab2;
-  --frost: #4fbfe0;
-  --frost-bright: #6fd3ef;
-  --ember: #ef9448;
-  --ember-bright: #ffb267;
-  --line: #1a2536;
-  --line-warm: #2a2218;
-  --term-bg: #05080e;
-  --term-ink: #c3d0e2;
-  --ok: #57cc92;
-  --ok-bg: #10241a;
-  --warn: #ef9448;
-  --warn-bg: #2a1e0c;
-  --mono: "JetBrains Mono", "SF Mono", ui-monospace, "Fira Code", Menlo, Consolas, monospace;
-  --sans: "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-  --display: "Newsreader", Georgia, serif;
-  --wrap: 1080px;
-  --radius: 12px;
-}
+@import './tokens.css';
+
+/* ============================================================
+   THE FIELD — frost bleeding from left, ember from right, over dark ramp.
+   Fixed pseudo-element (not background-attachment:fixed, which is unreliable).
+   ============================================================ */
+body::before{
+  content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
+  background:
+    linear-gradient(90deg,
+      rgba(79,191,224,.20) 0%, transparent 42%,
+      transparent 58%, rgba(239,148,72,.19) 100%),
+    #0b0e14;
+}
+@media(max-width:860px){
+  body::before{background:
+    linear-gradient(180deg,
+      rgba(79,191,224,.20) 0%, transparent 42%,
+      transparent 58%, rgba(239,148,72,.19) 100%),
+    #0b0e14;}
+}
+
+/* ============================================================
+   FULL-BLEED SEPARATOR — marks section boundaries without banding background.
+   ============================================================ */
+section { padding: 84px 0; }
+section + section { border-top: 1px solid var(--line); }
 
 * { box-sizing: border-box; }
 html { scroll-behavior: smooth; }
@@ -102,11 +104,7 @@ nav {
   border-radius: var(--radius); overflow: hidden;
 }
 .term-bar { display: flex; align-items: center; gap: 8px; padding: 12px 16px; border-bottom: 1px solid rgba(255,255,255,.06); }
-.term-bar .tl { width: 11px; height: 11px; border-radius: 50%; }
-.term-bar .tl:nth-child(1) { background: #ff5f57; }
-.term-bar .tl:nth-child(2) { background: #febc2e; }
-.term-bar .tl:nth-child(3) { background: #28c840; }
-.term-bar .title { margin-left: 10px; font-family: var(--mono); font-size: 12px; color: #7a8aa3; }
+.term-bar .title { margin-left: 10px; font-family: var(--mono); font-size: 12px; color: var(--faint); }
 .term-body { padding: 20px 22px 26px; font-family: var(--mono); font-size: 13.5px; line-height: 1.75; color: var(--term-ink); overflow-x: auto; }
 .term-body .ln { white-space: pre; display: block; }
 .c-prompt { color: #4fd18b; }
@@ -122,7 +120,6 @@ nav {
 /* docs.html uses smaller inline terminals — scope a compact variant */
 .doc-sec .term { margin-top: 18px; box-shadow: none; }
 .doc-sec .term-bar { padding: 10px 14px; }
-.doc-sec .term-bar .tl { width: 10px; height: 10px; }
 .doc-sec .term-bar .title { margin-left: 8px; font-size: 11.5px; }
 .doc-sec .term-body { padding: 16px 18px; font-size: 13px; line-height: 1.7; }
 .doc-sec .term-body .gap { height: 9px; }
@@ -171,27 +168,14 @@ a.fcard:hover { border-color: color-mix(in srgb, var(--frost) 45%, var(--line));
 .doc-sec .fcard h4 { font-size: 15px; margin: 9px 0 7px; }
 .doc-sec .fcard p { font-size: 14px; }
 
-/* ---- FOOTER (shared chrome — same max-width/padding as nav) ---- */
-footer { border-top: 1px solid var(--line); padding: 48px 0; }
-.foot-in { max-width: 1120px; margin: 0 auto; padding: 0 28px; display: flex; justify-content: space-between; gap: 24px; flex-wrap: wrap; align-items: center; }
-.foot-links { display: flex; gap: 22px; font-family: var(--mono); font-size: 13.5px; }
-.foot-links a { color: var(--muted); text-decoration: none; }
-.foot-links a:hover { color: var(--ink); }
-.foot-id { display: flex; flex-direction: column; gap: 7px; }
-.foot-id .brand { font-size: 15px; gap: 8px; }
-.foot-tagline { font-family: var(--mono); color: var(--muted); font-size: 12.5px; letter-spacing: .02em; }
-@media (max-width: 640px) {
-  footer { padding: 40px 0 48px; }
-  .foot-in { flex-direction: column; align-items: flex-start; gap: 24px; padding: 0 20px; }
-  .foot-id { gap: 8px; }
-  .foot-links { flex-wrap: wrap; gap: 14px 20px; }
-  .foot-links a { display: inline-block; padding: 3px 0; }
-}
+/* footer: moved to styles/footer.css (one definition, shared) */
 
 /* =========================================================
    DOCS PAGE — sidebar + reference layout
    ========================================================= */
-.docs { max-width: 1200px; margin: 0 auto; padding: 0 24px; display: grid; grid-template-columns: 236px 1fr; gap: 56px; align-items: start; }
+/* 1120/28 matches .nav-in and .wrap - at 1200/24 the docs content edge sat
+   44px left of the nav's, so the logo looked indented against the sidebar. */
+.docs { max-width: 1120px; margin: 0 auto; padding: 0 28px; display: grid; grid-template-columns: 236px 1fr; gap: 56px; align-items: start; }
 @media (max-width: 860px) { .docs { grid-template-columns: 1fr; gap: 0; } }
 
 .side { position: sticky; top: 64px; align-self: start; max-height: calc(100vh - 64px); overflow-y: auto; padding: 34px 0 60px; }
@@ -231,13 +215,29 @@ footer { border-top: 1px solid var(--line); padding: 48px 0; }
 .content h1 { font-family: var(--display); font-weight: 500; font-size: clamp(30px, 5vw, 40px); letter-spacing: -.01em; line-height: 1.1; }
 .content h2 { font-family: var(--display); font-weight: 500; font-size: clamp(21px, 3vw, 26px); letter-spacing: -.01em; }
 .content > p, .doc-sec > p, .prose p { color: var(--muted); font-size: 16px; margin-top: 14px; }
+/* Subsection heads inside a doc section. Sans, not the Newsreader display
+   face the h2s use - an h3 here is a shelf label, not another headline, and
+   the weight change alone is enough to rank it under the h2. This exists
+   because the install section was one 130-word paragraph plus two visually
+   identical flag tables, the second of which was not flags at all. */
+.doc-sec h3 { font-family: var(--sans); font-weight: 600; font-size: 15px; color: var(--ink); margin-top: 30px; }
+.doc-sec h3 + .flags { margin-top: 12px; }
+.doc-sec h3 + .term { margin-top: 12px; }
+.doc-sec h3 + p { margin-top: 10px; }
+
 .content p a, .doc-sec p a, .prose p a, .doc-sec li a { color: var(--frost); text-decoration: underline; text-decoration-color: color-mix(in srgb, var(--frost) 35%, transparent); text-underline-offset: 2px; }
 .content p a:hover, .doc-sec p a:hover, .prose p a:hover, .doc-sec li a:hover { text-decoration-color: currentColor; }
 .prose p + p { margin-top: 12px; }
 .lead-p { font-size: 18px !important; color: var(--muted); margin-top: 18px; }
 .content b, .prose b { color: var(--ink); font-weight: 600; }
 .content em { color: var(--ink); font-style: italic; }
-p code, li code, .prose code { font-size: 13.5px; background: var(--surface-2); border: 1px solid var(--line); border-radius: 6px; padding: 1px 6px; color: var(--ink); }
+/* Inline code in prose is EMBER, matching .keynote code in landing.css.
+   Before this, every docs and blog page rendered with zero ember on it —
+   16 frost elements and 0 warm ones on /docs/ — which is what made the
+   docs read as a single-colour site. Frost stays on the navigational
+   chrome (nav, kickers, active states); ember marks the artifacts the
+   text is about. */
+p code, li code, .prose code { font-size: 13.5px; background: rgba(239,148,72,.07); border: 1px solid var(--line-warm); border-radius: 6px; padding: 1px 6px; color: var(--ember); }
 
 .cmd { margin-top: 8px; }
 .cmd .name { font-family: var(--mono); font-size: 24px; font-weight: 700; letter-spacing: -.02em; display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
@@ -297,16 +297,9 @@ body.essay-page {
   --bg: #0b0e14;          /* lifted off pure black — easier for sustained reading */
   --surface: #141a24;
   --surface-2: #10151d;
-  --ink: #eef3fb;
-  --prose: #c9d3e2;       /* 12.8:1 — was #8b9ab2 at 6.9:1 */
-  --muted: #8b9ab2;
-  --faint: #7a8aa3;
+  /* --ink / --prose / --muted / --faint come from backdrop.css */
   --line: #1e2735;
   --line-soft: #182029;
-  --frost: #4fbfe0;
-  --frost-bright: #6fd3ef;
-  --ember: #ef9448;
-  --ember-bright: #ffb267;
   --term-border: #1e2735;
   --sel: rgba(79,191,224,.20);
   color-scheme: dark;
@@ -387,6 +380,12 @@ body.essay-page .term { border-color: var(--term-border); }
 .essay-meta .sep { color: var(--faint); letter-spacing: 0; }
 .essay-meta time,
 .essay-meta .rt { color: var(--muted); letter-spacing: .06em; }
+/* The kicker carries the post topic temperature: frost for the index and
+   measurement posts, ember for the notebook and memory ones. Reading time was
+   dropped from the card - at three segments the longest kicker wrapped to a
+   second line and pushed that one cards title out of alignment with its row. */
+.essay-meta .k { color: var(--frost); }
+.essay-meta .k.warm { color: var(--ember); }
 
 .essay-card h2 {
   font-family: var(--display);
@@ -532,11 +531,11 @@ body.essay-page .term { border-color: var(--term-border); }
 
 .essay-article code {
   font-size: .82em;
-  background: var(--surface);
-  border: 1px solid var(--line);
+  background: rgba(239,148,72,.07);
+  border: 1px solid var(--line-warm);
   border-radius: 5px;
   padding: 1.5px 6px;
-  color: var(--ink);
+  color: var(--ember);
   white-space: nowrap;
 }
 
diff --git a/site-astro/src/styles/footer.css b/site-astro/src/styles/footer.css
new file mode 100644
index 0000000..4c56025
--- /dev/null
+++ b/site-astro/src/styles/footer.css
@@ -0,0 +1,83 @@
+/* ============================================================
+   The footer — ONE definition, shared by every page.
+
+   It used to be a single row of five links, duplicated in
+   landing.css and docs.css (see the notebook note "site-astro has
+   two independent stylesheets that must be hand-kept in sync").
+   Both copies were deleted; this file is reached through an
+   @import at the top of backdrop.css, which every page shell
+   already imports. That is deliberate: adding a per-page import
+   would be a third thing a new page can silently forget, and the
+   notebook already has a note about /live/ shipping without its
+   backdrop for exactly that reason.
+
+   WHY IT IS BIG. Not for weight. The site ships /demo/, /live/,
+   /notebook/, /graph/, /vs/vector-rag, three how-it-works pages
+   and three docs pages, and most of them were reachable only from
+   the nav dropdown. A footer is where a reader who has finished a
+   page finds the next one, and it is also the site's only
+   internal-linking surface.
+
+   Sentence-case column headings, not tracked-out uppercase — the
+   uppercase eyebrow is the single most common generated-site tell
+   and DESIGN.md rules it out everywhere else on the site too.
+   ============================================================ */
+
+footer{
+  border-top:1px solid var(--line);
+  padding:64px 0 40px;
+  margin-top:0;
+}
+.foot-in{
+  max-width:1120px;margin:0 auto;padding:0 28px;
+  display:grid;grid-template-columns:minmax(220px,1.4fr) repeat(4,minmax(0,1fr));
+  gap:40px 32px;align-items:start;
+}
+
+/* ---- identity block ---- */
+.foot-id{display:flex;flex-direction:column;gap:12px;align-items:flex-start;}
+.foot-id .brand{font-size:16px;gap:9px;}
+.foot-blurb{
+  font-size:13.5px;line-height:1.6;color:var(--muted);max-width:30ch;
+}
+
+/* ---- link columns ---- */
+.foot-col{display:flex;flex-direction:column;gap:11px;min-width:0;}
+.foot-col h3{
+  font-family:var(--mono);font-size:11.5px;font-weight:500;
+  letter-spacing:.02em;color:var(--faint);margin:0 0 2px;
+}
+.foot-col a{
+  font-size:13.5px;line-height:1.35;color:var(--muted);text-decoration:none;
+  transition:color .14s;
+}
+.foot-col a:hover{color:var(--text);}
+.foot-col a.ext::after{content:"↗";margin-left:5px;font-size:11px;opacity:.55;}
+
+/* ---- bottom rule ---- */
+.foot-base{
+  max-width:1120px;margin:48px auto 0;padding:20px 28px 0;
+  border-top:1px solid var(--line);
+  display:flex;justify-content:space-between;align-items:center;gap:16px;flex-wrap:wrap;
+}
+.foot-tagline{
+  font-family:var(--mono);color:var(--faint);font-size:12px;letter-spacing:.02em;
+}
+/* The one warm mark down here: the same frost->ember pair the whole
+   page is built on, at the scale of a full stop. */
+.foot-temp{display:flex;align-items:center;gap:7px;
+  font-family:var(--mono);font-size:11.5px;color:var(--faint);}
+.foot-temp i{width:7px;height:7px;border-radius:50%;display:inline-block;}
+.foot-temp i.f{background:var(--frost);}
+.foot-temp i.e{background:var(--ember);}
+
+@media(max-width:1000px){
+  .foot-in{grid-template-columns:repeat(2,minmax(0,1fr));gap:34px 28px;}
+  .foot-id{grid-column:1 / -1;}
+}
+@media(max-width:520px){
+  footer{padding:44px 0 32px;}
+  .foot-in{grid-template-columns:1fr;padding:0 20px;gap:30px;}
+  .foot-base{padding:18px 20px 0;margin-top:36px;}
+  .foot-col a{padding:2px 0;}
+}
diff --git a/site-astro/src/styles/how.css b/site-astro/src/styles/how.css
index b4c4e42..da9018e 100644
--- a/site-astro/src/styles/how.css
+++ b/site-astro/src/styles/how.css
@@ -12,7 +12,6 @@ body.how-page {
   --paper: #e5d9bd;
   --paper-ink: #2a2620;
   --paper-line: #c7b790;
-  --faint: #7a8aa3;
   --ember-dim: #a86a35;
 }
 
@@ -384,7 +383,7 @@ body.how-page {
 .how-page .how-cmds.has-copy { position: relative; padding-right: 84px; }
 .how-page .copy-btn {
   position: absolute; top: 12px; right: 12px;
-  font-family: var(--mono); font-size: 11px; color: #8aa0bd; cursor: pointer;
+  font-family: var(--mono); font-size: 11px; color: var(--faint); cursor: pointer;
   background: rgba(255, 255, 255, .04); border: 1px solid var(--line);
   border-radius: 6px; padding: 5px 10px;
   transition: color .15s, background .15s, border-color .15s;
diff --git a/site-astro/src/styles/landing.css b/site-astro/src/styles/landing.css
index f1d1aab..ae2f139 100644
--- a/site-astro/src/styles/landing.css
+++ b/site-astro/src/styles/landing.css
@@ -2,32 +2,43 @@
    coldstart — home · notebook-first, destination nav (nextjs-style IA)
    temperature = concept: frost = the cold exact index, ember = the warm memory.
    ============================================================ */
-:root{
-  --void:#070a11;
-  --ink-1:#0b111c;
-  --ink-2:#0f1826;
-  --raised:#121d2d;
-  --warm-ground:#12100e;
-  --text:#e7eef8;
-  --muted:#8b9ab2;
-  --faint:#7a8aa3;
-  --frost:#4fbfe0;
-  --frost-dim:#2f89a8;
-  --ember:#ef9448;
-  --ember-dim:#a86a35;
-  --ok:#57cc92;
-  --line:#1a2536;
-  --line-warm:#2a2218;
-
-  --paper:#e5d9bd;
-  --paper-ink:#2a2620;
-  --paper-line:#c7b790;
-
-  --mono:"JetBrains Mono","SF Mono",ui-monospace,"Fira Code",Menlo,Consolas,monospace;
-  --sans:"IBM Plex Sans",system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
-  --display:"Newsreader",Georgia,serif;
-  --wrap:1120px;
+@import './tokens.css';
+
+/* ============================================================
+   THE FIELD — frost bleeding from left, ember from right, over dark ramp.
+   Fixed pseudo-element (not background-attachment:fixed, which is unreliable).
+   ============================================================ */
+body::before{
+  content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;
+  background:
+    linear-gradient(90deg,
+      rgba(79,191,224,.20) 0%, transparent 42%,
+      transparent 58%, rgba(239,148,72,.19) 100%),
+    #0b0e14;
 }
+@media(max-width:860px){
+  body::before{background:
+    linear-gradient(180deg,
+      rgba(79,191,224,.20) 0%, transparent 42%,
+      transparent 58%, rgba(239,148,72,.19) 100%),
+    #0b0e14;}
+}
+
+/* ============================================================
+   THE SEAM — hairline running full viewport height at column-6 gutter.
+   Shown only on desktop (≥1024px based on grid rules).
+   ============================================================ */
+.seam{position:fixed;top:0;bottom:0;width:1px;background:var(--seam);opacity:.34;
+  left:calc(50% - min(var(--wrap),100vw)/2 + 28px + (min(var(--wrap),100vw) - 56px) * 5 / 12 + 12px);
+  z-index:0;pointer-events:none;}
+@media(max-width:860px){.seam{display:none;}}
+
+/* ============================================================
+   FULL-BLEED SEPARATOR — marks section boundaries without banding background.
+   ============================================================ */
+section{padding:84px 0;}
+section + section{border-top:1px solid var(--line);}
+
 *{box-sizing:border-box;}
 body{
   margin:0;background:var(--void);color:var(--text);
@@ -107,9 +118,7 @@ h2{font-family:var(--display);font-weight:500;font-size:clamp(28px,4vw,42px);
 
 /* ---------- HERO ---------- */
 .hero{padding:44px 0 64px;position:relative;overflow:hidden;text-align:center;}
-.hero::before{content:"";position:absolute;inset:0;z-index:-1;
-  background:
-    radial-gradient(70% 55% at 50% -10%,color-mix(in srgb,var(--frost) 13%,transparent),transparent 60%);}
+/* No hero-local glow: the page-wide field in backdrop.css is the only field. */
 .hero-in{max-width:920px;margin:0 auto;}
 .kicker{font-family:var(--mono);font-size:13px;letter-spacing:.1em;text-transform:uppercase;
   color:var(--faint);margin-bottom:20px;}
@@ -147,10 +156,8 @@ h1.title .cold{color:var(--frost);}
 .navsec .term{margin-top:48px;}
 .term-bar{display:flex;align-items:center;gap:8px;padding:12px 15px;
   border-bottom:1px solid rgba(255,255,255,.05);background:rgba(255,255,255,.015);}
-.tl{width:11px;height:11px;border-radius:50%;}
-.tl:nth-child(1){background:#ff5f57;}.tl:nth-child(2){background:#febc2e;}.tl:nth-child(3){background:#28c840;}
-.term-title{margin-left:10px;font-family:var(--mono);font-size:11.5px;color:#7a8aa3;}
-.copy-btn{margin-left:auto;font-family:var(--mono);font-size:11px;color:#8aa0bd;cursor:pointer;
+.term-title{margin-left:10px;font-family:var(--mono);font-size:11.5px;color:var(--faint);}
+.copy-btn{margin-left:auto;font-family:var(--mono);font-size:11px;color:var(--faint);cursor:pointer;
   background:rgba(255,255,255,.04);border:1px solid rgba(255,255,255,.08);border-radius:6px;
   padding:4px 10px;transition:color .15s,background .15s,border-color .15s;}
 .copy-btn:hover{color:#eef3fb;background:rgba(255,255,255,.08);border-color:rgba(255,255,255,.16);}
@@ -170,7 +177,9 @@ h1.title .cold{color:var(--frost);}
 @keyframes blink{50%{opacity:0;}}
 
 /* ---------- NAVIGATION SECTION (the index) ---------- */
-.navsec{background:var(--ink-1);border-top:1px solid var(--line);border-bottom:1px solid var(--line);}
+/* No section background: the page-wide field runs underneath, and sections are
+   divided by a hairline instead of by a band of colour. */
+.navsec{border-top:1px solid var(--line);}
 .navsec > .wrap > .rise:first-child,
 .phil > .wrap > .rise:first-child{max-width:720px;margin-left:auto;margin-right:auto;text-align:center;}
 .navsec > .wrap > .rise:first-child .lead,
@@ -195,11 +204,7 @@ h1.title .cold{color:var(--frost);}
 .op p em{color:var(--text);font-style:normal;border-bottom:1px solid var(--frost-dim);}
 
 /* ---------- NOTEBOOK (the lead value, warm) ---------- */
-.nb{background:
-    radial-gradient(90% 70% at 82% -5%,color-mix(in srgb,var(--ember) 13%,transparent),transparent 58%),
-    radial-gradient(70% 60% at 0% 100%,color-mix(in srgb,var(--ember) 8%,transparent),transparent 55%),
-    var(--warm-ground);
-  border-top:1px solid var(--line-warm);border-bottom:1px solid var(--line-warm);}
+.nb{border-top:1px solid var(--line-warm);}
 .nb h2 .warm{color:var(--ember);}
 
 /* the notebook reads as one centered, intimate column — a diary entry, not a
@@ -262,7 +267,7 @@ h1.title .cold{color:var(--frost);}
 .viewer{border:1px solid var(--line-warm);border-radius:13px;background:#0e0c09;overflow:hidden;
   box-shadow:0 30px 70px -40px rgba(0,0,0,.9);}
 .vchrome{display:flex;align-items:center;gap:8px;padding:10px 14px;background:rgba(255,255,255,.02);border-bottom:1px solid var(--line-warm);}
-.vchrome .tl{width:10px;height:10px;}
+
 .vurl{margin-left:8px;font-family:var(--mono);font-size:11px;color:var(--faint);
   background:rgba(0,0,0,.4);border:1px solid var(--line-warm);border-radius:6px;padding:3px 10px;flex:1;}
 .vapp{display:grid;grid-template-columns:200px 1fr;min-height:300px;}
@@ -328,7 +333,7 @@ h1.title .cold{color:var(--frost);}
 .nb-foot b{color:var(--ember);font-weight:600;}
 
 /* ---------- PHILOSOPHY / why it works ---------- */
-.phil{background:var(--ink-1);border-top:1px solid var(--line);border-bottom:1px solid var(--line);}
+.phil{border-top:1px solid var(--line);}
 .cmp{display:grid;grid-template-columns:1fr 1fr;gap:20px;margin-top:44px;}
 @media(max-width:760px){.cmp{grid-template-columns:1fr;}}
 .col{border:1px solid var(--line);border-radius:13px;background:var(--void);padding:26px;}
@@ -366,7 +371,7 @@ h1.title .cold{color:var(--frost);}
 .article-card p{margin-top:12px;color:var(--muted);font-size:14.5px;}
 
 /* ---------- FAQ ---------- */
-.faq{background:var(--ink-1);border-top:1px solid var(--line);}
+.faq{border-top:1px solid var(--line);}
 .faq > .wrap > .rise:first-child{max-width:720px;margin-left:auto;margin-right:auto;text-align:center;}
 .faq > .wrap > .rise:first-child .lead{margin-left:auto;margin-right:auto;}
 .faq-list{display:flex;flex-direction:column;gap:0;margin-top:48px;max-width:720px;margin-left:auto;margin-right:auto;}
@@ -380,8 +385,10 @@ h1.title .cold{color:var(--frost);}
 .faq-q::marker{color:var(--frost-dim);}
 .faq-item[open] .faq-q{margin-bottom:14px;}
 .faq-a{font-size:15px;color:var(--muted);line-height:1.65;margin:0;padding:0;max-width:62ch;}
-.faq-a code{font-family:var(--mono);font-size:13px;color:var(--frost);background:rgba(79,191,224,.08);
-  border:1px solid var(--line);border-radius:4px;padding:1px 5px;}
+/* Ember, matching p code / li code in docs.css: inline code marks the
+   artifact the sentence is about. Frost stays on navigational chrome. */
+.faq-a code{font-family:var(--mono);font-size:13px;color:var(--ember);background:rgba(239,148,72,.08);
+  border:1px solid var(--line-warm);border-radius:4px;padding:1px 5px;}
 @media(max-width:640px){.faq-item{padding:20px;}.faq-q{font-size:15.5px;}.faq-a{font-size:14px;}}
 
 /* ---------- INSTALL (in hero) / FAQ CLOSE ---------- */
@@ -391,21 +398,7 @@ h1.title .cold{color:var(--frost);}
 .install-langs{margin-top:22px;font-family:var(--mono);font-size:12.5px;color:var(--faint);}
 
 /* ---------- FOOTER ---------- */
-footer{border-top:1px solid var(--line);padding:50px 0;}
-.foot-in{max-width:var(--wrap);margin:0 auto;padding:0 28px;display:flex;justify-content:space-between;
-  gap:24px;flex-wrap:wrap;align-items:center;}
-.foot-links{display:flex;gap:22px;font-family:var(--mono);font-size:13px;}
-.foot-links a{color:var(--muted);}.foot-links a:hover{color:var(--text);}
-.foot-id{display:flex;flex-direction:column;gap:7px;}
-.foot-id .brand{font-size:14px;gap:8px;}
-.foot-tagline{font-family:var(--mono);color:var(--faint);font-size:12.5px;letter-spacing:.02em;}
-@media(max-width:640px){
-  footer{padding:40px 0 48px;}
-  .foot-in{flex-direction:column;align-items:flex-start;gap:24px;padding:0 20px;}
-  .foot-id{gap:8px;}
-  .foot-links{flex-wrap:wrap;gap:14px 20px;}
-  .foot-links a{display:inline-block;padding:3px 0;}
-}
+/* footer: moved to styles/footer.css (one definition, shared) */
 
 @media(prefers-reduced-motion:reduce){
   *{animation:none!important;transition:none!important;}
diff --git a/site-astro/src/styles/tokens.css b/site-astro/src/styles/tokens.css
new file mode 100644
index 0000000..9e4939a
--- /dev/null
+++ b/site-astro/src/styles/tokens.css
@@ -0,0 +1,64 @@
+/* Design language tokens — one root block, imported by every page.
+   Consolidated from landing.css and docs.css. v2 design spec values. */
+:root {
+  /* --- The palette — NEW DESIGN SPEC ---------------------------------------- */
+  --ground: #0b0e14;
+  --frost: #4fbfe0;
+  --ember: #ef9448;
+  --ok: #7ec89a;
+  --text: #eef3fa;
+  --muted: #a8b6c9;
+  --faint: #7f8da2;
+  --surface: rgba(255,255,255,.035);
+  --line: rgba(255,255,255,.09);
+  --wash-frost: rgba(79,191,224,.07);
+  --wash-ember: rgba(239,148,72,.07);
+  --edge-ember: rgba(239,148,72,.22);
+
+  /* --- Claude Code panel — its own neutral ground ----------------------- */
+  --cc-bg: #1f1f1f;
+  --cc-raise: #2e2e2e;
+  --cc-box: #1a1a1a;
+  --cc-line: #383838;
+  --cc-text: #e3e3e3;
+  --cc-dim: #8a8a8a;
+  --cc-code: #d9a05b;
+  --cc-dot: #6b6b6b;
+  --cc-tool: #7ec89a;
+
+  /* --- Seam (the signature device) --------------------------------------- */
+  --seam: linear-gradient(180deg, var(--frost), var(--ember));
+
+  /* --- Typography — NEW DESIGN SPEC ---------------------------------------- */
+  --display: "Archivo", system-ui, sans-serif;
+  --sans: "IBM Plex Sans", system-ui, sans-serif;
+  --mono: "JetBrains Mono", ui-monospace, Menlo, monospace;
+
+  /* --- Layout ------------------------------------------------------------ */
+  --wrap: 1120px;
+
+  /* --- LEGACY VARIABLES (to be removed in subsequent steps) — currently used
+     by landing.css and docs.css. These are kept for step 1 consolidation only. */
+  --void: #070a11;
+  --ink-1: #0b111c;
+  --ink-2: #0f1826;
+  --raised: #121d2d;
+  --warm-ground: #12100e;
+  --frost-dim: #2f89a8;
+  --ember-dim: #a86a35;
+  --line-warm: #2a2218;
+  --paper: #e5d9bd;
+  --paper-ink: #2a2620;
+  --paper-line: #c7b790;
+  --bg: #070a11;
+  --surface-2: #0f1826;
+  --ink: #e7eef8;
+  --frost-bright: #6fd3ef;
+  --ember-bright: #ffb267;
+  --term-bg: #05080e;
+  --term-ink: #c3d0e2;
+  --ok-bg: #10241a;
+  --warn: #ef9448;
+  --warn-bg: #2a1e0c;
+  --radius: 12px;
+}
diff --git a/src/kb/view-template.ts b/src/kb/view-template.ts
index a3e2496..4ae565a 100644
--- a/src/kb/view-template.ts
+++ b/src/kb/view-template.ts
@@ -1,8 +1,35 @@
 /**
- * Embedded single-file notebook viewer (client). Generated from the
- * design source; do not hand-edit. Two placeholders are substituted by
- * `renderViewHtml` in `kb view`: `__TITLE__` (the tab title, repo-scoped) and
- * `__DATA_JSON__` (the baked note data). Shipped as a string because tsc does
- * not copy non-.ts assets into dist.
+ * Embedded single-file notebook viewer (client). THIS FILE IS THE SOURCE —
+ * unlike the graph viewer (scripts/graph-viewer/sphere.template.html +
+ * build-template.mjs) there is no generator for it; scripts/kb-viewer/ holds
+ * only build-site-page.mjs, which BAKES this template for the marketing site.
+ * Edit here. Two placeholders are substituted by `renderViewHtml` in
+ * `kb view`: `__TITLE__` (the tab title, repo-scoped) and `__DATA_JSON__`
+ * (the baked note data). Shipped as a string because tsc does not copy
+ * non-.ts assets into dist.
+ *
+ * PALETTE. The :root block below is the brand surface, shared by the local
+ * `kb view` output and by /notebook/ on coldstartmcp.dev - theming it here
+ * is what keeps the two identical. Three deliberate calls:
+ *
+ *  - It stays LIGHT-grounded. The site is dark, but this is a long-form
+ *    reading surface for note prose, and a dark ground is worse for that.
+ *    Brand uniformity is carried by hue, not by inverting the page.
+ *  - `--file` is FROST and `--flow` is EMBER, replacing a generic blue
+ *    (#1f4fd8) and teal. It matches the site: a file note is a fixed,
+ *    exact address (cold) and a flow note is a path through the code
+ *    (warm). `--accent` follows --file. These are the deep, on-white
+ *    values of the site pair, not #4fbfe0/#ef9448, which fail on white.
+ *  - The freshness scale (fresh/changed/missing/unver) stays a green/
+ *    amber/red/grey traffic light. That is status, not brand, and readers
+ *    already know how to read it. `--changed` was pushed redder (#b3400b)
+ *    so it does not collide with the new ember `--flow`.
+ *
+ * Contrast on --ground: ink 15.3, ink-soft 8.7, muted 5.0, faint 3.9.
+ * The old muted/faint measured 4.0 and 2.1 - both were below AA.
+ *
+ * FONTS stay system stacks on purpose. `kb view` output is opened as a
+ * local file, often offline; a webfont token here would look correct in
+ * the repo and in a screenshot and silently fail for the actual user.
  */
-export const VIEW_TEMPLATE ="<title>__TITLE__</title>\n<style>\n  :root{\n    --ground:#eaeef3; --surface:#ffffff; --rail:#f5f8fc; --sunk:#eef2f7;\n    --ink:#161a22; --ink-soft:#39414f; --muted:#69748a; --faint:#9aa6b8;\n    --line:#dce2ec; --line-soft:#e8edf3;\n    --accent:#1f4fd8; --accent-soft:#e7ecfd; --accent-ink:#173bab;\n    --fresh:#137a3b; --fresh-bg:#e4f4ea;\n    --changed:#a85a06; --changed-bg:#fbeedd;\n    --missing:#bb1436; --missing-bg:#fbe3e8;\n    --unver:#5a6577; --unver-bg:#eceff4;\n    --flow:#0b7285; --flow-bg:#dcf1f4;\n    --file:#1f4fd8; --file-bg:#e7ecfd;\n    --mono:ui-monospace,\"SF Mono\",SFMono-Regular,Menlo,Consolas,monospace;\n    --sans:system-ui,-apple-system,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif;\n    --sh:0 1px 2px rgba(20,28,45,.05),0 4px 16px rgba(20,28,45,.06);\n    --r:9px;\n  }\n  *{box-sizing:border-box}\n  html,body{height:100%}\n  body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);\n    font-size:14px;line-height:1.5;-webkit-font-smoothing:antialiased;\n    text-rendering:optimizeLegibility;}\n  button{font:inherit;color:inherit;cursor:pointer;border:0;background:none}\n  ::selection{background:var(--accent-soft)}\n\n  .app{display:grid;grid-template-rows:auto 1fr;height:100vh;overflow:hidden}\n\n  /* ---- top bar ---- */\n  .top{display:flex;align-items:center;gap:20px;padding:12px 20px;\n    background:var(--surface);border-bottom:1px solid var(--line);z-index:5}\n  #home{display:inline-flex;align-items:center;gap:5px;margin-right:2px;padding:5px 10px 5px 4px;border-radius:999px;font-family:var(--mono);font-size:11px;color:var(--faint);text-decoration:none;flex:none;transition:color .15s,background .15s}#home:hover{color:var(--accent);background:var(--accent-soft)}.brand{display:flex;flex-direction:column;justify-content:center;min-width:0;gap:1px}\n  .brand .kicker{font-family:var(--mono);font-size:9.5px;letter-spacing:.11em;\n    text-transform:uppercase;color:var(--faint);font-weight:600;line-height:1}\n  .brand .repo{display:inline-flex;align-items:center;gap:6px;font-size:17px;\n    font-weight:680;letter-spacing:-.02em;color:var(--ink);line-height:1.1}\n  .brand .repo::before{content:\"\";width:7px;height:7px;border-radius:50%;\n    background:var(--accent);flex-shrink:0}\n  .top .spacer{flex:1}\n  .stat{display:flex;flex-direction:column;line-height:1.15}\n  .stat b{font-size:16px;font-variant-numeric:tabular-nums;letter-spacing:-.02em}\n  .stat span{font-family:var(--mono);font-size:9.5px;letter-spacing:.09em;\n    text-transform:uppercase;color:var(--faint)}\n  .fresh-meter{display:flex;align-items:center;gap:8px}\n  .meter-bar{width:120px;height:8px;border-radius:5px;background:var(--sunk);\n    overflow:hidden;display:flex}\n  .meter-bar i{display:block;height:100%}\n  .segbtns{display:flex;background:var(--sunk);border-radius:8px;padding:3px}\n  .segbtns button{padding:5px 13px;border-radius:6px;font-size:12.5px;\n    font-weight:500;color:var(--muted)}\n  .segbtns button[aria-pressed=true]{background:var(--surface);color:var(--ink);\n    box-shadow:0 1px 2px rgba(20,28,45,.12);font-weight:600}\n\n  /* ---- body split ---- */\n  .split{display:grid;grid-template-columns:340px 1fr;min-height:0}\n  .split.graph-mode{grid-template-columns:1fr}\n  .split.graph-mode .rail{display:none}\n\n  /* ---- rail ---- */\n  .rail{background:var(--rail);border-right:1px solid var(--line);\n    display:flex;flex-direction:column;min-height:0}\n  .rail .controls{padding:12px 12px 0;display:flex;flex-direction:column;gap:10px}\n  .search{position:relative}\n  .search input{width:100%;padding:9px 12px 9px 32px;border:1px solid var(--line);\n    border-radius:8px;background:var(--surface);font-size:13px;outline:none}\n  .search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft)}\n  .search svg{position:absolute;left:10px;top:50%;transform:translateY(-50%);\n    width:15px;height:15px;stroke:var(--faint);fill:none;stroke-width:2}\n\n  /* lens tabs (Files / Flows) */\n  .lenses{display:flex;gap:4px}\n  .lens{flex:1;display:flex;align-items:center;justify-content:center;gap:7px;\n    padding:9px 0;border-radius:9px;font-size:13px;font-weight:600;color:var(--muted);\n    background:var(--sunk);border:1px solid transparent}\n  .lens .ct{font-family:var(--mono);font-size:11px;font-weight:700;\n    padding:1px 6px;border-radius:20px;background:rgba(105,116,138,.16);color:var(--muted);\n    font-variant-numeric:tabular-nums}\n  .lens[aria-pressed=true]{background:var(--surface);color:var(--ink);\n    border-color:var(--line);box-shadow:var(--sh)}\n  .lens.files[aria-pressed=true]{color:var(--file)} .lens.files[aria-pressed=true] .ct{background:var(--file-bg);color:var(--file)}\n  .lens.flows[aria-pressed=true]{color:var(--flow)} .lens.flows[aria-pressed=true] .ct{background:var(--flow-bg);color:var(--flow)}\n  .lens .ic{width:15px;height:15px;stroke:currentColor;fill:none;stroke-width:1.8}\n\n  /* status / freshness filter row */\n  .statusrow{display:flex;align-items:center;gap:8px;padding:2px}\n  .fchip{display:inline-flex;align-items:center;gap:7px;padding:5px 11px;border-radius:20px;\n    font-size:12px;font-weight:600;border:1px solid var(--line);background:var(--surface);color:var(--muted)}\n  .fchip .d{width:8px;height:8px;border-radius:50%;background:var(--fresh)}\n  .fchip.has-stale{color:var(--changed);border-color:var(--changed);background:var(--changed-bg)}\n  .fchip.has-stale .d{background:var(--changed)}\n  .fchip[aria-pressed=true]{outline:2px solid var(--changed);outline-offset:1px}\n  .fchip.all-fresh .d{background:var(--fresh)}\n  .treetools{margin-left:auto;display:flex;gap:2px}\n  .treetools button{font-family:var(--mono);font-size:10px;letter-spacing:.04em;\n    text-transform:uppercase;color:var(--faint);padding:4px 7px;border-radius:6px}\n  .treetools button:hover{color:var(--accent);background:var(--sunk)}\n\n  .list{overflow-y:auto;padding:8px 8px 60px;flex:1}\n\n  /* tree rows */\n  .row{display:flex;align-items:center;gap:7px;width:100%;text-align:left;\n    padding:5px 8px;border-radius:7px;min-height:30px}\n  .row:hover{background:var(--sunk)}\n  .row[aria-current=true]{background:var(--accent-soft)}\n  .row[aria-current=true] .lbl{color:var(--accent-ink);font-weight:600}\n  .chev{width:14px;height:14px;flex-shrink:0;stroke:var(--faint);fill:none;stroke-width:2;\n    transition:transform .12s}\n  .row.open>.chev{transform:rotate(90deg)}\n  .spacer-ic{width:14px;flex-shrink:0}\n  .ficon{width:15px;height:15px;flex-shrink:0;stroke:var(--faint);fill:none;stroke-width:1.6}\n  .row.dir .ficon{stroke:var(--accent);fill:var(--accent-soft)}\n  .lbl{font-size:12.5px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:0}\n  .row.dir .lbl{font-weight:600;color:var(--ink-soft)}\n  .row.dir .lbl .seg-dim{color:var(--faint);font-weight:500}\n  .badge{font-family:var(--mono);font-size:10px;color:var(--faint);\n    font-variant-numeric:tabular-nums;flex-shrink:0}\n  .dot{width:7px;height:7px;border-radius:50%;flex-shrink:0}\n  .dot.fresh{background:var(--fresh)} .dot.changed{background:var(--changed)}\n  .dot.missing{background:var(--missing)} .dot.unverified{background:var(--unver)}\n  .char{font-family:var(--mono);font-size:8.5px;font-weight:700;color:var(--faint);\n    border:1px solid var(--line);border-radius:3px;padding:0 3px;flex-shrink:0}\n\n  /* flow cards */\n  .flowcard{display:block;width:100%;text-align:left;padding:11px 12px;border-radius:9px;\n    border:1px solid var(--line-soft);background:var(--surface);margin-bottom:7px}\n  .flowcard:hover{border-color:var(--flow);box-shadow:var(--sh)}\n  .flowcard[aria-current=true]{border-color:var(--flow);background:var(--flow-bg)}\n  .fc-top{display:flex;align-items:center;gap:8px;margin-bottom:6px}\n  .fc-top .dot{margin-top:0}\n  .fc-title{font-size:13px;font-weight:600;line-height:1.35;flex:1;overflow-wrap:anywhere}\n  .fc-span{display:flex;flex-wrap:wrap;gap:4px}\n  .fc-file{font-family:var(--mono);font-size:10px;color:var(--muted);background:var(--sunk);\n    padding:1px 6px;border-radius:5px;max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n  .fc-more{font-family:var(--mono);font-size:10px;color:var(--faint);padding:1px 3px}\n  .empty-note{color:var(--faint);font-size:12px;font-style:italic;padding:20px 10px}\n\n  /* ---- reader ---- */\n  .reader{overflow-y:auto;padding:0}\n  .reader-inner{max-width:760px;margin:0 auto;padding:38px 40px 120px}\n  .eyebrow{display:flex;align-items:center;gap:8px;flex-wrap:wrap;\n    font-family:var(--mono);font-size:11px;margin-bottom:14px}\n  .eyebrow .id{color:var(--faint);overflow-wrap:anywhere}\n  .eyebrow .sep{color:var(--line)}\n  .kind{font-family:var(--mono);font-size:9px;letter-spacing:.06em;font-weight:700;\n    text-transform:uppercase;padding:1px 5px;border-radius:4px}\n  .kind.file{color:var(--file);background:var(--file-bg)}\n  .kind.flow{color:var(--flow);background:var(--flow-bg)}\n  h1.note-title{font-size:26px;line-height:1.22;letter-spacing:-.02em;\n    font-weight:680;margin:0 0 16px;text-wrap:balance;overflow-wrap:anywhere}\n  .metabar{display:flex;align-items:center;gap:14px;flex-wrap:wrap;\n    padding-bottom:18px;margin-bottom:22px;border-bottom:1px solid var(--line-soft)}\n  .pill{display:inline-flex;align-items:center;gap:6px;font-size:11.5px;\n    font-weight:600;padding:3px 10px;border-radius:20px;font-family:var(--mono);\n    letter-spacing:.02em}\n  .pill .d{width:7px;height:7px;border-radius:50%}\n  .pill.fresh{color:var(--fresh);background:var(--fresh-bg)} .pill.fresh .d{background:var(--fresh)}\n  .pill.changed{color:var(--changed);background:var(--changed-bg)} .pill.changed .d{background:var(--changed)}\n  .pill.missing{color:var(--missing);background:var(--missing-bg)} .pill.missing .d{background:var(--missing)}\n  .pill.unverified{color:var(--unver);background:var(--unver-bg)} .pill.unverified .d{background:var(--unver)}\n  .metabar .mi{font-size:12px;color:var(--muted)}\n  .metabar .mi b{color:var(--ink-soft);font-variant-numeric:tabular-nums;font-weight:600}\n\n  .sec-label{font-family:var(--mono);font-size:10px;letter-spacing:.09em;\n    text-transform:uppercase;color:var(--faint);font-weight:600;margin:26px 0 10px}\n\n  .anchor{border:1px solid var(--line);border-radius:var(--r);background:var(--surface);\n    padding:11px 13px;margin-bottom:8px}\n  .anchor-top{display:flex;align-items:center;gap:9px}\n  .apath{font-family:var(--mono);font-size:12px;color:var(--ink);font-weight:600;\n    overflow-wrap:anywhere;flex:1}\n  .apath .p{color:var(--faint)}\n  .astate{font-family:var(--mono);font-size:9px;letter-spacing:.06em;font-weight:700;\n    text-transform:uppercase;padding:2px 6px;border-radius:4px;white-space:nowrap}\n  .astate.fresh{color:var(--fresh);background:var(--fresh-bg)}\n  .astate.changed{color:var(--changed);background:var(--changed-bg)}\n  .astate.missing{color:var(--missing);background:var(--missing-bg)}\n  .astate.unverified{color:var(--unver);background:var(--unver-bg)}\n  .copy{font-family:var(--mono);font-size:10px;color:var(--faint);padding:2px 6px;\n    border-radius:4px;border:1px solid var(--line)}\n  .copy:hover{color:var(--accent);border-color:var(--accent)}\n  .syms{display:flex;flex-wrap:wrap;gap:5px;margin-top:9px}\n  .sym{font-family:var(--mono);font-size:11px;background:var(--sunk);\n    color:var(--ink-soft);padding:2px 7px;border-radius:5px;cursor:pointer;\n    transition:background .1s,color .1s;position:relative}\n  .sym:hover{background:var(--accent-soft);color:var(--accent-ink)}\n  .sym.copied{background:var(--accent);color:#fff}\n  .sym.copied::after{content:\"copied\";position:absolute;left:50%;bottom:calc(100% + 5px);\n    transform:translateX(-50%);background:var(--ink);color:#fff;font-size:9px;\n    padding:2px 6px;border-radius:4px;white-space:nowrap;letter-spacing:.04em}\n\n  .aliases{border:1px solid var(--line-soft);border-radius:var(--r);\n    background:var(--rail);overflow:hidden}\n  .aliases summary{list-style:none;cursor:pointer;padding:9px 13px;\n    display:flex;align-items:center;gap:8px;font-size:12px;color:var(--muted)}\n  .aliases summary::-webkit-details-marker{display:none}\n  .aliases summary b{color:var(--ink-soft);font-weight:600}\n  .aliases summary .chv{margin-left:auto;transition:transform .15s}\n  .aliases[open] summary .chv{transform:rotate(90deg)}\n  .alias-cloud{display:flex;flex-wrap:wrap;gap:6px;padding:2px 13px 13px}\n  .alias-cloud span{font-family:var(--mono);font-size:11px;color:var(--ink-soft);\n    background:var(--surface);border:1px solid var(--line);padding:2px 8px;border-radius:12px}\n\n  .md{font-size:14.5px;line-height:1.68;color:var(--ink-soft)}\n  .md h2{font-size:13px;font-family:var(--mono);letter-spacing:.05em;\n    text-transform:uppercase;color:var(--ink);font-weight:700;margin:30px 0 12px;\n    padding-bottom:7px;border-bottom:1px solid var(--line-soft)}\n  .md h3{font-size:15px;margin:22px 0 8px;color:var(--ink)}\n  .md p{margin:0 0 14px}\n  .md ul,.md ol{margin:0 0 14px;padding-left:22px}\n  .md li{margin:0 0 8px}\n  .md li::marker{color:var(--faint)}\n  .md code{font-family:var(--mono);font-size:12.5px;background:var(--sunk);\n    color:var(--accent-ink);padding:1px 5px;border-radius:5px;overflow-wrap:anywhere}\n  .md strong{color:var(--ink);font-weight:650}\n  .wl{font-family:var(--mono);font-size:12px;color:var(--accent);font-weight:600;\n    background:var(--accent-soft);padding:1px 6px;border-radius:5px;\n    text-decoration:none;overflow-wrap:anywhere}\n  .wl:hover{background:var(--accent);color:#fff}\n  .wl.dead{color:var(--muted);background:var(--sunk);cursor:default}\n\n  .links-grid{display:grid;grid-template-columns:1fr 1fr;gap:22px;margin-top:34px;\n    padding-top:22px;border-top:1px solid var(--line-soft)}\n  @media(max-width:640px){.links-grid{grid-template-columns:1fr}}\n  .linkcol .sec-label{margin-top:0}\n  .linkbtn{display:flex;align-items:center;gap:8px;width:100%;text-align:left;\n    padding:8px 10px;border-radius:7px;font-size:12px;margin-bottom:3px}\n  .linkbtn:hover{background:var(--sunk)}\n  .linkbtn .kind{flex-shrink:0}\n  .linkbtn span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n\n  .placeholder{display:flex;align-items:center;justify-content:center;height:100%;\n    color:var(--faint);font-size:13px}\n\n  /* ---- graph ---- */\n  .graph-wrap{position:relative;overflow:hidden;background:\n    radial-gradient(circle at 30% 20%, #f2f5fa, var(--ground))}\n  .graph-wrap canvas{display:block;width:100%;height:100%}\n  .graph-legend{position:absolute;top:16px;left:16px;background:var(--surface);\n    border:1px solid var(--line);border-radius:var(--r);padding:12px 14px;\n    box-shadow:var(--sh);font-size:12px;max-width:230px}\n  .graph-legend .lg-t{font-family:var(--mono);font-size:10px;letter-spacing:.07em;\n    text-transform:uppercase;color:var(--faint);margin-bottom:8px}\n  .graph-legend .lg-row{display:flex;align-items:center;gap:8px;margin-bottom:5px}\n  .graph-legend .lg-row i{width:12px;height:12px;border-radius:50%;flex-shrink:0}\n  .graph-legend .hint{color:var(--muted);margin-top:8px;line-height:1.4}\n  .graph-tip{position:absolute;pointer-events:none;background:var(--ink);color:#fff;\n    font-size:11.5px;padding:6px 10px;border-radius:7px;max-width:280px;opacity:0;\n    transform:translate(-50%,-140%);transition:opacity .1s;box-shadow:var(--sh);z-index:3}\n  .graph-tip .tk{font-family:var(--mono);font-size:9px;letter-spacing:.06em;\n    text-transform:uppercase;opacity:.7}\n\n  @media(max-width:860px){\n    .split{grid-template-columns:1fr}\n    .rail{position:absolute;inset:57px 0 0 0;z-index:4;width:min(340px,86vw);\n      box-shadow:var(--sh)}\n    .split:not(.rail-open) .rail{display:none}\n    .split.graph-mode .rail{display:none}\n    .reader-inner{padding:26px 20px 100px}\n    .menu-btn{display:inline-flex!important}\n  }\n  .menu-btn{display:none;align-items:center;gap:6px}\n</style>\n\n<div class=\"app\">\n  <header class=\"top\"><!--__HOME_LINK__-->\n    <button class=\"menu-btn segbtns\" id=\"menuBtn\" style=\"padding:6px 10px\"><svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"><path d=\"M2 4h12M2 8h12M2 12h12\"/></svg></button>\n    <div class=\"brand\">\n      <span class=\"kicker\">Coldstart&nbsp;Notebook</span>\n      <span class=\"repo\" id=\"repoName\">repo</span>\n    </div>\n    <div class=\"spacer\"></div>\n    <div class=\"stat\"><b id=\"sTotal\">0</b><span>notes</span></div>\n    <div class=\"stat\"><b id=\"sLinks\">0</b><span>links</span></div>\n    <div class=\"fresh-meter\">\n      <div class=\"meter-bar\" id=\"meterBar\"></div>\n      <div class=\"stat\"><b id=\"sFresh\">0%</b><span>fresh</span></div>\n    </div>\n    <div class=\"segbtns\" role=\"tablist\">\n      <button id=\"tabNotes\" aria-pressed=\"true\">Notes</button>\n      <button id=\"tabGraph\" aria-pressed=\"false\">Graph</button>\n    </div>\n  </header>\n\n  <div class=\"split\" id=\"split\">\n    <aside class=\"rail\" id=\"rail\">\n      <div class=\"controls\">\n        <div class=\"search\">\n          <svg viewBox=\"0 0 16 16\"><circle cx=\"7\" cy=\"7\" r=\"5\"/><path d=\"M11 11l3 3\"/></svg>\n          <input id=\"q\" placeholder=\"Search title, alias, path, symbol\u2026\" autocomplete=\"off\">\n        </div>\n        <div class=\"lenses\">\n          <button class=\"lens files\" data-lens=\"files\" aria-pressed=\"true\">\n            <svg class=\"ic\" viewBox=\"0 0 16 16\"><path d=\"M2 4.5h5l1.5 1.5H14v6.5a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1z\"/></svg>\n            Files <span class=\"ct\" id=\"ctFiles\">0</span>\n          </button>\n          <button class=\"lens flows\" data-lens=\"flows\" aria-pressed=\"false\">\n            <svg class=\"ic\" viewBox=\"0 0 16 16\"><circle cx=\"3.5\" cy=\"3.5\" r=\"1.6\"/><circle cx=\"12.5\" cy=\"8\" r=\"1.6\"/><circle cx=\"3.5\" cy=\"12.5\" r=\"1.6\"/><path d=\"M5 3.9h4a2 2 0 0 1 2 2v.5M5 12.1h4a2 2 0 0 0 2-2v-.5\"/></svg>\n            Flows <span class=\"ct\" id=\"ctFlows\">0</span>\n          </button>\n        </div>\n        <div class=\"statusrow\">\n          <button class=\"fchip all-fresh\" id=\"staleChip\" aria-pressed=\"false\"><span class=\"d\"></span><span id=\"staleLbl\">All fresh</span></button>\n          <div class=\"treetools\" id=\"treeTools\">\n            <button data-tt=\"expand\">Expand</button>\n            <button data-tt=\"collapse\">Collapse</button>\n          </div>\n        </div>\n      </div>\n      <div class=\"list\" id=\"list\"></div>\n    </aside>\n\n    <main class=\"reader\" id=\"reader\">\n      <div class=\"placeholder\">Select a note to read.</div>\n    </main>\n\n    <section class=\"graph-wrap\" id=\"graphWrap\" style=\"display:none\">\n      <canvas id=\"graphCanvas\"></canvas>\n      <div class=\"graph-legend\">\n        <div class=\"lg-t\">Note graph</div>\n        <div class=\"lg-row\"><i style=\"background:var(--file)\"></i>file note</div>\n        <div class=\"lg-row\"><i style=\"background:var(--flow)\"></i>flow note</div>\n        <div class=\"hint\" id=\"graphHint\">Only linked notes shown. Click a node to open it.</div>\n      </div>\n      <div class=\"graph-tip\" id=\"graphTip\"></div>\n    </section>\n  </div>\n</div>\n\n<script>const DB = __DATA_JSON__;</script>\n<script>\n(function(){\n  \"use strict\";\n  const notes = DB.notes;\n  const byId = new Map(notes.map(n=>[n.id,n]));\n  const fileNotes = notes.filter(n=>n.type==='file');\n  const flowNotes = notes.filter(n=>n.type==='flow');\n  const $ = s=>document.querySelector(s);\n  const esc = s=>String(s).replace(/[&<>]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));\n  // clipboard: navigator.clipboard is unreliable on file:// \u2014 fall back to execCommand\n  function copyText(t){\n    try{\n      if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(t).catch(()=>fallbackCopy(t));return;}\n    }catch(e){}\n    fallbackCopy(t);\n  }\n  function fallbackCopy(t){\n    try{const ta=document.createElement('textarea');ta.value=t;ta.style.position='fixed';ta.style.opacity='0';\n      document.body.appendChild(ta);ta.focus();ta.select();document.execCommand('copy');document.body.removeChild(ta);}catch(e){}\n  }\n  const RANK={fresh:0,unverified:1,changed:2,missing:3};\n  const isStale=n=>n.freshness==='changed'||n.freshness==='missing';\n\n  let state = { lens:'files', q:'', selected:null, view:'notes', staleOnly:false, open:new Set() };\n\n  // ---- header stats ----\n  $('#repoName').textContent = DB.summary.repo;\n  $('#sTotal').textContent = DB.summary.total;\n  $('#ctFiles').textContent = fileNotes.length;\n  $('#ctFlows').textContent = flowNotes.length;\n  // Both link kinds, deduped the same way buildGraph does, so the header\n  // stat and the graph hint can never disagree.\n  const edgeKeys = new Set();\n  for(const n of notes) for(const l of [...n.outLinks,...(n.anchorLinks||[])])\n    if(byId.has(l)&&l!==n.id) edgeKeys.add(n.id<l?n.id+'|'+l:l+'|'+n.id);\n  const edgeCount = edgeKeys.size;\n  $('#sLinks').textContent = edgeCount;\n  const fr = DB.summary.byFreshness;\n  const freshPct = Math.round(100*(fr.fresh||0)/DB.summary.total);\n  $('#sFresh').textContent = freshPct+'%';\n  const mb = $('#meterBar');\n  const morder=[['fresh','--fresh'],['changed','--changed'],['unverified','--unver'],['missing','--missing']];\n  mb.innerHTML = morder.filter(([k])=>fr[k]).map(([k,v])=>\n    `<i style=\"width:${100*fr[k]/DB.summary.total}%;background:var(${v})\"></i>`).join('');\n\n  // stale chip\n  const staleCount = notes.filter(isStale).length;\n  const chip=$('#staleChip');\n  if(staleCount){\n    chip.classList.remove('all-fresh');chip.classList.add('has-stale');\n    $('#staleLbl').textContent=`${staleCount} need review`;\n  }else{\n    $('#staleLbl').textContent='All fresh';\n  }\n\n  // ---- filter helpers ----\n  function matches(n,q){\n    if(!q) return true;\n    const hay=(n.title+' '+n.id+' '+n.aliases.join(' ')+' '+n.anchors.map(a=>a.path+' '+(a.symbols||[]).join(' ')).join(' ')).toLowerCase();\n    return q.toLowerCase().split(/\\s+/).every(t=>hay.includes(t));\n  }\n  function passFilter(n){\n    if(state.staleOnly && !isStale(n)) return false;\n    return matches(n,state.q);\n  }\n\n  // ================= FILE TREE =================\n  function buildTree(){\n    const root={name:'',path:'',children:new Map(),notes:[],dir:true};\n    for(const n of fileNotes){\n      const path=n.anchors[0]?n.anchors[0].path:n.title;\n      const segs=path.split('/');\n      let cur=root;\n      for(let i=0;i<segs.length-1;i++){\n        const s=segs[i], p=segs.slice(0,i+1).join('/');\n        if(!cur.children.has(s)) cur.children.set(s,{name:s,path:p,children:new Map(),notes:[],dir:true});\n        cur=cur.children.get(s);\n      }\n      cur.notes.push(Object.assign({leaf:segs[segs.length-1]},n));\n    }\n    // compact single-child dir chains (VSCode style), never the root\n    const compact=(node,isRoot)=>{\n      for(const c of node.children.values()) compact(c,false);\n      if(!isRoot){\n        while(node.children.size===1 && node.notes.length===0){\n          const only=[...node.children.values()][0];\n          node.name = node.name+'/'+only.name;\n          node.path = only.path; node.notes = only.notes; node.children = only.children;\n        }\n      }\n    };\n    compact(root,true);\n    // rollups\n    const roll=(node)=>{\n      let worst='fresh',cnt=node.notes.length;\n      for(const n of node.notes) if(RANK[n.freshness]>RANK[worst]) worst=n.freshness;\n      for(const c of node.children.values()){roll(c); if(RANK[c.roll]>RANK[worst]) worst=c.roll; cnt+=c.count;}\n      node.roll=worst; node.count=cnt;\n    };\n    roll(root);\n    return root;\n  }\n  const TREE=buildTree();\n\n  function nodeHasMatch(node){\n    if(node.notes.some(passFilter)) return true;\n    for(const c of node.children.values()) if(nodeHasMatch(c)) return true;\n    return false;\n  }\n  function ancestorsOf(id){\n    // dir paths that contain the selected file note\n    const n=byId.get(id); if(!n||n.type!=='file') return new Set();\n    const path=n.anchors[0]?n.anchors[0].path:n.title;\n    const set=new Set(); const segs=path.split('/');\n    for(let i=1;i<segs.length;i++) set.add(segs.slice(0,i).join('/'));\n    return set;\n  }\n  const FOLDER_SVG='<svg class=\"ficon\" viewBox=\"0 0 16 16\"><path d=\"M2 4.5h5l1.5 1.5H14v6.5a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1z\"/></svg>';\n  const FILE_SVG='<svg class=\"ficon\" viewBox=\"0 0 16 16\"><path d=\"M4 1.5h5L13 5v9a.5.5 0 0 1-.5.5h-9A.5.5 0 0 1 3 14V2a.5.5 0 0 1 1-.5z\"/><path d=\"M9 1.5V5h4\"/></svg>';\n\n  function renderTreeNode(node,depth,active,out){\n    const dirs=[...node.children.values()].filter(nodeHasMatch)\n      .sort((a,b)=>a.name.localeCompare(b.name));\n    const leaves=node.notes.filter(passFilter).sort((a,b)=>a.leaf.localeCompare(b.leaf));\n    const pad=8+depth*15;\n    for(const d of dirs){\n      const open = active || state.open.has(d.path);\n      const dimIdx=d.name.lastIndexOf('/');\n      const nm = dimIdx>-1 ? `<span class=\"seg-dim\">${esc(d.name.slice(0,dimIdx+1))}</span>${esc(d.name.slice(dimIdx+1))}` : esc(d.name);\n      out.push(`<button class=\"row dir ${open?'open':''}\" data-dir=\"${esc(d.path)}\" style=\"padding-left:${pad}px\">\n        <svg class=\"chev\" viewBox=\"0 0 16 16\"><path d=\"M6 3l5 5-5 5\"/></svg>${FOLDER_SVG}\n        <span class=\"lbl\">${nm}</span>\n        <span class=\"badge\">${d.count}</span>\n        ${d.roll!=='fresh'?`<span class=\"dot ${d.roll}\"></span>`:''}\n      </button>`);\n      if(open) renderTreeNode(d,depth+1,active,out);\n    }\n    for(const n of leaves){\n      out.push(`<button class=\"row leaf\" data-id=\"${esc(n.id)}\" aria-current=\"${n.id===state.selected}\" style=\"padding-left:${pad+21}px\">\n        ${FILE_SVG}\n        <span class=\"lbl\">${esc(n.leaf)}</span>\n        ${n.character?`<span class=\"char\" title=\"${esc(n.character)} note\">${n.character[0].toUpperCase()}</span>`:''}\n        <span class=\"dot ${n.freshness}\"></span>\n      </button>`);\n    }\n  }\n\n  function renderFiles(){\n    const active=!!(state.q||state.staleOnly);\n    const out=[];\n    renderTreeNode(TREE,0,active,out);\n    $('#list').innerHTML = out.length?out.join(''):'<div class=\"empty-note\">No file notes match.</div>';\n  }\n\n  // ================= FLOWS =================\n  function renderFlows(){\n    const list=flowNotes.filter(passFilter)\n      .sort((a,b)=>b.anchors.length-a.anchors.length||a.title.localeCompare(b.title));\n    if(!list.length){$('#list').innerHTML='<div class=\"empty-note\">No flows match.</div>';return;}\n    $('#list').innerHTML=list.map(n=>{\n      const files=n.anchors.map(a=>a.path.split('/').pop());\n      const shown=files.slice(0,4), extra=files.length-shown.length;\n      return `<button class=\"flowcard\" data-id=\"${esc(n.id)}\" aria-current=\"${n.id===state.selected}\">\n        <div class=\"fc-top\">\n          <span class=\"dot ${n.freshness}\"></span>\n          <span class=\"fc-title\">${esc(n.title)}</span>\n        </div>\n        <div class=\"fc-span\">\n          ${shown.map(f=>`<span class=\"fc-file\">${esc(f)}</span>`).join('')}\n          ${extra>0?`<span class=\"fc-more\">+${extra} more</span>`:''}\n        </div>\n      </button>`;\n    }).join('');\n  }\n\n  function renderList(){\n    $('#treeTools').style.visibility = state.lens==='files' ? 'visible':'hidden';\n    if(state.lens==='files') renderFiles(); else renderFlows();\n  }\n\n  // ---- markdown mini-renderer ----\n  function mdInline(t){\n    t=esc(t);\n    t=t.replace(/`([^`]+)`/g,(_,c)=>`<code>${c}</code>`);\n    t=t.replace(/\\[\\[([^\\]]+)\\]\\]/g,(_,id)=>{\n      const ok=byId.has(id);\n      return `<a class=\"wl${ok?'':' dead'}\" ${ok?`data-goto=\"${esc(id)}\"`:''} title=\"${esc(id)}\">${ok?esc(byId.get(id).title):esc(id)}</a>`;\n    });\n    t=t.replace(/\\*\\*([^*]+)\\*\\*/g,'<strong>$1</strong>');\n    return t;\n  }\n  function renderMd(src){\n    const lines=src.split('\\n');\n    let html='',i=0;\n    const flush=(buf,tag)=>buf.length?`<${tag}>${buf.join('')}</${tag}>`:'';\n    while(i<lines.length){\n      let ln=lines[i];\n      if(/^#\\s+/.test(ln)){i++;continue;}\n      if(/^##\\s+/.test(ln)){html+=`<h2>${mdInline(ln.replace(/^##\\s+/,''))}</h2>`;i++;continue;}\n      if(/^###\\s+/.test(ln)){html+=`<h3>${mdInline(ln.replace(/^###\\s+/,''))}</h3>`;i++;continue;}\n      if(/^\\s*[-*]\\s+/.test(ln)){\n        const buf=[];\n        while(i<lines.length&&/^\\s*[-*]\\s+/.test(lines[i])){buf.push(`<li>${mdInline(lines[i].replace(/^\\s*[-*]\\s+/,''))}</li>`);i++;}\n        html+=flush(buf,'ul');continue;\n      }\n      if(/^\\s*\\d+\\.\\s+/.test(ln)){\n        const buf=[];\n        while(i<lines.length&&/^\\s*\\d+\\.\\s+/.test(lines[i])){buf.push(`<li>${mdInline(lines[i].replace(/^\\s*\\d+\\.\\s+/,''))}</li>`);i++;}\n        html+=flush(buf,'ol');continue;\n      }\n      if(!ln.trim()){i++;continue;}\n      const buf=[];\n      while(i<lines.length&&lines[i].trim()&&!/^(#{1,3}\\s|\\s*[-*]\\s|\\s*\\d+\\.\\s)/.test(lines[i])){buf.push(lines[i]);i++;}\n      html+=`<p>${mdInline(buf.join(' '))}</p>`;\n    }\n    return html;\n  }\n  function anchorHtml(a){\n    const parts=a.path.split('/'); const file=parts.pop();\n    const dir=parts.length?parts.join('/')+'/':'';\n    return `<div class=\"anchor\">\n      <div class=\"anchor-top\">\n        <span class=\"apath\"><span class=\"p\">${esc(dir)}</span>${esc(file)}</span>\n        <span class=\"astate ${a.state}\">${a.state}</span>\n        <button class=\"copy\" data-copy=\"${esc(a.path)}\">copy</button>\n      </div>\n      ${(a.symbols&&a.symbols.length)?`<div class=\"syms\">${a.symbols.map(s=>`<button class=\"sym\" data-copysym=\"${esc(s)}\" title=\"click to copy symbol\">${esc(s)}</button>`).join('')}</div>`:''}\n    </div>`;\n  }\n  function linkBtn(id){\n    const n=byId.get(id);\n    return `<button class=\"linkbtn\" data-goto=\"${esc(id)}\"><span class=\"kind ${n.type}\">${n.type.toUpperCase()}</span><span>${esc(n.title)}</span></button>`;\n  }\n  function renderNote(id){\n    const n=byId.get(id); if(!n) return;\n    state.selected=id;\n    // reveal once: persist the file's ancestor folders so they stay open\n    // (and prior folders stay open too) \u2014 you can still collapse any by hand\n    if(n.type==='file') for(const p of ancestorsOf(id)) state.open.add(p);\n    const outs=n.outLinks.filter(l=>byId.has(l));\n    const r=$('#reader');\n    r.innerHTML=`<div class=\"reader-inner\">\n      <div class=\"eyebrow\">\n        <span class=\"kind ${n.type}\">${n.type.toUpperCase()}${n.character?' \u00b7 '+n.character:''}</span>\n        <span class=\"sep\">/</span><span class=\"id\">${esc(n.id)}</span>\n      </div>\n      <h1 class=\"note-title\">${esc(n.title)}</h1>\n      <div class=\"metabar\">\n        <span class=\"pill ${n.freshness}\"><span class=\"d\"></span>${n.freshness}</span>\n        <span class=\"mi\"><b>${n.anchors.length}</b> anchor${n.anchors.length===1?'':'s'}</span>\n        <span class=\"mi\"><b>${n.edits}</b> edit${n.edits===1?'':'s'}</span>\n        <span class=\"mi\">updated <b>${esc((n.updated||'').slice(0,10))}</b></span>\n      </div>\n      <div class=\"sec-label\">Anchors \u2014 verified code addresses</div>\n      ${n.anchors.length?n.anchors.map(anchorHtml).join(''):'<div class=\"empty-note\">No anchors.</div>'}\n      ${n.aliases.length?`<details class=\"aliases\" style=\"margin-top:14px\">\n        <summary><b>${n.aliases.length}</b> search aliases <span style=\"color:var(--faint)\">\u2014 queries that should surface this note</span><span class=\"chv\">\u203a</span></summary>\n        <div class=\"alias-cloud\">${n.aliases.map(a=>`<span>${esc(a)}</span>`).join('')}</div>\n      </details>`:''}\n      <div class=\"sec-label\">Note</div>\n      <div class=\"md\">${renderMd(n.body)}</div>\n      <div class=\"links-grid\">\n        <div class=\"linkcol\"><div class=\"sec-label\">Links to (${outs.length})</div>\n          ${outs.length?outs.map(linkBtn).join(''):'<div class=\"empty-note\">No outgoing links.</div>'}</div>\n        <div class=\"linkcol\"><div class=\"sec-label\">Referenced by (${n.backlinks.length})</div>\n          ${n.backlinks.length?n.backlinks.map(linkBtn).join(''):'<div class=\"empty-note\">Not referenced.</div>'}</div>\n      </div>\n    </div>`;\n    r.scrollTop=0;\n    // switch lens to match the note type so it's visible in the rail\n    if(n.type==='flow'&&state.lens!=='flows') setLens('flows');\n    else if(n.type==='file'&&state.lens!=='files') setLens('files');\n    else renderList();\n  }\n\n  // ---- events ----\n  $('#q').addEventListener('input',e=>{state.q=e.target.value;renderList();});\n  $('.lenses').addEventListener('click',e=>{const b=e.target.closest('.lens');if(b)setLens(b.dataset.lens);});\n  function setLens(l){\n    state.lens=l;\n    document.querySelectorAll('.lens').forEach(x=>x.setAttribute('aria-pressed',x.dataset.lens===l));\n    renderList();\n  }\n  chip.addEventListener('click',()=>{state.staleOnly=!state.staleOnly;chip.setAttribute('aria-pressed',state.staleOnly);renderList();});\n  $('#treeTools').addEventListener('click',e=>{\n    const b=e.target.closest('button');if(!b)return;\n    if(b.dataset.tt==='collapse'){state.open.clear();}\n    else{ // expand all dirs\n      const walk=nd=>{for(const c of nd.children.values()){state.open.add(c.path);walk(c);}};walk(TREE);\n    }\n    renderFiles();\n  });\n  document.addEventListener('click',e=>{\n    const dir=e.target.closest('[data-dir]');\n    if(dir){const p=dir.dataset.dir;state.open.has(p)?state.open.delete(p):state.open.add(p);renderFiles();return;}\n    const row=e.target.closest('[data-id]');\n    if(row){switchView('notes');renderNote(row.dataset.id);closeRail();return;}\n    const goto=e.target.closest('[data-goto]');\n    if(goto){switchView('notes');renderNote(goto.dataset.goto);return;}\n    const cs=e.target.closest('[data-copysym]');\n    if(cs){copyText(cs.dataset.copysym);cs.classList.add('copied');setTimeout(()=>cs.classList.remove('copied'),750);return;}\n    const cp=e.target.closest('[data-copy]');\n    if(cp){copyText(cp.dataset.copy);cp.textContent='copied';setTimeout(()=>cp.textContent='copy',900);return;}\n  });\n\n  // ---- view switching ----\n  function switchView(v){\n    state.view=v;\n    $('#tabNotes').setAttribute('aria-pressed',v==='notes');\n    $('#tabGraph').setAttribute('aria-pressed',v==='graph');\n    $('#split').classList.toggle('graph-mode',v==='graph');\n    $('#reader').style.display=v==='graph'?'none':'';\n    $('#graphWrap').style.display=v==='graph'?'':'none';\n    if(v==='graph') drawGraph();\n  }\n  $('#tabNotes').onclick=()=>switchView('notes');\n  $('#tabGraph').onclick=()=>switchView('graph');\n  function closeRail(){$('#split').classList.remove('rail-open');}\n  $('#menuBtn').onclick=()=>$('#split').classList.toggle('rail-open');\n\n  // ================= GRAPH =================\n  let G=null;\n  function buildGraph(){\n    const linked=new Set(); const edges=[];\n    const seen=new Set();\n    const addEdge=(a,b,kind)=>{const key=(a<b?a+'|'+b:b+'|'+a);if(seen.has(key))return;seen.add(key);\n      linked.add(a);linked.add(b);edges.push([a,b,kind]);};\n    // kind 0 = a hand-typed [[wikilink]]; kind 1 = the two notes anchor the\n    // same file. Wikilinks are added first so an explicit link is never\n    // downgraded to the derived kind by the dedup above.\n    for(const n of notes) for(const l of n.outLinks) if(byId.has(l)&&l!==n.id) addEdge(n.id,l,0);\n    for(const n of notes) for(const l of (n.anchorLinks||[])) if(byId.has(l)&&l!==n.id) addEdge(n.id,l,1);\n    const ids=[...linked]; const idx=new Map(ids.map((id,i)=>[id,i])); const N=ids.length;\n    const nodes=ids.map((id,i)=>{const a=2*Math.PI*i/N;\n      return {id,x:Math.cos(a)*260,y:Math.sin(a)*260,vx:0,vy:0,deg:0,type:byId.get(id).type,title:byId.get(id).title};});\n    const E=edges.map(([a,b,k])=>[idx.get(a),idx.get(b),k]);\n    for(const [a,b] of E){nodes[a].deg++;nodes[b].deg++;}\n    for(let it=0;it<320;it++){\n      const k=it<220?1:0.4;\n      for(let i=0;i<N;i++){let fx=0,fy=0;\n        for(let j=0;j<N;j++){if(i===j)continue;\n          let dx=nodes[i].x-nodes[j].x,dy=nodes[i].y-nodes[j].y,d2=dx*dx+dy*dy+0.01,d=Math.sqrt(d2);\n          const rep=1600/d2; fx+=dx/d*rep; fy+=dy/d*rep;}\n        fx-=nodes[i].x*0.012; fy-=nodes[i].y*0.012;\n        nodes[i].vx=(nodes[i].vx+fx)*0.82; nodes[i].vy=(nodes[i].vy+fy)*0.82;}\n      for(const [a,b] of E){let dx=nodes[b].x-nodes[a].x,dy=nodes[b].y-nodes[a].y,d=Math.sqrt(dx*dx+dy*dy)+0.01;\n        const spring=(d-90)*0.02,ux=dx/d*spring,uy=dy/d*spring;\n        nodes[a].vx+=ux;nodes[a].vy+=uy;nodes[b].vx-=ux;nodes[b].vy-=uy;}\n      for(const nd of nodes){nd.x+=nd.vx*k;nd.y+=nd.vy*k;}\n    }\n    G={nodes,E,idx};\n    const wl=edges.filter(e=>e[2]===0).length;\n    $('#graphHint').textContent=`${N} linked notes \u00b7 ${edges.length} links `+\n      `(${wl} written as [[links]], ${edges.length-wl} dashed: the notes share a file). Click a node to open it.`;\n  }\n  let cam={x:0,y:0,s:1},hover=-1;\n  function drawGraph(){\n    if(!G) buildGraph();\n    const cv=$('#graphCanvas'),wrap=$('#graphWrap'),dpr=window.devicePixelRatio||1;\n    const W=wrap.clientWidth,H=wrap.clientHeight;\n    cv.width=W*dpr;cv.height=H*dpr;\n    const ctx=cv.getContext('2d');ctx.setTransform(dpr,0,0,dpr,0,0);\n    const xs=G.nodes.map(n=>n.x),ys=G.nodes.map(n=>n.y);\n    const minX=Math.min(...xs),maxX=Math.max(...xs),minY=Math.min(...ys),maxY=Math.max(...ys),pad=70;\n    const s=Math.min((W-pad*2)/(maxX-minX||1),(H-pad*2)/(maxY-minY||1));\n    cam.s=s;cam.x=W/2-(minX+maxX)/2*s;cam.y=H/2-(minY+maxY)/2*s;\n    const T=(x,y)=>[x*cam.s+cam.x,y*cam.s+cam.y];\n    ctx.clearRect(0,0,W,H);\n    for(const [a,b,k] of G.E){const A=G.nodes[a],B=G.nodes[b],[ax,ay]=T(A.x,A.y),[bx,by]=T(B.x,B.y);\n      const on=hover>-1&&(a===hover||b===hover);\n      ctx.strokeStyle=on?'rgba(31,79,216,.55)':'rgba(105,116,138,.20)';ctx.lineWidth=on?1.8:1;\n      ctx.setLineDash(k?[4,4]:[]);\n      ctx.beginPath();ctx.moveTo(ax,ay);ctx.lineTo(bx,by);ctx.stroke();}\n    ctx.setLineDash([]);\n    const cs=getComputedStyle(document.documentElement);\n    const cFile=cs.getPropertyValue('--file').trim(),cFlow=cs.getPropertyValue('--flow').trim();\n    G.nodes.forEach((n,i)=>{const[x,y]=T(n.x,n.y),r=Math.max(4,Math.min(13,4+n.deg*1.6)),isH=i===hover;\n      ctx.beginPath();ctx.arc(x,y,r+(isH?2:0),0,7);ctx.fillStyle=n.type==='flow'?cFlow:cFile;\n      ctx.globalAlpha=hover>-1&&!isH&&!G.E.some(([a,b])=>(a===hover&&b===i)||(b===hover&&a===i))?0.35:1;\n      ctx.fill();if(isH){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();}ctx.globalAlpha=1;});\n    G._T=T;\n  }\n  const cv=$('#graphCanvas');\n  function pick(mx,my){if(!G||!G._T)return -1;let best=-1,bd=18*18;\n    G.nodes.forEach((n,i)=>{const[x,y]=G._T(n.x,n.y),d=(x-mx)**2+(y-my)**2,r=Math.max(4,Math.min(13,4+n.deg*1.6))+4;\n      if(d<r*r&&d<bd){bd=d;best=i;}});return best;}\n  cv.addEventListener('mousemove',e=>{const rect=cv.getBoundingClientRect(),mx=e.clientX-rect.left,my=e.clientY-rect.top,p=pick(mx,my),tip=$('#graphTip');\n    if(p!==hover){hover=p;drawGraph();}\n    if(p>-1){const n=G.nodes[p];tip.style.opacity=1;tip.style.left=mx+'px';tip.style.top=my+'px';\n      tip.innerHTML=`<div class=\"tk\">${n.type} \u00b7 ${n.deg} link${n.deg===1?'':'s'}</div>${esc(n.title)}`;cv.style.cursor='pointer';}\n    else{tip.style.opacity=0;cv.style.cursor='default';}});\n  cv.addEventListener('mouseleave',()=>{hover=-1;$('#graphTip').style.opacity=0;drawGraph();});\n  cv.addEventListener('click',e=>{const rect=cv.getBoundingClientRect(),p=pick(e.clientX-rect.left,e.clientY-rect.top);\n    if(p>-1){switchView('notes');renderNote(G.nodes[p].id);}});\n  window.addEventListener('resize',()=>{if(state.view==='graph')drawGraph();});\n\n  // ---- boot ----\n  // pre-open the top two directory levels so the Files tree opens usefully\n  (function preopen(node,depth){for(const c of node.children.values()){if(depth<2)state.open.add(c.path);preopen(c,depth+1);}})(TREE,0);\n  // land on the richest FILE note; the Flows tab (badged) is one click away\n  const seed=[...fileNotes].sort((a,b)=>(b.outLinks.length+b.backlinks.length)-(a.outLinks.length+a.backlinks.length))[0]\n    || notes[0];\n  renderList();\n  if(seed) renderNote(seed.id);\n})();\n</script>\n";
+export const VIEW_TEMPLATE ="<title>__TITLE__</title>\n<style>\n  :root{\n    --ground:#e8eef1; --surface:#ffffff; --rail:#f0f5f8; --sunk:#e9f0f4;\n    --ink:#111820; --ink-soft:#374250; --muted:#5a6674; --faint:#6a7887;\n    --line:#d7e0e6; --line-soft:#e5ecf0;\n    --accent:#0f6f8c; --accent-soft:#dcf0f6; --accent-ink:#0b5a72;\n    --fresh:#0f7a44; --fresh-bg:#dff2e7;\n    --changed:#b3400b; --changed-bg:#f9e0d6;\n    --missing:#b3132f; --missing-bg:#fbe2e7;\n    --unver:#586372; --unver-bg:#e9edf1;\n    --flow:#8a5410; --flow-bg:#f8e9d8;\n    --file:#0f6f8c; --file-bg:#dcf0f6;\n    --file-node:#1287a8; --flow-node:#d1791f;\n    --mono:ui-monospace,\"SF Mono\",SFMono-Regular,Menlo,Consolas,monospace;\n    --sans:system-ui,-apple-system,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif;\n    --sh:0 1px 2px rgba(20,28,45,.05),0 4px 16px rgba(20,28,45,.06);\n    --top:#0d141d; --top-ink:#eef2f8; --top-faint:#93a3b4;\n    --r:9px;\n  }\n  *{box-sizing:border-box}\n  html,body{height:100%}\n  body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);\n    font-size:14px;line-height:1.5;-webkit-font-smoothing:antialiased;\n    text-rendering:optimizeLegibility;}\n  button{font:inherit;color:inherit;cursor:pointer;border:0;background:none}\n  ::selection{background:var(--accent-soft)}\n\n  .app{display:grid;grid-template-rows:auto 1fr;height:100vh;overflow:hidden}\n\n  /* ---- top bar ----\n     Deliberately DARK against the light reading surface. It is the one place\n     the viewer looks like coldstartmcp.devs nav, which is what makes a note\n     opened from the site and a note opened from `kb view` read as one product\n     - without darkening the note prose, which is what people actually read.\n     The 2px frost -> ember hairline under it is the sites own device. */\n  .top{display:flex;align-items:center;gap:20px;padding:12px 20px;\n    background:var(--top);border-bottom:0;z-index:5;position:relative;color:var(--top-ink)}\n  .top::after{content:\"\";position:absolute;left:0;right:0;bottom:0;height:2px;\n    background:linear-gradient(90deg,#4fbfe0,#ef9448)}\n  #home{display:inline-flex;align-items:center;gap:5px;margin-right:2px;padding:5px 10px 5px 4px;border-radius:999px;font-family:var(--mono);font-size:11px;color:var(--top-faint);text-decoration:none;flex:none;transition:color .15s,background .15s}#home:hover{color:#4fbfe0;background:rgba(79,191,224,.13)}.brand{display:flex;flex-direction:column;justify-content:center;min-width:0;gap:1px}\n  .brand .kicker{font-family:var(--mono);font-size:9.5px;letter-spacing:.11em;\n    text-transform:uppercase;color:var(--top-faint);font-weight:600;line-height:1}\n  .brand .repo{display:inline-flex;align-items:center;gap:6px;font-size:17px;\n    font-weight:680;letter-spacing:-.02em;color:var(--top-ink);line-height:1.1}\n  .brand .repo::before{content:\"\";width:8px;height:8px;border-radius:50%;\n    background:radial-gradient(circle at 34% 30%,#ef9448,#4fbfe0);\n    box-shadow:0 0 10px rgba(79,191,224,.55);flex-shrink:0}\n  .top .spacer{flex:1}\n  .stat{display:flex;flex-direction:column;line-height:1.15}\n  .stat b{font-size:16px;font-variant-numeric:tabular-nums;letter-spacing:-.02em;color:var(--top-ink)}\n  .stat span{font-family:var(--mono);font-size:9.5px;letter-spacing:.09em;\n    text-transform:uppercase;color:var(--top-faint)}\n  .fresh-meter{display:flex;align-items:center;gap:8px}\n  .meter-bar{width:120px;height:8px;border-radius:5px;background:rgba(255,255,255,.11);\n    overflow:hidden;display:flex}\n  .meter-bar i{display:block;height:100%}\n  .segbtns{display:flex;background:rgba(255,255,255,.08);border-radius:8px;padding:3px}\n  .segbtns button{padding:5px 13px;border-radius:6px;font-size:12.5px;\n    font-weight:500;color:var(--top-faint)}\n  .segbtns button[aria-pressed=true]{background:rgba(255,255,255,.94);color:#111820;\n    box-shadow:0 1px 2px rgba(0,0,0,.3);font-weight:600}\n  /* ---- body split ---- */\n  .split{display:grid;grid-template-columns:340px 1fr;min-height:0}\n  .split.graph-mode{grid-template-columns:1fr}\n  .split.graph-mode .rail{display:none}\n\n  /* ---- rail ---- */\n  .rail{background:var(--rail);border-right:1px solid var(--line);\n    display:flex;flex-direction:column;min-height:0}\n  .rail .controls{padding:12px 12px 0;display:flex;flex-direction:column;gap:10px}\n  .search{position:relative}\n  .search input{width:100%;padding:9px 12px 9px 32px;border:1px solid var(--line);\n    border-radius:8px;background:var(--surface);font-size:13px;outline:none}\n  .search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft)}\n  .search svg{position:absolute;left:10px;top:50%;transform:translateY(-50%);\n    width:15px;height:15px;stroke:var(--faint);fill:none;stroke-width:2}\n\n  /* lens tabs (Files / Flows) */\n  .lenses{display:flex;gap:4px}\n  .lens{flex:1;display:flex;align-items:center;justify-content:center;gap:7px;\n    padding:9px 0;border-radius:9px;font-size:13px;font-weight:600;color:var(--muted);\n    background:var(--sunk);border:1px solid transparent}\n  .lens .ct{font-family:var(--mono);font-size:11px;font-weight:700;\n    padding:1px 6px;border-radius:20px;background:rgba(90,102,116,.16);color:var(--muted);\n    font-variant-numeric:tabular-nums}\n  .lens[aria-pressed=true]{background:var(--surface);color:var(--ink);\n    border-color:var(--line);box-shadow:var(--sh)}\n  .lens.files[aria-pressed=true]{color:var(--file)} .lens.files[aria-pressed=true] .ct{background:var(--file-bg);color:var(--file)}\n  .lens.flows[aria-pressed=true]{color:var(--flow)} .lens.flows[aria-pressed=true] .ct{background:var(--flow-bg);color:var(--flow)}\n  .lens .ic{width:15px;height:15px;stroke:currentColor;fill:none;stroke-width:1.8}\n\n  /* status / freshness filter row */\n  .statusrow{display:flex;align-items:center;gap:8px;padding:2px}\n  .fchip{display:inline-flex;align-items:center;gap:7px;padding:5px 11px;border-radius:20px;\n    font-size:12px;font-weight:600;border:1px solid var(--line);background:var(--surface);color:var(--muted)}\n  .fchip .d{width:8px;height:8px;border-radius:50%;background:var(--fresh)}\n  .fchip.has-stale{color:var(--changed);border-color:var(--changed);background:var(--changed-bg)}\n  .fchip.has-stale .d{background:var(--changed)}\n  .fchip[aria-pressed=true]{outline:2px solid var(--changed);outline-offset:1px}\n  .fchip.all-fresh .d{background:var(--fresh)}\n  .treetools{margin-left:auto;display:flex;gap:2px}\n  .treetools button{font-family:var(--mono);font-size:10px;letter-spacing:.04em;\n    text-transform:uppercase;color:var(--faint);padding:4px 7px;border-radius:6px}\n  .treetools button:hover{color:var(--accent);background:var(--sunk)}\n\n  .list{overflow-y:auto;padding:8px 8px 60px;flex:1}\n\n  /* tree rows */\n  .row{display:flex;align-items:center;gap:7px;width:100%;text-align:left;\n    padding:5px 8px;border-radius:7px;min-height:30px}\n  .row:hover{background:var(--sunk)}\n  .row[aria-current=true]{background:var(--accent-soft)}\n  .row[aria-current=true] .lbl{color:var(--accent-ink);font-weight:600}\n  .chev{width:14px;height:14px;flex-shrink:0;stroke:var(--faint);fill:none;stroke-width:2;\n    transition:transform .12s}\n  .row.open>.chev{transform:rotate(90deg)}\n  .spacer-ic{width:14px;flex-shrink:0}\n  .ficon{width:15px;height:15px;flex-shrink:0;stroke:var(--faint);fill:none;stroke-width:1.6}\n  .row.dir .ficon{stroke:var(--accent);fill:var(--accent-soft)}\n  .lbl{font-size:12.5px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;flex:1;min-width:0}\n  .row.dir .lbl{font-weight:600;color:var(--ink-soft)}\n  .row.dir .lbl .seg-dim{color:var(--faint);font-weight:500}\n  .badge{font-family:var(--mono);font-size:10px;color:var(--faint);\n    font-variant-numeric:tabular-nums;flex-shrink:0}\n  .dot{width:7px;height:7px;border-radius:50%;flex-shrink:0}\n  .dot.fresh{background:var(--fresh)} .dot.changed{background:var(--changed)}\n  .dot.missing{background:var(--missing)} .dot.unverified{background:var(--unver)}\n  .char{font-family:var(--mono);font-size:8.5px;font-weight:700;color:var(--faint);\n    border:1px solid var(--line);border-radius:3px;padding:0 3px;flex-shrink:0}\n\n  /* flow cards */\n  .flowcard{display:block;width:100%;text-align:left;padding:11px 12px;border-radius:9px;\n    border:1px solid var(--line-soft);background:var(--surface);margin-bottom:7px}\n  .flowcard:hover{border-color:var(--flow);box-shadow:var(--sh)}\n  .flowcard[aria-current=true]{border-color:var(--flow);background:var(--flow-bg)}\n  .fc-top{display:flex;align-items:center;gap:8px;margin-bottom:6px}\n  .fc-top .dot{margin-top:0}\n  .fc-title{font-size:13px;font-weight:600;line-height:1.35;flex:1;overflow-wrap:anywhere}\n  .fc-span{display:flex;flex-wrap:wrap;gap:4px}\n  .fc-file{font-family:var(--mono);font-size:10px;color:var(--muted);background:var(--sunk);\n    padding:1px 6px;border-radius:5px;max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n  .fc-more{font-family:var(--mono);font-size:10px;color:var(--faint);padding:1px 3px}\n  .empty-note{color:var(--faint);font-size:12px;font-style:italic;padding:20px 10px}\n\n  /* ---- reader ---- */\n  .reader{overflow-y:auto;padding:0}\n  .reader-inner{max-width:760px;margin:0 auto;padding:38px 40px 120px}\n  .eyebrow{display:flex;align-items:center;gap:8px;flex-wrap:wrap;\n    font-family:var(--mono);font-size:11px;margin-bottom:14px}\n  .eyebrow .id{color:var(--faint);overflow-wrap:anywhere}\n  .eyebrow .sep{color:var(--line)}\n  .kind{font-family:var(--mono);font-size:9px;letter-spacing:.06em;font-weight:700;\n    text-transform:uppercase;padding:1px 5px;border-radius:4px}\n  .kind.file{color:var(--file);background:var(--file-bg)}\n  .kind.flow{color:var(--flow);background:var(--flow-bg)}\n  h1.note-title{font-size:26px;line-height:1.22;letter-spacing:-.02em;\n    font-weight:680;margin:0 0 16px;text-wrap:balance;overflow-wrap:anywhere}\n  .metabar{display:flex;align-items:center;gap:14px;flex-wrap:wrap;\n    padding-bottom:18px;margin-bottom:22px;border-bottom:1px solid var(--line-soft)}\n  .pill{display:inline-flex;align-items:center;gap:6px;font-size:11.5px;\n    font-weight:600;padding:3px 10px;border-radius:20px;font-family:var(--mono);\n    letter-spacing:.02em}\n  .pill .d{width:7px;height:7px;border-radius:50%}\n  .pill.fresh{color:var(--fresh);background:var(--fresh-bg)} .pill.fresh .d{background:var(--fresh)}\n  .pill.changed{color:var(--changed);background:var(--changed-bg)} .pill.changed .d{background:var(--changed)}\n  .pill.missing{color:var(--missing);background:var(--missing-bg)} .pill.missing .d{background:var(--missing)}\n  .pill.unverified{color:var(--unver);background:var(--unver-bg)} .pill.unverified .d{background:var(--unver)}\n  .metabar .mi{font-size:12px;color:var(--muted)}\n  .metabar .mi b{color:var(--ink-soft);font-variant-numeric:tabular-nums;font-weight:600}\n\n  .sec-label{font-family:var(--mono);font-size:10px;letter-spacing:.09em;\n    text-transform:uppercase;color:var(--faint);font-weight:600;margin:26px 0 10px}\n\n  .anchor{border:1px solid var(--line);border-radius:var(--r);background:var(--surface);\n    padding:11px 13px;margin-bottom:8px}\n  .anchor-top{display:flex;align-items:center;gap:9px}\n  .apath{font-family:var(--mono);font-size:12px;color:var(--ink);font-weight:600;\n    overflow-wrap:anywhere;flex:1}\n  .apath .p{color:var(--faint)}\n  .astate{font-family:var(--mono);font-size:9px;letter-spacing:.06em;font-weight:700;\n    text-transform:uppercase;padding:2px 6px;border-radius:4px;white-space:nowrap}\n  .astate.fresh{color:var(--fresh);background:var(--fresh-bg)}\n  .astate.changed{color:var(--changed);background:var(--changed-bg)}\n  .astate.missing{color:var(--missing);background:var(--missing-bg)}\n  .astate.unverified{color:var(--unver);background:var(--unver-bg)}\n  .copy{font-family:var(--mono);font-size:10px;color:var(--faint);padding:2px 6px;\n    border-radius:4px;border:1px solid var(--line)}\n  .copy:hover{color:var(--accent);border-color:var(--accent)}\n  .syms{display:flex;flex-wrap:wrap;gap:5px;margin-top:9px}\n  .sym{font-family:var(--mono);font-size:11px;background:var(--sunk);\n    color:var(--ink-soft);padding:2px 7px;border-radius:5px;cursor:pointer;\n    transition:background .1s,color .1s;position:relative}\n  .sym:hover{background:var(--accent-soft);color:var(--accent-ink)}\n  .sym.copied{background:var(--accent);color:#fff}\n  .sym.copied::after{content:\"copied\";position:absolute;left:50%;bottom:calc(100% + 5px);\n    transform:translateX(-50%);background:var(--ink);color:#fff;font-size:9px;\n    padding:2px 6px;border-radius:4px;white-space:nowrap;letter-spacing:.04em}\n\n  .aliases{border:1px solid var(--line-soft);border-radius:var(--r);\n    background:var(--rail);overflow:hidden}\n  .aliases summary{list-style:none;cursor:pointer;padding:9px 13px;\n    display:flex;align-items:center;gap:8px;font-size:12px;color:var(--muted)}\n  .aliases summary::-webkit-details-marker{display:none}\n  .aliases summary b{color:var(--ink-soft);font-weight:600}\n  .aliases summary .chv{margin-left:auto;transition:transform .15s}\n  .aliases[open] summary .chv{transform:rotate(90deg)}\n  .alias-cloud{display:flex;flex-wrap:wrap;gap:6px;padding:2px 13px 13px}\n  .alias-cloud span{font-family:var(--mono);font-size:11px;color:var(--ink-soft);\n    background:var(--surface);border:1px solid var(--line);padding:2px 8px;border-radius:12px}\n\n  .md{font-size:14.5px;line-height:1.68;color:var(--ink-soft)}\n  .md h2{font-size:13px;font-family:var(--mono);letter-spacing:.05em;\n    text-transform:uppercase;color:var(--ink);font-weight:700;margin:30px 0 12px;\n    padding-bottom:7px;border-bottom:1px solid var(--line-soft)}\n  .md h3{font-size:15px;margin:22px 0 8px;color:var(--ink)}\n  .md p{margin:0 0 14px}\n  .md ul,.md ol{margin:0 0 14px;padding-left:22px}\n  .md li{margin:0 0 8px}\n  .md li::marker{color:var(--faint)}\n  .md code{font-family:var(--mono);font-size:12.5px;background:var(--sunk);\n    color:var(--accent-ink);padding:1px 5px;border-radius:5px;overflow-wrap:anywhere}\n  .md strong{color:var(--ink);font-weight:650}\n  .wl{font-family:var(--mono);font-size:12px;color:var(--accent);font-weight:600;\n    background:var(--accent-soft);padding:1px 6px;border-radius:5px;\n    text-decoration:none;overflow-wrap:anywhere}\n  .wl:hover{background:var(--accent);color:#fff}\n  .wl.dead{color:var(--muted);background:var(--sunk);cursor:default}\n\n  .links-grid{display:grid;grid-template-columns:1fr 1fr;gap:22px;margin-top:34px;\n    padding-top:22px;border-top:1px solid var(--line-soft)}\n  @media(max-width:640px){.links-grid{grid-template-columns:1fr}}\n  .linkcol .sec-label{margin-top:0}\n  .linkbtn{display:flex;align-items:center;gap:8px;width:100%;text-align:left;\n    padding:8px 10px;border-radius:7px;font-size:12px;margin-bottom:3px}\n  .linkbtn:hover{background:var(--sunk)}\n  .linkbtn .kind{flex-shrink:0}\n  .linkbtn span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n\n  .placeholder{display:flex;align-items:center;justify-content:center;height:100%;\n    color:var(--faint);font-size:13px}\n\n  /* ---- graph ---- */\n  .graph-wrap{position:relative;overflow:hidden;background:\n    radial-gradient(circle at 30% 20%, #f0f5f8, var(--ground))}\n  .graph-wrap canvas{display:block;width:100%;height:100%}\n  .graph-legend{position:absolute;top:16px;left:16px;background:var(--surface);\n    border:1px solid var(--line);border-radius:var(--r);padding:12px 14px;\n    box-shadow:var(--sh);font-size:12px;max-width:230px}\n  .graph-legend .lg-t{font-family:var(--mono);font-size:10px;letter-spacing:.07em;\n    text-transform:uppercase;color:var(--faint);margin-bottom:8px}\n  .graph-legend .lg-row{display:flex;align-items:center;gap:8px;margin-bottom:5px}\n  .graph-legend .lg-row i{width:12px;height:12px;border-radius:50%;flex-shrink:0}\n  .graph-legend .hint{color:var(--muted);margin-top:8px;line-height:1.4}\n  .graph-tip{position:absolute;pointer-events:none;background:var(--ink);color:#fff;\n    font-size:11.5px;padding:6px 10px;border-radius:7px;max-width:280px;opacity:0;\n    transform:translate(-50%,-140%);transition:opacity .1s;box-shadow:var(--sh);z-index:3}\n  .graph-tip .tk{font-family:var(--mono);font-size:9px;letter-spacing:.06em;\n    text-transform:uppercase;opacity:.7}\n\n  @media(max-width:860px){\n    .split{grid-template-columns:1fr}\n    .rail{position:absolute;inset:57px 0 0 0;z-index:4;width:min(340px,86vw);\n      box-shadow:var(--sh)}\n    .split:not(.rail-open) .rail{display:none}\n    .split.graph-mode .rail{display:none}\n    .reader-inner{padding:26px 20px 100px}\n    .menu-btn{display:inline-flex!important}\n  }\n  .menu-btn{display:none;align-items:center;gap:6px}\n</style>\n\n<div class=\"app\">\n  <header class=\"top\"><!--__HOME_LINK__-->\n    <button class=\"menu-btn segbtns\" id=\"menuBtn\" style=\"padding:6px 10px\"><svg width=\"16\" height=\"16\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"><path d=\"M2 4h12M2 8h12M2 12h12\"/></svg></button>\n    <div class=\"brand\">\n      <span class=\"kicker\">Coldstart&nbsp;Notebook</span>\n      <span class=\"repo\" id=\"repoName\">repo</span>\n    </div>\n    <div class=\"spacer\"></div>\n    <div class=\"stat\"><b id=\"sTotal\">0</b><span>notes</span></div>\n    <div class=\"stat\"><b id=\"sLinks\">0</b><span>links</span></div>\n    <div class=\"fresh-meter\">\n      <div class=\"meter-bar\" id=\"meterBar\"></div>\n      <div class=\"stat\"><b id=\"sFresh\">0%</b><span>fresh</span></div>\n    </div>\n    <div class=\"segbtns\" role=\"tablist\">\n      <button id=\"tabNotes\" aria-pressed=\"true\">Notes</button>\n      <button id=\"tabGraph\" aria-pressed=\"false\">Graph</button>\n    </div>\n  </header>\n\n  <div class=\"split\" id=\"split\">\n    <aside class=\"rail\" id=\"rail\">\n      <div class=\"controls\">\n        <div class=\"search\">\n          <svg viewBox=\"0 0 16 16\"><circle cx=\"7\" cy=\"7\" r=\"5\"/><path d=\"M11 11l3 3\"/></svg>\n          <input id=\"q\" placeholder=\"Search title, alias, path, symbol\u2026\" autocomplete=\"off\">\n        </div>\n        <div class=\"lenses\">\n          <button class=\"lens files\" data-lens=\"files\" aria-pressed=\"true\">\n            <svg class=\"ic\" viewBox=\"0 0 16 16\"><path d=\"M2 4.5h5l1.5 1.5H14v6.5a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1z\"/></svg>\n            Files <span class=\"ct\" id=\"ctFiles\">0</span>\n          </button>\n          <button class=\"lens flows\" data-lens=\"flows\" aria-pressed=\"false\">\n            <svg class=\"ic\" viewBox=\"0 0 16 16\"><circle cx=\"3.5\" cy=\"3.5\" r=\"1.6\"/><circle cx=\"12.5\" cy=\"8\" r=\"1.6\"/><circle cx=\"3.5\" cy=\"12.5\" r=\"1.6\"/><path d=\"M5 3.9h4a2 2 0 0 1 2 2v.5M5 12.1h4a2 2 0 0 0 2-2v-.5\"/></svg>\n            Flows <span class=\"ct\" id=\"ctFlows\">0</span>\n          </button>\n        </div>\n        <div class=\"statusrow\">\n          <button class=\"fchip all-fresh\" id=\"staleChip\" aria-pressed=\"false\"><span class=\"d\"></span><span id=\"staleLbl\">All fresh</span></button>\n          <div class=\"treetools\" id=\"treeTools\">\n            <button data-tt=\"expand\">Expand</button>\n            <button data-tt=\"collapse\">Collapse</button>\n          </div>\n        </div>\n      </div>\n      <div class=\"list\" id=\"list\"></div>\n    </aside>\n\n    <main class=\"reader\" id=\"reader\">\n      <div class=\"placeholder\">Select a note to read.</div>\n    </main>\n\n    <section class=\"graph-wrap\" id=\"graphWrap\" style=\"display:none\">\n      <canvas id=\"graphCanvas\"></canvas>\n      <div class=\"graph-legend\">\n        <div class=\"lg-t\">Note graph</div>\n        <div class=\"lg-row\"><i style=\"background:var(--file-node)\"></i>file note</div>\n        <div class=\"lg-row\"><i style=\"background:var(--flow-node)\"></i>flow note</div>\n        <div class=\"hint\" id=\"graphHint\">Only linked notes shown. Click a node to open it.</div>\n      </div>\n      <div class=\"graph-tip\" id=\"graphTip\"></div>\n    </section>\n  </div>\n</div>\n\n<script>const DB = __DATA_JSON__;</script>\n<script>\n(function(){\n  \"use strict\";\n  const notes = DB.notes;\n  const byId = new Map(notes.map(n=>[n.id,n]));\n  const fileNotes = notes.filter(n=>n.type==='file');\n  const flowNotes = notes.filter(n=>n.type==='flow');\n  const $ = s=>document.querySelector(s);\n  const esc = s=>String(s).replace(/[&<>]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));\n  // clipboard: navigator.clipboard is unreliable on file:// \u2014 fall back to execCommand\n  function copyText(t){\n    try{\n      if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(t).catch(()=>fallbackCopy(t));return;}\n    }catch(e){}\n    fallbackCopy(t);\n  }\n  function fallbackCopy(t){\n    try{const ta=document.createElement('textarea');ta.value=t;ta.style.position='fixed';ta.style.opacity='0';\n      document.body.appendChild(ta);ta.focus();ta.select();document.execCommand('copy');document.body.removeChild(ta);}catch(e){}\n  }\n  const RANK={fresh:0,unverified:1,changed:2,missing:3};\n  const isStale=n=>n.freshness==='changed'||n.freshness==='missing';\n\n  let state = { lens:'files', q:'', selected:null, view:'notes', staleOnly:false, open:new Set() };\n\n  // ---- header stats ----\n  $('#repoName').textContent = DB.summary.repo;\n  $('#sTotal').textContent = DB.summary.total;\n  $('#ctFiles').textContent = fileNotes.length;\n  $('#ctFlows').textContent = flowNotes.length;\n  // Both link kinds, deduped the same way buildGraph does, so the header\n  // stat and the graph hint can never disagree.\n  const edgeKeys = new Set();\n  for(const n of notes) for(const l of [...n.outLinks,...(n.anchorLinks||[])])\n    if(byId.has(l)&&l!==n.id) edgeKeys.add(n.id<l?n.id+'|'+l:l+'|'+n.id);\n  const edgeCount = edgeKeys.size;\n  $('#sLinks').textContent = edgeCount;\n  const fr = DB.summary.byFreshness;\n  const freshPct = Math.round(100*(fr.fresh||0)/DB.summary.total);\n  $('#sFresh').textContent = freshPct+'%';\n  const mb = $('#meterBar');\n  const morder=[['fresh','--fresh'],['changed','--changed'],['unverified','--unver'],['missing','--missing']];\n  mb.innerHTML = morder.filter(([k])=>fr[k]).map(([k,v])=>\n    `<i style=\"width:${100*fr[k]/DB.summary.total}%;background:var(${v})\"></i>`).join('');\n\n  // stale chip\n  const staleCount = notes.filter(isStale).length;\n  const chip=$('#staleChip');\n  if(staleCount){\n    chip.classList.remove('all-fresh');chip.classList.add('has-stale');\n    $('#staleLbl').textContent=`${staleCount} need review`;\n  }else{\n    $('#staleLbl').textContent='All fresh';\n  }\n\n  // ---- filter helpers ----\n  function matches(n,q){\n    if(!q) return true;\n    const hay=(n.title+' '+n.id+' '+n.aliases.join(' ')+' '+n.anchors.map(a=>a.path+' '+(a.symbols||[]).join(' ')).join(' ')).toLowerCase();\n    return q.toLowerCase().split(/\\s+/).every(t=>hay.includes(t));\n  }\n  function passFilter(n){\n    if(state.staleOnly && !isStale(n)) return false;\n    return matches(n,state.q);\n  }\n\n  // ================= FILE TREE =================\n  function buildTree(){\n    const root={name:'',path:'',children:new Map(),notes:[],dir:true};\n    for(const n of fileNotes){\n      const path=n.anchors[0]?n.anchors[0].path:n.title;\n      const segs=path.split('/');\n      let cur=root;\n      for(let i=0;i<segs.length-1;i++){\n        const s=segs[i], p=segs.slice(0,i+1).join('/');\n        if(!cur.children.has(s)) cur.children.set(s,{name:s,path:p,children:new Map(),notes:[],dir:true});\n        cur=cur.children.get(s);\n      }\n      cur.notes.push(Object.assign({leaf:segs[segs.length-1]},n));\n    }\n    // compact single-child dir chains (VSCode style), never the root\n    const compact=(node,isRoot)=>{\n      for(const c of node.children.values()) compact(c,false);\n      if(!isRoot){\n        while(node.children.size===1 && node.notes.length===0){\n          const only=[...node.children.values()][0];\n          node.name = node.name+'/'+only.name;\n          node.path = only.path; node.notes = only.notes; node.children = only.children;\n        }\n      }\n    };\n    compact(root,true);\n    // rollups\n    const roll=(node)=>{\n      let worst='fresh',cnt=node.notes.length;\n      for(const n of node.notes) if(RANK[n.freshness]>RANK[worst]) worst=n.freshness;\n      for(const c of node.children.values()){roll(c); if(RANK[c.roll]>RANK[worst]) worst=c.roll; cnt+=c.count;}\n      node.roll=worst; node.count=cnt;\n    };\n    roll(root);\n    return root;\n  }\n  const TREE=buildTree();\n\n  function nodeHasMatch(node){\n    if(node.notes.some(passFilter)) return true;\n    for(const c of node.children.values()) if(nodeHasMatch(c)) return true;\n    return false;\n  }\n  function ancestorsOf(id){\n    // dir paths that contain the selected file note\n    const n=byId.get(id); if(!n||n.type!=='file') return new Set();\n    const path=n.anchors[0]?n.anchors[0].path:n.title;\n    const set=new Set(); const segs=path.split('/');\n    for(let i=1;i<segs.length;i++) set.add(segs.slice(0,i).join('/'));\n    return set;\n  }\n  const FOLDER_SVG='<svg class=\"ficon\" viewBox=\"0 0 16 16\"><path d=\"M2 4.5h5l1.5 1.5H14v6.5a1 1 0 0 1-1 1H3a1 1 0 0 1-1-1z\"/></svg>';\n  const FILE_SVG='<svg class=\"ficon\" viewBox=\"0 0 16 16\"><path d=\"M4 1.5h5L13 5v9a.5.5 0 0 1-.5.5h-9A.5.5 0 0 1 3 14V2a.5.5 0 0 1 1-.5z\"/><path d=\"M9 1.5V5h4\"/></svg>';\n\n  function renderTreeNode(node,depth,active,out){\n    const dirs=[...node.children.values()].filter(nodeHasMatch)\n      .sort((a,b)=>a.name.localeCompare(b.name));\n    const leaves=node.notes.filter(passFilter).sort((a,b)=>a.leaf.localeCompare(b.leaf));\n    const pad=8+depth*15;\n    for(const d of dirs){\n      const open = active || state.open.has(d.path);\n      const dimIdx=d.name.lastIndexOf('/');\n      const nm = dimIdx>-1 ? `<span class=\"seg-dim\">${esc(d.name.slice(0,dimIdx+1))}</span>${esc(d.name.slice(dimIdx+1))}` : esc(d.name);\n      out.push(`<button class=\"row dir ${open?'open':''}\" data-dir=\"${esc(d.path)}\" style=\"padding-left:${pad}px\">\n        <svg class=\"chev\" viewBox=\"0 0 16 16\"><path d=\"M6 3l5 5-5 5\"/></svg>${FOLDER_SVG}\n        <span class=\"lbl\">${nm}</span>\n        <span class=\"badge\">${d.count}</span>\n        ${d.roll!=='fresh'?`<span class=\"dot ${d.roll}\"></span>`:''}\n      </button>`);\n      if(open) renderTreeNode(d,depth+1,active,out);\n    }\n    for(const n of leaves){\n      out.push(`<button class=\"row leaf\" data-id=\"${esc(n.id)}\" aria-current=\"${n.id===state.selected}\" style=\"padding-left:${pad+21}px\">\n        ${FILE_SVG}\n        <span class=\"lbl\">${esc(n.leaf)}</span>\n        ${n.character?`<span class=\"char\" title=\"${esc(n.character)} note\">${n.character[0].toUpperCase()}</span>`:''}\n        <span class=\"dot ${n.freshness}\"></span>\n      </button>`);\n    }\n  }\n\n  function renderFiles(){\n    const active=!!(state.q||state.staleOnly);\n    const out=[];\n    renderTreeNode(TREE,0,active,out);\n    $('#list').innerHTML = out.length?out.join(''):'<div class=\"empty-note\">No file notes match.</div>';\n  }\n\n  // ================= FLOWS =================\n  function renderFlows(){\n    const list=flowNotes.filter(passFilter)\n      .sort((a,b)=>b.anchors.length-a.anchors.length||a.title.localeCompare(b.title));\n    if(!list.length){$('#list').innerHTML='<div class=\"empty-note\">No flows match.</div>';return;}\n    $('#list').innerHTML=list.map(n=>{\n      const files=n.anchors.map(a=>a.path.split('/').pop());\n      const shown=files.slice(0,4), extra=files.length-shown.length;\n      return `<button class=\"flowcard\" data-id=\"${esc(n.id)}\" aria-current=\"${n.id===state.selected}\">\n        <div class=\"fc-top\">\n          <span class=\"dot ${n.freshness}\"></span>\n          <span class=\"fc-title\">${esc(n.title)}</span>\n        </div>\n        <div class=\"fc-span\">\n          ${shown.map(f=>`<span class=\"fc-file\">${esc(f)}</span>`).join('')}\n          ${extra>0?`<span class=\"fc-more\">+${extra} more</span>`:''}\n        </div>\n      </button>`;\n    }).join('');\n  }\n\n  function renderList(){\n    $('#treeTools').style.visibility = state.lens==='files' ? 'visible':'hidden';\n    if(state.lens==='files') renderFiles(); else renderFlows();\n  }\n\n  // ---- markdown mini-renderer ----\n  function mdInline(t){\n    t=esc(t);\n    t=t.replace(/`([^`]+)`/g,(_,c)=>`<code>${c}</code>`);\n    t=t.replace(/\\[\\[([^\\]]+)\\]\\]/g,(_,id)=>{\n      const ok=byId.has(id);\n      return `<a class=\"wl${ok?'':' dead'}\" ${ok?`data-goto=\"${esc(id)}\"`:''} title=\"${esc(id)}\">${ok?esc(byId.get(id).title):esc(id)}</a>`;\n    });\n    t=t.replace(/\\*\\*([^*]+)\\*\\*/g,'<strong>$1</strong>');\n    return t;\n  }\n  function renderMd(src){\n    const lines=src.split('\\n');\n    let html='',i=0;\n    const flush=(buf,tag)=>buf.length?`<${tag}>${buf.join('')}</${tag}>`:'';\n    while(i<lines.length){\n      let ln=lines[i];\n      if(/^#\\s+/.test(ln)){i++;continue;}\n      if(/^##\\s+/.test(ln)){html+=`<h2>${mdInline(ln.replace(/^##\\s+/,''))}</h2>`;i++;continue;}\n      if(/^###\\s+/.test(ln)){html+=`<h3>${mdInline(ln.replace(/^###\\s+/,''))}</h3>`;i++;continue;}\n      if(/^\\s*[-*]\\s+/.test(ln)){\n        const buf=[];\n        while(i<lines.length&&/^\\s*[-*]\\s+/.test(lines[i])){buf.push(`<li>${mdInline(lines[i].replace(/^\\s*[-*]\\s+/,''))}</li>`);i++;}\n        html+=flush(buf,'ul');continue;\n      }\n      if(/^\\s*\\d+\\.\\s+/.test(ln)){\n        const buf=[];\n        while(i<lines.length&&/^\\s*\\d+\\.\\s+/.test(lines[i])){buf.push(`<li>${mdInline(lines[i].replace(/^\\s*\\d+\\.\\s+/,''))}</li>`);i++;}\n        html+=flush(buf,'ol');continue;\n      }\n      if(!ln.trim()){i++;continue;}\n      const buf=[];\n      while(i<lines.length&&lines[i].trim()&&!/^(#{1,3}\\s|\\s*[-*]\\s|\\s*\\d+\\.\\s)/.test(lines[i])){buf.push(lines[i]);i++;}\n      html+=`<p>${mdInline(buf.join(' '))}</p>`;\n    }\n    return html;\n  }\n  function anchorHtml(a){\n    const parts=a.path.split('/'); const file=parts.pop();\n    const dir=parts.length?parts.join('/')+'/':'';\n    return `<div class=\"anchor\">\n      <div class=\"anchor-top\">\n        <span class=\"apath\"><span class=\"p\">${esc(dir)}</span>${esc(file)}</span>\n        <span class=\"astate ${a.state}\">${a.state}</span>\n        <button class=\"copy\" data-copy=\"${esc(a.path)}\">copy</button>\n      </div>\n      ${(a.symbols&&a.symbols.length)?`<div class=\"syms\">${a.symbols.map(s=>`<button class=\"sym\" data-copysym=\"${esc(s)}\" title=\"click to copy symbol\">${esc(s)}</button>`).join('')}</div>`:''}\n    </div>`;\n  }\n  function linkBtn(id){\n    const n=byId.get(id);\n    return `<button class=\"linkbtn\" data-goto=\"${esc(id)}\"><span class=\"kind ${n.type}\">${n.type.toUpperCase()}</span><span>${esc(n.title)}</span></button>`;\n  }\n  function renderNote(id){\n    const n=byId.get(id); if(!n) return;\n    state.selected=id;\n    // reveal once: persist the file's ancestor folders so they stay open\n    // (and prior folders stay open too) \u2014 you can still collapse any by hand\n    if(n.type==='file') for(const p of ancestorsOf(id)) state.open.add(p);\n    const outs=n.outLinks.filter(l=>byId.has(l));\n    const r=$('#reader');\n    r.innerHTML=`<div class=\"reader-inner\">\n      <div class=\"eyebrow\">\n        <span class=\"kind ${n.type}\">${n.type.toUpperCase()}${n.character?' \u00b7 '+n.character:''}</span>\n        <span class=\"sep\">/</span><span class=\"id\">${esc(n.id)}</span>\n      </div>\n      <h1 class=\"note-title\">${esc(n.title)}</h1>\n      <div class=\"metabar\">\n        <span class=\"pill ${n.freshness}\"><span class=\"d\"></span>${n.freshness}</span>\n        <span class=\"mi\"><b>${n.anchors.length}</b> anchor${n.anchors.length===1?'':'s'}</span>\n        <span class=\"mi\"><b>${n.edits}</b> edit${n.edits===1?'':'s'}</span>\n        <span class=\"mi\">updated <b>${esc((n.updated||'').slice(0,10))}</b></span>\n      </div>\n      <div class=\"sec-label\">Anchors \u2014 verified code addresses</div>\n      ${n.anchors.length?n.anchors.map(anchorHtml).join(''):'<div class=\"empty-note\">No anchors.</div>'}\n      ${n.aliases.length?`<details class=\"aliases\" style=\"margin-top:14px\">\n        <summary><b>${n.aliases.length}</b> search aliases <span style=\"color:var(--faint)\">\u2014 queries that should surface this note</span><span class=\"chv\">\u203a</span></summary>\n        <div class=\"alias-cloud\">${n.aliases.map(a=>`<span>${esc(a)}</span>`).join('')}</div>\n      </details>`:''}\n      <div class=\"sec-label\">Note</div>\n      <div class=\"md\">${renderMd(n.body)}</div>\n      <div class=\"links-grid\">\n        <div class=\"linkcol\"><div class=\"sec-label\">Links to (${outs.length})</div>\n          ${outs.length?outs.map(linkBtn).join(''):'<div class=\"empty-note\">No outgoing links.</div>'}</div>\n        <div class=\"linkcol\"><div class=\"sec-label\">Referenced by (${n.backlinks.length})</div>\n          ${n.backlinks.length?n.backlinks.map(linkBtn).join(''):'<div class=\"empty-note\">Not referenced.</div>'}</div>\n      </div>\n    </div>`;\n    r.scrollTop=0;\n    // switch lens to match the note type so it's visible in the rail\n    if(n.type==='flow'&&state.lens!=='flows') setLens('flows');\n    else if(n.type==='file'&&state.lens!=='files') setLens('files');\n    else renderList();\n  }\n\n  // ---- events ----\n  $('#q').addEventListener('input',e=>{state.q=e.target.value;renderList();});\n  $('.lenses').addEventListener('click',e=>{const b=e.target.closest('.lens');if(b)setLens(b.dataset.lens);});\n  function setLens(l){\n    state.lens=l;\n    document.querySelectorAll('.lens').forEach(x=>x.setAttribute('aria-pressed',x.dataset.lens===l));\n    renderList();\n  }\n  chip.addEventListener('click',()=>{state.staleOnly=!state.staleOnly;chip.setAttribute('aria-pressed',state.staleOnly);renderList();});\n  $('#treeTools').addEventListener('click',e=>{\n    const b=e.target.closest('button');if(!b)return;\n    if(b.dataset.tt==='collapse'){state.open.clear();}\n    else{ // expand all dirs\n      const walk=nd=>{for(const c of nd.children.values()){state.open.add(c.path);walk(c);}};walk(TREE);\n    }\n    renderFiles();\n  });\n  document.addEventListener('click',e=>{\n    const dir=e.target.closest('[data-dir]');\n    if(dir){const p=dir.dataset.dir;state.open.has(p)?state.open.delete(p):state.open.add(p);renderFiles();return;}\n    const row=e.target.closest('[data-id]');\n    if(row){switchView('notes');renderNote(row.dataset.id);closeRail();return;}\n    const goto=e.target.closest('[data-goto]');\n    if(goto){switchView('notes');renderNote(goto.dataset.goto);return;}\n    const cs=e.target.closest('[data-copysym]');\n    if(cs){copyText(cs.dataset.copysym);cs.classList.add('copied');setTimeout(()=>cs.classList.remove('copied'),750);return;}\n    const cp=e.target.closest('[data-copy]');\n    if(cp){copyText(cp.dataset.copy);cp.textContent='copied';setTimeout(()=>cp.textContent='copy',900);return;}\n  });\n\n  // ---- view switching ----\n  function switchView(v){\n    state.view=v;\n    $('#tabNotes').setAttribute('aria-pressed',v==='notes');\n    $('#tabGraph').setAttribute('aria-pressed',v==='graph');\n    $('#split').classList.toggle('graph-mode',v==='graph');\n    $('#reader').style.display=v==='graph'?'none':'';\n    $('#graphWrap').style.display=v==='graph'?'':'none';\n    if(v==='graph') drawGraph();\n  }\n  $('#tabNotes').onclick=()=>switchView('notes');\n  $('#tabGraph').onclick=()=>switchView('graph');\n  function closeRail(){$('#split').classList.remove('rail-open');}\n  $('#menuBtn').onclick=()=>$('#split').classList.toggle('rail-open');\n\n  // ================= GRAPH =================\n  let G=null;\n  function buildGraph(){\n    const linked=new Set(); const edges=[];\n    const seen=new Set();\n    const addEdge=(a,b,kind)=>{const key=(a<b?a+'|'+b:b+'|'+a);if(seen.has(key))return;seen.add(key);\n      linked.add(a);linked.add(b);edges.push([a,b,kind]);};\n    // kind 0 = a hand-typed [[wikilink]]; kind 1 = the two notes anchor the\n    // same file. Wikilinks are added first so an explicit link is never\n    // downgraded to the derived kind by the dedup above.\n    for(const n of notes) for(const l of n.outLinks) if(byId.has(l)&&l!==n.id) addEdge(n.id,l,0);\n    for(const n of notes) for(const l of (n.anchorLinks||[])) if(byId.has(l)&&l!==n.id) addEdge(n.id,l,1);\n    const ids=[...linked]; const idx=new Map(ids.map((id,i)=>[id,i])); const N=ids.length;\n    const nodes=ids.map((id,i)=>{const a=2*Math.PI*i/N;\n      return {id,x:Math.cos(a)*260,y:Math.sin(a)*260,vx:0,vy:0,deg:0,type:byId.get(id).type,title:byId.get(id).title};});\n    const E=edges.map(([a,b,k])=>[idx.get(a),idx.get(b),k]);\n    for(const [a,b] of E){nodes[a].deg++;nodes[b].deg++;}\n    for(let it=0;it<320;it++){\n      const k=it<220?1:0.4;\n      for(let i=0;i<N;i++){let fx=0,fy=0;\n        for(let j=0;j<N;j++){if(i===j)continue;\n          let dx=nodes[i].x-nodes[j].x,dy=nodes[i].y-nodes[j].y,d2=dx*dx+dy*dy+0.01,d=Math.sqrt(d2);\n          const rep=1600/d2; fx+=dx/d*rep; fy+=dy/d*rep;}\n        fx-=nodes[i].x*0.012; fy-=nodes[i].y*0.012;\n        nodes[i].vx=(nodes[i].vx+fx)*0.82; nodes[i].vy=(nodes[i].vy+fy)*0.82;}\n      for(const [a,b] of E){let dx=nodes[b].x-nodes[a].x,dy=nodes[b].y-nodes[a].y,d=Math.sqrt(dx*dx+dy*dy)+0.01;\n        const spring=(d-90)*0.02,ux=dx/d*spring,uy=dy/d*spring;\n        nodes[a].vx+=ux;nodes[a].vy+=uy;nodes[b].vx-=ux;nodes[b].vy-=uy;}\n      for(const nd of nodes){nd.x+=nd.vx*k;nd.y+=nd.vy*k;}\n    }\n    G={nodes,E,idx};\n    const wl=edges.filter(e=>e[2]===0).length;\n    $('#graphHint').textContent=`${N} linked notes \u00b7 ${edges.length} links `+\n      `(${wl} written as [[links]], ${edges.length-wl} dashed: the notes share a file). Click a node to open it.`;\n  }\n  let cam={x:0,y:0,s:1},hover=-1;\n  function drawGraph(){\n    if(!G) buildGraph();\n    const cv=$('#graphCanvas'),wrap=$('#graphWrap'),dpr=window.devicePixelRatio||1;\n    const W=wrap.clientWidth,H=wrap.clientHeight;\n    cv.width=W*dpr;cv.height=H*dpr;\n    const ctx=cv.getContext('2d');ctx.setTransform(dpr,0,0,dpr,0,0);\n    const xs=G.nodes.map(n=>n.x),ys=G.nodes.map(n=>n.y);\n    const minX=Math.min(...xs),maxX=Math.max(...xs),minY=Math.min(...ys),maxY=Math.max(...ys),pad=70;\n    const s=Math.min((W-pad*2)/(maxX-minX||1),(H-pad*2)/(maxY-minY||1));\n    cam.s=s;cam.x=W/2-(minX+maxX)/2*s;cam.y=H/2-(minY+maxY)/2*s;\n    const T=(x,y)=>[x*cam.s+cam.x,y*cam.s+cam.y];\n    ctx.clearRect(0,0,W,H);\n    for(const [a,b,k] of G.E){const A=G.nodes[a],B=G.nodes[b],[ax,ay]=T(A.x,A.y),[bx,by]=T(B.x,B.y);\n      const on=hover>-1&&(a===hover||b===hover);\n      ctx.strokeStyle=on?'rgba(15,111,140,.55)':'rgba(90,102,116,.20)';ctx.lineWidth=on?1.8:1;\n      ctx.setLineDash(k?[4,4]:[]);\n      ctx.beginPath();ctx.moveTo(ax,ay);ctx.lineTo(bx,by);ctx.stroke();}\n    ctx.setLineDash([]);\n    const cs=getComputedStyle(document.documentElement);\n    const cFile=cs.getPropertyValue('--file-node').trim(),cFlow=cs.getPropertyValue('--flow-node').trim();\n    G.nodes.forEach((n,i)=>{const[x,y]=T(n.x,n.y),r=Math.max(4,Math.min(13,4+n.deg*1.6)),isH=i===hover;\n      ctx.beginPath();ctx.arc(x,y,r+(isH?2:0),0,7);ctx.fillStyle=n.type==='flow'?cFlow:cFile;\n      ctx.globalAlpha=hover>-1&&!isH&&!G.E.some(([a,b])=>(a===hover&&b===i)||(b===hover&&a===i))?0.35:1;\n      ctx.fill();if(isH){ctx.lineWidth=2;ctx.strokeStyle='#fff';ctx.stroke();}ctx.globalAlpha=1;});\n    G._T=T;\n  }\n  const cv=$('#graphCanvas');\n  function pick(mx,my){if(!G||!G._T)return -1;let best=-1,bd=18*18;\n    G.nodes.forEach((n,i)=>{const[x,y]=G._T(n.x,n.y),d=(x-mx)**2+(y-my)**2,r=Math.max(4,Math.min(13,4+n.deg*1.6))+4;\n      if(d<r*r&&d<bd){bd=d;best=i;}});return best;}\n  cv.addEventListener('mousemove',e=>{const rect=cv.getBoundingClientRect(),mx=e.clientX-rect.left,my=e.clientY-rect.top,p=pick(mx,my),tip=$('#graphTip');\n    if(p!==hover){hover=p;drawGraph();}\n    if(p>-1){const n=G.nodes[p];tip.style.opacity=1;tip.style.left=mx+'px';tip.style.top=my+'px';\n      tip.innerHTML=`<div class=\"tk\">${n.type} \u00b7 ${n.deg} link${n.deg===1?'':'s'}</div>${esc(n.title)}`;cv.style.cursor='pointer';}\n    else{tip.style.opacity=0;cv.style.cursor='default';}});\n  cv.addEventListener('mouseleave',()=>{hover=-1;$('#graphTip').style.opacity=0;drawGraph();});\n  cv.addEventListener('click',e=>{const rect=cv.getBoundingClientRect(),p=pick(e.clientX-rect.left,e.clientY-rect.top);\n    if(p>-1){switchView('notes');renderNote(G.nodes[p].id);}});\n  window.addEventListener('resize',()=>{if(state.view==='graph')drawGraph();});\n\n  // ---- boot ----\n  // pre-open the top two directory levels so the Files tree opens usefully\n  (function preopen(node,depth){for(const c of node.children.values()){if(depth<2)state.open.add(c.path);preopen(c,depth+1);}})(TREE,0);\n  // land on the richest FILE note; the Flows tab (badged) is one click away\n  const seed=[...fileNotes].sort((a,b)=>(b.outLinks.length+b.backlinks.length)-(a.outLinks.length+a.backlinks.length))[0]\n    || notes[0];\n  renderList();\n  if(seed) renderNote(seed.id);\n})();\n</script>\n";