docs: scaffold VitePress site with detailed guides

[antosubash]

Summary

Adds a VitePress-powered documentation site under docs/. VitePress is Vite-based and pure-markdown, so the source stays readable in the repo but the rendered site gets search, sidebar navigation, dark mode, and code highlighting for free.

Structure

docs/
├── .vitepress/config.ts           # nav, sidebar, search, social links
├── index.md                       # home page with hero + features
├── guide/                         # getting-started
│   ├── introduction.md
│   ├── installation.md
│   ├── quickstart.md
│   ├── project-structure.md
│   ├── configuration.md
│   └── first-module.md
├── framework/                     # module-system deep dives
│   ├── overview.md
│   ├── discovery.md
│   ├── lifecycle.md
│   ├── middleware.md
│   ├── settings.md
│   ├── permissions.md
│   ├── events.md
│   └── i18n.md
├── database/
│   ├── models.md
│   ├── per-module-base.md
│   ├── mixins.md
│   ├── sessions.md
│   └── migrations.md
├── frontend/
│   ├── inertia.md
│   ├── pages.md
│   └── shared-props.md
├── testing/
│   ├── overview.md
│   └── fixtures.md
└── reference/
    ├── make-commands.md
    ├── env-vars.md
    ├── diagnostic-codes.md
    └── deployment.md

The pre-existing authoritative single-page docs (framework-conventions.md, module-authoring.md, e2e-testing.md, release.md) are preserved and linked from the sidebars — they remain the source of truth when conventions are ambiguous.

Contents covered

• Guide — install, env config, quickstart, project layout, full first-module walkthrough (scaffold → models → DTOs → migration → service → endpoints → permissions → menu → React page → test).
• Framework — boot sequence, discovery + entry points, all 10 lifecycle hooks with examples, middleware pipeline (LIFO ordering + module ordering rules), app.state.sm Services container, three settings surfaces (env / module-env / DB-backed), permissions, event bus, i18n.
• Database — SQLModel as the one-true standard, per-module Base, AuditMixin/SoftDeleteMixin/MultiTenantMixin/VersionedMixin, get_db commit-on-writes semantics, Alembic workflow + branch labels.
• Frontend — Inertia rendering, page-key discovery ("Orders/Browse" → modules/orders/orders/pages/Browse.tsx), shared-props contract, CSRF via SameSite=Lax.
• Testing — fixtures in conftest.py, auth'd vs anonymous clients, parametrization patterns.
• Reference — make targets, every SM_* env var, every SM0XX diagnostic code with fixes, production deploy checklist.

Build

cd docs
npm install
npm run dev      # http://localhost:5173
npm run build    # static output in docs/.vitepress/dist

Verified: npm run build succeeds locally. plans/, superpowers/, and release-notes/ are excluded from the VitePress build via srcExclude (pre-existing design docs contain unescaped <...> that vue-sfc chokes on).

Test plan

• npm run build completes without errors
• scripts/check_file_size.py passes (config.ts is under the 300-line cap)
• npm run dev and click through every sidebar entry to confirm nothing 404s
• Spot-check code samples render correctly (Python + TSX fences)
• Decide whether to wire docs into a publishing pipeline (GitHub Pages, Cloudflare, Vercel) — not in this PR

https://claude.ai/code/session_01HFcdxte9HSQpdG8BeNXAp6

---

Generated by Claude Code