diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e97ed51
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# SamsTechnical-wikijs
+
+**Bugatti-inspired design system for a Wiki.js technical knowledge base.**
+
+A complete dark-theme design system and page architecture for a self-hosted Wiki.js instance documenting a homelab fleet — machines, Docker ecosystem, AI development tooling, home automation, and network infrastructure.
+
+## What it is
+
+A curated Wiki.js theme that transforms the default wiki interface into a cinematic, monochrome knowledge base. The design language is inspired by Bugatti's luxury automotive aesthetic: pure-black canvas, monumental ALL-CAPS display typography, hairline borders, and zero drop shadows — engineered precision for technical documentation.
+
+## Design system
+
+| Token | Value | Role |
+|-------|-------|------|
+| Canvas | `#000000` | Page floor |
+| Ink / primary | `#ffffff` | Headlines, primary text |
+| Body | `#cccccc` | Running text |
+| Surface | `#141414` / `#0d0d0d` | Cards, code blocks |
+| Hairline | `#262626` | Dividers, borders |
+| Link | `#c3d9f3` | Only non-monochrome accent |
+| Display font | Saira Condensed | ALL-CAPS headings, wide tracking |
+| Body font | EB Garamond | Editorial serif |
+| Mono font | JetBrains Mono | Code, data, navigation |
+
+**Principles:** no shadows (depth via contrast), binary radius (0px / pill / full), monospace for technical data, serif for long-form reading.
+
+## Repository structure
+
+```
+├── DESIGN.md               # Structured design tokens (palette, type, spacing)
+├── wiki-global.css         # Global stylesheet injected via Wiki.js theme config
+├── index.html              # Home page mockup (hero, stats, card grid)
+├── article.html            # Article page mockup (TOC sidebar, spec grid, code)
+├── navigation-prototype.html  # Full sidebar hierarchy prototype
+├── create-pages.py         # GraphQL script — creates hub pages in Wiki.js
+└── set-nav.py              # GraphQL script — sets sidebar navigation tree
+```
+
+## Deployment to Wiki.js
+
+1. **Inject the theme:** in Wiki.js admin → *Theme*, set custom head HTML to wrap `wiki-global.css` in a `<style>` tag. Enable dark mode.
+2. **Create pages:** run `create-pages.py` (requires admin JWT) to create the hub pages: Home, Machines & OS, Docker Ecosystem, Dev & AI, AI Resume System, Home Assistant & IoT, Snapcast Audio, Network.
+3. **Configure navigation:** run `set-nav.py` to build the collapsible sidebar tree.
+
+## Architecture patterns
+
+- **Design-token driven** — all values centralized in CSS custom properties
+- **Page-type system** — hub pages (card grids), detail pages (TOC + content), reference pages (spec tables)
+- **Cross-referencing** — "Related Topics" cards link pages across sections
+- **API-first theming** — everything deployable via Wiki.js GraphQL API, no manual UI steps
+
+## Tech
+
+Wiki.js 2.x · GraphQL API · CSS custom properties · Google Fonts (Saira Condensed, EB Garamond, JetBrains Mono) · Python (deployment scripts)
+
+---
+
+*Part of a homelab documentation ecosystem — see also [TooraSt-wikijs](https://gitea.lab.audasmedia.com.au/sam/TooraSt-wikijs).*