You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Follow-up to #454, which publishes a static docs-viewer snapshot at guren.dev/_guren/docs. That snapshot is built from examples/blog, because the site itself has nothing to show: web/ has no docs/ at all.
The stronger claim is the site documenting itself. A visitor reading "your app's knowledge graph" on a page that is a Guren app should be able to open that app's own graph, not a sample's — and unlike the example, it keeps growing as the site does.
What the site's graph looks like today
Running guren spec:generate in web/ and reading the graph back:
No entity nodes, no ADRs, no document-to-document edges: entity nodes come from the entities: frontmatter of hand-written docs, so a bundle of generated views alone produces a skeleton. The blog example's bundle is 21 nodes / 18 edges and exercises every node kind, which is why #454 ships that one.
What this needs
ADRs for guren.dev. The decisions are real and mostly already argued in code comments (Workers + D1, the cookie-less Analytics Engine middleware, prerendering docs into static modules at build time, the admin allowlist). The comments are a starting point, not a source: each ADR has to state the reason the decision was actually made.
Commit web/docs/spec/ and gate it.check --spec runs for examples/blog only (ci.yml). Publishing the site's spec views without a drift gate means the page whose whole claim is "checked" can serve a spec that no longer matches the code it describes.
Point the snapshot at the new bundle — bundleRoot in web/scripts/prerender-docs-viewer.ts — or publish both, one URL each, if the example is still worth showing as a teaching bundle.
Notes
The generator already refuses to publish a bundle with no nodes or edges, so a misresolved root fails the build rather than shipping a blank screen.
Follow-up to #454, which publishes a static docs-viewer snapshot at
guren.dev/_guren/docs. That snapshot is built fromexamples/blog, because the site itself has nothing to show:web/has nodocs/at all.The stronger claim is the site documenting itself. A visitor reading "your app's knowledge graph" on a page that is a Guren app should be able to open that app's own graph, not a sample's — and unlike the example, it keeps growing as the site does.
What the site's graph looks like today
Running
guren spec:generateinweb/and reading the graph back:No entity nodes, no ADRs, no document-to-document edges: entity nodes come from the
entities:frontmatter of hand-written docs, so a bundle of generated views alone produces a skeleton. The blog example's bundle is 21 nodes / 18 edges and exercises every node kind, which is why #454 ships that one.What this needs
web/docs/spec/and gate it.check --specruns forexamples/blogonly (ci.yml). Publishing the site's spec views without a drift gate means the page whose whole claim is "checked" can serve a spec that no longer matches the code it describes.bundleRootinweb/scripts/prerender-docs-viewer.ts— or publish both, one URL each, if the example is still worth showing as a teaching bundle.Notes
examples/blog/**is a deploy trigger as of feat(web): publish the docs viewer's graph at guren.dev/_guren/docs #454; if the published bundle moves toweb/, that trigger can go back to being about the example only.