Documentation

This repo keeps product and developer docs under docs/ as plain Markdown.

There is no separate Docusaurus authoring workflow in this repo anymore. Edit the Markdown files directly.

Docs layout

docs/
├── intro.md
├── concepts/
├── how-to/
└── for-developers/

Main rules

• Use plain Markdown only.
• Do not add MDX, JSX, or import statements.
• Use relative links between docs pages.
• Keep pages short and specific.
• Prefer a direct, colleague-to-colleague tone.

What to write

Concept pages

• what the thing is
• why it matters
• the minimum example a reader needs

How-to pages

• what the task is
• prerequisites
• numbered steps
• expected result

Developer pages

• what file or system owns the behavior
• the commands people actually run
• the parts that usually trip people up

Writing style

• Lead with the answer.
• Cut filler.
• Prefer short sections over long tutorials.
• Keep examples real and close to the repo.
• If a section explains a tool we no longer use, remove it.

Links and images

Use relative links for nearby pages:

[System infrastructure](./system-infra.md)

Use standard Markdown images:

![Alt text](../assets/example.png)

For notes and warnings, use blockquotes:

!!! note
    Keep this in sync with `Dockerfile.prod`.

!!! warning
    Do not document commands you have not verified.

Before you commit docs changes

• Check that commands still exist in the repo.
• Check that file paths still exist.
• Check that internal links still point to the right page.
• Remove stale references instead of explaining outdated workflows.

Common sources of truth

• package.json for scripts
• Taskfile.yml for task aliases
• Dockerfile.prod for production build behavior
• docker-compose.prod.yml and docker-compose.staging.yml for service wiring
• prisma/schema/ for database structure

When docs need an update

Update docs when you change:

• build or deploy commands
• environment variables
• storage or email providers
• database migration flow
• file paths that docs point at