Documentation deployment handbook

This handbook covers the documentation site only. Publishing it does not deploy the API or change existing customer products.

1. Validate the canonical contract and example requests. Record a new immutable release version whenever public contract bytes change; never replace an existing version's YAML, JSON or manifest.
2. Verify the complete retained release registry against the last published source commit. Run the docs tests and production build. Confirm the proposed banner, disabled request execution/authentication persistence, local fonts, and placeholder API origin remain intact.
3. Commit the source and attest the build against that exact clean commit. Deploy an archive of that commit to the dedicated docs project. Do not upload credential files or unrelated application state.
4. Verify the preview's homepage and extensionless deep links return HTTP 200. Test desktop and mobile, inspect page errors and network requests, and compare published YAML/JSON hashes against the retained release manifest.
5. Promote only the verified release. Recheck the custom domain, certificate/SAN, security headers, deep links, mobile rendering, and artifact hashes. Keep the prior deployment identifier for rollback.

The docs host serves extensionless paths with clean URLs. The explorer must not contact model providers, customer endpoints, analytics, remote fonts, or the placeholder API. A failed deep link or unexpected network request blocks promotion even when the build exits successfully.

Rollback restores the prior verified docs deployment; immutable versioned downloads must remain available. It does not authorize API rollback, database changes, DNS changes on unrelated names, or changes to existing products.

Automatic documentation releases

The dedicated Vercel project mystro-docs is connected to chris247474/Verch-AI, with apps/docs as its root directory and main as its production branch. Pull requests receive Vercel previews; merging to main automatically builds and publishes the documentation to https://docs.mystro.me. This connection deploys only the docs application.

Before merging, require the existing GitHub CI checks, the Platform docs artifact workflow, and the docs Vercel preview to pass. Verify the preview using the checks above and compare its Git commit with the PR head. The artifact workflow retains a clean, exact-SHA build manifest and the immutable contract registry. After the main deployment finishes, verify its Git commit matches the merge commit and repeat the custom-domain checks. Retain the previous production deployment ID for rollback. Manual releases continue to use the clean-commit archive and verified promotion process above.