Guidelines

Documentation

Edit MDX under ragnarock-docs/content/docs/.
Update the folder meta.json when adding or renaming pages.
Use the MDX components reference (Callout, Steps, Tabs, EnvVarTable, Mermaid, etc.).
Prefer real routes (/dashboard/projects/...) and accurate env var names.
Run pnpm types:check and pnpm build before opening a PR.
CI also runs pnpm docs:scan:strict — ensure sibling repos are present locally when validating coverage.

Writing style

Task-oriented headings ("Create a project", not "Project creation overview")
Short paragraphs; tables for comparisons
Call out destructive actions with <Callout type="warn">

Code examples

Use fenced blocks with language tags: ts, tsx, bash, json, yaml, sql, prisma
Add a title="path/to/file" attribute when showing file-specific snippets
Use <Tabs> when the same task differs by package manager or runtime

Code

Frontend: ragnarock — pnpm, feature-first layouts
Backend: ragnarock-backend — Bun, NestJS, Prisma migrations required for schema changes
Agent: ragnarock-agent — Python, keep processors aligned with API queue contract

Commits

Use clear messages focused on why the change exists. Do not commit .env files or secrets.

Future automation (pnpm docs:scan) compares the codebase to documentation coverage — keep pages updated when routes or APIs change.

CI

Pull requests run GitHub Actions (when configured):

Job	Command
Typecheck & build	`pnpm types:check`, `pnpm build`
Documentation coverage	`pnpm docs:scan:strict`

The coverage job checks out the frontend, backend, and agent repositories alongside this repo. Override repo names with GitHub repository variables: DOCS_FRONTEND_REPO, DOCS_BACKEND_REPO, DOCS_AGENT_REPO.

Repository scan

Run from ragnarock-docs:

pnpm docs:scan

This writes:

Output	Purpose
`content/_generated/docs-map.json`	Routes, controllers, Prisma models, agents
`content/_generated/coverage-report.json`	Mapped features vs existing doc pages

Optional flags:

pnpm docs:scan --write-stubs   # draft MDX stubs for missing coverage
pnpm docs:scan:strict          # CI: require repos + fail on coverage gaps
pnpm docs:scan --strict        # exit 1 if any mapped feature lacks docs

Override repo paths with DOCS_SCAN_FRONTEND, DOCS_SCAN_BACKEND, DOCS_SCAN_AGENT.

Add new feature → doc mappings in scripts/docs-scan.config.ts (featureDocMap).