Documentation publication

The documentation site is generated with pinned mdBook 0.5.4 from canonical tracked product Markdown. It includes README, quickstart, installation, tutorial, recipes, command/contract references, architecture, business/design/research docs, the complete canonical ADR index and ADR pages, and changelog. Browser-side full-text search covers the generated chapters. No manual duplicate ADR index is maintained.

Internal session handoffs and authoring templates are excluded from public publication. Only tracked regular product files, branding assets and explicitly sanitized decision evaluation artifacts enter the book; untracked notes, environment files, private keys, database files and model weights are never copied. Publication records the exact source commit and source file hashes in publication.json.

Editorial standard

Follow the Febasi writing rule. Maintain English copy in README, product statements, ADRs, design pages and the site title. Do not use em dashes in authored prose. The canonical positioning is:

Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

Review the rendered homepage and affected chapters as well as source Markdown. The publisher preserves tracked source text; it does not translate or normalize legacy chapters automatically. Editorial changes must preserve historical decision status, code examples, identifiers and link targets.

Mermaid diagrams

The generated book uses official mdbook-mermaid 0.17.1, compatible with mdBook 0.5. The Pages workflow verifies both official release archive SHA-256 values before unpacking either executable. The standard mdbook-mermaid install command copies its bundled Mermaid runtime and initializer into the generated book. mdBook publishes both as local scripts, including on nested ADR pages. There is no runtime CDN dependency and no change to canonical Markdown fences. Upstream license banners remain in the bundled assets.

The publication verifier checks each chapter’s fenced diagram count against its HTML containers, rejects raw Mermaid code blocks, and requires the pinned local runtime and initializer in that order. Missing, changed, remote or escaping script references fail publication. These checks prove generated structure and asset identity. They do not execute JavaScript or prove SVG rendering, typography or layout. Browser acceptance must separately inspect diagrams, console errors, light/dark themes and nested-page navigation before closing SYN-342 (#347). See ADR-072.

Local validation

Install the same pinned official tools used by .github/workflows/pages.yml without compiling them, then run the full documentation publication suite:

python3 scripts/check-docsite.py -v
python3 scripts/check-docsite-independent-tests.py -v

For a persistent preview:

python3 scripts/prepare-docsite.py --output /tmp/synapse-docsite
mdbook-mermaid install /tmp/synapse-docsite
mdbook build /tmp/synapse-docsite
python3 scripts/verify-docsite.py /tmp/synapse-docsite
python3 -m http.server 8080 --bind 127.0.0.1 --directory /tmp/synapse-docsite/html

Use an absent dedicated output directory; regeneration never deletes an arbitrary folder. The verifier checks all generated chapter paths, tracked asset coverage, search contents, canonical ADR coverage and absence of private/runtime artifacts. It rejects em dashes in rendered chapter/navigation text, accessible labels and maintained SVG text. Tracked documentation SVGs are published with the book. Browser verification additionally checks actual search results and navigation. GitHub pull requests build and validate an artifact; merged main deploys through GitHub Pages with separate minimal deployment permissions. Both official tool archives are pinned by version and SHA-256 in the workflow.

The independent publication review preserves the original eight-mutant campaign and its three survivors. The added tests independently derive complete chapter coverage from tracked canonical sources and invoke the actual verifier CLI on broken non-release diagram pages. Pages requires both suites, 14 original methods plus three independent methods. Changes to either suite also select the documentation workflow. Final workflow wiring and browser acceptance remain distinct from the original frozen review.

Domain rollout

The initial Pages URL is https://romulofebasi.github.io/synapse/. The requested canonical URL is https://synapse.febasi.com.br/. The repository uses Pages workflow deployment; its Git repository remains private.

The authoritative DNS provider is Cloudflare. To finish the custom-domain acceptance of SYN-109, an authorized operator must provide access to the zone or create this new record:

Verify the exact domain through GitHub’s ownership/domain validation, configure the Pages custom domain after DNS resolves, wait for its certificate and enable HTTPS. The book’s site-url must be / for the custom domain (initial project-site prefix is /synapse/). Validate the final URL, HTTPS certificate, redirects, chapter links and browser search before marking #89 complete. Do not point a DNS record at a disabled/unowned Pages site.

The source publication and default Pages URL can be delivered while zone access is unavailable; that does not satisfy the requested custom-domain acceptance. No credentials belong in this document or generated artifact.

Primary references: mdBook installation, GitHub Pages custom domains.

Mermaid references: official mdbook-mermaid v0.17.1, mdBook local JavaScript configuration.