mafia docs

Development

Local services

Start FastAPI:

uv run uvicorn mafia.main:app --reload

Start Next.js in another terminal:

npm run dev

The root command loads the repository .env into Next.js.

Start the documentation site when changing guides or its interface:

npm run dev:site

Runtime state

Runtime state lives under data/ and is excluded from Git:

• SQLite workflow and operation state
• AG-UI checkpoints
• Repository caches
• Analysis worktrees
• Phase implementation worktrees

Validation

Run the complete local gate:

npm run check

Run individual gates when narrowing feedback:

npm run check:api
npm run check:web
npm run check:site
npm run check:scripts

The same commands back GitHub Actions.