@nexus-framework/cli 0.1.2 → 0.1.4

package/dist/generators/docs.js

@@ -11,6 +11,20 @@
  * status and auto-populate template docs from codebase analysis.
  */
 import { version } from '../version.js';
+/* ──────────────────────────────────────────────────────────────
+ * Display helpers
+ * ────────────────────────────────────────────────────────────── */
+function getFrameworkDisplay(framework) {
+    const map = {
+        nextjs: 'Next.js 15 (App Router)',
+        'react-vite': 'React + Vite',
+        sveltekit: 'SvelteKit',
+        nuxt: 'Nuxt 3',
+        astro: 'Astro',
+        remix: 'Remix',
+    };
+    return map[framework] ?? framework;
+}
 /* ──────────────────────────────────────────────────────────────
  * Frontmatter helper
  * ────────────────────────────────────────────────────────────── */
@@ -46,6 +60,8 @@ export function generateDocs(config) {
     files.push(generateTestStrategy(config));
     files.push(generateImplementation(config));
     files.push(generateDeployment(config));
+    files.push(generateProjectIndex(config));
+    files.push(generateKnowledge(config));
     files.push(generateNexusIndex(config));
     files.push(generateNexusManifest(config));
     return files;
@@ -56,57 +72,24 @@ function generateVision(config) {
         content: `${frontmatter('01_vision', 'Product Vision & Requirements')}# Product Vision & Requirements
 
 **Project:** ${config.displayName}
-**Created:** ${new Date().toISOString().split('T')[0]}
-**Status:** 🟡 In Development
 
 ---
 
 ## 🎯 Product Vision
-
-<!-- Describe what you're building and why. Be specific about the problem you're solving. -->
-
-TODO: Write your product vision here.
-
----
+<!-- What are you building and why? What problem does it solve? -->
 
 ## 👥 Target Users
-
-<!-- Who are your users? What are their pain points? Create 2-3 personas. -->
-
-TODO: Define your user personas.
-
----
+<!-- 2-3 personas: role, goals, pain points, needs -->
 
 ## ✨ Core Features (MVP)
-
-<!-- List your must-have features with acceptance criteria. -->
-
-### Feature 1: [Feature Name]
-**User Story:** As a [user], I want to [action] so that [benefit].
-
-**Acceptance Criteria:**
-- [ ] Criteria 1
-- [ ] Criteria 2
-- [ ] Criteria 3
-
----
+<!-- List each feature with a user story + acceptance criteria.
+     AI: After filling this, copy each feature into .nexus/docs/index.md Feature Backlog. -->
 
 ## 🚫 Out of Scope (V1)
-
-<!-- What are you explicitly NOT building? This is just as important. -->
-
-- ❌ Item 1
-- ❌ Item 2
-
----
+<!-- What you are explicitly NOT building yet -->
 
 ## 📊 Success Metrics
-
-<!-- How will you know if this project is successful? -->
-
-| Metric | Target | Timeframe |
-|--------|--------|-----------|
-| TODO   | TODO   | TODO      |
+<!-- How you'll measure success: metric, target, timeframe -->
 `,
     };
 }
@@ -122,14 +105,7 @@ function generateArchitecture(config) {
 ---
 
 ## 🏗️ Architecture Overview
-
-<!-- High-level diagram of your system. ASCII art or link to a diagram tool. -->
-
-\`\`\`
-TODO: Draw your architecture diagram here.
-\`\`\`
-
----
+<!-- High-level system diagram (ASCII or link to diagram tool) -->
 
 ## 🛠️ Tech Stack
 
@@ -139,21 +115,11 @@ TODO: Draw your architecture diagram here.
 | Data      | ${config.dataStrategy} | ${config.dataStrategy} strategy |
 | Testing   | ${config.testFramework} | Selected during project setup |
 
----
-
 ## 📁 Directory Structure
-
-<!-- Document your folder conventions and where things go. -->
-
-TODO: Document your project's directory conventions.
-
----
+<!-- Folder conventions: what goes where and why -->
 
 ## 🔄 Data Flow
-
-<!-- How does data move through your system? -->
-
-TODO: Describe your data flow.
+<!-- How data moves through the system: user → UI → store → API → DB -->
 `,
     };
 }
@@ -168,26 +134,13 @@ function generateDataContracts(config) {
 ---
 
 ## 📊 Database Schema
-
-<!-- Define your data models, tables, relationships. -->
-
-TODO: Define your data models.
-
----
+<!-- Define data models, tables/collections, and their fields with types -->
 
 ## ✅ Validation Rules
-
-<!-- What validation rules apply to your data? -->
-
-TODO: Document validation rules.
-
----
+<!-- Required fields, min/max, format constraints, custom validators -->
 
 ## 🔗 Relationships
-
-<!-- How do your data models relate to each other? -->
-
-TODO: Document data relationships.
+<!-- How models relate: one-to-many, many-to-many, foreign keys -->
 `,
     };
 }
@@ -201,21 +154,7 @@ function generateApiContracts(config) {
 ---
 
 ## 🔌 Endpoints
-
-<!-- Define your API endpoints with request/response shapes. -->
-
-### \`GET /api/example\`
-
-**Description:** TODO
-
-**Response:**
-\`\`\`json
-{
-  "data": []
-}
-\`\`\`
-
----
+<!-- Define each API endpoint: method, path, description, request/response shapes -->
 
 ## 📋 Status Codes
 
@@ -230,6 +169,42 @@ function generateApiContracts(config) {
     };
 }
 function generateBusinessLogic(config) {
+    const patterns = config.appPatterns;
+    // Build pattern-specific sections based on user's selections
+    const patternSections = [];
+    if (patterns.includes('offline-first') || config.dataStrategy === 'local-first') {
+        patternSections.push(`## 🔄 Sync & Conflict Resolution
+<!-- How do local changes sync with the server? What happens on conflict?
+     Define: sync trigger, queue structure, conflict strategy (last-write-wins / merge / user-prompt) -->`);
+    }
+    if (patterns.includes('real-time')) {
+        patternSections.push(`## ⚡ Real-Time System
+<!-- WebSocket or SSE? What events are broadcast? Who receives them?
+     Define: connection lifecycle, event types, reconnection strategy, presence -->`);
+    }
+    if (patterns.includes('pwa')) {
+        patternSections.push(`## 📲 PWA / Service Worker
+<!-- What is cached? Cache strategy (cache-first / network-first)?
+     Define: cache manifest, update flow, install prompt timing -->`);
+    }
+    if (patterns.includes('theming')) {
+        patternSections.push(`## 🎨 Theming System
+<!-- CSS variables? Theme provider? How are themes stored and applied?
+     Define: theme shape (colors, fonts, spacing), persistence, switching logic -->`);
+    }
+    if (patterns.includes('i18n')) {
+        patternSections.push(`## 🌍 Internationalization (i18n)
+<!-- Which i18n library? How are translations structured?
+     Define: default locale, supported locales, namespace strategy, lazy loading -->`);
+    }
+    if (patterns.includes('white-label')) {
+        patternSections.push(`## 🏷️ White Label / Multi-Tenant
+<!-- How are tenants identified? Subdomain, path, or config?
+     Define: tenant resolution, per-tenant config shape, branding override points -->`);
+    }
+    const patternContent = patternSections.length > 0
+        ? patternSections.join('\n\n') + '\n'
+        : '';
     return {
         path: '.nexus/docs/05_business_logic.md',
         content: `${frontmatter('05_business_logic', 'Business Logic')}# Business Logic
@@ -239,30 +214,20 @@ function generateBusinessLogic(config) {
 ---
 
 ## 📐 Business Rules
-
-<!-- Document the core rules and logic of your application. -->
-
-TODO: Define your business rules.
-
----
+<!-- Core rules of the application: what can/can't happen, constraints, permissions -->
 
 ## 🔄 State Machines
-
-<!-- If your app has complex state, document it here. -->
-
-TODO: Document state machines and flows.
-
----
+<!-- Complex state flows: e.g. task lifecycle, auth flow, checkout process -->
 
 ## 🧮 Algorithms
+<!-- Non-trivial logic: scoring, sorting, filtering, calculations -->
 
-<!-- Any non-trivial algorithms or calculations. -->
-
-TODO: Document algorithms.
-`,
+${patternContent}`,
     };
 }
 function generateTestStrategy(config) {
+    const pm = config.packageManager;
+    const runCmd = pm === 'npm' ? 'npm run' : pm;
     return {
         path: '.nexus/docs/06_test_strategy.md',
         content: `${frontmatter('06_test_strategy', 'Test Strategy')}# Test Strategy
@@ -273,13 +238,10 @@ function generateTestStrategy(config) {
 ---
 
 ## 🧪 Testing Philosophy
-
-<!-- What's your approach to testing? What's the coverage target? -->
+<!-- Coverage target, what gets tested, what doesn't -->
 
 **Coverage Target:** 80%+
 
----
-
 ## 📋 Test Types
 
 | Type | Tool | Coverage |
@@ -288,14 +250,11 @@ function generateTestStrategy(config) {
 | Integration | ${config.testFramework} | API routes, data flows |
 | E2E | Playwright | Critical user journeys |
 
----
-
 ## 🏃 Running Tests
 
 \`\`\`bash
-npm test              # Run all tests
-npm run test:watch    # Watch mode
-npm run test:coverage # With coverage report
+${runCmd} test              # Run all tests
+${runCmd} test -- --watch   # Watch mode
 \`\`\`
 `,
     };
@@ -309,32 +268,83 @@ function generateImplementation(config) {
 
 ---
 
-## 🔨 Build Order
+## 🎯 Current Phase
 
-<!-- What order should features be built in? -->
+<!-- AI: After populating this doc, set the current phase based on what exists in the codebase. -->
 
-### Phase 1: Foundation
-- [ ] Project setup ✅ (done by NEXUS CLI)
-- [ ] Core data models
-- [ ] Basic UI layout
+**Active Phase:** TODO — Set this to the current build phase
+**Blocked:** None
 
-### Phase 2: Core Features
-- [ ] Feature 1
-- [ ] Feature 2
-- [ ] Feature 3
+---
+
+## 🔨 Build Phases
 
-### Phase 3: Polish
-- [ ] Error handling
-- [ ] Loading states
-- [ ] Responsive design
+<!-- AI: Derive these phases from 01_vision.md features. Each phase should be a coherent milestone. -->
+
+### Phase 1: Foundation
+**Goal:** Project skeleton, core data models, basic navigation
+
+| Task | File(s) | Status | Notes |
+|------|---------|--------|-------|
+| Project setup | (auto) | ✅ Done by NEXUS CLI | — |
+| Core data models / types | \`src/types/\` or \`src/lib/\` | TODO | Define from 03_data_contracts.md |
+| Basic layout / navigation | \`src/app/\` or \`src/routes/\` | TODO | — |
+| Database / storage setup | \`src/lib/\` | TODO | Match data strategy: ${config.dataStrategy} |
+
+### Phase 2: Core Features (MVP)
+**Goal:** Implement the features from 01_vision.md that make this usable
+
+| Task | File(s) | Status | Notes |
+|------|---------|--------|-------|
+| Feature 1 | TODO | TODO | — |
+| Feature 2 | TODO | TODO | — |
+| Feature 3 | TODO | TODO | — |
+
+### Phase 3: Polish & Quality
+**Goal:** Error handling, loading states, tests, responsive design
+
+| Task | File(s) | Status | Notes |
+|------|---------|--------|-------|
+| Error boundaries / handling | TODO | TODO | — |
+| Loading / skeleton states | TODO | TODO | — |
+| Unit tests for core logic | \`tests/unit/\` | TODO | Match 06_test_strategy.md |
+| Responsive design | TODO | TODO | — |
+
+### Phase 4: Deployment
+**Goal:** CI/CD, environment config, production deploy
+
+| Task | File(s) | Status | Notes |
+|------|---------|--------|-------|
+| CI/CD pipeline | \`.github/workflows/\` | ✅ Generated | — |
+| Environment variables | \`.env.example\` | TODO | See 08_deployment.md |
+| Production deploy | TODO | TODO | — |
 
 ---
 
 ## 📁 File-by-File Plan
 
-<!-- For AI agents: list each file that needs to be created and what it should contain. -->
+<!-- AI: After populating 01_vision.md, list every file that needs creating.
+     Also copy each feature into .nexus/docs/index.md Feature Backlog table. -->
+
+| # | File Path | Purpose | Status |
+|---|-----------|---------|--------|
 
-TODO: Create a file-by-file implementation plan.
+---
+
+## 🧪 Testing Plan
+
+| Test File | What It Tests | Status |
+|-----------|--------------|--------|
+
+---
+
+## ⚠️ AI Agent: How To Use This File
+
+1. **Derive phases from \`01_vision.md\`** — turn user stories into build phases
+2. **Copy each feature into \`.nexus/docs/index.md\` Feature Backlog** — that drives all work
+3. **Fill the file-by-file plan** — list every file with its purpose
+4. **Update status as you work** — mark tasks ✅ when done
+5. **This file answers "what code do I write next?"**
 `,
     };
 }
@@ -348,12 +358,7 @@ function generateDeployment(config) {
 ---
 
 ## 🚀 Deployment Strategy
-
-<!-- Where and how will this be deployed? -->
-
-TODO: Define your deployment strategy.
-
----
+<!-- Where and how will this be deployed? Platform, region, scaling -->
 
 ## 🔧 Environment Variables
 
@@ -361,17 +366,223 @@ TODO: Define your deployment strategy.
 |----------|-------------|----------|---------|
 | \`NODE_ENV\` | Environment | Yes | \`development\` |
 
+## 📦 CI/CD
+
+GitHub Actions workflow at \`.github/workflows/ci.yml\` runs on push/PR to \`main\`:
+lint → typecheck → test → build
+`,
+    };
+}
+/* ──────────────────────────────────────────────────────────────
+ * Project Index — THE AI AGENT'S BRAIN
+ *
+ * This is THE most important file in the NEXUS system.
+ * It's NOT just a doc to fill in — it's the living project tracker
+ * that the AI agent must use to know:
+ *   - What's been built
+ *   - What to build next
+ *   - Current blockers
+ *   - Feature backlog
+ *   - Session-by-session progress
+ *
+ * The agent must READ this before every task and UPDATE it after.
+ * ────────────────────────────────────────────────────────────── */
+function generateProjectIndex(config) {
+    const frameworkDisplay = getFrameworkDisplay(config.frontendFramework);
+    const now = new Date().toISOString().split('T')[0];
+    return {
+        path: '.nexus/docs/index.md',
+        content: `${frontmatter('project_index', 'Project Index — AI Agent Brain')}# ${config.displayName} — Project Index
+
+> **🧠 THIS IS THE AI AGENT'S BRAIN.**
+> This is NOT just another doc to fill in. This is the living project tracker.
+> AI agents MUST read this file before every task and update it after every task.
+
+**Project:** ${config.displayName}
+**Framework:** ${frameworkDisplay}
+**Data Strategy:** ${config.dataStrategy}
+**Created:** ${now}
+**Status:** 🟡 Scaffolded — Awaiting vision + first feature
+
 ---
 
-## 📦 CI/CD
+## 🎯 Current Objective
+
+<!-- AI: This section must ALWAYS reflect what you're working on RIGHT NOW.
+     Update it at the start of every task. -->
+
+**Current Phase:** Phase 1 — Foundation
+**Active Task:** Populate NEXUS docs from user's project vision
+**Blocked:** None
+**Next Up:** See "What's Next" section below
+
+---
 
-A GitHub Actions workflow has been generated at \`.github/workflows/ci.yml\`.
+## 📊 Project Status Matrix
 
-It runs on every push and PR to \`main\`:
-1. ✅ Lint
-2. ✅ Type check
-3. ✅ Tests
-4. ✅ Build
+<!-- AI: Update these statuses as you complete work. This is how you track progress. -->
+
+| Area | Status | Notes |
+|------|--------|-------|
+| 📋 Vision & Requirements | 🔴 Template | Needs user input → \`.nexus/docs/01_vision.md\` |
+| 🏗️ Architecture | 🔴 Template | Auto-fill from codebase → \`.nexus/docs/02_architecture.md\` |
+| 📊 Data Contracts | 🔴 Template | Define from code → \`.nexus/docs/03_data_contracts.md\` |
+| 🔌 API Contracts | 🔴 Template | Define from code → \`.nexus/docs/04_api_contracts.md\` |
+| 📐 Business Logic | 🔴 Template | Needs user input → \`.nexus/docs/05_business_logic.md\` |
+| 🧪 Test Strategy | 🔴 Template | Auto-fill from code → \`.nexus/docs/06_test_strategy.md\` |
+| 🔨 Implementation Plan | 🔴 Template | Build from vision → \`.nexus/docs/07_implementation.md\` |
+| 🚀 Deployment | 🔴 Template | Auto-fill from code → \`.nexus/docs/08_deployment.md\` |
+| 🏠 Core Features | 🔴 Not started | See feature backlog below |
+| 🧪 Tests | 🔴 Not started | — |
+
+---
+
+## 🗂️ Feature Backlog
+
+<!-- AI: After populating 01_vision.md, copy EVERY Core Feature into this table.
+     Assign each a priority and phase. This is the ONLY list you work from. -->
+
+| # | Feature | Priority | Status | Phase | Notes |
+|---|---------|----------|--------|-------|-------|
+
+---
+
+## 📁 What Has Been Built
+
+<!-- AI: Update this as you create files. Track every module, component, and test.
+     This is how you know what exists and what doesn't. -->
+
+### Source Files
+
+| Module | Files | Status | Description |
+|--------|-------|--------|-------------|
+| Project scaffold | \`package.json\`, \`tsconfig.json\`, configs | ✅ | Generated by NEXUS CLI |
+| Landing page | \`src/\` (framework-specific) | ✅ | NEXUS branded starter page |
+| NEXUS docs | \`.nexus/docs/\` (8 files + index) | 🟡 Template | Awaiting population |
+| AI config | \`.nexus/ai/\` + root files | ✅ | AI agent instructions |
+| CI/CD | \`.github/workflows/ci.yml\` | ✅ | Lint + typecheck + test + build |
+
+### Tests
+
+| File | Tests | Covers |
+|------|-------|--------|
+| TODO | TODO | TODO |
+
+---
+
+## 🔄 Progress Log
+
+<!-- AI: Add an entry here every time you complete meaningful work.
+     This is the project's changelog and your memory across sessions. -->
+
+### ${now} — Project Created
+- ✅ Scaffolded with NEXUS CLI (${frameworkDisplay}, ${config.dataStrategy})
+- ✅ Generated project structure, configs, landing page, CI/CD
+- ✅ Generated NEXUS documentation system (8 template docs)
+- ⏳ Docs need to be populated with project-specific content
+
+---
+
+## 🎯 What's Next (Prioritized)
+
+<!-- AI: THIS IS YOUR TODO LIST. Work through it top to bottom.
+     After completing an item, move it to the Progress Log and update the status matrix.
+     Add new items as they emerge. -->
+
+### 🔴 Do First (Before Any Feature Work)
+1. **Populate NEXUS docs** — Read the codebase + ask the user about their vision, then fill in all 8 docs (see onboarding protocol in AI instructions)
+2. **Build the implementation plan** — Turn features from \`01_vision.md\` into concrete build phases in \`07_implementation.md\` with a file-by-file plan
+3. **Update this index** — Fill in the feature backlog, status matrix, and "What Has Been Built" sections
+
+### 🟡 Then Build (Phase 1 — Foundation)
+4. **Core data models / types** — Define from \`03_data_contracts.md\`
+5. **Basic layout / navigation** — Main app shell, routing
+6. **Database / storage setup** — Match data strategy: ${config.dataStrategy}
+
+### 🟢 Then Build (Phase 2 — Core Features)
+7. **Feature 1** — TODO (derive from vision)
+8. **Feature 2** — TODO (derive from vision)
+9. **Feature 3** — TODO (derive from vision)
+
+---
+
+## ⚠️ AI Agent Operating Rules
+
+**YOU MUST FOLLOW THESE RULES. They are not suggestions.**
+
+1. **READ this file before EVERY task** — it tells you what to do next
+2. **UPDATE this file after EVERY task** — move completed items to Progress Log, update status matrix
+3. **DON'T ask "what enhancements would you like?"** — check the "What's Next" section instead
+4. **DON'T treat docs as one-time fill-ins** — they are living documents, update them as the project evolves
+5. **The feature backlog is your roadmap** — suggest the next item from it, don't invent random features
+6. **The implementation plan (\`07_implementation.md\`) tells you WHAT CODE to write** — check it before every feature
+7. **The progress log is your memory** — add entries so you (or the next agent) know what happened
+8. **If the user asks for a feature, check if it's already in the backlog** — if yes, just build it; if no, add it first
+9. **After every session, ensure this file reflects reality** — statuses, progress, blockers, next steps
+10. **Learn as you go** — when you discover something non-obvious (bug pattern, architecture insight, package quirk), append it to \`.nexus/docs/knowledge.md\`. Scan that file before making big decisions.
+
+---
+
+*Generated by [NEXUS CLI](https://github.com/GDA-Africa/nexus-cli) v${version} — AI-native project scaffolding by [GDA Africa](https://github.com/GDA-Africa)*
+`,
+    };
+}
+/* ──────────────────────────────────────────────────────────────
+ * Progressive Knowledge Base — .nexus/docs/knowledge.md
+ *
+ * An append-only living document. AI agents add entries as they
+ * learn things about the project — architectural decisions,
+ * bug patterns, package quirks, performance findings, etc.
+ *
+ * NOT a template doc (no status: template frontmatter).
+ * Agents should NEVER delete entries — only append.
+ * ────────────────────────────────────────────────────────────── */
+function generateKnowledge(config) {
+    const now = new Date().toISOString().split('T')[0];
+    return {
+        path: '.nexus/docs/knowledge.md',
+        content: `# ${config.displayName} — Knowledge Base
+
+> **Progressive learning file.** AI agents append entries here as they discover
+> project-specific insights. This file grows organically — never delete entries.
+
+---
+
+## How This Works
+
+- **When to add:** After discovering something non-obvious — a bug pattern, an architecture decision, a package quirk, a performance finding, a convention choice
+- **When NOT to add:** Routine task completion (that goes in \`index.md\` Progress Log)
+- **Format:** One entry = category tag + one-line insight + optional detail line
+- **When to read:** Before making architectural decisions, debugging recurring issues, or choosing packages/patterns — scan for relevant categories first
+
+---
+
+## Categories
+
+| Tag | Use When |
+|-----|----------|
+| \`architecture\` | Design decisions, structural choices, why X over Y |
+| \`bug-fix\` | Recurring bugs, root causes, things to watch for |
+| \`pattern\` | Code patterns that work well (or don't) in this project |
+| \`package\` | Package quirks, version issues, config gotchas |
+| \`performance\` | Bottlenecks found, optimizations applied |
+| \`convention\` | Team/project conventions established during development |
+| \`gotcha\` | Non-obvious traps, edge cases, things that wasted time |
+
+---
+
+## Entries
+
+<!-- AI: Append new entries below this line. Format:
+
+### [CATEGORY] Short title
+**${now}** — One-line insight.
+Optional: Brief supporting detail (1-2 sentences max).
+
+-->
+
+### [convention] Project scaffolded with NEXUS CLI
+**${now}** — This project was generated with NEXUS CLI. Follow the doc system in \`.nexus/docs/\` and always read \`index.md\` (the brain) before each task.
 `,
     };
 }
@@ -386,18 +597,27 @@ function generateNexusIndex(config) {
 
 ---
 
+## 🧠 Start Here
+
+**AI agents: Read \`.nexus/docs/index.md\` FIRST** — that is your project brain.
+It tracks status, features, progress, and what to work on next.
+
+---
+
 ## 📚 Document Map
 
 | Doc | Path | Purpose |
 |-----|------|---------|
+| **🧠 Project Brain** | **\`.nexus/docs/index.md\`** | **Status, backlog, progress, what's next** |
 | Vision | \`.nexus/docs/01_vision.md\` | Product requirements & user stories |
 | Architecture | \`.nexus/docs/02_architecture.md\` | System design & tech stack |
 | Data Contracts | \`.nexus/docs/03_data_contracts.md\` | Database schemas & validation |
 | API Contracts | \`.nexus/docs/04_api_contracts.md\` | Endpoints & interfaces |
 | Business Logic | \`.nexus/docs/05_business_logic.md\` | Rules, algorithms & flows |
 | Test Strategy | \`.nexus/docs/06_test_strategy.md\` | Testing philosophy & coverage |
-| Implementation | \`.nexus/docs/07_implementation.md\` | Build order & file structure |
+| Implementation | \`.nexus/docs/07_implementation.md\` | Build order & file-by-file plan |
 | Deployment | \`.nexus/docs/08_deployment.md\` | Infrastructure & CI/CD |
+| **📚 Knowledge Base** | **\`.nexus/docs/knowledge.md\`** | **Learned insights, patterns & gotchas** |
 
 ---
 
@@ -405,11 +625,11 @@ function generateNexusIndex(config) {
 
 If you are an AI reading this project:
 
-1. **Start with** \`.nexus/docs/01_vision.md\` to understand what this project does
-2. **Read** \`.nexus/docs/02_architecture.md\` to understand the tech decisions
-3. **Reference** \`.nexus/docs/03_data_contracts.md\` and \`.nexus/docs/04_api_contracts.md\` for exact schemas
-4. **Follow** \`.nexus/docs/07_implementation.md\` for build order
-5. **Run tests** after every change using the commands in \`.nexus/docs/06_test_strategy.md\`
+1. **START with \`.nexus/docs/index.md\`** — your project brain, read it before every task
+2. **Read \`.nexus/docs/01_vision.md\`** to understand what this project does
+3. **Check \`.nexus/docs/07_implementation.md\`** for the file-by-file build plan
+4. **After every task, update \`.nexus/docs/index.md\`** — progress log, status, what's next
+5. **Never ask "what should we do next?"** — the index tells you
 `,
     };
 }