docs: scaffold VitePress site with detailed guides

.gitignore

@@ -36,6 +36,10 @@ uploads/
 # Vite
 host/static/dist/
 
+# VitePress (docs)
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+
 # Auto-generated frontend module manifest (regenerated by the host at boot
 # or via `make gen-pages`).
 host/client_app/modules.manifest.json

docs/.vitepress/config.ts

@@ -0,0 +1,180 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "simple_module_python",
+  description:
+    "A modular-monolith framework for Python: FastAPI + SQLModel + Inertia + React, with plugin modules that compose at boot.",
+  lastUpdated: true,
+  cleanUrls: true,
+  ignoreDeadLinks: true,
+
+  srcExclude: [
+    "**/node_modules/**",
+    "plans/**",
+    "superpowers/**",
+    "release-notes/**",
+    "README.md",
+  ],
+
+  head: [
+    ["meta", { name: "theme-color", content: "#3c82f6" }],
+    ["meta", { property: "og:title", content: "simple_module_python" }],
+    [
+      "meta",
+      {
+        property: "og:description",
+        content: "Modular-monolith framework for Python",
+      },
+    ],
+  ],
+
+  themeConfig: {
+    nav: [
+      { text: "Guide", link: "/guide/introduction", activeMatch: "/guide/" },
+      {
+        text: "Framework",
+        link: "/framework/overview",
+        activeMatch: "/framework/",
+      },
+      {
+        text: "Database",
+        link: "/database/models",
+        activeMatch: "/database/",
+      },
+      {
+        text: "Frontend",
+        link: "/frontend/inertia",
+        activeMatch: "/frontend/",
+      },
+      { text: "Testing", link: "/testing/overview", activeMatch: "/testing/" },
+      {
+        text: "Reference",
+        link: "/reference/make-commands",
+        activeMatch: "/reference/",
+      },
+    ],
+
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/antosubash/simple_module_python",
+      },
+    ],
+
+    search: { provider: "local" },
+
+    editLink: {
+      pattern:
+        "https://github.com/antosubash/simple_module_python/edit/main/docs/:path",
+      text: "Edit this page on GitHub",
+    },
+
+    footer: {
+      message: "Released under the MIT License.",
+      copyright: "Copyright © 2026 simple_module_python contributors",
+    },
+
+    outline: { level: [2, 3] },
+
+    sidebar: {
+      "/guide/": [
+        {
+          text: "Getting Started",
+          collapsed: false,
+          items: [
+            { text: "Introduction", link: "/guide/introduction" },
+            { text: "Installation", link: "/guide/installation" },
+            { text: "Quickstart", link: "/guide/quickstart" },
+            { text: "Project structure", link: "/guide/project-structure" },
+            { text: "Configuration", link: "/guide/configuration" },
+            { text: "Your first module", link: "/guide/first-module" },
+          ],
+        },
+        {
+          text: "Existing deep dives",
+          collapsed: true,
+          items: [
+            {
+              text: "Framework conventions",
+              link: "/framework-conventions",
+            },
+            { text: "Module authoring", link: "/module-authoring" },
+            { text: "E2E testing", link: "/e2e-testing" },
+            { text: "Release playbook", link: "/release" },
+          ],
+        },
+      ],
+
+      "/framework/": [
+        {
+          text: "Framework",
+          collapsed: false,
+          items: [
+            { text: "Overview", link: "/framework/overview" },
+            { text: "Discovery & entry points", link: "/framework/discovery" },
+            { text: "Lifecycle hooks", link: "/framework/lifecycle" },
+            { text: "Middleware pipeline", link: "/framework/middleware" },
+            { text: "Settings & app.state", link: "/framework/settings" },
+            { text: "Permissions", link: "/framework/permissions" },
+            { text: "Events", link: "/framework/events" },
+            { text: "Internationalization", link: "/framework/i18n" },
+          ],
+        },
+      ],
+
+      "/database/": [
+        {
+          text: "Database",
+          collapsed: false,
+          items: [
+            { text: "Models with SQLModel", link: "/database/models" },
+            { text: "Per-module Base", link: "/database/per-module-base" },
+            { text: "Mixins", link: "/database/mixins" },
+            { text: "Session lifecycle", link: "/database/sessions" },
+            { text: "Migrations", link: "/database/migrations" },
+          ],
+        },
+      ],
+
+      "/frontend/": [
+        {
+          text: "Frontend",
+          collapsed: false,
+          items: [
+            { text: "Inertia basics", link: "/frontend/inertia" },
+            { text: "Pages & discovery", link: "/frontend/pages" },
+            { text: "Shared props & layout", link: "/frontend/shared-props" },
+          ],
+        },
+      ],
+
+      "/testing/": [
+        {
+          text: "Testing",
+          collapsed: false,
+          items: [
+            { text: "Overview", link: "/testing/overview" },
+            { text: "Fixtures", link: "/testing/fixtures" },
+            { text: "E2E tests", link: "/e2e-testing" },
+          ],
+        },
+      ],
+
+      "/reference/": [
+        {
+          text: "Reference",
+          collapsed: false,
+          items: [
+            { text: "Make commands", link: "/reference/make-commands" },
+            { text: "Environment variables", link: "/reference/env-vars" },
+            {
+              text: "Diagnostic codes",
+              link: "/reference/diagnostic-codes",
+            },
+            { text: "Deployment", link: "/reference/deployment" },
+          ],
+        },
+      ],
+    },
+  },
+});

docs/README.md

@@ -0,0 +1,55 @@
+# Documentation site
+
+This is a [VitePress](https://vitepress.dev) site — markdown files under `docs/`, rendered by a Vite-powered dev server.
+
+## Run locally
+
+```bash
+cd docs
+npm install
+npm run dev
+```
+
+Open `http://localhost:5173`. Hot-reloads on any `.md` edit.
+
+## Build
+
+```bash
+cd docs
+npm run build       # output in docs/.vitepress/dist
+npm run preview     # serve the built site
+```
+
+## Structure
+
+```text
+docs/
+├── .vitepress/
+│   └── config.ts         # nav, sidebar, theme
+├── index.md              # home page
+├── guide/                # getting-started
+├── framework/            # module system deep dives
+├── database/             # SQLModel, mixins, migrations
+├── frontend/             # Inertia, pages, shared props
+├── testing/              # fixtures, unit + E2E
+├── reference/            # commands, env vars, diagnostic codes, deployment
+├── plans/                # dated design docs (pre-existing)
+├── superpowers/          # spec/plan pairs (pre-existing)
+├── release-notes/        # per-release notes (pre-existing)
+├── framework-conventions.md   # authoritative reference (pre-existing)
+├── module-authoring.md        # authoritative reference (pre-existing)
+├── e2e-testing.md             # authoritative reference (pre-existing)
+└── release.md                 # authoritative reference (pre-existing)
+```
+
+The four pre-existing root-level `.md` files are **authoritative** when conventions are ambiguous. The themed sub-directories are the narrative onboarding path; they link back to the authoritative docs where appropriate.
+
+## Adding a page
+
+1. Create `docs/<section>/<slug>.md`.
+2. Add it to the sidebar in `docs/.vitepress/config.ts`.
+3. `npm run dev` to preview.
+
+## Publishing
+
+Not yet wired into CI. The `docs:build` output can be served by any static host; the repo's release workflow is scoped to Python + npm packages, not docs.