docs: rebuild the site, snippet gallery, and registry on the 0.9 API (#93)
## Summary
Rebuild the documentation on the 0.9 API. Every page describes the
shipped modules, every code
sample is a slice of a file that compiles in CI, the component catalog
runs the real lifecycle in
the browser, and the shadcn registry names the operations and statuses
it renders.
The site described a surface that no longer exists —
`Provisioning.create`, `Digest`,
`InMemoryDnsProvider`, a Promise entry point, records with a `metadata`
block — so nothing on it
compiled.
## Snippets come from compiled files
```mdx
<Snippet file="examples/core/plans.ts" region="apply" />
<ReactExample story="domain-flow" />
```
| Tree | Gated by |
| ----------------------------- |
------------------------------------------- |
| `examples/` | root `typecheck:examples` (new) |
| `packages/domainkit/examples` | `domainkit release:check` (already) |
`components/snippets.ts` reads only those two, so a rename in the
packages fails CI instead of the
reader. `components/react-examples.ts`, the table of hand-typed source
strings, is gone.
## Pages
| Section | Pages |
| ---------- |
--------------------------------------------------------------------------------
|
| Concepts | plans, connections, verification, cleanup, failure reasons,
Domain Connect |
| Build | host integration, persistence, write a provider, testing,
troubleshooting |
| React | overview, controllers, composition, presentation, transport,
registry |
| Reference | entry points, `domainkit`, `/server`, `/client`,
`/testing`, react, capsuledb, provider contract |
| Also | quickstart, glossary, nine catalog pages with live previews |
Deleted with their surfaces: `reference/promise`,
`react/integration-levels`,
`guides/provision-and-clean-up`, `guides/observe-dns`, and the two 0.8
host-composition catalog
pages.
The entry-points page also covers the per-namespace subpaths #95 added,
and says when to reach for
one: a package that emits declarations needs a module path TypeScript
can name
(`import("domainkit/Principal").Service`), and a narrow import is the
other case. Root namespace
imports stay the documented default and are what every example here
uses.
## Landing page
Rewritten from the approved copy: the problem first, then the lifecycle
as four calls, the four
mechanisms behind it, the route group, and the React flow. Its code
blocks are the same example
regions, read through `snippet()` in the Astro frontmatter, so the page
cannot drift from the docs
either. Caption and code sit in two columns that collapse under 48rem.
## Catalog previews run the lifecycle
The preview island is rebuilt on the 0.9 React API over
`Testing.transport()`, which mounts
`domainkit/server` over memory storage and a fake provider in the tab.
Clicking Connect, reviewing
the plan, approving, and observing all behave the way they do against a
host.
## Registry vocabulary
```tsx
<DnsOperation operation="create" name="app.example.com" type="CNAME" value="edge.acme.dev" />
<DnsStatus status="satisfied" />
```
`operation` is one of `create | noop | conflict | delete`, `status` one
of
`satisfied | missing | mismatch | unknown`, each picking its own label
and tone from an exported
record the copier can edit. `DnsTableRecord` gains `purpose`. The items
still import no DomainKit
runtime.
## ADRs
The two root records described the old API. Their principles are now
`0009-authorization-connection-attachment.md` and
`0010-credential-scoped-provider-sessions.md` in
the package ADR set, and `docs/adr/` is deleted.
## CI
A second job beside `validate`, so package release checks stay fast:
```text
typecheck:examples -> reference:check -> docs typecheck -> docs build
-> registry:validate -> registry:check
-> blume validate --strict -> blume audit --strict
```
`registry:check` installs every registry item into a scratch shadcn
project and compiles it, so an
item that builds but does not install cannot reach the published
registry.
`audit --strict` fails on warnings, which is why every page now carries
a 110-160 character
description, a rendered title of at most 60 columns, and a link from
another page's body.
`apps/docs/AGENTS.md` records that.
## Screenshots
| Landing, desktop | Landing, mobile |
| --- | --- |
| 
| 
|
| Docs overview | Component catalog |
| --- | --- |
|

| 
|
| Concept page | Glossary |
| --- | --- |
|

|

|
## Validation
- `bun run release:check` (root, React leg included)
- `bun run typecheck:examples`
- `bun run --filter @domainkit/docs reference:check`
- `bun run --filter @domainkit/docs typecheck`
- `bun run --filter @domainkit/docs build` (55 pages)
- `blume validate --strict` (no broken links)
- `blume audit --strict` (3,724 audits, 0 errors, 0 warnings)
- `bun run --filter @domainkit/docs registry:validate` and
`registry:check` (`shadcn add`, `tsc`, `vite build` in a scratch
project)
## Known tradeoffs
`Testing.provider` registers its zones in one process-wide table that
`Testing.resolver` reads, so
two fakes for the same zone name in one process share public DNS
answers. That is documented as a
caution on the testing pages rather than worked around here. S
Saatvik Arya committed
af128b005263a06904eb295bc6d5810abd7c7d3a
Parent: 10b8a34
Committed by GitHub <noreply@github.com>
on 9/3/2026, 8:33:06 PM