@epiccontext/mcp 0.1.63 → 0.1.65

package/dist/cli/files.js

@@ -1,30 +1,30 @@
 import * as fs from "fs";
 import * as path from "path";
 import { getStorybookTemplateFiles } from "../templates/storybook.js";
-// Example content for each block type - used to generate _example-*.md files during init
+// Example content for each block type - placed in hidden .examples/ folders during init
 // These show AI agents the correct heading structure for each block type
+// `subfolder` defines where real blocks of this type should be organized
 // `frontmatterLinks` shows how to add schema refs and universal links in frontmatter
 const BLOCK_TYPE_EXAMPLES = {
     // Constitution
-    constraint: { body: `## No Third-Party Analytics
+    constraint: { subfolder: "constraints", body: `## No Third-Party Analytics
 
-**Priority:** high
-**Category:** privacy
+**Type:** privacy
 
-### Description
+All analytics must be first-party. No external tracking scripts allowed. User privacy is a core value — third-party scripts introduce data leakage risks.
 
-All analytics must be first-party. No external tracking scripts allowed.
+### Impact
 
-### Rationale
+- Cannot use Google Analytics, Mixpanel, or similar third-party tracking
+- All user data must stay within our own infrastructure
+- Limits vendor options for analytics tools
 
-User privacy is a core value. Third-party scripts introduce data leakage risks.
+### Mitigation
 
-### Implications
-
-- Must build or self-host analytics
-- No Google Analytics, Mixpanel, etc.
-- Server-side event tracking only` },
-    glossary: { body: `## Product-Specific Terms
+- Build or self-host analytics (e.g., PostHog self-hosted, Plausible)
+- Use server-side event tracking only
+- Implement privacy-first analytics architecture from the start` },
+    glossary: { subfolder: "glossaries", body: `## Product-Specific Terms
 
 | Term | Definition |
 |------|-----------|
@@ -32,46 +32,60 @@ User privacy is a core value. Third-party scripts introduce data leakage risks.
 | Block | A single piece of structured content |
 | Section | A category grouping related blocks |` },
     // Brand
-    brand_positioning: { body: `## Golden Circle
+    brand_positioning: { subfolder: "positioning", body: `## Brand Positioning: EpicContext
+
+**Tagline:** Context that works for everyone
 
-### WHY (Purpose)
-We believe product teams deserve a single source of truth for all context.
+---
 
-### HOW (Process)
-By combining structured documentation with AI-powered workflows.
+### Golden Circle (WHY -> HOW -> WHAT)
 
-### WHAT (Product)
-A context management platform for product teams.
+#### WHY - The Purpose
+We believe product teams deserve a single source of truth for all context. Documentation should work for both humans and AI agents, not just collect dust in wikis.
 
-## Positioning Statement
+#### HOW - The Unique Approach
+By combining structured documentation with AI-powered workflows. Every piece of content has a schema, a status, and can be consumed by coding agents via MCP.
 
-**For** product teams **who** struggle with scattered documentation, **our product** is a context management platform **that** provides a single source of truth. **Unlike** traditional wikis, **we** structure content for both humans and AI agents.
+#### WHAT - The Products/Services
+A context management platform for product teams that structures documentation into typed blocks, tracks completeness, and exports to multiple formats.
 
-## Brand Essence
+---
 
-**Tagline:** Context that works for everyone
-**Brand Promise:** Never lose product context again` },
-    brand_visual_identity: { body: `## Colors
+### Positioning Statement
+
+> For **product teams who struggle with scattered documentation**,
+>
+> **EpicContext** is the **context management platform**
+>
+> that **provides a single source of truth for both humans and AI agents**
+>
+> unlike **traditional wikis and docs tools**,
+>
+> because **we structure content into typed blocks that AI coding agents can consume directly via MCP**.` },
+    brand_visual_identity: { subfolder: "visual-identity", body: `## Brand Visual Identity
 
-### Primary Palette
+### Usage Guidelines
 
-| Name | Hex | Usage |
-|------|-----|-------|
-| Brand Blue | #2563EB | Primary actions, links |
-| Dark | #111827 | Text, headings |
-| Light | #F9FAFB | Backgrounds |
+Use the brand blue (#2563EB) for primary actions and links. Dark (#111827) for text and headings. Light (#F9FAFB) for backgrounds.
 
-## Typography
+Typography: Inter for headings and body, JetBrains Mono for code. Minimum logo size is 24px height, always use SVG format.
 
-**Primary Font:** Inter
-**Heading Font:** Inter
-**Mono Font:** JetBrains Mono
+Always maintain sufficient contrast ratios (WCAG AA minimum). Use the primary palette for UI elements and the extended palette sparingly for accents.
 
-## Logo
+### Do's
 
-**Format:** SVG
-**Minimum Size:** 24px height` },
-    brand_moodboard: { body: `## Mood & Inspiration
+- Use consistent spacing (8px grid system)
+- Maintain logo clear space (minimum 16px around logo)
+- Use brand colors for interactive elements
+- Apply the mono font for all code snippets and technical content
+
+### Don'ts
+
+- Don't stretch or distort the logo
+- Don't use brand blue on dark backgrounds without checking contrast
+- Don't mix more than 3 typeface weights on a single page
+- Don't use gradients on the logo` },
+    brand_moodboard: { subfolder: "moodboards", body: `## Mood & Inspiration
 
 ### Visual Direction
 Clean, modern, developer-friendly aesthetic with subtle warmth.
@@ -83,57 +97,105 @@ Clean, modern, developer-friendly aesthetic with subtle warmth.
 
 ### Color Mood
 Professional blues with warm accent colors.` },
-    tone_of_voice: { body: `## Voice Archetype
+    tone_of_voice: { subfolder: "tone-of-voice", body: `### Brand Personality
 
-**Primary:** The Expert Guide
-**Secondary:** The Supportive Teammate
+Expert, approachable, clear, developer-friendly, pragmatic. We sound like a knowledgeable colleague who explains things simply — not a salesperson, not a professor.
 
-## Personality Traits
+**Archetype:** sage
 
-| Trait | Scale (1-10) |
-|-------|-------------|
-| Formal ↔ Casual | 4 |
-| Serious ↔ Playful | 3 |
-| Technical ↔ Simple | 6 |
+### Tone Attributes
+
+- Confident but not arrogant
+- Technical but not jargon-heavy
+- Helpful but not patronizing
+- Direct but not blunt
+- Professional but not corporate
+
+### We Are...
+
+- Clear and concise communicators
+- Respectful of the reader's time
+- Honest about limitations
+- Focused on practical solutions
+
+### We Are NOT...
+
+- Overly casual or slangy
+- Condescending or preachy
+- Vague or hand-wavy
+- Marketing-speak driven
+
+### Writing Principles
 
-## Vocabulary
+1. Lead with the action — tell users what to do first
+2. Use code examples whenever possible
+3. Keep paragraphs under 3 sentences
+4. Use bullet points for lists of 3+ items
+5. Write in second person ("you") not third person
 
-### Preferred Terms
+### Vocabulary
+**Words We Use:**
 - "workspace" not "organization"
 - "block" not "document"
 - "sync" not "upload"
+- "context" not "documentation"
 
-### Avoid
+**Words We Avoid:**
 - Jargon without explanation
 - Passive voice
-- Marketing buzzwords` },
-    messaging_framework: { body: `## Elevator Pitch
+- Marketing buzzwords ("revolutionary", "game-changing")
+- Filler words ("basically", "simply", "just")
 
-A context management platform that gives product teams a single source of truth — structured for both humans and AI agents.
+### Examples
+**Good Example:**
+Export your project context as markdown. Your AI coding agent reads it directly — no copy-pasting needed.
 
-## Value Propositions
+**Bad Example:**
+Our revolutionary platform seamlessly enables teams to leverage cutting-edge AI-powered documentation synergies.
 
-### For Developers
-Write code with full product context. AI agents read structured docs, not scattered wikis.
+### Grammar & Style
 
-### For Product Managers
-Track documentation completeness across every section. Know what's missing at a glance.
+- Use sentence case for headings (not Title Case)
+- Oxford comma always
+- Use em dashes (—) not double hyphens
+- Contractions are fine (don't, can't, you'll)
+- American English spelling` },
+    messaging_framework: { subfolder: "messaging", body: `### Elevator Pitch
 
-## Key Messages
+A context management platform that gives product teams a single source of truth — structured for both humans and AI agents. Write once, consume everywhere.
+
+### Value Propositions
+
+- **For Developers:** Write code with full product context. AI agents read structured docs, not scattered wikis.
+- **For Product Managers:** Track documentation completeness across every section. Know what's missing at a glance.
+- **For Teams:** One place for brand, product, technical, and user documentation. Always up to date.
+
+### Key Messages
 
 | Audience | Message |
 |----------|---------|
 | Developers | "Your AI coding assistant finally has context" |
-| Product Managers | "See documentation gaps before they become problems" |` },
+| Product Managers | "See documentation gaps before they become problems" |
+| Leadership | "Product documentation that actually gets maintained" |
+
+### Calls to Action
+
+- Primary: "Start for free"
+- Secondary: "See how it works"
+- Developer: "Try the MCP integration"
+
+### Boilerplate
+
+EpicContext is a context management platform for product teams. It structures documentation into typed blocks that are consumed by both humans and AI agents. Teams use EpicContext to keep product context complete, consistent, and accessible.` },
     // Product
-    product_overview: { frontmatterLinks: `personas_ref:  # Who this product is for
-  - _example-persona
+    product_overview: { subfolder: "overviews", frontmatterLinks: `personas_ref:  # Who this product is for
+  - example-persona
 features_ref:  # Key features
-  - _example-feature
+  - example-feature
 epics_ref:  # Development epics
-  - _example-epic
+  - example-epic
 links:  # Universal links
-  - target: _example-competitor
+  - target: example-competitor
     label: inspired_by`, body: `### Vision
 Become the standard way product teams manage context for both humans and AI.
 
@@ -147,30 +209,31 @@ Product teams scatter context across wikis, docs, Slack, and spreadsheets. AI ag
 - Product managers tracking documentation completeness
 - Developers who need product context while coding
 - AI coding agents that consume structured documentation` },
-    feature: { subfolder: "features", frontmatterLinks: `product_ref: _example-product-overview  # Link to parent product
+    feature: { subfolder: "features", frontmatterLinks: `product_ref: example-product-overview  # Link to parent product
 personas_ref:  # Who benefits from this feature
-  - _example-persona
+  - example-persona
 links:  # Universal links
-  - target: _example-user-story
+  - target: example-user-story
     label: relates_to
-  - target: _example-competitor
+  - target: example-competitor
     label: inspired_by`, body: `## Smart Notifications
 
+Intelligent notification system that only alerts users about changes relevant to their role and current work.
+
 **Priority:** high
 **Status:** planned
 
-### Description
-Intelligent notification system that only alerts users about changes relevant to their role and current work.
-
 ### User Story
+
 As a developer, I want to be notified only about changes to blocks I'm working on, so I'm not overwhelmed by noise.
 
 ### Acceptance Criteria
+
 - [ ] Users can set notification preferences per section
 - [ ] AI determines relevance based on recent activity
 - [ ] Daily digest option available
 - [ ] Mute specific blocks` },
-    product_strategy_canvas: { body: `## Product Strategy Canvas
+    product_strategy_canvas: { subfolder: "strategy", body: `## Product Strategy Canvas
 
 ### Target Customer
 Small-to-medium product teams (5-50 people) using multiple tools for documentation.
@@ -186,7 +249,7 @@ The only documentation platform designed for both humans AND AI agents.
 
 ### Competitive Advantage
 AI-native format, MCP integration, structured schemas for every content type.` },
-    feature_market_analysis: { body: `## AI-Assisted Documentation
+    feature_market_analysis: { subfolder: "market-analysis", body: `## AI-Assisted Documentation
 
 ### Market Opportunity
 Growing demand for AI-integrated development tools. 68% of teams want AI help with documentation.
@@ -198,131 +261,213 @@ No current tool combines structured documentation with MCP-based AI agent integr
 First-mover advantage in structured context for AI coding agents.` },
     // Users
     persona: { subfolder: "personas", frontmatterLinks: `jtbds_ref:  # What jobs this persona has
-  - _example-jtbd
+  - example-jtbd
 journeys_ref:  # Journey maps for this persona
-  - _example-journey-map
+  - example-journey-map
 links:  # Universal links
-  - target: _example-product-overview
+  - target: example-product-overview
     label: relates_to
-  - target: _example-user-story
+  - target: example-user-story
     label: relates_to`, body: `> "I need one place where all product context lives."
 
-## Demographics
+**Role:** Product Manager
+**Primary Persona:** Yes
+**Tech Comfort:** intermediate
+
+## Profile
+
+**Age:** 28-40
+**Education:** Bachelor's in Business/Tech
+**Location:** Urban, remote-first company
+**Occupation:** Product Manager at SaaS startup
+
+## Motivations
 
-| Attribute | Value |
-|-----------|-------|
-| Role | Product Manager |
-| Age | 28-40 |
-| Experience | 3-8 years |
-| Team Size | 5-20 |
+- Wants the team to ship faster with fewer miscommunications
+- Values clarity and completeness over perfection
+- Motivated by reducing "knowledge gaps" in the team
 
 ## Goals
+
 - Keep documentation complete and up-to-date
-- Give developers the context they need
+- Give developers the context they need without meetings
 - Track what's documented and what's missing
 
-## Frustrations
-- Documentation scattered across tools
-- Can't tell what's outdated
+## Pain Points
+
+- Documentation scattered across Confluence, Google Docs, and Slack
+- Can't tell what's outdated or incomplete
 - Developers ask the same questions repeatedly
+- No single source of truth for product context
 
 ## Behaviors
+
 - Checks documentation status weekly
 - Creates user stories with acceptance criteria
-- Reviews AI-generated summaries` },
-    jtbd: { subfolder: "jobs-to-be-done", frontmatterLinks: `persona_ref: _example-persona  # Who has this job
+- Reviews AI-generated summaries
+
+### Tools
+Notion, Linear, Figma, Slack, Google Docs
+
+## Jobs to Be Done
+
+- When onboarding a new team member, I want to point them to one place with all context, so they ramp up quickly
+- When planning a sprint, I want to see what documentation is missing, so nothing blocks development` },
+    jtbd: { subfolder: "jobs-to-be-done", frontmatterLinks: `persona_ref: example-persona  # Who has this job
 links:  # Universal links
-  - target: _example-user-story
+  - target: example-user-story
     label: relates_to
-  - target: _example-feature
+  - target: example-feature
     label: relates_to`, body: `## Keep Product Context Accessible
 
 ### Job Statement
+
 When I'm onboarding a new team member, I want to point them to one place with all product context, so they can ramp up quickly without asking everyone questions.
 
-### Functional Job
-- Find all product documentation in one place
-- Verify documentation is complete and current
-- Share context with new team members
+### Situation
+
+A new developer joins the team and needs to understand the product vision, technical stack, brand guidelines, and current priorities. Information is scattered across Confluence, Google Docs, Slack messages, and tribal knowledge.
+
+### Motivation
+
+- Feel confident the team has what they need to be productive
+- Reduce anxiety about knowledge gaps across the organization
+- Minimize repetitive questions from new hires
+- Get new team members contributing code faster
 
-### Emotional Job
-- Feel confident the team has what they need
-- Reduce anxiety about knowledge gaps
+### Desired Outcome
 
-### Current Solutions
-- Confluence wiki (messy, outdated)
-- Google Docs (scattered, hard to find)
-- Tribal knowledge (risky, doesn't scale)` },
-    journey_map: { subfolder: "journey-maps", frontmatterLinks: `persona_ref: _example-persona  # REQUIRED: Whose journey is this?
+- New team members can self-serve all product context from one place
+- Documentation is always current and complete
+- Onboarding time is reduced from weeks to days
+- Fewer interruptions to existing team members` },
+    journey_map: { subfolder: "journey-maps", frontmatterLinks: `persona_ref: example-persona  # REQUIRED: Whose journey is this?
 links:  # Universal links
-  - target: _example-feature
+  - target: example-feature
     label: relates_to
-  - target: _example-user-story
+  - target: example-user-story
     label: implements`, body: `## New User Onboarding Journey
 
-**Persona:** primary-user
-
-### Stages
-
-#### 1. Discovery
-**Touchpoints:** Landing page, blog post
-**Actions:** Reads about the product, watches demo
-**Emotions:** Curious, skeptical
-**Pain Points:** "Will this be another tool that gets abandoned?"
-
-#### 2. Sign Up
-**Touchpoints:** Registration form, email verification
-**Actions:** Creates account, verifies email
-**Emotions:** Hopeful, impatient
-**Pain Points:** "I hope this is quick to set up"
-
-#### 3. First Use
-**Touchpoints:** Dashboard, guided tour
-**Actions:** Creates first project, explores sections
-**Emotions:** Engaged, slightly overwhelmed
-**Pain Points:** "Where do I start?"
-
-#### 4. Ongoing Use
-**Touchpoints:** Editor, export API
-**Actions:** Fills in blocks, syncs with AI tools
-**Emotions:** Productive, satisfied
-**Pain Points:** "Need better collaboration features"` },
+User discovers the platform, signs up, and completes their first project setup.
+
+**Persona:** example-persona
+**Variant:** as-is
+**Trigger:** User hears about the product from a colleague or finds it via search
+
+## Phases
+
+1. Discovery
+2. Sign Up
+3. First Use
+
+## Steps
+
+### Step 1: Finds the product
+**Phase:** Discovery
+**Actions:**
+- Touchpoint: Search engine, colleague recommendation
+
+**Experience:**
+- activity: Curious about whether this solves their documentation problem
+
+**Insights:**
+- Landing page must immediately communicate the value proposition
+
+### Step 2: Browses landing page
+**Phase:** Discovery
+**Actions:**
+- Touchpoint: Landing page, feature overview
+
+**Experience:**
+- activity: Evaluating if this is worth trying
+- need: Wants to see how it works before committing
+
+### Step 3: Creates account
+**Phase:** Sign Up
+**Actions:**
+- Touchpoint: Registration form, email verification
+
+**Experience:**
+- pain: Registration asks for too much information upfront (impact: -2)
+- activity: Hopeful but impatient
+
+**Insights:**
+- Minimize required fields; collect additional info later
+
+### Step 4: First project setup
+**Phase:** First Use
+**Actions:**
+- Touchpoint: Dashboard, project creation wizard
+
+**Experience:**
+- pain: Unclear where to start — too many empty sections (impact: -2)
+- gain: Templates pre-fill common sections (impact: +2)
+
+**Insights:**
+- Guided onboarding tour should highlight the 3 most important sections first
+
+### Step 5: Fills in first blocks
+**Phase:** First Use
+**Actions:**
+- Touchpoint: Block editor, section view
+
+**Experience:**
+- gain: Auto-save makes editing feel safe (impact: +1)
+- activity: Starting to see the value
+
+### Success Outcome
+
+User has a project with at least 3 sections partially filled and understands the block-based structure.
+
+### Key Insights
+
+- Reduce sign-up friction by asking only email and password initially
+- Provide a "quick start" template that pre-fills common sections
+- Show progress percentage early to create momentum` },
     // Research
     competitor: { subfolder: "competitors", frontmatterLinks: `links:  # Universal links to blocks this competitor analysis informs
-  - target: _example-feature
+  - target: example-feature
     label: informs
-  - target: _example-product-overview
+  - target: example-product-overview
     label: informs
-  - target: _example-decision
+  - target: example-decision
     label: references`, body: `## Linear
 
 **Website:** https://linear.app
-**Category:** Project Management
+**Tagline:** Linear is a better way to build software
+**Threat Level:** medium
 
-### Description
-Modern project management tool for software teams with fast UI and keyboard shortcuts.
-
-### Target Market
-Software development teams, startups to mid-market.
-
-### Pricing
-Free for small teams, $8/user/month for standard.
+Modern project management tool for software teams with fast UI and keyboard shortcuts. Strong in issue tracking and sprint planning, but lacks documentation and AI agent features.
 
 ### Strengths
+
 - Extremely fast and polished UI
-- Great keyboard navigation
-- GitHub integration
+- Great keyboard navigation and shortcuts
+- Tight GitHub integration
+- Clean, focused design
 
 ### Weaknesses
-- Limited documentation features
-- No AI agent integration
-- No structured content export
+
+- Limited documentation features — no structured content
+- No AI agent integration or MCP support
+- No content export for AI consumption
+- Focused on issue tracking, not product context
+
+### Pricing
+
+Free for small teams, $8/user/month for standard, $14/user/month for plus.
+
+### Target Market
+
+Software development teams at startups to mid-market (10-200 people). Engineering-led organizations that value speed and keyboard-driven workflows.
 
 ### Our Differentiators
+
 - Structured documentation, not just task tracking
-- AI-native MCP integration
-- Content consumable by coding agents` },
-    user_research: { body: `## User Research Interviews Q1
+- AI-native MCP integration for coding agents
+- Content consumable by both humans and AI
+- Full product context, not just development tasks` },
+    user_research: { subfolder: "user-research", body: `## User Research Interviews Q1
 
 ### Methodology
 - 12 semi-structured interviews (45 min each)
@@ -359,7 +504,7 @@ Free for small teams, $8/user/month for standard.
 
 The developer documentation tool market is growing at 13% CAGR. Key growth driver is AI integration demand.` },
     // Technical
-    tech_stack: { body: `## Technology Stack
+    tech_stack: { subfolder: "stacks", body: `## Technology Stack
 
 ### Frontend
 | Technology | Purpose | Version |
@@ -380,7 +525,7 @@ The developer documentation tool market is growing at 13% CAGR. Key growth drive
 |-----------|---------|
 | Vercel | Hosting |
 | GitHub Actions | CI/CD |` },
-    architecture_diagram: { body: `## System Architecture
+    architecture_diagram: { subfolder: "architecture", body: `## System Architecture
 
 **Level:** container
 **Notation:** C4
@@ -398,30 +543,29 @@ High-level system architecture showing main containers and their interactions.
 [API] --> [Database]
 \`\`\`` },
     integration: { subfolder: "integrations", frontmatterLinks: `decisions_ref:  # Decisions related to this integration
-  - _example-decision
+  - example-decision
 links:  # Universal links
-  - target: _example-task
+  - target: example-task
     label: relates_to
-  - target: _example-epic
+  - target: example-epic
     label: relates_to`, body: `## GitHub Integration
 
-**Provider:** GitHub
 **Type:** oauth
 **Status:** planned
 
-### Purpose
-Connect GitHub repositories to sync PRs, issues, and code context.
+Connect GitHub repositories to sync PRs, issues, and code context with project blocks.
+
+**Documentation:** https://docs.github.com/en/rest
+**Credentials:** Stored in environment variable GITHUB_TOKEN
 
-### API Details
-**Base URL:** https://api.github.com
-**Auth Method:** OAuth 2.0
-**Rate Limit:** 5000 requests/hour
+### Notes
 
-### Data Flow
-1. User connects GitHub account via OAuth
-2. App reads repository metadata
-3. PRs are linked to relevant blocks` },
-    dev_setup: { body: `## Local Development Setup
+- Uses OAuth 2.0 for user authentication
+- Base URL: https://api.github.com
+- Rate limit: 5000 requests/hour (authenticated)
+- User connects GitHub account, app reads repository metadata
+- PRs and issues are linked to relevant blocks automatically` },
+    dev_setup: { subfolder: "setup", body: `## Local Development Setup
 
 ### Prerequisites
 - Node.js 20+
@@ -464,7 +608,7 @@ List all blocks for a project, optionally filtered by section.
   ]
 }
 \`\`\`` },
-    api_spec: { body: `## API Specification
+    api_spec: { subfolder: "api-specs", body: `## API Specification
 
 **Version:** v1
 **Base URL:** /api/v1
@@ -493,7 +637,7 @@ All endpoints require an API key passed in the X-API-Key header.` },
 ### Indexes
 - Unique: (section_id, key)
 - Index: status` },
-    data_schema: { body: `## Database Schema
+    data_schema: { subfolder: "schemas", body: `## Database Schema
 
 ### Overview
 PostgreSQL database with JSONB content storage for flexible block schemas.
@@ -509,7 +653,7 @@ PostgreSQL database with JSONB content storage for flexible block schemas.
 - JSONB for block values (flexible schema per type)
 - UUID primary keys
 - Row Level Security via Supabase` },
-    testing_strategy: { body: `## Testing Strategy
+    testing_strategy: { subfolder: "testing", body: `## Testing Strategy
 
 ### Philosophy
 Test behavior, not implementation. Focus on user-facing functionality.
@@ -525,7 +669,7 @@ Test behavior, not implementation. Focus on user-facing functionality.
 - API endpoint responses
 - Block CRUD operations
 - Export format correctness` },
-    cost_calculator: { body: `## Infrastructure Costs
+    cost_calculator: { subfolder: "costs", body: `## Infrastructure Costs
 
 ### Monthly Breakdown
 | Service | Tier | Monthly Cost |
@@ -542,7 +686,7 @@ Test behavior, not implementation. Focus on user-facing functionality.
 | 1,000 | $150 |
 | 10,000 | $500 |` },
     // Design System
-    storybook_link: { body: `## Component Library
+    storybook_link: { subfolder: "storybook", body: `## Component Library
 
 **Storybook URL:** https://storybook.example.com
 **Repository:** https://github.com/org/design-system
@@ -554,7 +698,7 @@ Test behavior, not implementation. Focus on user-facing functionality.
 
 ### Access
 Requires EpicContext authentication token.` },
-    figma_embed: { body: `## Main Design File
+    figma_embed: { subfolder: "figma", body: `## Main Design File
 
 **Figma URL:** https://figma.com/file/example
 **Last Updated:** 2025-01-15
@@ -567,7 +711,7 @@ Requires EpicContext authentication token.` },
 ### Handoff Notes
 Use Auto Layout for all new components. Follow 8px grid.` },
     // Information Architecture
-    ia_tree: { body: `## Application Structure
+    ia_tree: { subfolder: "trees", body: `## Application Structure
 
 ### Description
 Main navigation hierarchy for the web application.
@@ -601,7 +745,7 @@ Home
 - status: draft, complete, empty
 - audience: developer, designer, manager` },
     // Metrics
-    metric: { body: `## Weekly Active Users
+    metric: { subfolder: "indicators", body: `## Weekly Active Users
 
 **Metric Type:** kpi
 **Category:** activation
@@ -617,7 +761,7 @@ Count distinct user IDs with any event in the last 7 days.
 
 ### Cadence
 Measured weekly, reported in Monday standup.` },
-    north_star: { body: `## Blocks Completed Per Week
+    north_star: { subfolder: "north-stars", body: `## Blocks Completed Per Week
 
 **Metric Type:** north_star
 **Category:** activation
@@ -630,7 +774,7 @@ Total blocks marked as "complete" across all projects per week.
 
 ### Why This Metric
 Blocks completed = documentation being actively maintained = product delivering value.` },
-    kpi: { body: `## Documentation Completeness
+    kpi: { subfolder: "kpis", body: `## Documentation Completeness
 
 **Metric Type:** kpi
 **Category:** activation
@@ -640,7 +784,7 @@ Blocks completed = documentation being actively maintained = product delivering
 
 ### Description
 Percentage of blocks with status "complete" across all sections.` },
-    analytics_event: { body: `## block_completed
+    analytics_event: { subfolder: "events", body: `## block_completed
 
 **Category:** activation
 **Trigger:** User marks a block as complete
@@ -652,129 +796,169 @@ Percentage of blocks with status "complete" across all sections.` },
 | section | string | Section the block belongs to |
 | time_to_complete | number | Seconds from creation to completion |` },
     // Decisions
-    decision: { frontmatterLinks: `epics_ref:  # Epics affected by this decision
-  - _example-epic
+    decision: { subfolder: "adrs", frontmatterLinks: `epics_ref:  # Epics affected by this decision
+  - example-epic
 integrations_ref:  # Integrations related to this decision
-  - _example-integration
+  - example-integration
 links:  # Universal links
-  - target: _example-feature
+  - target: example-feature
     label: informs
-  - target: _example-competitor
+  - target: example-competitor
     label: references`, body: `## Use Supabase for Database
 
-**Status:** accepted
 **Date:** 2025-01-15
-**Deciders:** Engineering team
+**Status:** accepted
 
 ### Context
-Need a database solution that supports real-time, authentication, and JSONB storage.
+
+Need a database solution that supports real-time subscriptions, built-in authentication, and JSONB storage for flexible block schemas.
 
 ### Options Considered
 
 #### Option 1: Supabase
-- **Pros:** Built-in auth, real-time, PostgreSQL, generous free tier
-- **Cons:** Vendor lock-in, limited customization
+- **Pros:** Built-in auth, real-time, PostgreSQL, generous free tier, Row Level Security
+- **Cons:** Vendor lock-in, limited customization of auth flows
 
 #### Option 2: PlanetScale
-- **Pros:** MySQL, great scaling
-- **Cons:** No JSONB support, separate auth needed
+- **Pros:** MySQL, great scaling, branching workflow
+- **Cons:** No JSONB support, separate auth needed, no real-time
 
 ### Decision
+
 Choose Supabase for its combination of PostgreSQL, built-in auth, and real-time capabilities.
 
+### Rationale
+
+Supabase gives us PostgreSQL (needed for JSONB block storage), built-in auth (saves months of development), and real-time subscriptions (for collaborative editing). The trade-off of vendor lock-in is acceptable at our scale.
+
 ### Consequences
+
 - Committed to PostgreSQL ecosystem
-- Use Row Level Security for authorization
-- Real-time updates available for free` },
-    meeting_notes: { body: `## Sprint Planning - Week 12
+- Use Row Level Security for authorization instead of custom middleware
+- Real-time updates available out of the box
+- Migration path exists to self-hosted Supabase if needed
+
+### Evidence
+
+- Supabase benchmarks show sub-50ms query times for our expected load
+- Three comparable SaaS products successfully use Supabase at 10x our scale` },
+    meeting_notes: { subfolder: "meetings", body: `## Sprint Planning - Week 12
 
 **Date:** 2025-03-15
+**Type:** sprint_planning
 **Attendees:** Engineering team
 
-### Discussion Points
-1. Review of completed work from last sprint
-2. Prioritization of upcoming features
-3. Technical debt items
+### Meeting Transcript
+
+1. Reviewed completed work from last sprint — export API is 80% done
+2. Discussed prioritization of upcoming features
+3. Identified technical debt items: markdown parser edge cases, test coverage gaps
+4. Agreed on sprint goals for next two weeks
 
 ### Decisions Made
-- Prioritize export API for next sprint
+
+- Prioritize export API completion for next sprint
 - Defer dark mode to Q2
+- Allocate 20% of sprint to technical debt
 
-### Action Items
-- [ ] Create export API epic
-- [ ] Update roadmap` },
+### Summary & Action Items
+
+Sprint focus is completing the export system. Key actions:
+- [ ] Create export API epic with remaining tasks
+- [ ] Update roadmap to reflect Q2 dark mode timeline
+- [ ] Schedule design review for export UI` },
     // Development
-    epic: { subfolder: "epics", frontmatterLinks: `product_ref: _example-product-overview  # Link to parent product
+    epic: { subfolder: "epics", frontmatterLinks: `product_ref: example-product-overview  # Link to parent product
 stories_ref:  # List user stories in this epic
-  - _example-user-story
+  - example-user-story
 links:  # Universal links to related blocks across sections
-  - target: _example-persona
+  - target: example-persona
     label: relates_to
-  - target: _example-decision
+  - target: example-decision
     label: implements`, body: `## Context Export System
 
+Enable teams to export their entire product context in multiple formats for AI agent consumption.
+
 **Priority:** high
 **Status:** planned
-**Estimated Effort:** 3 sprints
 
-### Goal
-Enable teams to export their entire product context in multiple formats for AI agent consumption.
+### Goals
 
-### Scope
-- Markdown export (full project)
-- llms.txt format
-- JSON API endpoint
-- MCP server integration
+- Support markdown, llms.txt, and JSON export formats
+- Enable AI coding agents to consume project context via MCP
+- Provide both full-project and per-section exports
 
 ### Success Criteria
-- [ ] Export generates valid markdown
-- [ ] AI agents can consume exported context
-- [ ] Export updates automatically on content change` },
-    user_story: { subfolder: "stories", frontmatterLinks: `epic_ref: _example-epic  # REQUIRED: Link to parent epic
+
+- [ ] Export generates valid markdown with correct frontmatter
+- [ ] AI agents can consume exported context via MCP server
+- [ ] Export updates automatically when content changes
+- [ ] Per-section export available for focused context` },
+    user_story: { subfolder: "stories", frontmatterLinks: `epic_ref: example-epic  # REQUIRED: Link to parent epic
 personas_ref:  # Who this story is for
-  - _example-persona
+  - example-persona
 links:  # Universal links to related blocks
-  - target: _example-feature
+  - target: example-feature
     label: implements
-  - target: _example-jtbd
+  - target: example-jtbd
     label: relates_to`, body: `## Export Context as Markdown
 
+Enable developers to export project context so AI coding agents can consume it.
+
 **Priority:** high
 **Status:** planned
-**Story Points:** 5
 
 ### User Story
-As a developer, I want to export my project context as markdown, so my AI coding agent can read it.
+
+As a developer, I want to export my project context as markdown, so my AI coding agent can read it as structured documentation.
 
 ### Acceptance Criteria
+
 - [ ] Export button on project settings page
-- [ ] Generates valid markdown with frontmatter
-- [ ] Includes all sections and blocks
-- [ ] Downloads as .zip file` },
-    task: { subfolder: "tasks", frontmatterLinks: `story_ref: _example-user-story  # REQUIRED: Link to parent user story
+- [ ] Generates valid markdown with YAML frontmatter
+- [ ] Includes all sections and blocks grouped by section
+- [ ] Downloads as .zip file with proper folder structure` },
+    task: { subfolder: "tasks", frontmatterLinks: `story_ref: example-user-story  # REQUIRED: Link to parent user story
 links:  # Universal links to related blocks
-  - target: _example-integration
+  - target: example-integration
     label: depends_on
-  - target: _example-decision
+  - target: example-decision
     label: implements`, body: `## Implement Markdown Export API
 
-**Priority:** high
+Create a GET endpoint at /api/projects/[id]/markdown that generates a full markdown export of all project blocks.
+
 **Status:** planned
 **Estimated Hours:** 8
+**Assignee:** backend-team
 
-### Description
-Create a GET endpoint at /api/projects/[id]/markdown that generates a full markdown export of all project blocks.
+### Implementation Plan
 
-### Technical Approach
-1. Query all blocks for project
-2. Group by section
-3. Apply markdown templates per block type
-4. Return as downloadable zip
+1. Query all blocks for the project from database
+2. Group blocks by section type
+3. Apply markdown templates per block type from block-type-masters
+4. Generate YAML frontmatter for each block
+5. Bundle into downloadable zip with correct folder structure
+6. Add caching to avoid regenerating unchanged blocks
 
-### Files to Modify
-- \`lib/export/to-markdown.ts\`
-- \`app/api/projects/[projectId]/markdown/route.ts\`` },
-    roadmap: { body: `## Q1 2025 Roadmap
+### Technical Notes
+
+Use the existing \`to-markdown.ts\` export functions. The markdown template is defined in each block type master's \`markdown.template\` field.
+
+### Files Affected
+
+- \`lib/export/to-markdown.ts\` — add zip bundling
+- \`app/api/projects/[projectId]/markdown/route.ts\` — new endpoint
+- \`lib/export/to-multi-file.ts\` — folder structure mapping
+
+### Dependencies
+
+- Block type masters must have markdown templates for all types
+- Export auth middleware must be in place
+
+### Outcome
+
+Working GET endpoint that returns a zip file containing all project blocks as markdown files, organized by section.` },
+    roadmap: { subfolder: "roadmaps", body: `## Q1 2025 Roadmap
 
 **Planning Horizon:** quarterly
 
@@ -794,7 +978,7 @@ Create a GET endpoint at /api/projects/[id]/markdown that generates a full markd
 - Team invites
 - Activity log
 - Comments` },
-    impact_effort_matrix: { body: `## Product Prioritization Matrix
+    impact_effort_matrix: { subfolder: "matrices", body: `## Product Prioritization Matrix
 
 ### High Impact / Low Effort
 - Smart notifications
@@ -813,7 +997,7 @@ Create a GET endpoint at /api/projects/[id]/markdown that generates a full markd
 ### Low Impact / High Effort
 - Offline support
 - Video embeds` },
-    kanban_board: { body: `## Sprint Board
+    kanban_board: { subfolder: "boards", body: `## Sprint Board
 
 ### Backlog
 - Implement search
@@ -830,7 +1014,7 @@ Create a GET endpoint at /api/projects/[id]/markdown that generates a full markd
 - Project creation
 - Section navigation` },
     // Business Strategy
-    ogsm: { body: `## Annual OGSM
+    ogsm: { subfolder: "ogsm", body: `## Annual OGSM
 
 ### Objective
 Become the leading context management platform for product teams.
@@ -851,7 +1035,7 @@ Become the leading context management platform for product teams.
 - Weekly active users growth rate
 - Conversion from free to paid
 - Feature adoption rate` },
-    business_model_canvas: { body: `## Business Model Canvas
+    business_model_canvas: { subfolder: "canvases", body: `## Business Model Canvas
 
 ### Key Partners
 - AI tool providers (Anthropic, OpenAI)
@@ -873,28 +1057,43 @@ Become the leading context management platform for product teams.
 ### Revenue Streams
 - SaaS subscription ($10-25/user/month)
 - Enterprise tier` },
-    swot_analysis: { body: `## SWOT Analysis
+    swot_analysis: { subfolder: "swot", body: `## SWOT Analysis
 
-### Strengths
-- First-mover in AI-native documentation
-- Strong technical foundation
-- MCP integration
+### Strengths (Internal, Helpful)
 
-### Weaknesses
-- Small team
-- No brand recognition yet
-- Limited funding
+- First-mover in AI-native documentation space
+- Strong technical foundation with MCP integration
+- Structured block-based approach is unique in the market
+- Developer-friendly CLI and API
 
-### Opportunities
-- Growing AI tool adoption
-- Developer tool market expanding
-- Remote work driving documentation needs
+### Weaknesses (Internal, Harmful)
 
-### Threats
-- Large players (Notion, Confluence) adding AI
-- New entrants with similar vision
-- Market downturn reducing tool budgets` },
-    porters_five_forces: { body: `## Porter's Five Forces Analysis
+- Small team with limited bandwidth
+- No brand recognition yet in the market
+- Limited funding constrains marketing and hiring
+- Documentation of our own product is still incomplete
+
+### Opportunities (External, Helpful)
+
+- Growing AI tool adoption across development teams
+- Developer tool market expanding rapidly
+- Remote work driving documentation and context-sharing needs
+- MCP becoming a standard protocol for AI agent integrations
+
+### Threats (External, Harmful)
+
+- Large players (Notion, Confluence) adding AI features
+- New entrants with similar structured documentation vision
+- Market downturn reducing tool budgets at startups
+- Open-source alternatives could commoditize core features
+
+### Key Action Items
+
+- Double down on MCP integration as key differentiator
+- Build community around the open-source CLI before competitors catch up
+- Focus on developer experience to build organic growth
+- Secure partnerships with AI coding tool providers` },
+    porters_five_forces: { subfolder: "porters", body: `## Porter's Five Forces Analysis
 
 ### Threat of New Entrants
 **Rating:** Medium
@@ -915,7 +1114,7 @@ Teams could use wikis, docs, or custom solutions.
 ### Competitive Rivalry
 **Rating:** High
 Crowded market with well-funded competitors.` },
-    strategic_group_map: { body: `## Market Positioning Map
+    strategic_group_map: { subfolder: "strategic-maps", body: `## Market Positioning Map
 
 ### Dimensions
 - **X-axis:** Target audience (Individual → Enterprise)
@@ -928,7 +1127,7 @@ We target the "developer sweet spot" — more powerful than Trello but simpler t
 1. **Launch:** Start with small teams
 2. **Grow:** Move to mid-market
 3. **Defend:** AI moat prevents commoditization` },
-    obeya_board: { body: `## Product Obeya Board
+    obeya_board: { subfolder: "obeya", body: `## Product Obeya Board
 
 ### Vision & Strategy (North Wall)
 Platform vision: Make product context accessible to both humans and AI.
@@ -986,7 +1185,7 @@ Learn how product teams manage context documentation effectively. Discover tools
 4. Tools comparison
 5. Getting started guide` },
     // Environments
-    environment_link: { body: `## Production Environment
+    environment_link: { subfolder: "environments", body: `## Production Environment
 
 **URL:** https://app.example.com
 **Environment Type:** production
@@ -1001,7 +1200,7 @@ Learn how product teams manage context documentation effectively. Discover tools
 - Uptime: Better Stack
 - Errors: Sentry
 - Analytics: PostHog` },
-    release_note: { body: `## v1.2.0 - Export System
+    release_note: { subfolder: "releases", body: `## v1.2.0 - Export System
 
 **Version:** 1.2.0
 **Date:** 2025-03-01
@@ -1035,7 +1234,7 @@ EpicContext is ready for public launch. Core features are complete, early users
 ### Recommendation
 Proceed with public launch, focusing on developer community.` },
     // Section Guide (generic - used across all sections)
-    section_guide: { body: `## Overview
+    section_guide: { subfolder: "guides", body: `## Overview
 
 This section contains [description of section content].
 
@@ -1433,9 +1632,9 @@ export function readContextFolder(contextPath) {
                 }
             }
             else if (entry.isFile() && entry.name.endsWith(".md")) {
-                // Skip README, AI-GUIDE, and _example-* files
+                // Skip README and AI-GUIDE (examples are in hidden .examples/ folder, already skipped above)
                 const lowerName = entry.name.toLowerCase();
-                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md" && !entry.name.startsWith("_example-")) {
+                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md") {
                     const content = fs.readFileSync(fullPath, "utf-8");
                     files.push({
                         path: relativePath,
@@ -1601,9 +1800,9 @@ npx @epiccontext/mcp add-app ./apps/my-app --name "my-app"
     }
 }
 /**
- * Generate _example-*.md files for each block type in each section.
+ * Generate example .md files inside a hidden `.examples/` folder in each section.
  * These show AI agents the correct heading structure and format.
- * They are skipped by readContextFolder, push, and import pipelines.
+ * They are hidden from file browsers (dot-prefixed folder) and skipped by push/import pipelines.
  */
 /**
  * Check if a section directory has any real (non-example, non-README) markdown files
@@ -1620,7 +1819,7 @@ function sectionHasRealBlocks(sectionDir) {
             }
             else if (entry.isFile() && entry.name.endsWith(".md")) {
                 const lower = entry.name.toLowerCase();
-                if (lower !== "readme.md" && !entry.name.startsWith("_example-")) {
+                if (lower !== "readme.md") {
                     return true;
                 }
             }
@@ -1647,21 +1846,22 @@ function generateExampleFiles(contextPath, skipIfHasBlocks) {
         // Skip sections that already have real blocks (upgrade mode)
         if (skipIfHasBlocks && sectionsWithBlocks.has(info.folder))
             continue;
+        // Create the hidden .examples/ folder inside the section
+        const examplesDir = path.join(contextPath, info.folder, ".examples");
+        if (!fs.existsSync(examplesDir)) {
+            fs.mkdirSync(examplesDir, { recursive: true });
+        }
         for (const blockType of info.blockTypes) {
             const example = BLOCK_TYPE_EXAMPLES[blockType];
             if (!example)
                 continue;
-            // Determine target folder (some block types use subfolders)
-            let targetDir = path.join(contextPath, info.folder);
-            if (example.subfolder) {
-                targetDir = path.join(targetDir, example.subfolder);
+            // Also create the actual subfolder (empty, for real blocks)
+            const subfolderDir = path.join(contextPath, info.folder, example.subfolder);
+            if (!fs.existsSync(subfolderDir)) {
+                fs.mkdirSync(subfolderDir, { recursive: true });
             }
-            // Ensure subfolder exists
-            if (!fs.existsSync(targetDir)) {
-                fs.mkdirSync(targetDir, { recursive: true });
-            }
-            const filename = `_example-${blockType.replace(/_/g, "-")}.md`;
-            const filePath = path.join(targetDir, filename);
+            const filename = `${blockType.replace(/_/g, "-")}.md`;
+            const filePath = path.join(examplesDir, filename);
             // Don't overwrite existing example files
             if (fs.existsSync(filePath))
                 continue;
@@ -1671,7 +1871,7 @@ function generateExampleFiles(contextPath, skipIfHasBlocks) {
             const frontmatterLines = [
                 `type: ${blockType}`,
                 `section: ${sectionForFrontmatter}`,
-                `key: _example-${blockType.replace(/_/g, "-")}`,
+                `key: example-${blockType.replace(/_/g, "-")}`,
                 `name: "Example ${blockType.split("_").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}"`,
                 `status: draft`,
                 `created: ${today}`,
@@ -1687,8 +1887,8 @@ ${frontmatterLines.join("\n")}
 
 # Example: ${blockType.split("_").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
 
-> **This is an example file.** Delete it after you've created your own ${blockType} block.
-> It shows the correct heading structure, format, and **how to link** for traceability.
+> **This is an example file.** It shows the correct heading structure, format, and **how to link** for traceability.
+> Create your own blocks in the \`${example.subfolder}/\` folder next to this \`.examples/\` folder.
 > Every block must trace back to what created it and forward to what it enables — see frontmatter above.
 
 ${example.body}
@@ -1805,6 +2005,10 @@ epicontext watch
 - **Glossary**: Domain-specific terminology and definitions
 - **Section Guide**: Overview and navigation for this section
 
+Organize files in subfolders:
+- \`constraints/\` - Constraint files
+- \`glossaries/\` - Glossary/terminology files
+
 This is the first section AI agents should read to understand project boundaries.`,
             blockTypes: ["constraint", "glossary", "section_guide"],
         },
@@ -1815,7 +2019,14 @@ This is the first section AI agents should read to understand project boundaries
 - **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`,
+- **Messaging**: Elevator pitch, value propositions, CTAs
+
+Organize files in subfolders:
+- \`positioning/\` - Brand positioning files
+- \`visual-identity/\` - Visual identity files
+- \`moodboards/\` - Brand moodboard files
+- \`tone-of-voice/\` - Tone of voice files
+- \`messaging/\` - Messaging framework files`,
             blockTypes: ["brand_positioning", "brand_visual_identity", "brand_moodboard", "tone_of_voice", "messaging_framework", "section_guide"],
         },
         "product": {
@@ -1825,7 +2036,14 @@ This is the first section AI agents should read to understand project boundaries
 - **Features**: Individual feature definitions with acceptance criteria
 - **Product Strategy Canvas**: Product-specific strategy and goals
 - **Feature Market Analysis**: Competitive analysis for specific features
-- **Glossary**: Domain-specific terminology and definitions`,
+- **Glossary**: Domain-specific terminology and definitions
+
+Organize files in subfolders:
+- \`overviews/\` - Product overview files
+- \`features/\` - Feature files
+- \`strategy/\` - Strategy canvas files
+- \`market-analysis/\` - Feature market analysis files
+- \`glossaries/\` - Glossary files`,
             blockTypes: ["product_overview", "feature", "product_strategy_canvas", "feature_market_analysis", "glossary", "section_guide"],
         },
         "business-strategy": {
@@ -1836,7 +2054,15 @@ This is the first section AI agents should read to understand project boundaries
 - **SWOT Analysis**: Strengths, weaknesses, opportunities, threats
 - **Porter's Five Forces**: Competitive forces analysis
 - **Strategic Group Map**: Market positioning visualization
-- **Obeya Board**: Visual management board`,
+- **Obeya Board**: Visual management board
+
+Organize files in subfolders:
+- \`ogsm/\` - OGSM framework files
+- \`canvases/\` - Business model canvas files
+- \`swot/\` - SWOT analysis files
+- \`porters/\` - Porter's Five Forces files
+- \`strategic-maps/\` - Strategic group map files
+- \`obeya/\` - Obeya board files`,
             blockTypes: ["ogsm", "business_model_canvas", "swot_analysis", "porters_five_forces", "strategic_group_map", "obeya_board", "section_guide"],
         },
         "users": {
@@ -1859,7 +2085,10 @@ Organize files in subfolders:
 - **User Research**: Research documents with highlights and key insights
 - **Research Data**: Tabular research data with charts and analysis
 
-Organize files in subfolders: \`competitors/\`, \`data-research/\``,
+Organize files in subfolders:
+- \`competitors/\` - Competitor analysis files
+- \`user-research/\` - User research files
+- \`data-research/\` - Research data files`,
             blockTypes: ["competitor", "user_research", "research_data", "section_guide"],
         },
         "technical": {
@@ -1878,9 +2107,17 @@ Organize files in subfolders: \`competitors/\`, \`data-research/\``,
 - **Cost Calculator**: Infrastructure and operational costs breakdown
 
 Organize files in subfolders:
+- \`stacks/\` - Tech stack files
+- \`architecture/\` - Architecture diagram files
 - \`integrations/\` - Integration files
+- \`constraints/\` - Constraint files
+- \`setup/\` - Dev setup files
 - \`api/\` - API endpoint files
-- \`models/\` - Data model files`,
+- \`api-specs/\` - API specification files
+- \`models/\` - Data model files
+- \`schemas/\` - Data schema files
+- \`testing/\` - Testing strategy files
+- \`costs/\` - Cost calculator files`,
             blockTypes: ["tech_stack", "architecture_diagram", "integration", "constraint", "dev_setup", "api_endpoint", "api_spec", "data_model", "data_schema", "testing_strategy", "cost_calculator", "section_guide"],
         },
         "design-system": {
@@ -1891,6 +2128,10 @@ Organize files in subfolders:
   - Use the storybook-template repo for easy setup
 - **Figma Embed**: Link to Figma design files
 
+Organize files in subfolders:
+- \`storybook/\` - Storybook link files
+- \`figma/\` - Figma embed files
+
 Note: This section is for linking external design tools, not for documenting
 components directly. Component documentation lives in Storybook.`,
             blockTypes: ["storybook_link", "figma_embed", "section_guide"],
@@ -1906,6 +2147,10 @@ components directly. Component documentation lives in Storybook.`,
   - Categories, tags, and content types
   - Hierarchical organization of content
 
+Organize files in subfolders:
+- \`trees/\` - IA tree files
+- \`taxonomies/\` - Taxonomy files
+
 These blocks use visual editors in the EpicContext app.`,
             blockTypes: ["ia_tree", "taxonomy", "section_guide"],
         },
@@ -1919,6 +2164,12 @@ These blocks use visual editors in the EpicContext app.`,
   - \`input\`: Leading indicators that drive other metrics
 - **Analytics Events**: Event tracking definitions for implementation
 
+Organize files in subfolders:
+- \`indicators/\` - Metric files
+- \`north-stars/\` - North star metric files
+- \`kpis/\` - KPI files
+- \`events/\` - Analytics event files
+
 Use AARRR categories (acquisition, activation, retention, revenue, referral) for the \`category\` field.`,
             blockTypes: ["metric", "north_star", "kpi", "analytics_event", "section_guide"],
         },
@@ -1931,9 +2182,14 @@ Use AARRR categories (acquisition, activation, retention, revenue, referral) for
   - Decision: What was decided?
   - Rationale: Why this choice over alternatives?
   - Consequences: What are the implications?
+- **Meeting Notes**: Sprint planning, retrospectives, key meetings
+
+Organize files in subfolders:
+- \`adrs/\` - Architecture Decision Records
+- \`meetings/\` - Meeting notes
 
 Good ADRs help future team members understand why things are built this way.`,
-            blockTypes: ["decision", "section_guide"],
+            blockTypes: ["decision", "meeting_notes", "section_guide"],
         },
         "development": {
             description: "Epics, stories, tasks, and roadmaps",
@@ -1949,7 +2205,9 @@ Organize files in subfolders:
 - \`epics/\` - Epic files
 - \`stories/\` - User story files
 - \`tasks/\` - Task/implementation plan files
-- \`roadmaps/\` - Roadmap files`,
+- \`roadmaps/\` - Roadmap files
+- \`matrices/\` - Impact/effort matrix files
+- \`boards/\` - Kanban board files`,
             blockTypes: ["epic", "user_story", "task", "roadmap", "impact_effort_matrix", "kanban_board", "section_guide"],
         },
         "environments": {
@@ -1960,7 +2218,9 @@ Organize files in subfolders:
 - **Release Notes**: Changelog and release documentation
   - Version numbers, dates, and changes
 
-Organize files as needed in the environments folder.`,
+Organize files in subfolders:
+- \`environments/\` - Environment link files
+- \`releases/\` - Release note files`,
             blockTypes: ["environment_link", "release_note", "section_guide"],
         },
         "marketing": {