@epiccontext/mcp 0.1.47 → 0.1.49

package/dist/cli/files.js

@@ -1,2313 +1,564 @@
 import * as fs from "fs";
 import * as path from "path";
 import { getStorybookTemplateFiles } from "../templates/storybook.js";
-/**
- * Read all markdown files from a directory recursively
- */
-export function readContextFolder(contextPath) {
-    const files = [];
-    if (!fs.existsSync(contextPath)) {
-        return files;
-    }
-    function walkDir(dir, relativeTo) {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            const relativePath = path.relative(relativeTo, fullPath);
-            if (entry.isDirectory()) {
-                // Skip hidden directories and node_modules
-                if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
-                    walkDir(fullPath, relativeTo);
-                }
-            }
-            else if (entry.isFile() && entry.name.endsWith(".md")) {
-                // Skip README and AI-GUIDE
-                const lowerName = entry.name.toLowerCase();
-                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md") {
-                    const content = fs.readFileSync(fullPath, "utf-8");
-                    files.push({
-                        path: relativePath,
-                        content,
-                    });
-                }
-            }
-        }
-    }
-    walkDir(contextPath, contextPath);
-    return files;
-}
-/**
- * Write files to the context folder
- * By default, skips files where local version is newer than cloud version
- */
-export function writeContextFolder(contextPath, files, options = {}) {
-    let written = 0;
-    let skipped = 0;
-    const skippedPaths = [];
-    for (const file of files) {
-        const fullPath = path.join(contextPath, file.path);
-        const dir = path.dirname(fullPath);
-        // Create directory if needed
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        // Always overwrite AI-GUIDE.md (it's server-generated and should be authoritative)
-        // This ensures users get the latest block type definitions on every pull
-        const isAIGuide = file.path.toLowerCase() === "ai-guide.md";
-        // Check if local file is newer than cloud version (unless force is set or it's AI-GUIDE.md)
-        if (!options.force && !isAIGuide && file.updatedAt && fs.existsSync(fullPath)) {
-            const localMtime = getFileModTime(fullPath);
-            const cloudMtime = new Date(file.updatedAt);
-            if (localMtime && localMtime > cloudMtime) {
-                // Local file is newer, skip overwriting
-                skipped++;
-                skippedPaths.push(file.path);
-                continue;
-            }
-        }
-        // Write file
-        try {
-            fs.writeFileSync(fullPath, file.content, "utf-8");
-            written++;
-        }
-        catch (error) {
-            console.error(`Failed to write ${file.path}:`, error);
-            skipped++;
-        }
-    }
-    return { written, skipped, skippedPaths };
-}
-/**
- * Delete local files that don't exist in the cloud
- * Used during pull to remove files that were deleted in the UI
- */
-export function deleteOrphanedLocalFiles(contextPath, cloudFiles) {
-    // Build a set of all cloud file paths (normalized)
-    const cloudPaths = new Set();
-    for (const file of cloudFiles) {
-        cloudPaths.add(file.path);
-    }
-    // Get all local markdown files
-    const localFiles = readContextFolder(contextPath);
-    const deleted = [];
-    for (const localFile of localFiles) {
-        // If local file doesn't exist in cloud, delete it
-        if (!cloudPaths.has(localFile.path)) {
-            const fullPath = path.join(contextPath, localFile.path);
-            try {
-                fs.unlinkSync(fullPath);
-                deleted.push(localFile.path);
-            }
-            catch (error) {
-                console.error(`Failed to delete ${localFile.path}:`, error);
-            }
-        }
-    }
-    return { deleted: deleted.length, deletedPaths: deleted };
-}
-/**
- * Ensure the context folder exists with basic structure
- */
-export function ensureContextFolder(contextPath) {
-    if (!fs.existsSync(contextPath)) {
-        fs.mkdirSync(contextPath, { recursive: true });
-    }
-    // Create default section folders
-    // Note: folder names use hyphens, but section types in the app use underscores
-    const defaultSections = [
-        "constitution",
-        "brand",
-        "product",
-        "business-strategy",
-        "users",
-        "research",
-        "technical",
-        "design-system",
-        "information-architecture",
-        "metrics",
-        "decisions",
-        "development",
-        "marketing",
-    ];
-    for (const section of defaultSections) {
-        const sectionPath = path.join(contextPath, section);
-        if (!fs.existsSync(sectionPath)) {
-            fs.mkdirSync(sectionPath, { recursive: true });
-        }
-    }
-    // Create README.md
-    const readmePath = path.join(contextPath, "README.md");
-    if (!fs.existsSync(readmePath)) {
-        const readme = `# CONTEXT
-
-This folder contains product context documentation synced with EpicContext.
-
-## IMPORTANT: File Format
-
-**All markdown files MUST have YAML frontmatter with these required fields:**
-
-\`\`\`yaml
----
-type: persona       # Block type (persona, feature, decision, etc.)
-section: brand      # Section name (must match folder name)
-key: unique-key     # Unique identifier (use kebab-case)
-name: Display Name  # Human-readable name
-status: draft       # Status: draft, complete, or empty
----
-\`\`\`
-
-See \`AI-GUIDE.md\` for detailed format instructions.
-
-## Structure
-
-Each folder represents a section of your product documentation:
-
-- \`constitution/\` - Non-negotiable rules and principles
-- \`brand/\` - Identity, voice, and visual system
-- \`product/\` - Vision, features, and roadmap
-- \`business-strategy/\` - Strategic planning and business models
-- \`users/\` - Personas, jobs to be done, and user journeys
-- \`research/\` - Market and competitor analysis
-- \`technical/\` - Stack, architecture, and constraints
-- \`design-system/\` - Links to Storybook and Figma
-- \`information-architecture/\` - Site structure and taxonomies
-- \`metrics/\` - KPIs and analytics
-- \`decisions/\` - Architecture decision records
-- \`development/\` - Epics, stories, tasks, and roadmaps
-- \`marketing/\` - Marketing campaigns and SEO content strategy
-
-## Syncing
-
-This folder is synced with your EpicContext project using the MCP server.
-
-To sync changes:
-\`\`\`bash
-epicontext sync
-\`\`\`
-
-To watch for changes and auto-sync:
-\`\`\`bash
-epicontext watch
-\`\`\`
-`;
-        fs.writeFileSync(readmePath, readme, "utf-8");
-    }
-    // Create AI-GUIDE.md with detailed format instructions
-    const aiGuidePath = path.join(contextPath, "AI-GUIDE.md");
-    if (!fs.existsSync(aiGuidePath)) {
-        const aiGuide = `# AI Agent Guide for EpicContext
-
-This file contains instructions for AI agents (Claude, Cursor, etc.) on how to create and edit documentation files in this CONTEXT folder.
-
-## CRITICAL: Required YAML Frontmatter
-
-Every markdown file in this folder **MUST** have YAML frontmatter with these required fields:
-
-\`\`\`yaml
----
-type: persona           # REQUIRED: Block type (see list below)
-section: brand          # REQUIRED: Section name (must match folder name)
-key: my-unique-key      # REQUIRED: Unique identifier within section (use kebab-case)
-name: My Display Name   # REQUIRED: Human-readable display name
-status: draft           # REQUIRED: One of: draft, complete, empty
----
-
-Your content goes here after the frontmatter...
-\`\`\`
-
-## Block Types by Section
-
-**Note:** Every section also supports \`section_guide\` blocks for section-specific AI instructions.
-
-### constitution/
-- \`constraint\` - Technical, business, or resource constraints
-- \`implementation_log\` - Implementation tracking for AI agents
-- \`ai_rules\` - Rules and guidelines for AI agents
-- \`context_guide\` - Guide for using this context
-- \`glossary\` - Domain-specific terminology and definitions
-
-### brand/
-- \`brand_positioning\` - Golden Circle (WHY/HOW/WHAT) + Positioning Statement
-- \`brand_color_palette\` - Visual color palette with hex, RGB, and usage
-- \`brand_typography\` - Font families with preview at all sizes
-- \`brand_iconography\` - Icon library selection and style guide
-- \`tone_of_voice\` - Voice archetype, tone attributes, vocabulary
-- \`messaging_framework\` - Elevator pitch, value props, CTAs
-- \`logo\` - Logo assets with multiple background versions
-- \`brand_assets\` - Photography, illustrations, patterns, graphics
-
-### product/
-- \`product_overview\` - Vision, overview, strategy
-- \`feature\` - Feature definitions
-- \`feature_market_analysis\` - Feature competitive analysis
-- \`product_strategy_canvas\` - Product strategy canvas
-
-### business-strategy/
-- \`ogsm\` - Objectives, Goals, Strategies, Measures framework
-- \`obeya_board\` - Visual management board
-- \`swot_analysis\` - SWOT analysis matrix
-- \`business_model_canvas\` - Business model canvas
-- \`porters_five_forces\` - Porter's Five Forces analysis
-- \`strategic_group_map\` - Strategic group mapping
-
-### users/
-- \`persona\` - User personas
-- \`jtbd\` - Jobs to be done
-- \`journey_map\` - User journey maps
-
-### research/
-- \`competitor\` - Competitor analysis
-- \`market_research\` - Market research and insights
-- \`user_research\` - User research findings
-- \`research_data\` - Tabular research data with charts and analysis
-- \`research_document\` - Long-form research documents with insights
-
-### technical/
-- \`tech_stack\` - Technology stack (frontend, backend, infrastructure)
-- \`architecture_diagram\` - C4 model system architecture diagrams
-- \`integration\` - Third-party integrations
-- \`constraint\` - Technical constraints
-- \`dev_setup\` - Local development setup and prerequisites
-- \`api_endpoint\` - Individual API endpoint documentation
-- \`api_spec\` - Complete API specification (collection of endpoints in one file)
-- \`data_model\` - Individual database model/entity
-- \`data_schema\` - Complete database schema (collection of models in one file)
-- \`environment\` - Deployment environment configuration
-- \`testing_strategy\` - Testing philosophy and standards
-- \`cost_calculator\` - Infrastructure and operational costs breakdown
-
-### design-system/
-- \`storybook_link\` - Link to hosted Storybook with authentication
-- \`figma_embed\` - Link to Figma design files
-
-### information-architecture/
-- \`ia_tree\` - Information architecture tree (page hierarchy with links)
-- \`taxonomy\` - Hierarchical classification systems (content types, categories)
-
-### metrics/
-- \`metric\` - Unified metrics (north_star, kpi, supporting, input types via metric_type field)
-- \`analytics_event\` - Analytics event definitions
-
-### decisions/
-- \`decision\` - Architecture Decision Records (ADRs)
-
-### development/
-- \`epic\` - Large initiatives that group user stories
-- \`user_story\` - User-facing features with acceptance criteria
-- \`task\` - Technical implementation tasks / AI agent plans
-- \`roadmap\` - Timeline view of epics and milestones
-- \`impact_effort_matrix\` - Prioritization matrix
-- \`release\` - Release planning
-
-### marketing/
-- \`marketing_campaign\` - Paid advertising campaigns (Meta, Google, LinkedIn, TikTok) with creative assets
-- \`seo_content\` - SEO content strategy and optimization plans
-
-## Example Files
-
-### Tone of Voice Block
-\`\`\`markdown
----
-type: tone_of_voice
-section: brand
-key: brand-voice
-name: Brand Voice
-status: draft
----
-
-# Brand Voice
-
-## Brand Personality
-Professional, helpful, clear, innovative
-
-**Archetype:** The Sage
-
-## We Are...
-- Clear and concise
-- Helpful and supportive
-- Professional yet approachable
-
-## We Are NOT...
-- Overly casual or slangy
-- Condescending or preachy
-\`\`\`
-
-### Persona Block
-\`\`\`markdown
----
-type: persona
-section: users
-key: primary-user
-name: Primary User Persona
-status: draft
-role: Product Manager
-tech_comfort: advanced
-is_primary: true
----
-
-# Sarah - Product Manager
-
-> "I need tools that help me stay organized without adding overhead."
-
-**Role:** Product Manager
-**Primary Persona:** true
-**Tech Comfort:** advanced
-
-## Profile
-
-**Age:** 28-35
-**Education:** Bachelor's
-**Location:** San Francisco
-**Gender:** Female
-**Occupation:** Product Manager
-**Relationship Status:**
-
-**Personality Traits:** Organized, Data-driven, Collaborative
-
-## Motivations
-
-Values efficiency and wants to ensure the team works from a single source of truth.
-
-## Goals
-
-- Ship features faster
-- Keep stakeholders informed
-- Reduce context switching
-
-## Pain Points
-
-- Too many disconnected tools
-- Context switching overhead
-- Hard to keep documentation up to date
-
-## Behaviors
-
-- Uses multiple productivity tools daily
-- Prefers async communication
-- Documents decisions thoroughly
-
-### Tools
-Notion, Slack, Figma, Linear
-
-## Jobs to Be Done
-
-- When I plan a sprint, I want to see all relevant context, so I can make informed prioritization decisions
-\`\`\`
-
-### Decision Block (ADR)
-\`\`\`markdown
----
-type: decision
-section: decisions
-key: database-choice
-name: Database Technology Choice
-status: complete
----
-
-# ADR-001: Database Technology Choice
-
-**Date:** 2024-01-15
-**Status:** Accepted
-
-### Context
-We need to choose a database for our application...
-
-### Decision
-We will use PostgreSQL with Supabase...
-
-### Rationale
-PostgreSQL offers the best balance of features...
-
-### Consequences
-- Need to set up Supabase project
-- Team needs PostgreSQL knowledge
-\`\`\`
-
-### Feature Block
-\`\`\`markdown
----
-type: feature
-section: product
-key: user-auth
-name: User Authentication
-status: draft
----
-
-# User Authentication
-
-Enable users to create accounts and sign in securely.
-
-**Priority:** Must Have
-**Status:** Planned
-
-### User Story
-As a user, I want to create an account so that I can save my preferences.
-
-### Acceptance Criteria
-- Users can sign up with email
-- Users can sign in with password
-- Password reset flow works
-\`\`\`
-
-### Journey Map Block (with Block Reference)
-\`\`\`markdown
----
-type: journey_map
-section: users
-key: user-onboarding
-name: User Onboarding Journey
-status: draft
-persona_ref: primary-user
----
-
-# User Onboarding Journey
-
-A journey map showing how new users get started with our product.
-
-## Phases
-1. Discovery
-2. Sign Up
-3. First Use
-
-## Steps
-
-### Step 1: Landing Page
-**Phase:** Discovery
-**Actions:**
-- User visits homepage
-- Reads value proposition
-
-**Experience:**
-- gain: Clear messaging (impact: 2)
-- pain: Too much information (impact: -1)
-
-**Insights:**
-- Users want quick overview
-\`\`\`
-
-### Information Architecture Block (ia_tree)
-
-IA tree blocks document the application's page hierarchy, navigation structure, and connections between pages. They use embedded JSON in a \`sync:data\` block with a \`tree\` (hierarchy) and \`links\` (connections) structure.
-
-#### Purpose
-- Map out the complete site/app structure visually
-- Show parent-child relationships between pages
-- Document modals, sections, and components within pages
-- **Define connections/links between pages and components**
-- Track page types with visual differentiation
-
-#### Data Structure
-
-The sync:data block contains two top-level properties:
-
-\`\`\`json
-{
-  "tree": { ... },   // The page/node hierarchy (IATreeNode)
-  "links": [ ... ]   // Connections between nodes (IALink[])
-}
-\`\`\`
-
-#### Node Structure (IATreeNode)
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| \`id\` | Yes | Unique identifier (use kebab-case, e.g., "user-settings") |
-| \`label\` | Yes | Display name shown in the UI |
-| \`type\` | Yes | Node type: \`page\`, \`modal\`, \`external\`, or \`node\` |
-| \`url\` | No | Route path for navigable pages (e.g., "/dashboard") |
-| \`description\` | No | Brief description of the page/section purpose |
-| \`position\` | Yes | Visual position: \`{ "x": number, "y": number }\` |
-| \`children\` | No | Array of child nodes |
-| \`subNodes\` | No | Sections/components within this page |
-| \`isNew\` | No | Flag to show "NEW" badge on the node |
-
-#### Node Types (Visual Shapes)
-
-| Type | Visual | Description |
-|------|--------|-------------|
-| \`page\` | Square (sharp corners) | A routable page/screen |
-| \`modal\` | Rounded (large radius) | Modal/dialog overlay |
-| \`external\` | Dashed border | External link |
-| \`node\` | Rounded corners | Generic structural node |
-
-#### Sub-Node Types (Content Areas Within Nodes)
-
-| Type | Description |
-|------|-------------|
-| \`section\` | A major content section |
-| \`component\` | A reusable UI component |
-| \`widget\` | Interactive widget/feature |
-
-Sub-nodes appear inside their parent node and can be the source of links to other nodes.
-
-#### Link Structure (IALink)
-
-Links define relationships and navigation paths between nodes. **IMPORTANT:** You MUST include the \`links\` array to show connections.
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| \`id\` | Yes | Unique ID for the link (e.g., "link-login-to-dashboard") |
-| \`sourceId\` | Yes | ID of the source node |
-| \`targetId\` | Yes | ID of the target node |
-| \`sourceSubNodeId\` | No | If link starts from a sub-node, its ID |
-| \`type\` | Yes | Link type (see below) |
-| \`label\` | No | Description of the connection |
-
-#### Link Types
-
-| Type | Color | Style | Use Case |
-|------|-------|-------|----------|
-| \`action\` | Green (#22c55e) | Solid | User action that navigates (clicks, taps) |
-| \`related\` | Purple (#8b5cf6) | Solid | Related content connection |
-| \`parent\` | Blue (#3b82f6) | Solid | Parent-child hierarchy |
-| \`references\` | Amber (#f59e0b) | Dashed | Content reference/link |
-
-#### Connection Types
-
-**1. Node → Node Connection:**
-\`\`\`json
-{
-  "id": "link-home-to-settings",
-  "sourceId": "home-page",
-  "targetId": "settings-modal",
-  "type": "action",
-  "label": "Opens settings"
-}
-\`\`\`
-
-**2. Sub-Node → Node Connection:**
-\`\`\`json
-{
-  "id": "link-cta-to-signup",
-  "sourceId": "home-page",
-  "sourceSubNodeId": "hero-cta-button",
-  "targetId": "signup-page",
-  "type": "action",
-  "label": "Sign up CTA click"
-}
-\`\`\`
-
-#### Complete Example
-
-\`\`\`markdown
----
-type: ia_tree
-section: information-architecture
-key: app-structure
-name: Application Structure
-status: draft
----
-
-# Application Structure
-
-Complete information architecture showing pages, modals, and navigation flows.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "tree": {
-    "id": "app-root",
-    "label": "Application",
-    "type": "node",
-    "description": "Root application node",
-    "position": { "x": 50, "y": 50 },
-    "children": [
-      {
-        "id": "login",
-        "label": "Login",
-        "type": "page",
-        "url": "/login",
-        "position": { "x": 50, "y": 200 },
-        "subNodes": [
-          { "id": "login-form", "name": "Login Form", "type": "component" },
-          { "id": "forgot-link", "name": "Forgot Password Link", "type": "component" }
-        ]
-      },
-      {
-        "id": "dashboard",
-        "label": "Dashboard",
-        "type": "page",
-        "url": "/dashboard",
-        "description": "Main workspace",
-        "position": { "x": 400, "y": 200 },
-        "subNodes": [
-          { "id": "project-grid", "name": "Project Grid", "type": "section" },
-          { "id": "create-btn", "name": "Create Project Button", "type": "component" }
-        ]
-      },
-      {
-        "id": "new-project",
-        "label": "New Project",
-        "type": "modal",
-        "description": "Create project dialog",
-        "position": { "x": 750, "y": 200 }
-      }
-    ]
-  },
-  "links": [
-    {
-      "id": "link-login-form-to-dashboard",
-      "sourceId": "login",
-      "sourceSubNodeId": "login-form",
-      "targetId": "dashboard",
-      "type": "action",
-      "label": "Successful login"
-    },
-    {
-      "id": "link-forgot-to-reset",
-      "sourceId": "login",
-      "sourceSubNodeId": "forgot-link",
-      "targetId": "password-reset",
-      "type": "action",
-      "label": "Forgot password flow"
-    },
-    {
-      "id": "link-create-btn-to-modal",
-      "sourceId": "dashboard",
-      "sourceSubNodeId": "create-btn",
-      "targetId": "new-project",
-      "type": "action",
-      "label": "Opens create dialog"
-    },
-    {
-      "id": "link-modal-to-dashboard",
-      "sourceId": "new-project",
-      "targetId": "dashboard",
-      "type": "action",
-      "label": "After creation, returns to dashboard"
-    }
-  ]
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
-#### Best Practices
-
-1. **Always include positions for nodes:**
-   Space nodes ~300-400px apart horizontally, ~150-200px vertically to avoid overlap.
-
-2. **Create meaningful connections:**
-   - Every sub-node that leads somewhere should have a link
-   - Data flows should show input → processing → output
-   - User journeys should connect in logical sequence
-
-3. **Use descriptive IDs:**
-   - Node IDs: \`home-page\`, \`settings-modal\`, \`auth-flow\`
-   - Sub-node IDs: \`nav-menu\`, \`hero-cta\`, \`project-list\`
-   - Link IDs: \`link-nav-to-dashboard\`, \`link-cta-to-signup\`
-
-4. **Group related nodes visually:**
-   - Authentication pages together (x: 50-300)
-   - Dashboard pages together (x: 400-700)
-   - Settings/admin together (x: 800-1100)
-
-5. **Choose appropriate link types:**
-   - \`action\`: User clicks/taps to navigate
-   - \`related\`: Content is related but not direct navigation
-   - \`parent\`: Hierarchical relationship
-   - \`references\`: One content references another
-
-#### Common Mistakes
-
-WRONG: Missing links array
-\`\`\`json
-{ "tree": { "id": "root", ... } }
-\`\`\`
-
-CORRECT: Always include links (even if empty)
-\`\`\`json
-{ "tree": { "id": "root", ... }, "links": [] }
-\`\`\`
-
-WRONG: Missing position for nodes
-\`\`\`json
-{ "id": "dashboard", "label": "Dashboard", "type": "page" }
-\`\`\`
-
-CORRECT: Always include position
-\`\`\`json
-{ "id": "dashboard", "label": "Dashboard", "type": "page", "position": { "x": 400, "y": 200 } }
-\`\`\`
-
-WRONG: Link without type
-\`\`\`json
-{ "id": "link-1", "sourceId": "a", "targetId": "b" }
-\`\`\`
-
-CORRECT: Always specify link type
-\`\`\`json
-{ "id": "link-1", "sourceId": "a", "targetId": "b", "type": "action" }
-\`\`\`
-
-### Architecture Diagram Block (C4 Model)
-
-Architecture diagram blocks document system architecture visually using the C4 model (Context, Container, Component). They use embedded JSON in a \`sync:data\` block with \`elements\` and \`connections\`.
-
-#### Purpose
-- Visualize system architecture at different abstraction levels
-- Show how systems, containers, and components interact
-- Document communication patterns and technologies
-- Provide clear diagrams for different audiences (technical, leadership)
-
-#### C4 Model Levels
-
-| Level | Purpose | Shows | Audience |
-|-------|---------|-------|----------|
-| **Context** | Big picture | Systems + external actors | Everyone |
-| **Container** | Applications & data stores | Apps, databases, services within your system | Technical + Leadership |
-| **Component** | Inside a container | Components, modules, classes | Developers, Architects |
-
-#### Data Structure
-
-The sync:data block contains:
-
-\`\`\`json
-{
-  "elements": [ ... ],      // Systems, containers, components, people
-  "connections": [ ... ],   // Communication paths between elements
-  "legend": [ ... ]         // Optional color legend
-}
-\`\`\`
-
-#### Element Structure (ArchitectureElement)
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| \`id\` | Yes | Unique identifier (kebab-case, e.g., "web-app") |
-| \`label\` | Yes | Display name shown in the diagram |
-| \`type\` | Yes | Element type (see types below) |
-| \`description\` | No | Brief description of what this element does |
-| \`technology\` | No | Technology stack (e.g., "React", "Node.js", "PostgreSQL") |
-| \`isExternal\` | No | True if outside your system boundary |
-| \`position\` | Yes | Visual position: \`{ "x": number, "y": number }\` |
-| \`color\` | No | Override default color (hex code) |
-| \`icon\` | No | Lucide icon name for visual representation |
-
-#### Element Types
-
-| Type | Default Color | Description | Visual |
-|------|--------------|-------------|--------|
-| \`system\` | #438DD5 (blue) | Software system (yours or external) | Large box |
-| \`container\` | #438DD5 (blue) | Application, service, database | Medium box |
-| \`component\` | #85BBF0 (light blue) | Module, class, or logical component | Small box |
-| \`person\` | #08427B (dark blue) | User, actor, or role | Person shape |
-| \`database\` | #438DD5 (blue) | Data store (SQL, NoSQL, file) | Cylinder |
-| \`queue\` | #438DD5 (blue) | Message queue, event stream | Rounded box |
-| \`external\` | #999999 (gray) | External system you don't control | Dashed box |
-
-#### Connection Structure (ArchitectureConnection)
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| \`id\` | Yes | Unique ID (e.g., "conn-web-to-api") |
-| \`sourceId\` | Yes | ID of the source element |
-| \`targetId\` | Yes | ID of the target element |
-| \`label\` | No | Description of what flows (e.g., "REST API", "Events") |
-| \`communicationType\` | No | Type of communication (see below) |
-| \`technology\` | No | Protocol or technology (e.g., "HTTPS", "gRPC", "WebSocket") |
-| \`description\` | No | Additional details about the connection |
-
-#### Communication Types
-
-| Type | Arrow Style | Description |
-|------|-------------|-------------|
-| \`sync\` | Solid → | Synchronous request/response |
-| \`async\` | Dashed → | Asynchronous messaging |
-| \`read\` | Solid → (read) | Data read operation |
-| \`write\` | Solid → (write) | Data write operation |
-| \`bidirectional\` | ↔ | Two-way communication |
-
-#### Complete Example
-
-\`\`\`markdown
----
-type: architecture_diagram
-section: technical
-key: system-context
-name: System Context Diagram
-status: draft
-level: context
-audience: non-technical
----
-
-# System Context Diagram
-
-High-level overview of how our application fits into the broader ecosystem.
-
-## Description
-This diagram shows our EpicContext application and how it interacts with external users and systems.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "elements": [
-    {
-      "id": "user",
-      "label": "Product Team",
-      "type": "person",
-      "description": "Uses EpicContext to manage product documentation",
-      "position": { "x": 400, "y": 50 }
-    },
-    {
-      "id": "epiccontext",
-      "label": "EpicContext",
-      "type": "system",
-      "description": "SaaS platform for managing design context documentation",
-      "technology": "Next.js, Supabase",
-      "position": { "x": 400, "y": 250 }
+// Section metadata for modular AI guides
+// Note: "section_guide" is allowed in ALL sections but is a generic/admin type
+const SECTION_INFO = {
+    constitution: {
+        name: "Constitution",
+        description: "Non-negotiable rules for all work",
+        folder: "constitution",
+        blockTypes: ["ai_rules", "context_guide", "constraint", "glossary", "section_guide"],
     },
-    {
-      "id": "ai-agents",
-      "label": "AI Coding Agents",
-      "type": "person",
-      "description": "Claude Code, Cursor, etc. that consume context",
-      "position": { "x": 700, "y": 50 }
+    brand: {
+        name: "Brand",
+        description: "Identity, voice, and visual expression",
+        folder: "brand",
+        blockTypes: ["brand_positioning", "brand_visual_identity", "brand_moodboard", "tone_of_voice", "messaging_framework", "section_guide"],
     },
-    {
-      "id": "supabase",
-      "label": "Supabase",
-      "type": "external",
-      "description": "Backend-as-a-Service for auth and database",
-      "technology": "PostgreSQL",
-      "isExternal": true,
-      "position": { "x": 400, "y": 450 }
+    product: {
+        name: "Product",
+        description: "Vision, features, and roadmap",
+        folder: "product",
+        blockTypes: ["product_overview", "feature", "product_strategy_canvas", "feature_market_analysis", "glossary", "section_guide"],
     },
-    {
-      "id": "clerk",
-      "label": "Clerk",
-      "type": "external",
-      "description": "Authentication provider",
-      "isExternal": true,
-      "position": { "x": 150, "y": 250 }
+    users: {
+        name: "Users & Journeys",
+        description: "Personas, jobs to be done, and user journeys",
+        folder: "users",
+        blockTypes: ["persona", "jtbd", "journey_map", "section_guide"],
     },
-    {
-      "id": "mcp-server",
-      "label": "MCP Server",
-      "type": "system",
-      "description": "Local server that syncs context to codebase",
-      "technology": "Node.js",
-      "position": { "x": 700, "y": 250 }
-    }
-  ],
-  "connections": [
-    {
-      "id": "conn-user-to-app",
-      "sourceId": "user",
-      "targetId": "epiccontext",
-      "label": "Manages documentation",
-      "communicationType": "sync",
-      "technology": "HTTPS"
+    research: {
+        name: "Research",
+        description: "Market, competitors, and insights",
+        folder: "research",
+        blockTypes: ["competitor", "user_research", "research_data", "section_guide"],
     },
-    {
-      "id": "conn-app-to-supabase",
-      "sourceId": "epiccontext",
-      "targetId": "supabase",
-      "label": "Stores data",
-      "communicationType": "sync",
-      "technology": "PostgreSQL/REST"
+    technical: {
+        name: "Technical",
+        description: "Stack, architecture, and constraints",
+        folder: "technical",
+        blockTypes: ["tech_stack", "architecture_diagram", "integration", "constraint", "dev_setup", "api_endpoint", "api_spec", "data_model", "data_schema", "environment", "testing_strategy", "cost_calculator", "section_guide"],
     },
-    {
-      "id": "conn-app-to-clerk",
-      "sourceId": "epiccontext",
-      "targetId": "clerk",
-      "label": "Authenticates users",
-      "communicationType": "sync",
-      "technology": "HTTPS"
+    "design-system": {
+        name: "Design System",
+        description: "Components, tokens, and implementation patterns",
+        folder: "design-system",
+        blockTypes: ["storybook_link", "figma_embed", "section_guide"],
     },
-    {
-      "id": "conn-app-to-mcp",
-      "sourceId": "epiccontext",
-      "targetId": "mcp-server",
-      "label": "Syncs via API",
-      "communicationType": "sync",
-      "technology": "REST API"
+    "information-architecture": {
+        name: "Information Architecture",
+        description: "Site structure and navigation hierarchy",
+        folder: "information-architecture",
+        blockTypes: ["ia_tree", "taxonomy", "section_guide"],
     },
-    {
-      "id": "conn-ai-to-mcp",
-      "sourceId": "ai-agents",
-      "targetId": "mcp-server",
-      "label": "Reads context",
-      "communicationType": "read",
-      "technology": "MCP Protocol"
-    }
-  ],
-  "legend": [
-    { "color": "#08427B", "label": "Person/User" },
-    { "color": "#438DD5", "label": "Our System" },
-    { "color": "#999999", "label": "External System" }
-  ]
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
-#### Container Level Example
-
-\`\`\`markdown
----
-type: architecture_diagram
-section: technical
-key: container-diagram
-name: Container Diagram
-status: draft
-level: container
-audience: technical
----
-
-# Container Diagram
-
-Applications and data stores that make up EpicContext.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "elements": [
-    {
-      "id": "web-app",
-      "label": "Web Application",
-      "type": "container",
-      "description": "SPA for managing context",
-      "technology": "Next.js 14, React, TypeScript",
-      "position": { "x": 200, "y": 100 }
+    metrics: {
+        name: "Metrics",
+        description: "KPIs and analytics",
+        folder: "metrics",
+        blockTypes: ["metric", "north_star", "kpi", "analytics_event", "section_guide"],
     },
-    {
-      "id": "api",
-      "label": "API Routes",
-      "type": "container",
-      "description": "Server-side API endpoints",
-      "technology": "Next.js API Routes",
-      "position": { "x": 500, "y": 100 }
+    decisions: {
+        name: "Decisions",
+        description: "What we decided and why",
+        folder: "decisions",
+        blockTypes: ["decision", "section_guide"],
     },
-    {
-      "id": "database",
-      "label": "Database",
-      "type": "database",
-      "description": "Stores all application data",
-      "technology": "PostgreSQL (Supabase)",
-      "position": { "x": 500, "y": 300 }
+    development: {
+        name: "Development",
+        description: "Epics, user stories, tasks, roadmap, and prioritization",
+        folder: "development",
+        blockTypes: ["epic", "user_story", "task", "roadmap", "impact_effort_matrix", "kanban_board", "section_guide"],
     },
-    {
-      "id": "file-storage",
-      "label": "File Storage",
-      "type": "database",
-      "description": "Stores uploaded assets",
-      "technology": "Supabase Storage",
-      "position": { "x": 200, "y": 300 }
+    "business-strategy": {
+        name: "Business & Strategy",
+        description: "Strategic planning frameworks and business models",
+        folder: "business-strategy",
+        blockTypes: ["ogsm", "business_model_canvas", "swot_analysis", "porters_five_forces", "strategic_group_map", "obeya_board", "section_guide"],
     },
-    {
-      "id": "mcp-package",
-      "label": "MCP Package",
-      "type": "container",
-      "description": "NPM package for local sync",
-      "technology": "Node.js, TypeScript",
-      "position": { "x": 750, "y": 200 }
-    }
-  ],
-  "connections": [
-    {
-      "id": "conn-web-to-api",
-      "sourceId": "web-app",
-      "targetId": "api",
-      "label": "API calls",
-      "communicationType": "sync",
-      "technology": "HTTPS/JSON"
+    marketing: {
+        name: "Marketing",
+        description: "Marketing campaigns, ads, and content strategy",
+        folder: "marketing",
+        blockTypes: ["marketing_campaign", "seo_content", "section_guide"],
     },
-    {
-      "id": "conn-api-to-db",
-      "sourceId": "api",
-      "targetId": "database",
-      "label": "Queries",
-      "communicationType": "bidirectional",
-      "technology": "Supabase Client"
+    environments: {
+        name: "Environments",
+        description: "Environment links, deployments, and release notes",
+        folder: "environments",
+        blockTypes: ["environment_link", "release_note", "section_guide"],
     },
-    {
-      "id": "conn-web-to-storage",
-      "sourceId": "web-app",
-      "targetId": "file-storage",
-      "label": "Uploads/Downloads",
-      "communicationType": "bidirectional",
-      "technology": "Supabase Storage API"
+    reports: {
+        name: "Reports",
+        description: "Business cases, pain point analysis, and user sentiment reports",
+        folder: "reports",
+        blockTypes: ["business_case", "pain_points_report", "user_sentiment_report", "section_guide"],
     },
-    {
-      "id": "conn-mcp-to-api",
-      "sourceId": "mcp-package",
-      "targetId": "api",
-      "label": "Syncs context",
-      "communicationType": "sync",
-      "technology": "REST API"
-    }
-  ]
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
-#### Best Practices
-
-1. **Choose the right level:**
-   - Start with Context for stakeholder communication
-   - Use Container for development planning
-   - Use Component for detailed design of complex containers
-
-2. **Position elements logically:**
-   - Users/actors at top
-   - Your system in the middle
-   - External dependencies at bottom or sides
-   - Space elements ~200-300px apart
-
-3. **Label connections clearly:**
-   - Use verbs: "Reads data", "Sends events", "Authenticates"
-   - Include technology when relevant: "REST API", "gRPC", "WebSocket"
-   - Keep labels concise but informative
-
-4. **Use consistent colors:**
-   - Blue (#438DD5) for your internal systems
-   - Gray (#999999) for external systems
-   - Dark blue (#08427B) for people/users
-   - Add legend for custom colors
-
-5. **Include technology details:**
-   - For Container level: framework, language, runtime
-   - For connections: protocol, message format
-   - Helps developers understand the stack
-
-6. **Keep diagrams focused:**
-   - Context: 3-6 systems maximum
-   - Container: 5-10 containers maximum
-   - Component: 5-15 components maximum
-   - Create multiple diagrams if needed
-
-#### Common Mistakes
-
-WRONG: Missing positions
-\`\`\`json
-{ "id": "api", "label": "API", "type": "container" }
-\`\`\`
-
-CORRECT: Always include positions
-\`\`\`json
-{ "id": "api", "label": "API", "type": "container", "position": { "x": 400, "y": 200 } }
-\`\`\`
-
-WRONG: Vague connection labels
-\`\`\`json
-{ "id": "conn-1", "sourceId": "a", "targetId": "b", "label": "uses" }
-\`\`\`
-
-CORRECT: Specific, actionable labels
-\`\`\`json
-{ "id": "conn-1", "sourceId": "a", "targetId": "b", "label": "Fetches user data", "technology": "REST API" }
-\`\`\`
-
-WRONG: Too many elements on one diagram
-Create separate diagrams for different aspects or zoom levels.
-
-CORRECT: Focused diagrams
-- One Context diagram for the big picture
-- Separate Container diagrams per major system
-- Component diagrams only for complex containers
-
-### Brand Section Blocks
-
-The brand section uses specialized visual block types that store complex data. These blocks use embedded JSON in \`sync:data\` blocks for reliable import/export.
-
-#### Brand Positioning Block
-
-Documents strategic brand positioning using the Golden Circle (WHY/HOW/WHAT) and Positioning Statement frameworks.
-
-**Fields:**
-- \`brand_name\` - Your brand name
-- \`tagline\` - Brand slogan/tagline
-- \`positioning_statement\` - Structured positioning statement
-- \`why_purpose\` - WHY: Why does the brand exist?
-- \`how_approach\` - HOW: How do you deliver on your WHY?
-- \`what_offering\` - WHAT: What products/services do you offer?
-
-**Example:**
-\`\`\`markdown
----
-type: brand_positioning
-section: brand
-key: main-positioning
-name: Brand Positioning
-status: complete
----
-
-# Brand Positioning
-
-Our strategic brand positioning defines why we exist and how we communicate value.
-
-## Brand Identity
-
-**Brand Name:** EpicContext
-**Tagline:** Context for AI, Clarity for Teams
-
-## Positioning Statement
-
-For **product teams who use AI coding agents**,
-**EpicContext** is the **context management platform**
-that **gives AI agents complete product understanding**
-unlike **scattered docs and chat conversations**,
-because **we structure context in AI-native formats**.
-
-## Golden Circle (WHY → HOW → WHAT)
-
-### WHY - The Purpose
-We believe AI coding agents can build better software when they truly understand the product context. We exist to bridge the gap between human knowledge and AI capability.
-
-### HOW - The Unique Approach
-By providing structured, versioned context documentation that syncs directly to codebases and AI tools, with visual editors that make documentation effortless.
-
-### WHAT - The Products/Services
-A SaaS platform with block-based editors for brand, product, users, and technical context, plus MCP integration for Claude and other AI agents.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "brand_name": "EpicContext",
-  "tagline": "Context for AI, Clarity for Teams",
-  "positioning_statement": {
-    "target_market": "product teams who use AI coding agents",
-    "category": "context management platform",
-    "unique_benefit": "gives AI agents complete product understanding",
-    "competitors": "scattered docs and chat conversations",
-    "reason_to_believe": "we structure context in AI-native formats"
-  },
-  "why_purpose": "We believe AI coding agents can build better software when they truly understand the product context. We exist to bridge the gap between human knowledge and AI capability.",
-  "how_approach": "By providing structured, versioned context documentation that syncs directly to codebases and AI tools, with visual editors that make documentation effortless.",
-  "what_offering": "A SaaS platform with block-based editors for brand, product, users, and technical context, plus MCP integration for Claude and other AI agents."
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Brand Color Palette Block
-
-Visual color palette with multiple color definitions including hex, RGB, CMYK, and Pantone values.
-
-**Structure:**
-\`\`\`json
-{
-  "description": "Overview of the color palette",
-  "palette": {
-    "colors": [
-      {
-        "id": "unique-id",
-        "name": "Color Name",
-        "hex": "#RRGGBB",
-        "rgb": "R, G, B",
-        "cmyk": "C, M, Y, K",
-        "pantone": "Pantone Code",
-        "category": "primary|secondary|neutral|accent|semantic",
-        "usage": "When to use this color"
-      }
-    ]
-  },
-  "usage_guidelines": "General color usage guidelines"
-}
-\`\`\`
-
-**Example:**
-\`\`\`markdown
----
-type: brand_color_palette
-section: brand
-key: primary-colors
-name: Primary Brand Colors
-status: complete
----
-
-# Primary Brand Colors
-
-Our primary color palette establishes brand recognition and visual hierarchy.
-
-## Colors
-
-### EpicContext Blue
-- HEX: #3B82F6
-- RGB: 59, 130, 246
-- Usage: Primary actions, links, brand elements
-
-### Success Green
-- HEX: #22C55E
-- RGB: 34, 197, 94
-- Usage: Success states, positive actions
-
-### Dark Gray
-- HEX: #1F2937
-- RGB: 31, 41, 55
-- Usage: Primary text, headings
-
-## Usage Guidelines
-Use EpicContext Blue for primary CTAs and brand elements. Reserve Success Green for positive feedback only.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "description": "Our primary color palette establishes brand recognition and visual hierarchy.",
-  "palette": {
-    "colors": [
-      {
-        "id": "brand-blue",
-        "name": "EpicContext Blue",
-        "hex": "#3B82F6",
-        "rgb": "59, 130, 246",
-        "category": "primary",
-        "usage": "Primary actions, links, brand elements"
-      },
-      {
-        "id": "success-green",
-        "name": "Success Green",
-        "hex": "#22C55E",
-        "rgb": "34, 197, 94",
-        "category": "semantic",
-        "usage": "Success states, positive actions"
-      },
-      {
-        "id": "dark-gray",
-        "name": "Dark Gray",
-        "hex": "#1F2937",
-        "rgb": "31, 41, 55",
-        "category": "neutral",
-        "usage": "Primary text, headings"
-      }
-    ]
-  },
-  "usage_guidelines": "Use EpicContext Blue for primary CTAs and brand elements. Reserve Success Green for positive feedback only."
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Brand Typography Block
-
-Typography system with font family, weights, and preview sizes.
-
-**Structure:**
-\`\`\`json
-{
-  "description": "Overview of typography choices",
-  "typography": {
-    "fontFamily": "Font Name",
-    "fontRole": "primary|secondary|display|code",
-    "fontSource": "google|adobe|system|custom",
-    "fontSourceUrl": "URL to font",
-    "weights": ["400", "500", "600", "700"],
-    "styles": ["normal", "italic"],
-    "usage": "When to use this font"
-  }
-}
-\`\`\`
-
-**Example:**
-\`\`\`markdown
----
-type: brand_typography
-section: brand
-key: primary-typography
-name: Primary Typography
-status: complete
----
-
-# Primary Typography
-
-Our typography system uses Inter for its excellent readability and modern aesthetic.
-
-## Font
-
-**Family:** Inter
-**Role:** Primary (headings and body)
-**Source:** Google Fonts
-
-### Weights
-- 400 (Regular)
-- 500 (Medium)
-- 600 (SemiBold)
-- 700 (Bold)
-
-### Usage
-Use Inter for all UI text, headings, and body copy. Use 600 weight for emphasis, 700 for headings.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "description": "Our typography system uses Inter for its excellent readability and modern aesthetic.",
-  "typography": {
-    "fontFamily": "Inter",
-    "fontRole": "primary",
-    "fontSource": "google",
-    "fontSourceUrl": "https://fonts.google.com/specimen/Inter",
-    "weights": ["400", "500", "600", "700"],
-    "styles": ["normal"],
-    "usage": "Use Inter for all UI text, headings, and body copy. Use 600 weight for emphasis, 700 for headings."
-  }
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Brand Iconography Block
-
-Icon library selection with style settings and curated icon list.
-
-**Structure:**
-\`\`\`json
-{
-  "description": "Overview of iconography style",
-  "iconography": {
-    "library": "lucide|heroicons|phosphor|feather|custom",
-    "style": "outline|solid|duotone",
-    "strokeWidth": 2,
-    "defaultSize": 24,
-    "cornerStyle": "rounded|sharp",
-    "selectedIcons": ["icon-name-1", "icon-name-2"],
-    "usage": "How to use icons"
-  }
-}
-\`\`\`
-
-**Example:**
-\`\`\`markdown
----
-type: brand_iconography
-section: brand
-key: icon-system
-name: Icon System
-status: complete
----
-
-# Icon System
-
-We use Lucide icons with consistent styling across all interfaces.
-
-## Icon Library
-
-**Library:** Lucide
-**Style:** Outline
-**Stroke Width:** 2px
-**Default Size:** 24px
-
-### Selected Brand Icons
-- Home, Search, Settings
-- User, Users, Bell
-- File, Folder, Upload
-
-### Usage Guidelines
-Always use outline style. Maintain 2px stroke width. Use 24px for standard UI, 20px for compact areas.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "description": "We use Lucide icons with consistent styling across all interfaces.",
-  "iconography": {
-    "library": "lucide",
-    "style": "outline",
-    "strokeWidth": 2,
-    "defaultSize": 24,
-    "cornerStyle": "rounded",
-    "selectedIcons": ["home", "search", "settings", "user", "users", "bell", "file", "folder", "upload"],
-    "usage": "Always use outline style. Maintain 2px stroke width. Use 24px for standard UI, 20px for compact areas."
-  }
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Logo Block
-
-Logo assets with multiple background versions and usage guidelines.
-
-**Structure:**
-\`\`\`json
-{
-  "description": "Overview of this logo variant",
-  "logo": {
-    "logoType": "primary|secondary|wordmark|icon|monochrome",
-    "versions": [
-      {
-        "id": "version-id",
-        "url": "https://storage.example.com/logo.svg",
-        "backgroundColor": "#FFFFFF",
-        "backgroundName": "Light Background"
-      }
-    ],
-    "primaryColor": "#3B82F6",
-    "secondaryColor": "#1F2937",
-    "minimumSize": "32px",
-    "clearSpace": "1x logo height",
-    "usageGuidelines": "When and how to use this logo",
-    "donts": "What to avoid"
-  }
-}
-\`\`\`
-
-**Example:**
-\`\`\`markdown
----
-type: logo
-section: brand
-key: primary-logo
-name: Primary Logo
-status: complete
----
-
-# Primary Logo
-
-Our primary logo for use across all brand touchpoints.
-
-## Description
-The primary EpicContext logo combines the mark with the wordmark for maximum brand recognition.
-
-## Logo Versions
-
-### Light Background (#FFFFFF)
-[Logo image on white background]
-
-### Dark Background (#1A1A1A)
-[Logo image on dark background]
-
-## Logo Colors
-- Primary: #3B82F6
-- Secondary: #1F2937
-
-## Sizing
-- Minimum Size: 32px height
-- Clear Space: 1x logo height around all sides
-
-## Usage Guidelines
-Use the full logo on marketing materials, website headers, and official documents. Use the icon only where space is limited.
-
-## Don't
-- Don't stretch or distort the logo
-- Don't change the colors
-- Don't place on busy backgrounds
-- Don't add effects or shadows
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "description": "The primary EpicContext logo combines the mark with the wordmark for maximum brand recognition.",
-  "logo": {
-    "logoType": "primary",
-    "versions": [
-      {
-        "id": "light",
-        "url": "",
-        "backgroundColor": "#FFFFFF",
-        "backgroundName": "Light Background"
-      },
-      {
-        "id": "dark",
-        "url": "",
-        "backgroundColor": "#1A1A1A",
-        "backgroundName": "Dark Background"
-      }
-    ],
-    "primaryColor": "#3B82F6",
-    "secondaryColor": "#1F2937",
-    "minimumSize": "32px",
-    "clearSpace": "1x logo height",
-    "usageGuidelines": "Use the full logo on marketing materials, website headers, and official documents. Use the icon only where space is limited.",
-    "donts": "Don't stretch or distort the logo. Don't change the colors. Don't place on busy backgrounds. Don't add effects or shadows."
-  }
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Brand Assets Block
-
-Visual assets library for photography, illustrations, patterns, and other brand graphics.
-
-**Structure:**
-\`\`\`json
-{
-  "name": "Collection Name",
-  "description": "Overview of this asset collection",
-  "assets": {
-    "assets": [
-      {
-        "id": "unique-id",
-        "category": "photography|illustration|pattern|texture|icon|graphic|template|background|other",
-        "url": "https://storage.example.com/asset.jpg",
-        "name": "Asset Name",
-        "backgroundColor": "#F5F5F5",
-        "description": "Asset description"
-      }
-    ],
-    "sizes": [
-      { "name": "Full", "size": 200 },
-      { "name": "Large", "size": 120 },
-      { "name": "Medium", "size": 64 },
-      { "name": "Small", "size": 32 }
-    ],
-    "dos": "Best practices for using these assets",
-    "donts": "What to avoid",
-    "guidelines": "General usage guidelines"
-  }
-}
-\`\`\`
-
-**Example:**
-\`\`\`markdown
----
-type: brand_assets
-section: brand
-key: photography-library
-name: Photography Library
-status: draft
----
-
-# Photography Library
-
-Our curated photography collection for marketing and product materials.
-
-## Description
-Professional photography that reflects our brand values of clarity, professionalism, and innovation.
-
-## Assets
-
-### photography: Hero Image 1
-[Product screenshot showing the dashboard]
-Clean workspace photography showing our app in use.
-
-### photography: Team Collaboration
-[Team working together]
-Diverse team collaborating in a modern office setting.
-
-## Do's
-- Use high-resolution images (minimum 1200px wide)
-- Maintain consistent lighting and color grading
-- Show real product interfaces when possible
-- Feature diverse representation
-
-## Don'ts
-- Don't use overly staged or stock-looking photos
-- Don't apply heavy filters that alter brand colors
-- Don't use outdated product screenshots
-- Don't crop faces awkwardly
-
-## Guidelines
-All photography should feel authentic and professional. Prefer candid moments over posed shots. Ensure proper model releases for any identifiable people.
-
-<!-- sync:data -->
-\\\`\`\`json
-{
-  "name": "Photography Library",
-  "description": "Professional photography that reflects our brand values of clarity, professionalism, and innovation.",
-  "assets": {
-    "assets": [
-      {
-        "id": "hero-1",
-        "category": "photography",
-        "url": "",
-        "name": "Hero Image 1",
-        "backgroundColor": "#F5F5F5",
-        "description": "Clean workspace photography showing our app in use."
-      },
-      {
-        "id": "team-collab",
-        "category": "photography",
-        "url": "",
-        "name": "Team Collaboration",
-        "backgroundColor": "#F5F5F5",
-        "description": "Diverse team collaborating in a modern office setting."
-      }
-    ],
-    "sizes": [
-      { "name": "Full", "size": 200 },
-      { "name": "Large", "size": 120 },
-      { "name": "Medium", "size": 64 },
-      { "name": "Small", "size": 32 }
-    ],
-    "dos": "Use high-resolution images (minimum 1200px wide). Maintain consistent lighting and color grading. Show real product interfaces when possible. Feature diverse representation.",
-    "donts": "Don't use overly staged or stock-looking photos. Don't apply heavy filters that alter brand colors. Don't use outdated product screenshots. Don't crop faces awkwardly.",
-    "guidelines": "All photography should feel authentic and professional. Prefer candid moments over posed shots. Ensure proper model releases for any identifiable people."
-  }
-}
-\\\`\`\`
-<!-- /sync:data -->
-\`\`\`
-
----
-
-#### Tone of Voice Block
-
-Brand voice personality and communication guidelines.
-
-**Fields:**
-- \`voice_personality\` - Brand personality traits
-- \`voice_archetype\` - Voice archetype (sage, hero, creator, etc.)
-- \`tone_attributes\` - Key tone attributes
-- \`we_are\` - Positive characteristics
-- \`we_are_not\` - What to avoid
-- \`writing_principles\` - Core writing principles
-- \`vocabulary_do\` - Words we use
-- \`vocabulary_dont\` - Words we avoid
-- \`example_good\` - Good copy example
-- \`example_bad\` - Bad copy example
-- \`grammar_style\` - Grammar and style rules
-
-**Example:**
-\`\`\`markdown
----
-type: tone_of_voice
-section: brand
-key: brand-voice
-name: Brand Voice
-status: complete
----
-
-# Brand Voice
-
-## Brand Personality
-Professional, helpful, clear, innovative, empowering
-
-**Archetype:** The Sage - Wise, knowledgeable, trusted advisor
-
-## Tone Attributes
-Confident but not arrogant. Helpful but not patronizing. Technical but accessible. Enthusiastic but measured.
-
-## We Are...
-- Clear and concise
-- Helpful and supportive
-- Confident and knowledgeable
-- Professional yet approachable
-
-## We Are NOT...
-- Overly casual or slangy
-- Condescending or preachy
-- Robotic or cold
-- Vague or ambiguous
-
-## Writing Principles
-1. Lead with the benefit
-2. Use active voice
-3. Be specific, not generic
-4. Respect the reader's time
-
-## Vocabulary
-
-**Words We Use:**
-Context, clarity, empower, streamline, intelligent, seamless, structured
-
-**Words We Avoid:**
-Revolutionary, best-in-class, synergy, leverage (as verb), utilize (use "use")
-
-## Examples
-
-**Good Example:**
-"Save hours every week by giving AI agents the context they need. No more explaining your product from scratch."
-
-**Bad Example:**
-"Our revolutionary AI-powered solution leverages cutting-edge technology to synergize your workflow paradigms."
-
-## Grammar & Style
-- Use sentence case for headings
-- Oxford comma always
-- Numbers under 10 spelled out
-- Contractions are fine (we're, you'll)
-\`\`\`
-
----
-
-#### Messaging Framework Block
-
-External communication: elevator pitch, value props, and CTAs.
-
-**Fields:**
-- \`core_message\` - The single most important message
-- \`elevator_pitch\` - 30-second explanation
-- \`value_prop_1/2/3\` - Key value propositions
-- \`proof_points\` - Evidence and social proof
-- \`audience_specific\` - Audience-tailored messaging
-- \`call_to_action\` - Primary CTA
-- \`secondary_ctas\` - Alternative CTAs
-- \`boilerplate\` - Company description
-
-**Example:**
-\`\`\`markdown
----
-type: messaging_framework
-section: brand
-key: core-messaging
-name: Core Messaging Framework
-status: complete
----
-
-# Core Messaging Framework
-
-## Core Message
-AI coding agents build better software when they understand your product context.
-
-## Elevator Pitch
-EpicContext helps product teams give AI coding agents the context they need to build features that actually match your vision. Instead of explaining your product in every chat, create structured documentation that AI agents can reference automatically.
-
-## Value Propositions
-
-### 1. Save Time
-Stop re-explaining your product in every AI conversation. Document once, reference forever.
-
-### 2. Better AI Output
-AI agents with context produce code that matches your patterns, follows your conventions, and understands your users.
-
-### 3. Team Alignment
-Keep everyone on the same page with a single source of truth for product context.
-
-## Proof Points
-- Teams save 5+ hours per week on context documentation
-- 90% reduction in AI misunderstandings
-- "Finally, AI that understands our product" - CTO, TechCorp
-
-## Audience-Specific Messaging
-
-**For Developers:**
-Write better prompts with less effort. EpicContext gives your AI assistant the background it needs.
-
-**For Product Managers:**
-Ensure AI-built features match your vision. Document requirements once, reference them in every AI interaction.
-
-## Calls to Action
-
-**Primary:** Start Free Trial
-
-**Secondary:** Watch Demo, Read Case Studies, Join Waitlist
-
-## Boilerplate
-EpicContext is the leading context management platform for product teams using AI coding agents. We help teams document and share product context in formats AI agents can understand, resulting in better code and faster development cycles.
-\`\`\`
-
----
-
-#### Best Practices for Brand Blocks
-
-1. **Use specialized block types**: Never use \`text\` for brand content. Each type has specific fields and visual editors.
-
-2. **Include sync:data blocks**: For blocks with complex visual data (colors, typography, icons, logos, assets), always include the \`<!-- sync:data -->\` block with full JSON for reliable import/export.
-
-3. **Be comprehensive**: Fill all relevant fields. Thin brand documentation leads to inconsistent AI-generated content.
-
-4. **Keep it updated**: Brand guidelines change. Update status to \`draft\` when editing, \`complete\` when finalized.
-
-5. **Cross-reference**: Messaging should align with positioning. Colors should be referenced in usage guidelines.
-
----
-
-### Development Section Blocks (Epic → Story → Task)
-
-The development section uses a hierarchical structure to plan and track work. This creates a clear flow from high-level initiatives down to specific implementation tasks.
-
-#### Hierarchy Flow
-
-\`\`\`
-Epic (Large initiative)
-  └── User Story (User-facing feature)
-        └── Task / Agent Plan (Technical implementation)
-\`\`\`
-
-**How AI/Developers Should Use This:**
-1. **Product Owner/User** creates Epics for major initiatives
-2. **Product Owner/User** breaks Epics into User Stories
-3. **AI Agent/Developer** reads Stories and creates Tasks with implementation plans
-4. **AI Agent/Developer** executes Tasks and updates outcomes
-
----
-
-#### Epic Block
-
-An Epic represents a large body of work that delivers significant value. It groups related User Stories.
-
-**Required Fields:**
-- \`summary\` - One-line description
-- \`status\` - todo, in_progress, done
-
-**Key Fields:**
-- \`description\` - Detailed explanation
-- \`priority\` - highest, high, medium, low, lowest
-- \`story_refs\` - Links to child User Stories
-- \`impact_score\` / \`effort_score\` - 1-5 scale for prioritization
-- \`start_date\` / \`due_date\` - Timeline
-- \`labels\` - Comma-separated tags
-
-**Example:**
-\`\`\`markdown
----
-type: epic
-section: development
-key: user-authentication
-name: User Authentication System
-status: draft
-priority: high
-start_date: 2025-01-15
-due_date: 2025-02-28
-labels: security, mvp, phase-1
-story_refs:
-  - email-login
-  - oauth-integration
-  - password-reset
----
-
-# User Authentication System
+};
+/**
+ * Generate the CORE AI guide (slim version without detailed schemas)
+ * This is ~250 lines instead of ~1900 lines
+ */
+function generateCoreAIGuide() {
+    const today = new Date().toISOString().split("T")[0];
+    const allBlockTypes = Object.values(SECTION_INFO)
+        .flatMap(s => s.blockTypes)
+        .filter((v, i, a) => a.indexOf(v) === i) // unique
+        .sort();
+    return `# AI Agent Guide for CONTEXT Folder
 
-Implement a complete authentication system allowing users to securely access their accounts.
+> **For Claude Code, Cursor, and other AI coding agents**
+> This guide explains how to create and structure content in this CONTEXT folder.
 
-## Summary
-Build secure user authentication with email/password and OAuth support.
+## Guide Structure
 
-## Description
-This epic covers all authentication-related features including registration, login, logout, password management, and third-party OAuth integration. The goal is to provide a frictionless yet secure authentication experience.
+This guide is **modular** to reduce context loading:
 
-### Goals
-- Enable secure user registration with email verification
-- Support login via email/password and OAuth (Google, GitHub)
-- Implement password reset flow with secure tokens
-- Add session management with JWT
+- **This file (AI-GUIDE.md)**: Core rules, block type list, navigation (~250 lines)
+- **Section guides (.ai-guides/)**: Detailed schemas for each section (~200-400 lines each)
 
-### Success Criteria
-- Users can create accounts and verify email
-- Login works with email/password and OAuth providers
-- Password reset emails arrive within 30 seconds
-- Sessions expire after 24 hours of inactivity
+**Load only what you need:**
+1. Always read this core guide first
+2. Then read the section guide for the section you're working on
 
-### Out of Scope
-- Two-factor authentication (planned for Phase 2)
-- Social login beyond Google/GitHub
+\`\`\`
+CONTEXT/
+├── AI-GUIDE.md                    ← You are here (core rules)
+├── .ai-guides/
+│   ├── brand-guide.md             ← Brand section schemas
+│   ├── development-guide.md       ← Development section schemas
+│   ├── product-guide.md           ← Product section schemas
+│   ├── users-guide.md             ← Users section schemas
+│   └── ...                        ← Other section guides
 \`\`\`
 
 ---
 
-#### User Story Block
-
-A User Story describes a feature from the user's perspective. It belongs to an Epic and can have Tasks.
-
-**Required Fields:**
-- \`summary\` - Brief description
-- \`status\` - todo, in_progress, in_review, done
-
-**Key Fields:**
-- \`user_story\` - "As a [role], I want [goal], so that [benefit]" format
-- \`acceptance_criteria\` - Testable conditions (Given/When/Then)
-- \`epic_ref\` - Link to parent Epic
-- \`story_points\` - 1, 2, 3, 5, 8, 13, 21 (Fibonacci)
-- \`priority\` - highest, high, medium, low, lowest
-- \`impact_score\` / \`effort_score\` - 1-5 scale
-- \`sprint\` - Sprint assignment
-
-**Example:**
-\`\`\`markdown
----
-type: user_story
-section: development
-key: email-login
-name: Email Login
-status: draft
-priority: high
-story_points: 5
-impact_score: 5
-effort_score: 3
-epic_ref: user-authentication
-sprint: Sprint 1
----
+## CRITICAL RULES - READ FIRST
 
-# Email Login
+### BLOCK TYPE ENFORCEMENT
 
-Allow users to securely log in with their email and password.
+**ONLY use block types from the Valid Block Types list below.** Using undefined types will:
+- Show "No schema defined" in the UI
+- Lose all content when synced
+- Break import/export
 
-## Summary
-Implement email/password authentication with proper security measures.
+### DO:
+- **ONLY use block types listed in this guide**
+- Create **ONE FILE PER BLOCK** (one user story = one file)
+- Use the **exact folder structure** shown below
+- Include **YAML frontmatter** with type, section, key, name, status
+- Use **kebab-case** for keys and filenames
+- **Read the section guide** for detailed schemas before creating blocks
 
-## User Story
-As a registered user, I want to log in with my email and password, so that I can access my account securely and quickly.
+### DO NOT:
+- ❌ **Invent new block types** - if it's not in this guide, it doesn't exist
+- ❌ Create a single large file with multiple items
+- ❌ Put files in wrong folders
+- ❌ Use generic markdown without frontmatter
+- ❌ Skip reading the section guide for detailed schemas
 
-## Description
-Users need a fast and secure way to access their accounts. The login form should validate input, show helpful error messages, and redirect to the dashboard on success.
+### LANGUAGE CONSISTENCY
 
-## Acceptance Criteria
+**CRITICAL:** All content must be in ONE consistent language.
+Check existing CONTEXT files to determine the project's language.
 
-### Scenario: Successful login
-- Given I am on the login page
-- When I enter a valid email and correct password
-- Then I am redirected to the dashboard
-- And I see a welcome message with my name
+---
 
-### Scenario: Invalid credentials
-- Given I am on the login page
-- When I enter an invalid email or wrong password
-- Then I see an error message "Invalid email or password"
-- And I remain on the login page
-- And the password field is cleared
+## Valid Block Types (Quick Reference)
 
-### Scenario: Rate limiting
-- Given I have failed login 5 times in 5 minutes
-- When I try to login again
-- Then I see "Too many attempts. Please try again in 15 minutes"
+These are the ONLY valid values for \`type:\` in frontmatter:
 
-## Technical Notes
-- Use bcrypt for password hashing (cost factor 12)
-- Implement rate limiting: 5 attempts per 5 minutes per IP
-- Generate JWT with 24h expiry
-- Store refresh token in httpOnly cookie
 \`\`\`
+${allBlockTypes.join(", ")}
+\`\`\`
+
+**For detailed schemas, see the section guide in \`.ai-guides/\`**
 
 ---
 
-#### Task / Agent Plan Block
+## Block Type → Section → Folder Reference
 
-A Task contains the technical implementation plan. AI coding agents (Claude Code, Cursor, etc.) should create Tasks when planning work.
+| Block Type | Section | Folder | Guide |
+|------------|---------|--------|-------|
+${Object.entries(SECTION_INFO).flatMap(([key, info]) => info.blockTypes.map(bt => `| \`${bt}\` | ${info.name} | \`${info.folder}/\` | \`.ai-guides/${info.folder}-guide.md\` |`)).join("\n")}
 
-**Required Fields:**
-- \`description\` - What needs to be done
-- \`status\` - planned, todo, in_progress, in_review, done, abandoned
+---
 
-**Key Fields:**
-- \`story_ref\` - Link to parent User Story
-- \`plan_steps\` - Step-by-step implementation plan
-- \`agent_source\` - manual, claude_code, cursor, copilot, windsurf, aider, other_ai
-- \`files_affected\` - List of files to create/modify
-- \`codebase_context\` - Relevant architecture notes
-- \`technical_notes\` - Implementation details
-- \`dependencies\` - Prerequisites or packages needed
-- \`estimated_hours\` - Time estimate
-- \`outcome\` - Results after completion
+## Universal File Template
 
-**Example (AI Agent Plan):**
 \`\`\`markdown
 ---
-type: task
-section: development
-key: implement-login-api
-name: Implement Login API Endpoint
+type: [block_type]
+section: [section_type]
+key: [unique-kebab-case-key]
+name: "Human Readable Name"
 status: draft
-priority: high
-agent_source: claude_code
-story_ref: email-login
-estimated_hours: 4
+created: ${today}
+updated: ${today}
 ---
 
-# Implement Login API Endpoint
-
-Create the POST /api/auth/login endpoint that validates credentials and returns JWT tokens.
-
-## Description
-Implement the login API endpoint with proper validation, rate limiting, and token generation.
-
-## Implementation Plan
-
-### Step 1: Create Login Route Handler
-Create \`app/api/auth/login/route.ts\` with POST handler:
-- Accept email and password in request body
-- Validate input format using zod schema
-- Return 400 for invalid input with specific error messages
-
-### Step 2: Implement User Lookup
-Query the users table by email:
-- Use Supabase client with service role for server-side
-- Return generic "Invalid credentials" to prevent email enumeration
-- Handle case-insensitive email matching
-
-### Step 3: Password Verification
-Compare provided password with stored hash:
-- Use bcrypt.compare() for timing-safe comparison
-- Log failed attempts for security monitoring
-- Increment rate limit counter on failure
-
-### Step 4: Generate JWT Tokens
-On successful authentication:
-- Generate access token (24h expiry) with user ID and email
-- Generate refresh token (7d expiry) stored in httpOnly cookie
-- Include minimal claims to reduce token size
-
-### Step 5: Implement Rate Limiting
-Add rate limiting middleware:
-- Use Redis or in-memory store for attempt tracking
-- Key by IP address + email combination
-- Block after 5 failed attempts for 15 minutes
-- Return 429 with Retry-After header
-
-### Step 6: Add Tests
-Create \`app/api/auth/login/route.test.ts\`:
-- Test successful login returns tokens
-- Test invalid email format returns 400
-- Test wrong password returns 401
-- Test rate limiting blocks after 5 attempts
-
-## Files Affected
-- \`app/api/auth/login/route.ts\` (create)
-- \`lib/auth/jwt.ts\` (create)
-- \`lib/auth/password.ts\` (create)
-- \`lib/middleware/rate-limit.ts\` (create)
-- \`app/api/auth/login/route.test.ts\` (create)
-
-## Codebase Context
-- Using Next.js 14 App Router
-- Supabase for database and auth
-- JWT library: jose
-- Password hashing: bcrypt
-- Validation: zod
-
-## Dependencies
-- jose (JWT handling)
-- bcrypt (password hashing)
-- zod (validation)
-
-## Technical Notes
-- Follow existing API patterns in \`app/api/\` folder
-- Use \`@/lib/supabase/server\` for database access
-- Error responses should match the ErrorResponse type in \`types/api.ts\`
-\`\`\`
-
----
+# Title
 
-#### Roadmap Block
-
-A Roadmap provides a timeline view of Epics across time periods (quarters, months, sprints).
-
-**Key Fields:**
-- \`description\` - Purpose of this roadmap
-- \`timeline\` - Visual timeline data with columns and epic placements
-- \`notes\` - Additional context, risks, assumptions
-
-**Timeline Structure:**
-\`\`\`json
-{
-  "columns": [
-    { "id": "q1-2025", "name": "Q1 2025", "period": "quarter" },
-    { "id": "q2-2025", "name": "Q2 2025", "period": "quarter" }
-  ],
-  "items": [
-    {
-      "epicRef": "user-authentication",
-      "startColumn": "q1-2025",
-      "spanColumns": 1,
-      "row": 0
-    }
-  ],
-  "settings": { "defaultPeriod": "quarter" }
-}
+[Content following the block type schema from section guide]
 \`\`\`
 
 ---
 
-#### Workflow: From User Request to Implementation
+## Which Block Type Should I Use?
 
-**1. User/Product Owner Creates Epic:**
-\`\`\`
-"We need user authentication for the MVP"
-  → Create Epic: user-authentication
-  → Set priority: high
-  → Set dates: Q1 2025
-\`\`\`
+| What You're Documenting | Block Type | Folder |
+|------------------------|------------|--------|
+| User persona | \`persona\` | \`users/personas/\` |
+| Job to be done | \`jtbd\` | \`users/jobs-to-be-done/\` |
+| User journey | \`journey_map\` | \`users/journey-maps/\` |
+| Product vision | \`product_overview\` | \`product/\` |
+| Feature | \`feature\` | \`product/features/\` |
+| Large initiative (weeks) | \`epic\` | \`development/epics/\` |
+| User story (days) | \`user_story\` | \`development/stories/\` |
+| Technical task (hours) | \`task\` | \`development/tasks/\` |
+| Brand positioning | \`brand_positioning\` | \`brand/\` |
+| Visual identity | \`brand_visual_identity\` | \`brand/\` |
+| Tone of voice | \`tone_of_voice\` | \`brand/\` |
+| Architecture decision | \`decision\` | \`decisions/\` |
+| Technical constraint | \`constraint\` | \`technical/\` |
+| External service | \`integration\` | \`technical/integrations/\` |
+| Competitor analysis | \`competitor\` | \`research/competitors/\` |
+| Site structure | \`ia_tree\` | \`information-architecture/\` |
+| Metric/KPI | \`metric\` | \`metrics/\` |
 
-**2. User/Product Owner Breaks Down Stories:**
-\`\`\`
-Epic: user-authentication
-  → Story: email-login (5 points)
-  → Story: oauth-integration (8 points)
-  → Story: password-reset (3 points)
-\`\`\`
+---
 
-**3. AI Agent Reads Story and Plans:**
-\`\`\`
-AI reads: email-login story
-  → Creates Task: implement-login-api (4 hours)
-  → Creates Task: build-login-form (3 hours)
-  → Creates Task: add-login-tests (2 hours)
-\`\`\`
+## Context Navigation
 
-**4. AI Agent Executes and Documents:**
-\`\`\`
-Task: implement-login-api
-  → Status: in_progress
-  → [AI implements code]
-  → Status: done
-  → Outcome: "Completed. Added rate limiting as discussed."
-\`\`\`
+**Read enough to answer these questions, then stop:**
+1. What should I build? (from task/story)
+2. Who am I building it for? (from persona)
+3. What constraints apply? (from constitution/technical)
+4. How should it look/behave? (from brand/design system)
+
+**Link Priority:**
+- **ALWAYS READ:** \`constitution/\`, parent refs (\`story_ref\`, \`epic_ref\`)
+- **IF RELEVANT:** \`personas_ref\`, \`decisions_ref\`, \`integrations_ref\`
+- **SKIP UNLESS NEEDED:** Sibling blocks, metrics, competitors
 
 ---
 
-#### Best Practices for AI Agents
+## Linking Blocks
 
-1. **Read the Story First**: Before creating tasks, fully understand the user story and acceptance criteria.
+Key relationships (use exact \`key\` values from target blocks):
 
-2. **Break Down Thoughtfully**: Create tasks that are:
-   - Independently testable
-   - 2-8 hours of work each
-   - Clearly scoped with specific files
+| From | Field | To | Required? |
+|------|-------|---|-----------|
+| \`user_story\` | \`epic_ref\` | \`epic\` | **Yes** |
+| \`task\` | \`story_ref\` | \`user_story\` | **Yes** |
+| \`journey_map\` | \`persona_ref\` | \`persona\` | **Yes** |
+| \`jtbd\` | \`persona_ref\` | \`persona\` | No |
+| \`feature\` | \`personas_ref\` | \`persona\` | No |
+| \`epic\` | \`product_ref\` | \`product_overview\` | No |
 
-3. **Document Your Plan**: In \`plan_steps\`, explain:
-   - What you'll do in each step
-   - Why you're making certain choices
-   - What files you'll touch
+---
 
-4. **Track Codebase Context**: Note relevant:
-   - Existing patterns to follow
-   - Related code to reference
-   - Constraints or dependencies
+## Syncing with EpicContext
 
-5. **Update Outcomes**: After completing a task, document:
-   - What was actually done
-   - Any deviations from the plan
-   - Issues encountered and how they were resolved
+\`\`\`bash
+npx @epiccontext/mcp push   # Push local changes to cloud
+npx @epiccontext/mcp pull   # Pull cloud changes to local
+npx @epiccontext/mcp status # Check sync status
+\`\`\`
 
 ---
 
-### Design System Blocks
-
-#### Storybook Link Block
+## Section Guides Reference
 
-A Storybook Link connects your EpicContext project to a deployed Storybook design system with authentication.
+For detailed block schemas, examples, and guidelines, read the appropriate section guide:
 
-**Key Fields:**
-- \`name\` - Display name for the Storybook
-- \`url\` - Deployed Storybook URL (Vercel, Netlify, etc.)
-- \`description\` - What's documented in this Storybook
-- \`requires_auth\` - Enable EpicContext authentication
-- \`auth_secret\` - Shared secret for token validation
-- \`tokens_path\` - URL path to design tokens docs
-- \`components_path\` - URL path to component docs
-- \`repo_url\` - Git repository URL (optional)
+| Section | Guide File | Block Types |
+|---------|-----------|-------------|
+${Object.entries(SECTION_INFO).map(([key, info]) => `| ${info.name} | \`.ai-guides/${info.folder}-guide.md\` | ${info.blockTypes.length} types |`).join("\n")}
 
-**Example:**
-\`\`\`markdown
----
-type: storybook_link
-section: design-system
-key: main-storybook
-name: Design System Storybook
-status: complete
 ---
 
-# Design System Storybook
+*Core AI guide - auto-generated by EpicContext CLI*
+*Generated: ${new Date().toISOString()}*
 
-Component library, design tokens, and usage guidelines.
-
-**URL:** https://design-system.yourcompany.vercel.app
-**Repository:** https://github.com/yourcompany/design-system
-**Authentication:** Enabled (EpicContext SSO)
-
-## Quick Links
-- [Design Tokens](https://design-system.yourcompany.vercel.app?path=/docs/tokens-colors--docs)
-- [Components](https://design-system.yourcompany.vercel.app?path=/docs/components-button--docs)
+**Next step:** Read the section guide for the section you're working on.
+`;
+}
+/**
+ * Generate a section-specific guide
+ */
+function generateSectionGuide(sectionKey) {
+    const info = SECTION_INFO[sectionKey];
+    if (!info)
+        return null;
+    const today = new Date().toISOString().split("T")[0];
+    return `# ${info.name} Section Guide
 
-## Categories
-Tokens, Components, Patterns
-\`\`\`
+> ${info.description}
+> Folder: \`CONTEXT/${info.folder}/\`
 
-**Setting Up Protected Storybook:**
+This guide contains detailed schemas and examples for this section.
+For core rules and navigation, see \`CONTEXT/AI-GUIDE.md\`.
 
-1. Clone the EpicContext Storybook template:
-   \`\`\`bash
-   npx degit epiccontext/storybook-template my-design-system
-   cd my-design-system && npm install
-   \`\`\`
-2. Deploy to Vercel: \`npx vercel\`
-3. In EpicContext, create a Storybook Link block and click "Generate Secret"
-4. Add \`EPICCONTEXT_STORYBOOK_SECRET\` to Vercel environment variables
-5. Add your Storybook URL to the block
-6. Team members can access via "Open Storybook" in EpicContext UI
+---
 
-The template includes middleware that validates JWT tokens signed by EpicContext, providing SSO-style access to your design system.
+## Block Types in This Section
 
-**Template Repository:** https://github.com/epiccontext/storybook-template
+| Block Type | Description | File Location |
+|------------|-------------|---------------|
+${info.blockTypes.map(bt => `| \`${bt}\` | See schema below | \`${info.folder}/\` |`).join("\n")}
 
 ---
 
-## Block References
+## Detailed Block Schemas
+
+${info.blockTypes.map(bt => `### ${bt}
 
-Some blocks can reference other blocks using reference fields in frontmatter:
+**Type:** \`${bt}\`
+**Section:** ${sectionKey}
+**File Location:** \`${info.folder}/[name].md\`
 
-### Single Reference (one-to-one)
+**Required Frontmatter:**
 \`\`\`yaml
 ---
-type: journey_map
-section: users
-key: user-onboarding
-persona_ref: primary-user    # References a persona block
+type: ${bt}
+section: ${sectionKey}
+key: example-${bt.replace(/_/g, "-")}
+name: "Example ${bt.split("_").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}"
+status: draft
+created: ${today}
+updated: ${today}
 ---
 \`\`\`
 
-### Multiple References (one-to-many)
-\`\`\`yaml
----
-type: epic
-section: development
-key: authentication-epic
-stories_ref:                 # References multiple user_story blocks
-  - login-story
-  - signup-story
-  - password-reset-story
+**Content:** Follow the standard block structure with appropriate headings for this block type.
+
 ---
-\`\`\`
+`).join("\n")}
 
-### Common Reference Fields
-| Field | Used In | References |
-|-------|---------|------------|
-| \`persona_ref\` | journey_map, jtbd | persona block |
-| \`epic_ref\` | user_story | epic block |
-| \`story_ref\` | task | user_story block |
-| \`stories_ref\` | epic | user_story blocks |
-| \`product_ref\` | feature, epic | product overview block |
+*Section guide for ${info.name} - auto-generated by EpicContext CLI*
+*Generated: ${new Date().toISOString()}*
+`;
+}
+/**
+ * Generate all section guides in the .ai-guides folder
+ */
+function generateSectionGuides(aiGuidesDir) {
+    for (const [sectionKey, info] of Object.entries(SECTION_INFO)) {
+        const guideContent = generateSectionGuide(sectionKey);
+        if (guideContent) {
+            const guidePath = path.join(aiGuidesDir, `${info.folder}-guide.md`);
+            if (!fs.existsSync(guidePath)) {
+                fs.writeFileSync(guidePath, guideContent, "utf-8");
+            }
+        }
+    }
+}
+/**
+ * Read all markdown files from a directory recursively
+ */
+export function readContextFolder(contextPath) {
+    const files = [];
+    if (!fs.existsSync(contextPath)) {
+        return files;
+    }
+    function walkDir(dir, relativeTo) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativePath = path.relative(relativeTo, fullPath);
+            if (entry.isDirectory()) {
+                // Skip hidden directories and node_modules
+                if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
+                    walkDir(fullPath, relativeTo);
+                }
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                // Skip README and AI-GUIDE
+                const lowerName = entry.name.toLowerCase();
+                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md") {
+                    const content = fs.readFileSync(fullPath, "utf-8");
+                    files.push({
+                        path: relativePath,
+                        content,
+                    });
+                }
+            }
+        }
+    }
+    walkDir(contextPath, contextPath);
+    return files;
+}
+/**
+ * Write files to the context folder
+ * By default, skips files where local version is newer than cloud version
+ */
+export function writeContextFolder(contextPath, files, options = {}) {
+    let written = 0;
+    let skipped = 0;
+    const skippedPaths = [];
+    for (const file of files) {
+        const fullPath = path.join(contextPath, file.path);
+        const dir = path.dirname(fullPath);
+        // Create directory if needed
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Always overwrite AI-GUIDE.md (it's server-generated and should be authoritative)
+        // This ensures users get the latest block type definitions on every pull
+        const isAIGuide = file.path.toLowerCase() === "ai-guide.md";
+        // Check if local file is newer than cloud version (unless force is set or it's AI-GUIDE.md)
+        if (!options.force && !isAIGuide && file.updatedAt && fs.existsSync(fullPath)) {
+            const localMtime = getFileModTime(fullPath);
+            const cloudMtime = new Date(file.updatedAt);
+            if (localMtime && localMtime > cloudMtime) {
+                // Local file is newer, skip overwriting
+                skipped++;
+                skippedPaths.push(file.path);
+                continue;
+            }
+        }
+        // Write file
+        try {
+            fs.writeFileSync(fullPath, file.content, "utf-8");
+            written++;
+        }
+        catch (error) {
+            console.error(`Failed to write ${file.path}:`, error);
+            skipped++;
+        }
+    }
+    return { written, skipped, skippedPaths };
+}
+/**
+ * Delete local files that don't exist in the cloud
+ * Used during pull to remove files that were deleted in the UI
+ */
+export function deleteOrphanedLocalFiles(contextPath, cloudFiles) {
+    // Build a set of all cloud file paths (normalized)
+    const cloudPaths = new Set();
+    for (const file of cloudFiles) {
+        cloudPaths.add(file.path);
+    }
+    // Get all local markdown files
+    const localFiles = readContextFolder(contextPath);
+    const deleted = [];
+    for (const localFile of localFiles) {
+        // If local file doesn't exist in cloud, delete it
+        if (!cloudPaths.has(localFile.path)) {
+            const fullPath = path.join(contextPath, localFile.path);
+            try {
+                fs.unlinkSync(fullPath);
+                deleted.push(localFile.path);
+            }
+            catch (error) {
+                console.error(`Failed to delete ${localFile.path}:`, error);
+            }
+        }
+    }
+    return { deleted: deleted.length, deletedPaths: deleted };
+}
+/**
+ * Ensure the context folder exists with basic structure
+ */
+export function ensureContextFolder(contextPath) {
+    if (!fs.existsSync(contextPath)) {
+        fs.mkdirSync(contextPath, { recursive: true });
+    }
+    // Create default section folders
+    // Note: folder names use hyphens, but section types in the app use underscores
+    const defaultSections = [
+        "constitution",
+        "brand",
+        "product",
+        "business-strategy",
+        "users",
+        "research",
+        "technical",
+        "design-system",
+        "information-architecture",
+        "metrics",
+        "decisions",
+        "development",
+        "marketing",
+        "environments",
+        "reports",
+    ];
+    for (const section of defaultSections) {
+        const sectionPath = path.join(contextPath, section);
+        if (!fs.existsSync(sectionPath)) {
+            fs.mkdirSync(sectionPath, { recursive: true });
+        }
+    }
+    // Create README.md
+    const readmePath = path.join(contextPath, "README.md");
+    if (!fs.existsSync(readmePath)) {
+        const readme = `# CONTEXT
 
-## Important Rules
+This folder contains product context documentation synced with EpicContext.
 
-1. **Always include all 5 frontmatter fields** (type, section, key, name, status)
-2. **The \`section\` field must match the folder name** (e.g., files in \`brand/\` must have \`section: brand\`)
-3. **The \`key\` must be unique within the section** (use kebab-case, no spaces)
-4. **Always use specific block types** - each section has its own block types, never use generic \`text\`
-5. **Set \`status: draft\` for new content** and \`status: complete\` when finalized
+## IMPORTANT: File Format
 
-## Common Mistakes to Avoid
+**All markdown files MUST have YAML frontmatter with these required fields:**
 
-WRONG: Using \`title\` and \`description\` instead of proper frontmatter
 \`\`\`yaml
 ---
-title: My Document        # WRONG - not recognized
-description: About this   # WRONG - not recognized
+type: persona       # Block type (persona, feature, decision, etc.)
+section: brand      # Section name (must match folder name)
+key: unique-key     # Unique identifier (use kebab-case)
+name: Display Name  # Human-readable name
+status: draft       # Status: draft, complete, or empty
 ---
 \`\`\`
 
-CORRECT: Using the required frontmatter fields
-\`\`\`yaml
----
-type: tone_of_voice
-section: brand
-key: brand-voice
-name: Brand Voice
-status: draft
----
-\`\`\`
+See \`AI-GUIDE.md\` for detailed format instructions.
 
-WRONG: Missing required fields
-\`\`\`yaml
----
-type: persona
-name: My Persona
-# Missing: section, key, status
----
+## Structure
+
+Each folder represents a section of your product documentation:
+
+- \`constitution/\` - Non-negotiable rules and principles
+- \`brand/\` - Identity, voice, and visual system
+- \`product/\` - Vision, features, and roadmap
+- \`business-strategy/\` - Strategic planning and business models
+- \`users/\` - Personas, jobs to be done, and user journeys
+- \`research/\` - Market and competitor analysis
+- \`technical/\` - Stack, architecture, and constraints
+- \`design-system/\` - Links to Storybook and Figma
+- \`information-architecture/\` - Site structure and taxonomies
+- \`metrics/\` - KPIs and analytics
+- \`decisions/\` - Architecture decision records
+- \`development/\` - Epics, stories, tasks, and roadmaps
+- \`marketing/\` - Marketing campaigns and SEO content strategy
+
+## Syncing
+
+This folder is synced with your EpicContext project using the MCP server.
+
+To sync changes:
+\`\`\`bash
+epicontext sync
 \`\`\`
 
-CORRECT: All required fields present
-\`\`\`yaml
----
-type: persona
-section: users
-key: primary-user
-name: Primary User
-status: draft
----
+To watch for changes and auto-sync:
+\`\`\`bash
+epicontext watch
 \`\`\`
 `;
+        fs.writeFileSync(readmePath, readme, "utf-8");
+    }
+    // Create .ai-guides folder for modular section guides
+    const aiGuidesDir = path.join(contextPath, ".ai-guides");
+    if (!fs.existsSync(aiGuidesDir)) {
+        fs.mkdirSync(aiGuidesDir, { recursive: true });
+    }
+    // Generate section-specific guides
+    generateSectionGuides(aiGuidesDir);
+    // Create AI-GUIDE.md (slim core version) with detailed format instructions
+    const aiGuidePath = path.join(contextPath, "AI-GUIDE.md");
+    if (!fs.existsSync(aiGuidePath)) {
+        const aiGuide = generateCoreAIGuide();
         fs.writeFileSync(aiGuidePath, aiGuide, "utf-8");
     }
     // Create README.md for each section with detailed guidance
@@ -2322,19 +573,17 @@ status: draft
 - **Glossary**: Domain-specific terminology and definitions
 
 This is the first section AI agents should read to understand project boundaries.`,
-            blockTypes: ["ai_rules", "context_guide", "constraint", "implementation_log", "glossary"],
+            blockTypes: ["ai_rules", "context_guide", "constraint", "glossary", "section_guide"],
         },
         "brand": {
             description: "Identity, voice, and visual system",
             guidance: `Use this section to document:
 - **Brand Positioning**: Golden Circle (WHY/HOW/WHAT) and positioning statement
-- **Color Palette**: Primary, secondary, and semantic colors with hex/RGB values
-- **Typography**: Font families, weights, and usage guidelines
-- **Iconography**: Icon library, style, and selected icons
+- **Visual Identity**: Colors, typography, logo, icons, assets combined (use brand_visual_identity)
+- **Brand Moodboard**: Inspiration and reference images for brand development
 - **Tone of Voice**: Brand personality, voice archetype, vocabulary
-- **Messaging**: Elevator pitch, value propositions, CTAs
-- **Logos**: Logo variants for different backgrounds`,
-            blockTypes: ["brand_positioning", "brand_color_palette", "brand_typography", "brand_iconography", "tone_of_voice", "messaging_framework", "logo", "brand_assets"],
+- **Messaging**: Elevator pitch, value propositions, CTAs`,
+            blockTypes: ["brand_positioning", "brand_visual_identity", "brand_moodboard", "tone_of_voice", "messaging_framework", "section_guide"],
         },
         "product": {
             description: "Vision, features, and roadmap",
@@ -2342,8 +591,9 @@ This is the first section AI agents should read to understand project boundaries
 - **Product Overview**: Vision, mission, and product strategy
 - **Features**: Individual feature definitions with acceptance criteria
 - **Product Strategy Canvas**: Product-specific strategy and goals
-- **Feature Market Analysis**: Competitive analysis for specific features`,
-            blockTypes: ["product_overview", "feature", "product_strategy_canvas", "feature_market_analysis"],
+- **Feature Market Analysis**: Competitive analysis for specific features
+- **Glossary**: Domain-specific terminology and definitions`,
+            blockTypes: ["product_overview", "feature", "product_strategy_canvas", "feature_market_analysis", "glossary", "section_guide"],
         },
         "business-strategy": {
             description: "Strategic planning frameworks and business models",
@@ -2354,7 +604,7 @@ This is the first section AI agents should read to understand project boundaries
 - **Porter's Five Forces**: Competitive forces analysis
 - **Strategic Group Map**: Market positioning visualization
 - **Obeya Board**: Visual management board`,
-            blockTypes: ["ogsm", "business_model_canvas", "swot_analysis", "porters_five_forces", "strategic_group_map", "obeya_board"],
+            blockTypes: ["ogsm", "business_model_canvas", "swot_analysis", "porters_five_forces", "strategic_group_map", "obeya_board", "section_guide"],
         },
         "users": {
             description: "Personas, jobs to be done, and user journeys",
@@ -2367,19 +617,17 @@ Organize files in subfolders:
 - \`personas/\` - User persona files
 - \`jobs-to-be-done/\` - JTBD files
 - \`journey-maps/\` - Journey map files`,
-            blockTypes: ["persona", "jtbd", "journey_map"],
+            blockTypes: ["persona", "jtbd", "journey_map", "section_guide"],
         },
         "research": {
             description: "Market and competitor analysis",
             guidance: `Use this section to document:
 - **Competitors**: Analysis of competing products/services
-- **Market Research**: Market size, trends, and opportunities
-- **User Research**: Findings from user interviews, usability tests
+- **User Research**: Research documents with highlights and key insights
 - **Research Data**: Tabular research data with charts and analysis
-- **Research Documents**: Long-form research documents with insights
 
-Organize files in subfolders: \`competitors/\`, \`data-research/\`, \`research-documents/\``,
-            blockTypes: ["competitor", "market_research", "user_research", "research_data", "research_document"],
+Organize files in subfolders: \`competitors/\`, \`data-research/\``,
+            blockTypes: ["competitor", "user_research", "research_data", "section_guide"],
         },
         "technical": {
             description: "Stack, architecture, and constraints",
@@ -2401,7 +649,7 @@ Organize files in subfolders:
 - \`api/\` - API endpoint files
 - \`models/\` - Data model files
 - \`environments/\` - Environment files`,
-            blockTypes: ["tech_stack", "architecture_diagram", "integration", "constraint", "dev_setup", "api_endpoint", "api_spec", "data_model", "data_schema", "environment", "testing_strategy", "cost_calculator"],
+            blockTypes: ["tech_stack", "architecture_diagram", "integration", "constraint", "dev_setup", "api_endpoint", "api_spec", "data_model", "data_schema", "environment", "testing_strategy", "cost_calculator", "section_guide"],
         },
         "design-system": {
             description: "Links to Storybook and Figma design resources",
@@ -2413,7 +661,7 @@ Organize files in subfolders:
 
 Note: This section is for linking external design tools, not for documenting
 components directly. Component documentation lives in Storybook.`,
-            blockTypes: ["storybook_link", "figma_embed"],
+            blockTypes: ["storybook_link", "figma_embed", "section_guide"],
         },
         "information-architecture": {
             description: "Site structure and taxonomies",
@@ -2427,7 +675,7 @@ components directly. Component documentation lives in Storybook.`,
   - Hierarchical organization of content
 
 These blocks use visual editors in the EpicContext app.`,
-            blockTypes: ["ia_tree", "taxonomy"],
+            blockTypes: ["ia_tree", "taxonomy", "section_guide"],
         },
         "metrics": {
             description: "KPIs and analytics",
@@ -2440,7 +688,7 @@ These blocks use visual editors in the EpicContext app.`,
 - **Analytics Events**: Event tracking definitions for implementation
 
 Use AARRR categories (acquisition, activation, retention, revenue, referral) for the \`category\` field.`,
-            blockTypes: ["metric", "analytics_event"],
+            blockTypes: ["metric", "north_star", "kpi", "analytics_event", "section_guide"],
         },
         "decisions": {
             description: "Architecture decision records",
@@ -2453,7 +701,7 @@ Use AARRR categories (acquisition, activation, retention, revenue, referral) for
   - Consequences: What are the implications?
 
 Good ADRs help future team members understand why things are built this way.`,
-            blockTypes: ["decision"],
+            blockTypes: ["decision", "section_guide"],
         },
         "development": {
             description: "Epics, stories, tasks, and roadmaps",
@@ -2470,7 +718,18 @@ Organize files in subfolders:
 - \`stories/\` - User story files
 - \`tasks/\` - Task/implementation plan files
 - \`roadmaps/\` - Roadmap files`,
-            blockTypes: ["epic", "user_story", "task", "roadmap", "release", "impact_effort_matrix"],
+            blockTypes: ["epic", "user_story", "task", "roadmap", "impact_effort_matrix", "kanban_board", "section_guide"],
+        },
+        "environments": {
+            description: "Environment links, deployments, and release notes",
+            guidance: `Use this section to document deployment environments and releases:
+- **Environment Links**: Links to deployed environments (production, staging, dev)
+  - URL, status, and purpose for each environment
+- **Release Notes**: Changelog and release documentation
+  - Version numbers, dates, and changes
+
+Organize files as needed in the environments folder.`,
+            blockTypes: ["environment_link", "release_note", "section_guide"],
         },
         "marketing": {
             description: "Marketing campaigns, ads, and content strategy",
@@ -2491,7 +750,28 @@ Organize files in subfolders:
 - \`seo/\` - SEO content strategy files
 
 Always link campaigns to target personas and success metrics.`,
-            blockTypes: ["marketing_campaign", "seo_content"],
+            blockTypes: ["marketing_campaign", "seo_content", "section_guide"],
+        },
+        "reports": {
+            description: "Business cases, pain point analysis, and user sentiment reports",
+            guidance: `Use this section to create synthesis documents that analyze project context:
+- **Business Case**: One-page business case with executive summary, market opportunity, value proposition, and recommendations
+  - Link to personas, features, and competitors for traceability
+  - Include confidence level based on data quality
+- **Pain Points Report**: Analysis of bottlenecks across product, tech, and UX
+  - Categorize by domain (product, technical, UX, process)
+  - Include severity assessment and recommendations
+- **User Sentiment Report**: User experience analysis with quotes and emotional journey
+  - Include positive/negative themes with supporting quotes
+  - Track satisfaction drivers and churn risks
+
+Organize files in subfolders:
+- \`business-cases/\` - Business case documents
+- \`pain-points/\` - Pain points analysis reports
+- \`sentiment/\` - User sentiment analysis reports
+
+Reports should always reference source blocks (personas, journeys, research) for traceability.`,
+            blockTypes: ["business_case", "pain_points_report", "user_sentiment_report", "section_guide"],
         },
     };
     for (const section of defaultSections) {