@epiccontext/mcp 0.1.61 → 0.1.63

package/dist/cli/files.js

@@ -1,6 +1,1058 @@
 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
+// These show AI agents the correct heading structure for each block type
+// `frontmatterLinks` shows how to add schema refs and universal links in frontmatter
+const BLOCK_TYPE_EXAMPLES = {
+    // Constitution
+    constraint: { body: `## No Third-Party Analytics
+
+**Priority:** high
+**Category:** privacy
+
+### Description
+
+All analytics must be first-party. No external tracking scripts allowed.
+
+### Rationale
+
+User privacy is a core value. Third-party scripts introduce data leakage risks.
+
+### Implications
+
+- Must build or self-host analytics
+- No Google Analytics, Mixpanel, etc.
+- Server-side event tracking only` },
+    glossary: { body: `## Product-Specific Terms
+
+| Term | Definition |
+|------|-----------|
+| Workspace | Top-level container for projects and members |
+| Block | A single piece of structured content |
+| Section | A category grouping related blocks |` },
+    // Brand
+    brand_positioning: { body: `## Golden Circle
+
+### 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.
+
+### WHAT (Product)
+A context management platform for product teams.
+
+## Positioning Statement
+
+**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.
+
+## Brand Essence
+
+**Tagline:** Context that works for everyone
+**Brand Promise:** Never lose product context again` },
+    brand_visual_identity: { body: `## Colors
+
+### Primary Palette
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| Brand Blue | #2563EB | Primary actions, links |
+| Dark | #111827 | Text, headings |
+| Light | #F9FAFB | Backgrounds |
+
+## Typography
+
+**Primary Font:** Inter
+**Heading Font:** Inter
+**Mono Font:** JetBrains Mono
+
+## Logo
+
+**Format:** SVG
+**Minimum Size:** 24px height` },
+    brand_moodboard: { body: `## Mood & Inspiration
+
+### Visual Direction
+Clean, modern, developer-friendly aesthetic with subtle warmth.
+
+### Reference Images
+- Minimal SaaS dashboards
+- Developer tool interfaces
+- Clean data visualizations
+
+### Color Mood
+Professional blues with warm accent colors.` },
+    tone_of_voice: { body: `## Voice Archetype
+
+**Primary:** The Expert Guide
+**Secondary:** The Supportive Teammate
+
+## Personality Traits
+
+| Trait | Scale (1-10) |
+|-------|-------------|
+| Formal ↔ Casual | 4 |
+| Serious ↔ Playful | 3 |
+| Technical ↔ Simple | 6 |
+
+## Vocabulary
+
+### Preferred Terms
+- "workspace" not "organization"
+- "block" not "document"
+- "sync" not "upload"
+
+### Avoid
+- Jargon without explanation
+- Passive voice
+- Marketing buzzwords` },
+    messaging_framework: { body: `## Elevator Pitch
+
+A context management platform that gives product teams a single source of truth — structured for both humans and AI agents.
+
+## 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.
+
+## Key Messages
+
+| Audience | Message |
+|----------|---------|
+| Developers | "Your AI coding assistant finally has context" |
+| Product Managers | "See documentation gaps before they become problems" |` },
+    // Product
+    product_overview: { frontmatterLinks: `personas_ref:  # Who this product is for
+  - _example-persona
+features_ref:  # Key features
+  - _example-feature
+epics_ref:  # Development epics
+  - _example-epic
+links:  # Universal links
+  - target: _example-competitor
+    label: inspired_by`, body: `### Vision
+Become the standard way product teams manage context for both humans and AI.
+
+### Mission
+Make product documentation structured, complete, and consumable by any tool.
+
+### Problem Statement
+Product teams scatter context across wikis, docs, Slack, and spreadsheets. AI agents can't use unstructured information effectively.
+
+### Target Users
+- 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
+personas_ref:  # Who benefits from this feature
+  - _example-persona
+links:  # Universal links
+  - target: _example-user-story
+    label: relates_to
+  - target: _example-competitor
+    label: inspired_by`, body: `## Smart Notifications
+
+**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
+
+### Target Customer
+Small-to-medium product teams (5-50 people) using multiple tools for documentation.
+
+### Key Problem
+Documentation is scattered, incomplete, and not consumable by AI coding tools.
+
+### Solution Approach
+Structured, block-based documentation with real-time sync to AI coding agents.
+
+### Unique Value Proposition
+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
+
+### Market Opportunity
+Growing demand for AI-integrated development tools. 68% of teams want AI help with documentation.
+
+### Competitive Landscape
+No current tool combines structured documentation with MCP-based AI agent integration.
+
+### Differentiation
+First-mover advantage in structured context for AI coding agents.` },
+    // Users
+    persona: { subfolder: "personas", frontmatterLinks: `jtbds_ref:  # What jobs this persona has
+  - _example-jtbd
+journeys_ref:  # Journey maps for this persona
+  - _example-journey-map
+links:  # Universal links
+  - target: _example-product-overview
+    label: relates_to
+  - target: _example-user-story
+    label: relates_to`, body: `> "I need one place where all product context lives."
+
+## Demographics
+
+| Attribute | Value |
+|-----------|-------|
+| Role | Product Manager |
+| Age | 28-40 |
+| Experience | 3-8 years |
+| Team Size | 5-20 |
+
+## Goals
+- Keep documentation complete and up-to-date
+- Give developers the context they need
+- Track what's documented and what's missing
+
+## Frustrations
+- Documentation scattered across tools
+- Can't tell what's outdated
+- Developers ask the same questions repeatedly
+
+## 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
+links:  # Universal links
+  - target: _example-user-story
+    label: relates_to
+  - 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
+
+### Emotional Job
+- Feel confident the team has what they need
+- Reduce anxiety about knowledge gaps
+
+### 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?
+links:  # Universal links
+  - target: _example-feature
+    label: relates_to
+  - 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"` },
+    // Research
+    competitor: { subfolder: "competitors", frontmatterLinks: `links:  # Universal links to blocks this competitor analysis informs
+  - target: _example-feature
+    label: informs
+  - target: _example-product-overview
+    label: informs
+  - target: _example-decision
+    label: references`, body: `## Linear
+
+**Website:** https://linear.app
+**Category:** Project Management
+
+### 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.
+
+### Strengths
+- Extremely fast and polished UI
+- Great keyboard navigation
+- GitHub integration
+
+### Weaknesses
+- Limited documentation features
+- No AI agent integration
+- No structured content export
+
+### Our Differentiators
+- Structured documentation, not just task tracking
+- AI-native MCP integration
+- Content consumable by coding agents` },
+    user_research: { body: `## User Research Interviews Q1
+
+### Methodology
+- 12 semi-structured interviews (45 min each)
+- Participants: 6 developers, 4 PMs, 2 designers
+- All from teams of 10-50 people
+
+### Key Findings
+
+#### Finding 1: Tool Fatigue
+10 of 12 participants use 3+ tools for documentation. All want consolidation.
+
+#### Finding 2: AI Integration is Critical
+8 of 12 ranked AI integration as their top feature request.
+
+#### Finding 3: Completeness Tracking
+9 of 12 said they can't tell what documentation is missing.
+
+### Recommendations
+1. Prioritize documentation completeness tracking
+2. Build AI agent integration from day one
+3. Import from existing tools` },
+    research_data: { subfolder: "data-research", body: `## Market Size Research
+
+### Key Data Points
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Total Addressable Market | $7.6B | Gartner 2025 |
+| Developer-focused segment | $1.2B | Internal estimate |
+| Teams dissatisfied with PM tools | 42% | Stack Overflow Survey |
+| Average tool spend | $12/user/month | Market research |
+
+### Analysis
+
+The developer documentation tool market is growing at 13% CAGR. Key growth driver is AI integration demand.` },
+    // Technical
+    tech_stack: { body: `## Technology Stack
+
+### Frontend
+| Technology | Purpose | Version |
+|-----------|---------|---------|
+| Next.js | Framework | 14+ |
+| TypeScript | Language | 5.x |
+| Tailwind CSS | Styling | 3.x |
+
+### Backend
+| Technology | Purpose | Version |
+|-----------|---------|---------|
+| Node.js | Runtime | 20+ |
+| Supabase | Database | Latest |
+| PostgreSQL | Database | 15+ |
+
+### Infrastructure
+| Technology | Purpose |
+|-----------|---------|
+| Vercel | Hosting |
+| GitHub Actions | CI/CD |` },
+    architecture_diagram: { body: `## System Architecture
+
+**Level:** container
+**Notation:** C4
+
+### Description
+High-level system architecture showing main containers and their interactions.
+
+### Diagram
+\`\`\`
+[User] --> [Web App (Next.js)]
+[Web App] --> [Database (Supabase)]
+[Web App] --> [Auth (Clerk)]
+[AI Agent] --> [MCP Server]
+[MCP Server] --> [API]
+[API] --> [Database]
+\`\`\`` },
+    integration: { subfolder: "integrations", frontmatterLinks: `decisions_ref:  # Decisions related to this integration
+  - _example-decision
+links:  # Universal links
+  - target: _example-task
+    label: relates_to
+  - 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.
+
+### API Details
+**Base URL:** https://api.github.com
+**Auth Method:** OAuth 2.0
+**Rate Limit:** 5000 requests/hour
+
+### 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
+
+### Prerequisites
+- Node.js 20+
+- npm or pnpm
+- Git
+
+### Quick Start
+\`\`\`bash
+git clone <repo-url>
+cd project
+npm install
+cp .env.example .env.local
+npm run dev
+\`\`\`
+
+### Environment Variables
+| Variable | Description | Required |
+|----------|-------------|----------|
+| DATABASE_URL | Supabase connection string | Yes |
+| CLERK_SECRET_KEY | Auth provider key | Yes |` },
+    api_endpoint: { subfolder: "api", body: `## GET /api/blocks
+
+**Method:** GET
+**Auth:** Required (API key)
+
+### Description
+List all blocks for a project, optionally filtered by section.
+
+### Parameters
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| section | string | No | Filter by section type |
+| status | string | No | Filter by status |
+
+### Response
+\`\`\`json
+{
+  "blocks": [
+    { "key": "example", "type": "feature", "status": "draft" }
+  ]
+}
+\`\`\`` },
+    api_spec: { body: `## API Specification
+
+**Version:** v1
+**Base URL:** /api/v1
+**Auth:** API key via X-API-Key header
+
+### Overview
+RESTful API for managing project blocks and context.
+
+### Authentication
+All endpoints require an API key passed in the X-API-Key header.` },
+    data_model: { subfolder: "models", body: `## Block Model
+
+### Fields
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | UUID | Auto | Primary key |
+| key | string | Yes | Unique identifier |
+| type | string | Yes | Block type |
+| value | JSONB | No | Content |
+| status | string | Yes | draft/complete/empty |
+
+### Relationships
+- Belongs to Section (many-to-one)
+- Has many Links (one-to-many)
+
+### Indexes
+- Unique: (section_id, key)
+- Index: status` },
+    data_schema: { body: `## Database Schema
+
+### Overview
+PostgreSQL database with JSONB content storage for flexible block schemas.
+
+### Tables Overview
+| Table | Purpose | Row Count |
+|-------|---------|-----------|
+| blocks | Content storage | ~500 |
+| sections | Section groupings | ~15 |
+| projects | Project metadata | ~10 |
+
+### Key Design Decisions
+- JSONB for block values (flexible schema per type)
+- UUID primary keys
+- Row Level Security via Supabase` },
+    testing_strategy: { body: `## Testing Strategy
+
+### Philosophy
+Test behavior, not implementation. Focus on user-facing functionality.
+
+### Test Types
+| Type | Tool | Coverage Target |
+|------|------|----------------|
+| Unit | Vitest | 80% |
+| Integration | Playwright | Critical paths |
+| E2E | Playwright | Happy paths |
+
+### What to Test
+- API endpoint responses
+- Block CRUD operations
+- Export format correctness` },
+    cost_calculator: { body: `## Infrastructure Costs
+
+### Monthly Breakdown
+| Service | Tier | Monthly Cost |
+|---------|------|-------------|
+| Vercel | Pro | $20 |
+| Supabase | Pro | $25 |
+| Clerk | Starter | $0 |
+| **Total** | | **$45/mo** |
+
+### Scaling Projections
+| Users | Monthly Cost |
+|-------|-------------|
+| 100 | $45 |
+| 1,000 | $150 |
+| 10,000 | $500 |` },
+    // Design System
+    storybook_link: { body: `## Component Library
+
+**Storybook URL:** https://storybook.example.com
+**Repository:** https://github.com/org/design-system
+
+### Pages
+- Components
+- Tokens
+- Patterns
+
+### Access
+Requires EpicContext authentication token.` },
+    figma_embed: { body: `## Main Design File
+
+**Figma URL:** https://figma.com/file/example
+**Last Updated:** 2025-01-15
+
+### Pages
+- Home Page
+- Dashboard
+- Settings
+
+### Handoff Notes
+Use Auto Layout for all new components. Follow 8px grid.` },
+    // Information Architecture
+    ia_tree: { body: `## Application Structure
+
+### Description
+Main navigation hierarchy for the web application.
+
+\`\`\`
+Home
+├── Dashboard
+│   ├── Overview
+│   └── Activity
+├── Projects
+│   ├── Project Detail
+│   │   ├── Sections
+│   │   └── Settings
+│   └── New Project
+├── Settings
+│   ├── Profile
+│   └── Team
+└── Help
+\`\`\`` },
+    taxonomy: { subfolder: "taxonomies", body: `## Content Taxonomy
+
+### Categories
+| Category | Description | Examples |
+|----------|-------------|----------|
+| Brand | Identity and voice | Colors, typography, tone |
+| Product | Features and vision | Overview, features, roadmap |
+| Technical | Architecture and stack | APIs, data models, setup |
+
+### Tags
+- priority: high, medium, low
+- status: draft, complete, empty
+- audience: developer, designer, manager` },
+    // Metrics
+    metric: { body: `## Weekly Active Users
+
+**Metric Type:** kpi
+**Category:** activation
+**Current Value:** 1,200
+**Target:** 2,000
+**Unit:** users
+
+### Description
+Number of unique users who perform at least one action per week.
+
+### Measurement
+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
+
+**Metric Type:** north_star
+**Category:** activation
+**Current Value:** 450
+**Target:** 1,000
+**Unit:** blocks
+
+### Description
+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
+
+**Metric Type:** kpi
+**Category:** activation
+**Current Value:** 62%
+**Target:** 80%
+**Unit:** percent
+
+### Description
+Percentage of blocks with status "complete" across all sections.` },
+    analytics_event: { body: `## block_completed
+
+**Category:** activation
+**Trigger:** User marks a block as complete
+
+### Properties
+| Property | Type | Description |
+|----------|------|-------------|
+| block_type | string | Type of block completed |
+| 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
+integrations_ref:  # Integrations related to this decision
+  - _example-integration
+links:  # Universal links
+  - target: _example-feature
+    label: informs
+  - target: _example-competitor
+    label: references`, body: `## Use Supabase for Database
+
+**Status:** accepted
+**Date:** 2025-01-15
+**Deciders:** Engineering team
+
+### Context
+Need a database solution that supports real-time, authentication, and JSONB storage.
+
+### Options Considered
+
+#### Option 1: Supabase
+- **Pros:** Built-in auth, real-time, PostgreSQL, generous free tier
+- **Cons:** Vendor lock-in, limited customization
+
+#### Option 2: PlanetScale
+- **Pros:** MySQL, great scaling
+- **Cons:** No JSONB support, separate auth needed
+
+### Decision
+Choose Supabase for its combination of PostgreSQL, built-in auth, and real-time capabilities.
+
+### Consequences
+- Committed to PostgreSQL ecosystem
+- Use Row Level Security for authorization
+- Real-time updates available for free` },
+    meeting_notes: { body: `## Sprint Planning - Week 12
+
+**Date:** 2025-03-15
+**Attendees:** Engineering team
+
+### Discussion Points
+1. Review of completed work from last sprint
+2. Prioritization of upcoming features
+3. Technical debt items
+
+### Decisions Made
+- Prioritize export API for next sprint
+- Defer dark mode to Q2
+
+### Action Items
+- [ ] Create export API epic
+- [ ] Update roadmap` },
+    // Development
+    epic: { subfolder: "epics", frontmatterLinks: `product_ref: _example-product-overview  # Link to parent product
+stories_ref:  # List user stories in this epic
+  - _example-user-story
+links:  # Universal links to related blocks across sections
+  - target: _example-persona
+    label: relates_to
+  - target: _example-decision
+    label: implements`, body: `## Context Export System
+
+**Priority:** high
+**Status:** planned
+**Estimated Effort:** 3 sprints
+
+### Goal
+Enable teams to export their entire product context in multiple formats for AI agent consumption.
+
+### Scope
+- Markdown export (full project)
+- llms.txt format
+- JSON API endpoint
+- MCP server integration
+
+### 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
+personas_ref:  # Who this story is for
+  - _example-persona
+links:  # Universal links to related blocks
+  - target: _example-feature
+    label: implements
+  - target: _example-jtbd
+    label: relates_to`, body: `## Export Context as Markdown
+
+**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.
+
+### 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
+links:  # Universal links to related blocks
+  - target: _example-integration
+    label: depends_on
+  - target: _example-decision
+    label: implements`, body: `## Implement Markdown Export API
+
+**Priority:** high
+**Status:** planned
+**Estimated Hours:** 8
+
+### Description
+Create a GET endpoint at /api/projects/[id]/markdown that generates a full markdown export of all project blocks.
+
+### Technical Approach
+1. Query all blocks for project
+2. Group by section
+3. Apply markdown templates per block type
+4. Return as downloadable zip
+
+### Files to Modify
+- \`lib/export/to-markdown.ts\`
+- \`app/api/projects/[projectId]/markdown/route.ts\`` },
+    roadmap: { body: `## Q1 2025 Roadmap
+
+**Planning Horizon:** quarterly
+
+### Milestones
+
+#### January: Foundation
+- Core block editor
+- Authentication system
+- Basic sections
+
+#### February: Export
+- Markdown export
+- llms.txt format
+- API endpoints
+
+#### March: Collaboration
+- Team invites
+- Activity log
+- Comments` },
+    impact_effort_matrix: { body: `## Product Prioritization Matrix
+
+### High Impact / Low Effort
+- Smart notifications
+- Keyboard shortcuts
+- Export improvements
+
+### High Impact / High Effort
+- AI-assisted documentation
+- Real-time collaboration
+- Mobile app
+
+### Low Impact / Low Effort
+- Dark mode
+- Custom themes
+
+### Low Impact / High Effort
+- Offline support
+- Video embeds` },
+    kanban_board: { body: `## Sprint Board
+
+### Backlog
+- Implement search
+- Add filtering
+
+### In Progress
+- Export API endpoint
+- Block editor improvements
+
+### Review
+- Authentication flow
+
+### Done
+- Project creation
+- Section navigation` },
+    // Business Strategy
+    ogsm: { body: `## Annual OGSM
+
+### Objective
+Become the leading context management platform for product teams.
+
+### Goals
+| Goal | Metric | Target |
+|------|--------|--------|
+| Growth | Monthly Active Users | 10,000 |
+| Revenue | ARR | $1M |
+| Quality | NPS | 50+ |
+
+### Strategies
+1. Focus on developer experience
+2. Build AI-native integrations
+3. Create viral onboarding loop
+
+### Measures
+- Weekly active users growth rate
+- Conversion from free to paid
+- Feature adoption rate` },
+    business_model_canvas: { body: `## Business Model Canvas
+
+### Key Partners
+- AI tool providers (Anthropic, OpenAI)
+- Cloud providers (Vercel, Supabase)
+
+### Key Activities
+- Platform development
+- AI integration partnerships
+- Developer community building
+
+### Value Propositions
+- Single source of truth for product context
+- AI-consumable documentation
+
+### Customer Segments
+- Small product teams (5-20)
+- Mid-market teams (20-50)
+
+### Revenue Streams
+- SaaS subscription ($10-25/user/month)
+- Enterprise tier` },
+    swot_analysis: { body: `## SWOT Analysis
+
+### Strengths
+- First-mover in AI-native documentation
+- Strong technical foundation
+- MCP integration
+
+### Weaknesses
+- Small team
+- No brand recognition yet
+- Limited funding
+
+### Opportunities
+- Growing AI tool adoption
+- Developer tool market expanding
+- Remote work driving documentation needs
+
+### 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
+
+### Threat of New Entrants
+**Rating:** Medium
+New developer tools launch frequently, but our MCP integration creates a defensible moat.
+
+### Bargaining Power of Suppliers
+**Rating:** Low
+Cloud infrastructure is commoditized with many providers.
+
+### Bargaining Power of Buyers
+**Rating:** High
+Many alternatives exist; switching costs are moderate.
+
+### Threat of Substitutes
+**Rating:** Medium
+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
+
+### Dimensions
+- **X-axis:** Target audience (Individual → Enterprise)
+- **Y-axis:** Complexity (Simple → Complex)
+
+### Our Position
+We target the "developer sweet spot" — more powerful than Trello but simpler than Jira, with AI-native capabilities.
+
+### Movement Strategy
+1. **Launch:** Start with small teams
+2. **Grow:** Move to mid-market
+3. **Defend:** AI moat prevents commoditization` },
+    obeya_board: { body: `## Product Obeya Board
+
+### Vision & Strategy (North Wall)
+Platform vision: Make product context accessible to both humans and AI.
+
+### Performance Metrics (East Wall)
+| Metric | Current | Target |
+|--------|---------|--------|
+| WAU | 1,200 | 2,000 |
+| Completion Rate | 62% | 80% |
+
+### Problem Solving (South Wall)
+- Issue: Slow import for large projects
+- Root cause: Sequential file processing
+- Solution: Parallel batch processing
+
+### Improvement Activities (West Wall)
+- Improve onboarding flow
+- Add template library
+- Build API documentation` },
+    // Marketing
+    marketing_campaign: { subfolder: "campaigns", body: `## Developer Launch Campaign
+
+**Platform:** twitter
+**Status:** planned
+**Budget:** $5,000
+**Start Date:** 2025-04-01
+**End Date:** 2025-04-30
+
+### Objective
+Drive 1,000 sign-ups from the developer community.
+
+### Target Audience
+Software developers and product managers at small teams.
+
+### Creative Assets
+- Launch video (60s)
+- Product screenshots
+- Developer testimonials` },
+    seo_content: { subfolder: "seo", body: `## Product Context Management Guide
+
+**Target Keyword:** product context management
+**Search Intent:** informational
+**Status:** planned
+
+### Meta Title
+Product Context Management: The Complete Guide for Teams
+
+### Meta Description
+Learn how product teams manage context documentation effectively. Discover tools and best practices for keeping your team aligned.
+
+### Content Outline
+1. What is product context?
+2. Why documentation fails
+3. Structured vs. unstructured approaches
+4. Tools comparison
+5. Getting started guide` },
+    // Environments
+    environment_link: { body: `## Production Environment
+
+**URL:** https://app.example.com
+**Environment Type:** production
+**Status:** active
+
+### Infrastructure
+- Hosted on Vercel
+- Database: Supabase (us-east-1)
+- CDN: Vercel Edge Network
+
+### Monitoring
+- Uptime: Better Stack
+- Errors: Sentry
+- Analytics: PostHog` },
+    release_note: { body: `## v1.2.0 - Export System
+
+**Version:** 1.2.0
+**Date:** 2025-03-01
+**Type:** feature
+
+### What's New
+- Markdown export for full projects
+- llms.txt format support
+- JSON API endpoint for AI agents
+
+### Bug Fixes
+- Fixed block save race condition
+- Corrected section ordering
+
+### Breaking Changes
+None` },
+    // Reports
+    one_pager: { subfolder: "one-pagers", body: `## Product Launch Brief
+
+**Category:** business_case
+**Confidence:** high
+
+### Executive Summary
+EpicContext is ready for public launch. Core features are complete, early users show strong engagement.
+
+### Key Insights
+1. 62% documentation completion rate among active users
+2. AI agents consume context 10x faster than traditional docs
+3. Onboarding time reduced from 30min to 5min with templates
+
+### Recommendation
+Proceed with public launch, focusing on developer community.` },
+    // Section Guide (generic - used across all sections)
+    section_guide: { body: `## Overview
+
+This section contains [description of section content].
+
+## Guidelines
+
+### What Belongs Here
+- [List of content types for this section]
+
+### Best Practices
+- Keep blocks focused on a single topic
+- Link related blocks using frontmatter references
+- Update status as content is completed
+
+## Resources
+- See AI-GUIDE.md for format rules
+- See .ai-guides/ for detailed schemas` },
+};
 // Section metadata for modular AI guides
 // Note: "section_guide" is allowed in ALL sections but is a generic/admin type
 const SECTION_INFO = {
@@ -350,12 +1402,12 @@ updated: ${today}
 /**
  * Generate all section guides in the .ai-guides folder
  */
-function generateSectionGuides(aiGuidesDir) {
+function generateSectionGuides(aiGuidesDir, forceOverwrite) {
     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)) {
+            if (forceOverwrite || !fs.existsSync(guidePath)) {
                 fs.writeFileSync(guidePath, guideContent, "utf-8");
             }
         }
@@ -381,9 +1433,9 @@ export function readContextFolder(contextPath) {
                 }
             }
             else if (entry.isFile() && entry.name.endsWith(".md")) {
-                // Skip README and AI-GUIDE
+                // Skip README, AI-GUIDE, and _example-* files
                 const lowerName = entry.name.toLowerCase();
-                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md") {
+                if (lowerName !== "readme.md" && lowerName !== "ai-guide.md" && !entry.name.startsWith("_example-")) {
                     const content = fs.readFileSync(fullPath, "utf-8");
                     files.push({
                         path: relativePath,
@@ -548,7 +1600,104 @@ npx @epiccontext/mcp add-app ./apps/my-app --name "my-app"
 `, "utf-8");
     }
 }
-export function ensureContextFolder(contextPath) {
+/**
+ * Generate _example-*.md files for each block type in each section.
+ * These show AI agents the correct heading structure and format.
+ * They are skipped by readContextFolder, push, and import pipelines.
+ */
+/**
+ * Check if a section directory has any real (non-example, non-README) markdown files
+ */
+function sectionHasRealBlocks(sectionDir) {
+    function check(dir) {
+        if (!fs.existsSync(dir))
+            return false;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && !entry.name.startsWith(".")) {
+                if (check(path.join(dir, entry.name)))
+                    return true;
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                const lower = entry.name.toLowerCase();
+                if (lower !== "readme.md" && !entry.name.startsWith("_example-")) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    return check(sectionDir);
+}
+function generateExampleFiles(contextPath, skipIfHasBlocks) {
+    const today = new Date().toISOString().split("T")[0];
+    // When upgrading, check which sections already have real blocks
+    const sectionsWithBlocks = new Set();
+    if (skipIfHasBlocks) {
+        for (const [_key, info] of Object.entries(SECTION_INFO)) {
+            const sectionDir = path.join(contextPath, info.folder);
+            if (fs.existsSync(sectionDir)) {
+                if (sectionHasRealBlocks(sectionDir)) {
+                    sectionsWithBlocks.add(info.folder);
+                }
+            }
+        }
+    }
+    for (const [_sectionKey, info] of Object.entries(SECTION_INFO)) {
+        // Skip sections that already have real blocks (upgrade mode)
+        if (skipIfHasBlocks && sectionsWithBlocks.has(info.folder))
+            continue;
+        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);
+            }
+            // 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);
+            // Don't overwrite existing example files
+            if (fs.existsSync(filePath))
+                continue;
+            // Use the section key that matches the folder (handle hyphen vs underscore)
+            const sectionForFrontmatter = info.folder;
+            // Build frontmatter with optional link examples
+            const frontmatterLines = [
+                `type: ${blockType}`,
+                `section: ${sectionForFrontmatter}`,
+                `key: _example-${blockType.replace(/_/g, "-")}`,
+                `name: "Example ${blockType.split("_").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}"`,
+                `status: draft`,
+                `created: ${today}`,
+                `updated: ${today}`,
+            ];
+            // Add link examples if this block type has them
+            if (example.frontmatterLinks) {
+                frontmatterLines.push(example.frontmatterLinks);
+            }
+            const content = `---
+${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.
+> Every block must trace back to what created it and forward to what it enables — see frontmatter above.
+
+${example.body}
+`;
+            fs.writeFileSync(filePath, content, "utf-8");
+        }
+    }
+}
+export function ensureContextFolder(contextPath, options = {}) {
     if (!fs.existsSync(contextPath)) {
         fs.mkdirSync(contextPath, { recursive: true });
     }
@@ -639,11 +1788,11 @@ epicontext watch
     if (!fs.existsSync(aiGuidesDir)) {
         fs.mkdirSync(aiGuidesDir, { recursive: true });
     }
-    // Generate section-specific guides
-    generateSectionGuides(aiGuidesDir);
+    // Generate section-specific guides (force overwrite on upgrade)
+    generateSectionGuides(aiGuidesDir, options.forceRegenerateGuides);
     // Create AI-GUIDE.md (slim core version) with detailed format instructions
     const aiGuidePath = path.join(contextPath, "AI-GUIDE.md");
-    if (!fs.existsSync(aiGuidePath)) {
+    if (options.forceRegenerateGuides || !fs.existsSync(aiGuidePath)) {
         const aiGuide = generateCoreAIGuide();
         fs.writeFileSync(aiGuidePath, aiGuide, "utf-8");
     }
@@ -853,7 +2002,7 @@ Reports should always reference source blocks (personas, journeys, research) for
     };
     for (const section of defaultSections) {
         const sectionReadmePath = path.join(contextPath, section, "README.md");
-        if (!fs.existsSync(sectionReadmePath)) {
+        if (options.forceRegenerateGuides || !fs.existsSync(sectionReadmePath)) {
             const sectionInfo = sectionDescriptions[section];
             const description = sectionInfo?.description || section;
             const guidance = sectionInfo?.guidance || "Add blocks via the EpicContext app or create markdown files with proper frontmatter.";
@@ -883,6 +2032,8 @@ See \`AI-GUIDE.md\` in the root CONTEXT folder for detailed format instructions.
             fs.writeFileSync(sectionReadmePath, sectionReadme, "utf-8");
         }
     }
+    // Generate example files for each block type (skipped by push/import)
+    generateExampleFiles(contextPath, options.skipExamplesIfHasBlocks);
 }
 /**
  * Create a sample file with correct frontmatter if it doesn't exist