Pages / Docs
Freeform markdown documentation pages stored in a registry.
A page (handoff_page) is a freeform markdown document, foundation overrides, guidelines,
custom write-ups, distinct from every other structured entity in this pillar. It's pushed
wholesale from a workspace's pages/**/*.md and can also be created or edited directly by a
stakeholder or an agent once the registry exists.
Not the same as the MCP 'Pages & Compositions' tools
MCP's tool catalog has a category literally named Pages & Compositions
(handoff_list_pages, handoff_get_page, handoff_create_page, handoff_update_page), those
tools operate on patterns (saved component compositions from the Playground), not this
entity. The markdown pages on this page are reached through MCP's separate Documentation
tool family instead (below). See Concepts → Patterns
for the other side of this naming collision.
Shape
handoff_page is keyed by slug (the path under pages/, e.g. getting-started/install) and
holds type (markdown today; mdx/html/plugin reserved for future page-rendering stages
per ADR-001 §7, see Registry → Model), frontmatter (jsonb), markdown
(the body), and assets (jsonb, for any per-page asset bundle, unused while type stays
markdown). handoff_page_change is the parallel append-only audit table: one row per
create/update/delete push, recording the action, title before/after, markdown-length before/after,
and the same human-message + lazy-AI-summary "why" pattern used elsewhere, see
Changelog / audit.
Three surfaces
| Surface | Where |
|---|---|
| UI | Rendered under the registry's catch-all page routes (/[...slug]) and, for foundation-specific overrides, under /foundations/[...slug] — falls back to handoff-app's own bundled default markdown when a workspace hasn't pushed an override. Managed (create/edit/organize) at /admin/pages, see Registry → Stakeholder-facing UI routes. |
| REST | Session-authenticated CRUD: GET/POST/DELETE /api/handoff/pages (GET ?slug= for one full page, otherwise all summaries; POST upserts by slug), see API → /api/handoff. Workspace push/read: POST /api/registry/pages (all markdown + frontmatter, from push:all), GET /api/registry/pages (public, every page as a summary list — it takes no query params), see API → /api/registry. |
| MCP | The Documentation tool family: handoff_list_doc_pages, handoff_get_doc_page, handoff_create_doc_page (sync:write), handoff_update_doc_page (sync:write), handoff_delete_doc_page (sync:write), handoff_move_doc_page (sync:write, renames a slug while preserving content/history), see MCP → Tool catalog § Documentation. More agent-authoring-oriented than the REST CRUD above: these are the tools an agent uses to write documentation directly into a registry. |