docs: publish complete desktop Help corpus preview

.gitignore

@@ -2,6 +2,9 @@ node_modules/
 dist/
 .astro/
 .tmp/
+.generated/
+.playwright-cli/
+src/generated/scient-docs/
 .wrangler/
 .DS_Store
 *.log

AGENTS.md

@@ -15,8 +15,9 @@ must render an approved exact source/version instead of maintaining a second
 copy. Website Docs work owns rendering, navigation, search, accessibility,
 deployment, and truthful version/source selection. A change to app behavior or
 source prose uses a separate desktop pull request with explicit landing order.
-Do not invent the final source transport before the publishing pilot selects
-and proves it.
+Use the exact-source manifest transport recorded in
+`docs/architecture/scient-docs-publishing.md`; replace it only through a
+reviewed architecture change with concrete evidence.
 
 Every pull request includes one `Documentation impact` declaration: `None —
 reason`, `Updated — paths`, or `Dependent PR — repository and link`. For Docs

README.md

@@ -50,6 +50,16 @@ Do not deploy production from a feature branch or store Cloudflare credentials i
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow. The cross-repository operating model is maintained in [`ScientFactory/Scient`](https://github.com/ScientFactory/Scient).
 
+## Scient Docs publishing
+
+The public `/docs` experience is generated from reviewed Markdown in
+`scient-desktop/docs/user/` at an exact commit. The source manifest, hashes,
+preview/stable qualification, correction path, and rollback contract live in
+[`docs/scient-docs-manifest.json`](docs/scient-docs-manifest.json) and
+[`docs/architecture/scient-docs-publishing.md`](docs/architecture/scient-docs-publishing.md).
+Generated website files are intentionally ignored; `bun run docs:sync` rebuilds
+them and fails closed if source content no longer matches the reviewed hashes.
+
 ## First-party event measurement
 
 Cloudflare D1 stores four website event types:

docs/architecture/scient-docs-publishing.md

@@ -0,0 +1,91 @@
+# Scient Docs Publishing Architecture
+
+Status: Active
+Owner: Yaacov
+Created: 2026-08-28
+Last updated: 2026-08-28
+Purpose: Defines the website-owned transport, provenance, failure, correction, and rollback contract for publishing canonical Scient Desktop Help.
+Doc type: Architecture decision
+
+## Authority
+
+`scient-desktop/docs/user/` owns Help prose. The website owns selection,
+transport, rendering, navigation, search, accessibility, source/version
+display, and deployment. `docs/scient-docs-manifest.json` is the reviewed
+publication selection; it is not a second prose source. `scient-agent` is
+outside this publishing pass.
+
+## Selected Transport
+
+The website build reads a committed manifest that pins:
+
+- a full immutable `ScientFactory/scient-desktop` commit;
+- every selected `docs/user/` source path;
+- a SHA-256 digest for each source page;
+- stable or preview channel and truthful applicability wording; and
+- corpus defaults plus page-level topic, title, summary, navigation priority,
+  and surface metadata.
+
+CI and ordinary builds fetch each page from GitHub's immutable raw-commit URL.
+Local development may set `SCIENT_DOCS_SOURCE_ROOT` to an exact checkout at the
+same commit; the generator rejects a different head, and page hashes still
+apply. Generated files are ignored build products. The website never commits a
+hand-maintained prose copy.
+
+This transport was selected in the pilot and retained for the complete
+desktop-first corpus because it remains small, independently deployable, exact,
+auditable, and reversible without introducing a package registry or release
+artifact before one is justified. Re-evaluate it if corpus size, availability,
+rate limits, private sources, or release engineering make raw-commit transport
+materially unreliable.
+
+## Build And Safety Contract
+
+`scripts/sync-scient-docs.mjs` validates the manifest, fetches exact content,
+checks every digest and H1, rejects executable/unsafe raw Markdown patterns,
+rewrites selected relative Help links to stable public routes, and sends
+unselected relative Help links to the exact GitHub source. It generates:
+
+- Astro Markdown pages under stable `/docs/<slug>/` routes;
+- exact raw Markdown under `/docs/raw/<slug>.md`;
+- `/docs/index.json` with title, summary, topic, channel, applicability, page
+  URL, raw URL, source path/revision/URL, and search text; and
+- the metadata used by client-side topic/text search, navigation, and the
+  compact source footer.
+
+Missing content, a changed hash, unsafe content, a mutable/non-full revision,
+duplicate routing, an unqualified stable manifest, or a wrong local checkout
+fails the build. There is no stale cache fallback that could silently publish
+the wrong content. The previously deployed website remains live while CI or a
+preview exposes the failure.
+
+## Preview, Stable, And Corrections
+
+A preview manifest may pin an exact documentation or application PR head. The
+website labels every page as preview, shows what it applies to, and links to the
+exact source. It must not be presented as stable released behavior.
+
+A stable manifest must name at least one reviewed desktop release tag and pin
+the exact Help revision that truthfully describes it. A release triggers a
+reviewed website manifest PR; publication should complete within 24 hours. A
+Help-only correction uses a desktop documentation PR followed by a dependent
+website manifest PR and deployment, without requiring a new app binary. Its
+applicability text continues to name the releases the corrected prose
+describes.
+
+Rollback reverts the manifest pin or website publishing change. It never
+rewrites canonical desktop Help. A reverted or failed deployment leaves the
+last successful public corpus in place and visible through ordinary website
+deployment history.
+
+## Current corpus and deferred scope
+
+The preview manifest selects all 31 desktop-first Help pages qualified at the
+exact desktop source revision. It deliberately excludes the retained mobile
+page because Scient has no public mobile release. Directory membership still
+does not imply publication, and future Help owners require factual
+qualification before entering the manifest.
+
+Stable release publication, a documentation MCP, and any larger metadata
+schema remain separate decisions. Evaluate MCP only after stable HTML, raw
+Markdown, the index, and search reveal a concrete agent-retrieval gap.