docs: define template authoring architecture

[josephfarina]

Why

Astryx has a detailed template contribution guide and a versioned grading rubric, but no repository architecture record connecting template source, metadata, discovery, previews, and the CLI. The review loop has evidence for grading a template but no durable map of the shipped system or its compatibility boundary.

Cindy started that record in #5915. This recovers its architecture half instead of duplicating the existing guide or rubric.

What

• Records the source-specific discovery rules for built-in pages, blocks, external packages, and integrations.
• Documents the three shipped catalog projections: comprehensive discovery, Project.templates(), and init's built-in-page starter list.
• Separates the docsite's curated page-preview registry from CLI catalog membership.
• Records copying as a snapshot: later catalog changes never rewrite a consumer project.
• Keeps template-local behavior local unless an approved shared contract says otherwise.
• Treats rubric scores as exact-commit, exact-version evidence rather than approval.
• Aligns compatibility with accepted AST-017/DEC-2: slugs, metadata, and starter source are mutable catalog data; the surrounding CLI operation and response schema remain contractual.

Three corrections from #5915 are deliberate:

1. Template slugs are not frozen API after docs(spec): define breaking-change classification #5930 / AST-017.
2. The docsite registry is a curated subset, not a completeness gate for the CLI catalog.
3. The shipped system does not have one catalog path: template/search/layout use comprehensive discovery, Project.templates() re-collects integrations for project issue handling, and init uses a built-in-page-only starter list. The draft records that split and asks whether it should converge.

The record stays authority: draft. It does not change design:template-composition, the public wiki rubric, or package behavior.

Validation

• pnpm exec prettier --check docs/architecture/template-authoring.md
• pnpm check:knowledge
• 84 focused authoring/discovery/Project/init/template tests
• pnpm check:repo
• git diff --check

No Changeset: this is a draft knowledge record and publishes no package change.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 3, 2026 8:11pm UTC

[github-actions]

PR Analysis Report

Preview availability: Storybook and Sandbox were not published for this CI run.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | View full report}

[cixzhang]

Template authors currently face inconsistent visibility because docsite live previews are selected by a separate hand-maintained registry. Please make one validated template catalog the membership source, with each consumer using an explicit projection. CLI may expose all eligible pages and blocks; init may select scaffoldable pages; docsite may exclude entries through catalog metadata. A valid exclusion such as scaffold: true on blank must remain supported. What should not remain contractual is a separate manual list whose membership can drift: current main has 49 non-scaffold page templates eligible for the docsite metadata registry but only 41 live previews, missing nine pages. Revise INV2/INV3, system model, change coupling, verification, and OQ1/OQ3 so intentional differences come from declared metadata and manual registration is recorded as a migration gap rather than accepted architecture.

[cixzhang]

OQ4 should be answered alongside catalog convergence. Source-specific authoring shapes may remain different, and first-party TemplateDoc may stay richer than the integration envelope, but every template should cross one validated normalized-catalog boundary before any CLI, init, or docsite projection consumes it. At minimum that boundary should validate required identity/type metadata, source pairing, projection flags such as scaffold/overview visibility, and fields each projection relies on. Repository TypeScript checking may remain an additional first-party authoring check; it should not substitute for catalog validation, and missing/invalid source or membership metadata should not be silently defaulted or skipped. Please state whether built-in, external, and integration templates converge on this boundary and record any intentional source-specific differences explicitly.