diff --git a/docs/superpowers/specs/2026-05-03-onboarding-docs-design.md b/docs/superpowers/specs/2026-05-03-onboarding-docs-design.md
new file mode 100644
index 0000000..5c3568b
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-03-onboarding-docs-design.md
@@ -0,0 +1,130 @@
+# Onboarding Documentation Design
+
+## Goal
+
+Write thorough documentation that enables a new developer (team member or external contributor) to set up, understand, and work with the VDI-Starter-v5 WordPress theme with minimal hand-holding.
+
+## Audience
+
+Both internal team members and external contributors, served with layered docs — quick-start up top, deep dives below.
+
+## Approach
+
+Keep the existing README.md as a project overview (trimmed of deep-dive content that moves to `docs/`). Add a `docs/` directory with four focused guides. The README links to each guide.
+
+## Doc Structure
+
+```
+docs/
+├── getting-started.md        # Setup from zero, local WP, env config, first build
+├── architecture.md           # Bootstrap flow, layers, conventions, namespacing, globals
+├── creating-blocks.md        # Step-by-step ACF block creation with block.json, fields, CSS
+└── reference.md              # Hooks/filters, theme.json tokens, CSS architecture, JS modules, deployment
+```
+
+Plus updates to README.md: trim deep-dive content, add Documentation section with links, fix known discrepancies.
+
+## Writing Style
+
+Detailed and explanatory — include context and rationale ("why"), not just "what" and "how". Short paragraphs with code examples and tables where appropriate. Designed to be read end-to-end by a newcomer, but also scannable for quick lookup.
+
+## Guide Contents
+
+### 1. getting-started.md
+
+**Purpose:** Get a developer from zero to a running local environment.
+
+- Prerequisites (Node 22+, pnpm/npm, PHP 8+, Composer, Local by Flywheel or equivalent)
+- Local WordPress setup options (Local by Flywheel, DevKinsta, Docker) with pros/cons
+- Clone, install, build, run steps (npm install, composer install, npm run build, npm run start/watch)
+- .env configuration (LOCALHOST_URL, BROWSERSYNC_PORT)
+- BrowserSync behavior (what triggers reload, which port, how to configure)
+- What happens on theme activation — **important warning**:
+  - Plugin auto-installation (7 plugins downloaded from URLs)
+  - Default page creation (Home, News, 404, Contact Us)
+  - WordPress reading settings configuration
+  - Owner role creation
+  - Warning: do not activate on existing sites without reviewing `lib/activation.php`
+- Troubleshooting common issues:
+  - CSS not compiling → run `npm run build`
+  - Blocks not appearing → ACF Pro must be active
+  - Menu not rendering → must assign menu to location in WP admin
+  - JavaScript not loading → check script module support (WP 6.5+)
+
+### 2. architecture.md
+
+**Purpose:** Explain how the theme is organized and how it boots.
+
+- Bootstrap flow: `functions.php` → glob autoload of `lib/*.php` → `init` hook → class instantiation
+- The 7 architectural layers (from knowledge graph):
+  1. **Entry** — `functions.php` and `style.css` (theme declaration)
+  2. **Service Layer** — PHP classes in `lib/` (Enqueue, MenuItems, Breadcrumbs, ACF, Resources)
+  3. **UI Templates** — WordPress template hierarchy, ACF blocks, components, partials, icons
+  4. **Styling** — Layered CSS with Tailwind v4 (base → components → blocks → navigation)
+  5. **Client Scripts** — JS modules (Navigation, BackToTop, Button, GetHeaderHeight, TagExternalLinks)
+  6. **Data Layer** — ACF field group JSON schemas in `acf/`
+  7. **Infrastructure** — Build scripts, CI/CD pipelines, project configs, tests
+- Namespace conventions:
+  - PHP namespace: `BasicWP`
+  - Text domain: `basicwp`
+  - Block category: `vdi-blocks`
+  - WP Engine folder: `vdi-v5`
+  - Explain the relationship between these naming choices
+- Global variables: `$views` (path to views/ directory) and `$theme` (theme directory path)
+- WordPress hooks cleanup in `hooks.php`: what gets removed (emojis, block library styles, REST links, XML-RPC) and why — performance and security rationale
+- Enqueue system: `wp_enqueue_script_module()` for JS (dependency graph: theme → button, backToTop, Navigation, etc.) vs traditional `wp_enqueue_script` for admin
+- theme.json design system: color palette (12 colors via CSS custom properties), font sizes (15 presets), spacing, layout
+
+### 3. creating-blocks.md
+
+**Purpose:** Teach a developer how to create a new ACF block from scratch.
+
+- Anatomy of a block: `block.json` (registration) + PHP template (rendering) + CSS file (scoped styles)
+- Step-by-step tutorial creating a new "Testimonial" block:
+  1. Create directory `views/blocks/testimonial/`
+  2. Create `block.json` with required fields (name, title, description, category, icon, supports)
+  3. Create `testimonial.php` template using `blockWrapperAttributes()` and `getFieldValue()`
+  4. Create `testimonial.css` for block-specific styles
+  5. Create ACF field group in WP admin → exported to `acf/` as JSON
+- How blocks are auto-registered: `regACFBlocks()` in `functions.php` scans `views/blocks/*/block.json`
+- Helper functions: `blockWrapperAttributes()` for class/id passthrough, `getFieldValue()` for dot-notation ACF access
+- Parent-child block patterns: buttons→button, grid→grid-cell (using `allowed_blocks` or `InnerBlocks`)
+- Tailwind in blocks: how the whitelist system works (`whitelist.php`), how to add editor-only classes
+- Block CSS loading: each block's CSS file is auto-enqueued by the block registration
+
+### 4. reference.md
+
+**Purpose:** Complete API and configuration reference for quick lookup.
+
+- **Hooks and Filters** — Complete table of all `add_action`/`add_filter` calls from `hooks.php`, `extras.php`, `search-features.php`, and class files, with priority, callback, and purpose
+- **theme.json Design Tokens** — Color palette (12 colors with CSS variable names), font sizes (15 presets with rem values), spacing scale, layout sizes
+- **CSS Architecture** — Import tree from `theme.css`, explanation of each layer (base, components, blocks, navigation), how to add new stylesheets
+- **JS Module Dependency Graph** — Visual/text tree showing `theme.js` → Navigation, BackToTop, Button, GetHeaderHeight, TagExternalLinks; `admin.js` → Button
+- **Navigation Class API** — Methods for the sliding viewport feature (initializeSlidingViewport, navigateToLevel, navigateBack, etc.), configuration options
+- **Helper Functions** — `getFieldValue()`, `blockWrapperAttributes()`, `customMenuOrder()`, `blockCategories()`, `consoleLog()`, `customExcerpt()`, `escEmbeds()`
+- **Class Reference** — Enqueue (enqFEAssets, enqBEAssets, enqEditorAssets), ACF (saveJson, loadJson), Breadcrumbs (generate, render, and per-page-type methods), MenuItems (render), Resources (CPT + permalink rewrite), ShowTemplate (debug template path)
+- **CLI Commands** — `npm run build`, `npm run start`/`npm run watch`, `composer lint`, `composer fix`, Playwright test commands
+- **Deployment Workflow** — GitHub Actions `wpengine.yml` pipeline: install deps → build Tailwind → rsync to WP Engine
+- **Testing** — Playwright a11y test setup and commands, PHPCS configuration and usage
+
+## README.md Changes
+
+- Trim: Remove the detailed function-level API docs (they move to `reference.md`)
+- Trim: Remove the detailed project structure tree (keep a shorter version, point to `architecture.md` for the full picture)
+- Add: "Documentation" section with links to all four guides
+- Fix: Wrong CSS paths (`views/styles/` → `styles/`)
+- Fix: Missing `contact-info` block from the block list
+- Fix: Deployment filename typo (`wpengine,yml` → `wpengine.yml`)
+- Fix: Note that `class-enqueue.php` also has `enqEditorAssets()`
+- Add: Mention `backToTop.js` custom element (missing from current README)
+- Add: Clarify namespace conventions (BasicWP, basicwp, vdi-blocks, vdi-v5)
+
+## Implementation Plan
+
+This is a documentation-only change — no code modifications. Implementation consists of:
+
+1. Create `docs/` directory with 4 markdown files
+2. Update `README.md` with trimmed content and links
+3. Fix known discrepancies in README
+
+Estimated scope: ~4 documentation files of ~200-400 lines each, plus README edits.
\ No newline at end of file