# Consume and contribute documentation

Export verified Markdown/JSON and publish the versioned docsp portal.

Status: headless content pipeline supplied in **0.7.0**. The first
consumer is dotnet-foundation itself. The future ERP app SDK will reuse this
contract after its contribution/visibility policy is defined.

## Content sources

docs/documentation.json explicitly declares pages, package projects and examples.
Markdown holds authored explanations. Stable page IDs produce versioned routes;
doc:page-id links are validated and rewritten. Example tokens insert reviewed
source fixtures rather than maintaining a second copy of executable code.

Public API symbols come from compiled metadata through Roslyn. The exporter does
not execute target assemblies. XML summaries come from compiler XML or source
comments matched by compiler documentation ID, without expanding filesystem
includes; missing summaries are counted in catalog.json. API generation cannot
replace authored tutorials or invent explanations for undocumented members.

## Generate a bundle

Build Release, then run from the checkout root:

```text
dotnet run --project tools/Fabricators.Documentation.Tool -c Release --no-build -- . docs/documentation.json artifacts/documentation/0.19.0
```

The destination must be new. The exporter validates all content first, writes a
staging directory, then publishes the complete directory with a rename. It never
overwrites an existing destination. The same command works on Windows, Linux and
macOS with the pinned .NET SDK.

## Frontend contract

| Artifact | Purpose |
| --- | --- |
| catalog.json | Schema version, product/version/channel/locale, ordered groups, page metadata, routes, source paths, hashes and heading anchors |
| pages/*.md | Versioned content with resolved documentation links and source examples |
| api.json | Stable compiler documentation IDs, kinds, signatures, summaries, parameter descriptions and return descriptions |
| search.json | Title, summary, keywords and page text tied to canonical routes |
| examples.json | Source code, language, verification label, provenance and hash |
| manifest.schema.json | Machine-readable input contract for authoring tooling |
| catalog/api/search/examples.schema.json | Machine-readable output contracts for renderer/client tooling |
| llms.txt | Compact discovery index for developer agents |

Treat the catalog's anchors as authoritative. The renderer must produce these
exact IDs, including duplicate-heading suffixes. Use the page route for navigation
and Content for the corresponding artifact fetch. The hash covers normalized UTF-8
Markdown without a BOM. Search and API references share the bundle version.

## Rendering and trust

No UI, HTML site, CSS or JavaScript is generated. The frontend owns layout, code
highlighting, responsive navigation, accessible search and visual quality. Disable
raw HTML/active Markdown and sanitize rendered output and URLs; Markdown is data,
not executable MDX. Do not infer safe rendering from content validation alone.

All current content is reviewed developer documentation. This static public bundle
is not a tenant authorization system. A future restricted ERP documentation endpoint
must filter pages, navigation, search, API metadata and agent indexes server-side,
and partition caches by authority. Hiding a sidebar entry is insufficient.

## Editorial structure

Cloudflare is the primary information-architecture reference, together with Stripe
and rfw: entry points by goal, separate tutorials/concepts/how-to/reference, clear
prerequisites, examples, configuration, limitations, troubleshooting and next steps.
Plain Markdown is the initial portable format. Rich tabs, callouts and interactive
API explorers require a later versioned renderer contract, not arbitrary components
embedded by third-party authors.

## Extension boundaries

OpenAPI already comes from the host's Swashbuckle integration. Importing OpenAPI,
generating SDK-language variants, restricted ERP app composition and replacing the
developer MCP's embedded catalog are tracked next steps, not implemented exports.

## Public portal publication

The public documentation is published with docsp at
[docs.fabricators.dev](https://docs.fabricators.dev/foundation/guides/overview/).
Authored Markdown remains in this repository; the versioned export supplies the
same guides and compiler-derived API reference to the shared portal.

A release is not documentation-complete until the corresponding docsp project
has been imported, checked, built and deployed. Initially this is a manual
Wrangler deployment from the docs-portal repository; CI automation is a separate
follow-up. Preserve previous documentation versions and other portal projects.
Never publish private runtime configuration, tokens or generated logs.

The consumer integration and deployment commands are documented in
`docs-portal/portals/fabricators/README.md`. Generated content is verified against
its catalog SHA-256 values before import. Keep the original catalog/API JSON
available as versioned downloads for tooling clients.
