┌─────────────────────────────────────────────────────────────────────────────┐
│                              BROWSER                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                     Next.js 15 App (App Router)                      │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐    │    │
│  │  │ BEP List │  │ BEP View │  │ Comments │  │ AI Assistant     │    │    │
│  │  │          │  │          │  │ (live)   │  │ (streaming)      │    │    │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘    │    │
│  │                                                                     │    │
│  │         Real-time subscriptions via Convex React hooks              │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                          WebSocket (automatic)
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           CONVEX BACKEND                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                        Queries (real-time reads)                     │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │    │
│  │  │ beps.list    │  │ comments.    │  │ decisions.byBep          │  │    │
│  │  │ beps.get     │  │   byBep      │  │ issues.byBep             │  │    │
│  │  └───��──────────┘  └──────────────┘  └──────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                       Mutations (writes)                             │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │    │
│  │  │ beps.create  │  │ comments.add │  │ decisions.create         │  │    │
│  │  │ beps.update  │  │ comments.    │  │ issues.create            │  │    │
│  │  │              │  │   resolve    │  │ issues.resolve           │  │    │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                        HTTP Actions (AI)                             │    │
│  │  ┌──────────────────────────────────────────────────────────────┐  │    │
│  │  │ /api/ai/stream-assistant - Streaming AI responses             │  │    │
│  │  └──────────────────────────────────────────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         CONVEX DATABASE                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐    │
│  │ users    │  │ beps     │  │ comments │  │ decisions│  │ summaries │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └───────────┘    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────────────────────┐  │
│  │ bepPages │  │openIssues│  │ bepVersions (content history)           │  │
│  └──────────┘  └──────────┘  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

beps-app/
├── convex/                           # Backend (Convex functions)
│   ├── schema.ts                     # Database schema definition
│   ├── users.ts                      # User queries/mutations
│   ├── beps.ts                       # BEP CRUD + versioning
│   ├── comments.ts                   # Comment operations
│   ├── decisions.ts                  # Decision tracking
│   ├── issues.ts                     # Issue management
│   ├── export.ts                     # Export query
│   ├── http.ts                       # HTTP endpoints (AI streaming)
│   ├── migrations.ts                 # Data migrations
│   └── lib/
│       └── prompts.ts                # AI prompt templates
│
├── src/
│   ├── app/                          # Next.js App Router pages
│   │   ├── layout.tsx                # Root layout with providers
│   │   ├── page.tsx                  # Home (BEP list)
│   │   ├── login/page.tsx            # Login page
│   │   ├── api/agent/beps/route.ts   # Public read-only BEP context API
│   │   └── beps/
│   │       ├── new/page.tsx          # Create BEP
│   │       └── [number]/
│   │           ├── page.tsx          # View BEP
│   │           └── edit/page.tsx     # Edit BEP
│   │
│   ├── components/
│   │   ├── ui/                       # shadcn/ui components
│   │   ├── providers/                # Context providers
│   │   ├── bep/                      # BEP-specific components
│   │   ├── comments/                 # Comment system
│   │   ├── decisions/                # Decision tracking
│   │   ├── issues/                   # Issue management
│   │   └── ai-assistant/             # AI assistant panel
│   │
│   ├── hooks/
│   │   └── use-text-selection.ts     # Text selection for inline comments
│   │
│   └── lib/
│       ├── utils.ts                  # Utility functions
│       ├── markdown.tsx              # Markdown styling
│       ├── export-utils.ts           # ZIP export formatting
│       └── import-utils.ts           # ZIP import parsing
│
├── package.json
├── tsconfig.json
├── next.config.ts
├── components.json                   # shadcn/ui config
└── .env.local.example

{
  selectedText: string;   // The exact text commented on
  lineNumber: number;     // Line number in content
  lineContent: string;    // Full line content for matching
}

{
  "mode": "list",
  "total": 2,
  "beps": [
    {
      "id": "BEP-001",
      "number": 1,
      "title": "Structured Error Payloads",
      "status": "accepted",
      "updatedAt": "2026-02-18T20:13:34.000Z"
    }
  ],
  "usage": {
    "list": "/api/agent/beps",
    "fetch": "/api/agent/beps?name=<bep-name-or-id>",
    "omitOtherVersions": "/api/agent/beps?name=<bep-name-or-id>&omitOtherVersions=true"
  }
}

{
  "mode": "bep",
  "query": "structured error payloads",
  "matched": {
    "id": "BEP-001",
    "number": 1,
    "title": "Structured Error Payloads",
    "status": "accepted",
    "score": 1.732
  },
  "currentVersion": 5,
  "omitOtherVersions": false,
  "markdown": "<!-- FILE: README.md -->\n# BEP-001 ...",
  "files": [
    {
      "path": "README.md",
      "content": "# BEP-001 ..."
    }
  ]
}

<!-- FILE: README.md -->
# BEP-001 Structured Error Payloads
...

{
  "error": "Could not find a BEP that matches \"<query>\".",
  "suggestions": [
    { "id": "BEP-003", "title": "..." },
    { "id": "BEP-010", "title": "..." }
  ]
}

{
  "error": "Missing NEXT_PUBLIC_CONVEX_URL environment variable."
}

{
  "error": "Failed to fetch BEP list.",
  "detail": "<error message>"
}

{
  "error": "Failed to fetch BEP export data.",
  "detail": "<error message>"
}

{
  "error": "Invalid BEP export payload shape."
}

Authorization: Bearer bep_xxxxxxxxxxxxx

{
  "title": "Your Proposal Title",
  "content": "# Your Proposal Title\n\n## Summary\n\n...",
  "pages": [
    {
      "slug": "background",
      "title": "Background Research",
      "content": "# Background\n\nDetailed research..."
    },
    {
      "slug": "examples",
      "title": "Code Examples",
      "content": "# Examples\n\nUsage examples..."
    }
  ]
}

{
  "success": true,
  "bepId": "abc123...",
  "number": 15,
  "formattedId": "BEP-015",
  "createdBy": "Your Name",
  "url": "https://beps.boundaryml.com/beps/15"
}

{
  "number": 15,
  "content": "# Updated Content\n\n...",
  "pages": [
    {
      "slug": "background",
      "title": "Updated Background",
      "content": "# Background\n\nUpdated research..."
    },
    {
      "slug": "new-addendum",
      "title": "New Addendum",
      "content": "# New Section\n\nNew content..."
    }
  ],
  "editNote": "Added new addendum, updated background",
  "versionMode": "new"
}

{
  "success": true,
  "bepId": "abc123...",
  "number": 15,
  "formattedId": "BEP-015",
  "versionNumber": 3,
  "versionAction": "created",
  "pagesCreated": 1,
  "pagesUpdated": 1,
  "pagesDeleted": 0,
  "updatedBy": "Your Name",
  "url": "https://beps.boundaryml.com/beps/15"
}

# Download to a new timestamped folder (copy mode)
curl -o all-beps.zip "https://beps.boundaryml.com/api/agent/beps/pull"
unzip all-beps.zip -d all-beps-$(date +%Y%m%d)

# Download and replace existing folder (inplace mode)
curl -o all-beps.zip "https://beps.boundaryml.com/api/agent/beps/pull"
rm -rf ./all-beps && unzip all-beps.zip -d .

all-beps/
├── Claude.md                    # Main index with status-sorted list
├── NEW-BEP/
│   └── INSTRUCTIONS.md          # API usage instructions
├── BEP-001-proposal-slug/
│   ├── meta.json                # Metadata (status, version, pages)
│   ├── README.md                # Full proposal content
│   └── pages/                   # Additional pages (if any)
└── BEP-002-another-slug/
    └── ...

BEP-001/
├── README.md                 # Main content with inline comments embedded
├── pages/
│   ├── background.md         # Additional pages with comments
│   ├── tooling.md
│   └── background/           # One level of nesting supported
│       └── research.md       # Child of the "background" page (parentSlug)
├── AGENT_CONTEXT.md          # AI-friendly summary
├── metadata.json             # Machine-readable metadata
├── discussion/
│   ├── issues.md             # Open and resolved issues
│   └── decisions.md          # Recorded decisions
└── history/
    ├── versions.md           # Version history
    └── summaries.md          # AI-generated summaries

**catch as an operator on blocks**.

<!-- INLINE_COMMENT
version: 3
line: 4
selected_text: "catch as an operator on blocks"
author: Dave
date: 2025-01-20
type: suggestion
status: open
-->
> Should we add an example showing operator precedence?
<!-- /INLINE_COMMENT -->

---

<!-- GENERAL_COMMENTS -->

## Comments

### Concern by Alice (v2, 2025-01-15) [OUTDATED]
> This might confuse newcomers

<!-- /GENERAL_COMMENTS -->

# Development (runs Next.js + Convex in parallel)
bun run dev

# Run only Next.js
bun run dev:next

# Run only Convex
bun run dev:convex

# Build for production
bun run build

# Start production server
bun run start

# Run linting
bun run lint

# Check the BAML project
bun run baml:check

# Regenerate the ignored BAML v1 TypeScript SDK
bun run baml:generate

bunx --bun shadcn@latest add <component-name>