Design language v2: Steps 1-2 foundation migration

.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"}]}