File & Document Naming

Documentation pages

New Astro content pages use kebab-case.mdx (e.g. environment-and-secrets.mdx) and live under docs/src/content/docs/<section>/. Substantive, durable documentation belongs in this central docs/ Astro site, not as loose .md files scattered across apps/* or packages/*.

Note

The MX Fuels migration, identity, and PostgreSQL operation guides are now consolidated into the Astro pages under /apps/mx-fuels-reporting-app/. Remaining loose files in that app directory are feature notes or design records, not the source of truth for deployment or identity guidance.

One-off planning docs

For ad hoc planning documents (feature kickoffs, bugfix write-ups, doc-update proposals), use the existing kickoff templates rather than inventing a new naming scheme:

• templates/docs/development/feature.md
• templates/docs/development/bugfix.md
• templates/docs/development/documentation_update.md

Avoid names like FIX_SUMMARY.md, NEXT_STEPS.md, or MIGRATION_STATUS.md scattered in app directories going forward — prefer the templates above, and once work lands, fold durable content into the Astro site and let the planning doc be discarded or archived.

This matters more than it looks. A delivery summary kept as reference documentation describes a past work session, not the system, and it goes stale the moment the next change lands. Two such files under docs/ai-experts/ sat in the repo contradicting each other for months — one announcing a removal the other still instructed readers to perform. Delete them once the work lands.

Package naming & versioning

Shared packages (packages/utils, packages/vcl, packages/db) follow semantic versioning (MAJOR.MINOR.PATCH) in their own pyproject.toml:

• MAJOR — breaking API changes
• MINOR — new features, backward-compatible
• PATCH — bug fixes, backward-compatible

Read the current version from each package’s pyproject.toml. Do not copy a version number into a page — it goes stale on the next release, and CI rejects a pinned wheel filename in documentation. See Pull Requests for the release/tag workflow when bumping a version.

Documentation is checked in CI

The Docs check workflow runs on any PR touching docs/, and fails on:

• an internal link to a page that does not exist
• a backticked repo path that does not exist on disk
• a hardcoded shared-package version in a wheel filename (write the version component as <version> instead)

Run it locally before pushing:

cd docs
pnpm check     # references only, no install needed
pnpm build     # full site build

If a path is intentionally absent — a build artifact, or a file generated by a pipeline stage — add it to ALLOWLIST in docs/scripts/check-docs-links.mjs with a one-line reason. Keep that list short: each entry is a check that no longer runs.