Dotabase-Backed Documentation Publishing

Description

Dotabase-Backed Documentation Publishing turns versioned Markdown into the public Dots documentation corpus through a guarded four-stage workflow. A strict frontmatter contract validates page identity, doorway, DIIICE type, kind, summary, draft state, and authored edges. The pipeline ensures the Docs Dotabase schema, synchronizes repository pages one way into rows, derives reading time from body text, reconciles managed typed edges, and prunes rows whose source files disappeared.

Export reads only the Docs Dotabase and emits deterministic static artifacts for the browser and agents. Deployment runs validation, sync, and export before building the site. Nightly republishing computes a stable hash over authored page, envelope, and llms.txt artifacts; an unchanged hash succeeds without redeploying, while changed content proceeds through Railway deployment and a health check. This keeps repository authoring, stored rows, and public delivery connected without giving the static browser production credentials.

User Story

A documentation author adds a Markdown guide with validated frontmatter and links it to a prerequisite page. After merge, the scheduled workflow validates the entire corpus, upserts the new Docs row, calculates reading minutes, creates the canonical graph edge, exports all static artifacts, and compares the content hash. Because the authored output changed, the site redeploys and passes health checks; an unrelated later merge produces a successful no-op.

Extension Surface

This feature is automatable, not pluggable. apps/docs/package.json exposes separate validation, ensure, sync, export, and hash commands for CI or an operator, and .github/workflows/docs-republish.yml drives the full refresh. The frontmatter vocabulary and committed normalizer are configurable authoring contracts, but there is no external provider interface for replacing storage, synchronization, or export stages. Custom pipeline stages require repository changes.

Capabilities & Limits

• Validates corpus-wide uniqueness and edge targets before writing, then synchronizes rows, derived reading time, and managed edges.
• Exports byte-stable page artifacts, agent envelopes, corpus data, counts, metadata, and llms.txt.
• Prunes orphaned Docs rows while scoping edge reconciliation to the pipeline’s managed edge types.
• Limit: synchronization is intentionally one-way; editing a Docs row does not write changes back to repository Markdown.
• Limit: a code-only docs-site fix does not change the authored-content hash and needs an explicit deploy workflow rather than the nightly content gate.

Implementation Map

• apps/docs/pipeline/frontmatter.ts
• apps/docs/pipeline/content.ts
• apps/docs/pipeline/sync.ts
• apps/docs/pipeline/export.ts
• apps/docs/scripts/content-hash.ts
• .github/workflows/docs-republish.yml

Related Features

- Implements the delivery substrate for Public Documentation Portal and Agent-Readable Documentation Exports. - Requires the platform’s Markdown import, Dotabase rows, and knowledge-graph edge services. - Complements Product Changelog and Contextual Documentation Glossary, whose entries are specialized Docs rows flowing through the same pipeline.