feat: automated versioning and docs site sync

[ethnjs]

Summary

Adds automated versioning with release-please, makes the API report the released version, and builds the seam that pushes our docs content to docs.ethanshih.com on release.

Versioning is SemVer with a flat -beta suffix during the pilot year (v1.0.0-beta → v1.1.0-beta on a feat), not an incrementing beta.N. The first release is pinned to v1.0.0-beta.

What changed

Backend

Schemas and routes

• Swagger (/docs) and Scalar (/reference) are served only when APP_ENV is development or preview. Production serves just /openapi.json, which the docs site renders.
• CORS allows https://docs.ethanshih.com so the docs site's API reference can read the spec.

Logic

• main.py reads backend/VERSION instead of hardcoding 0.2.0, so the OpenAPI spec reports the released version.
• The file lives in backend/ so a backend-only deploy ships it, and falls back to 0.0.0-unknown rather than failing startup if it's missing.

Release automation

• release-please-config.json / .release-please-manifest.json — simple release type at the repo root, so backend-only commits still trigger releases. version-file writes backend/VERSION; an extra-files JSON updater writes frontend/package.json.
• skip-changelog: true — no CHANGELOG.md is committed. The GitHub release keeps release-please's generated commit list as the dev-facing changelog.
• release-as: "1.0.0-beta" — one-time pin for the first release. Remove it after that release ships, or every later release stays pinned.
• .github/workflows/release-please.yml opens the release PR on pushes to main.
• A dispatch-docs job fires a repository_dispatch to ethnjs/docs when a release publishes, with { repo, tag, version }. It's a second job in the same workflow because releases created with GITHUB_TOKEN don't trigger separate workflows. It uses the DOCS_SITE_DISPATCH_TOKEN PAT and requests no repo permissions of its own.
• docs/ now holds synced content (getting-started.mdx) and is no longer gitignored.
• CONTRIBUTING.md documents Conventional Commits with a type-to-version-bump table, the versioning scheme, "Cutting a release", and the docs content rules.
• .github/RELEASE_NOTES_TEMPLATE.mdx is the starting point for the per-release user-facing page in docs/release-notes/.

Out of scope

• The receiving side in ethnjs/docs — sync workflow, sidebar config, release notes landing page.
• Generating release notes MDX. Those stay hand-written per release, by design.

Test plan

• pytest passes locally — not run; no test touches the changed routes.

Automated

• None. No test covers app startup under a given APP_ENV.

Manual

• Imported the app under APP_ENV of development, preview, production, and test — dev and preview serve /docs, /reference, and /openapi.json; production and test serve only /openapi.json.
• Confirmed main.py resolves backend/VERSION and reads 0.1.0.
• Parsed release-please-config.json, .release-please-manifest.json, and the workflow YAML.
• Read release-please's source to confirm the default strategy carries a -beta suffix forward while still bumping the core version, and that the prerelease strategy would instead produce beta.N.

Not testable until this is on main — both read config from the default branch:

• release-please opening a release PR.
• The dispatch to ethnjs/docs.

[vercel]

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

Project	Deployment	Actions	Updated
nexus	Ready	Preview	Sep 12, 2026 8:17am UTC

[railway-app]

🚅 Deployed to the nexus-pr-76 environment in nexus

Service	Status	Web	Updated
nexus	✅ Success (View Logs)		Sep 12, 2026 at 8:17 am UTC