Docs automation

Keep Taskcenter documentation generated from real project surfaces

Overview

Docs automation turns project files into documentation pages that the docs shell, search index, and docs assistant can read. It is a build-time feature: it scans source files, generates a typed manifest, and keeps generated pages separate from authored product docs.

Entry route

/docs/introduction/docs-automation.

Status

Live as a local build-time generator.

Data source

docs/source/*.md, src/features/**, src/app/api/**/route.ts, src/app/**/page.tsx, .agents/skills/**/SKILL.md, skills/**/SKILL.md, and src/lib/permissions.ts.

Required permissions

none at runtime because generation is local and read-only; authenticated access is still required for the docs assistant route, and North Star's docs tools require `search:read` at agent-tool admission.

Empty state

if no generated sources are present, the authored docs still render.

Failure state

the generator exits with a clear error and leaves the previous generated manifest untouched.

Operating model

The generator creates pages from authored Markdown sources and from project inventory scans. Generated pages are merged into the existing docs registry instead of replacing manually curated pages. That keeps the current shadcn-style shell while reducing the maintenance burden.

Agent-facing behavior

Generated docs become part of the docs assistant context through the same read-only documentation registry as authored pages. The docs assistant remains docs-only: it can summarize generated documentation, but it cannot mutate records, run tools, deploy, or inspect private workspace data. North Star can also inspect this registry through the read-only `searchDocs` and `readDocs` runtime tools. In the deployed Agent Worker, those tools call the web Worker's bounded `/api/docs/retrieval` child-effect route through `WORKER_SELF_REFERENCE`; the docs corpus and unrelated agent-tool modules are not materialized inside the conversational Durable Object. A turn may search once, read a bounded page chunk, and then must author the answer from that evidence. Search returns at most five results, reads return at most 8,000 content characters, responses are capped at 12,000 bytes, and the combined per-turn retrieval budget is 18,000 bytes. Pagination uses the returned `nextCursor` when another chunk is essential. The route reads only the same public Taskcenter product-doc registry; it does not expose private workspace records. The registry includes a searchable contract view of `docs/plans/MASTER-PLAN.md` at `features/north-star-runtime-contract`; an exact `readDocs` request for the Master Plan path resolves to that bounded page. It identifies `TaskcenterChatAgent` as the canonical conversational owner and names the `admit`, `compile`, `run`, `checkpoint`, and `verify` loop states without treating the product-doc mirror as production-acceptance evidence. Source intent is also respected at admission: a request for public web research, including a correction phrased as “not internal docs,” selects the research policy and requires `webSearch` provenance instead of being captured by the internal-doc route. If the Worker self-reference is missing, a response exceeds its cap, or the per-turn budget is exhausted, the tools return a specific unavailable/budget blocker rather than loading the corpus in the Durable Object or claiming an answer was retrieved. Successful evidence must be synthesized into a substantive answer that names the source page; search narration is progress, not a completed answer.

Completion rule

Feature work should update either an authored docs source file or enough real project surface for the generator to discover it. A generated inventory page is evidence of what exists, not a substitute for a complete feature-specific docs page when behavior, permissions, or data contracts change. Run pnpm docs:generate after changing a source page, route inventory, feature block, permission, or skill catalog. The feature-safety gate runs pnpm docs:check and fails when the committed typed manifest differs from the generator output. Developer guides for the HTTP API, remote MCP endpoint, and access model live under docs/source so their public status cannot be silently replaced by a stale hand-authored catalog entry.