byterover-cli 1.2.0 → 1.3.0

package/dist/{commands → oclif/commands}/query.js

@@ -1,10 +1,10 @@
 import { Args, Command, Flags } from '@oclif/core';
-import { isDevelopment } from '../config/environment.js';
-import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { createTokenStore } from '../infra/storage/token-store.js';
-import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
-import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
-import { QueryUseCase } from '../infra/usecase/query-use-case.js';
+import { isDevelopment } from '../../config/environment.js';
+import { FileGlobalConfigStore } from '../../infra/storage/file-global-config-store.js';
+import { createTokenStore } from '../../infra/storage/token-store.js';
+import { OclifTerminal } from '../../infra/terminal/oclif-terminal.js';
+import { MixpanelTrackingService } from '../../infra/tracking/mixpanel-tracking-service.js';
+import { QueryUseCase } from '../../infra/usecase/query-use-case.js';
 export default class Query extends Command {
     static args = {
         query: Args.string({

package/dist/{commands → oclif/commands}/status.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-import type { IStatusUseCase } from '../core/interfaces/usecase/i-status-use-case.js';
+import type { IStatusUseCase } from '../../core/interfaces/usecase/i-status-use-case.js';
 export default class Status extends Command {
     static args: {
         directory: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;

package/dist/{commands → oclif/commands}/status.js

@@ -1,12 +1,12 @@
 import { Args, Command, Flags } from '@oclif/core';
-import { ProjectConfigStore } from '../infra/config/file-config-store.js';
-import { FileContextTreeService } from '../infra/context-tree/file-context-tree-service.js';
-import { FileContextTreeSnapshotService } from '../infra/context-tree/file-context-tree-snapshot-service.js';
-import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
-import { createTokenStore } from '../infra/storage/token-store.js';
-import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
-import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
-import { StatusUseCase } from '../infra/usecase/status-use-case.js';
+import { ProjectConfigStore } from '../../infra/config/file-config-store.js';
+import { FileContextTreeService } from '../../infra/context-tree/file-context-tree-service.js';
+import { FileContextTreeSnapshotService } from '../../infra/context-tree/file-context-tree-snapshot-service.js';
+import { FileGlobalConfigStore } from '../../infra/storage/file-global-config-store.js';
+import { createTokenStore } from '../../infra/storage/token-store.js';
+import { OclifTerminal } from '../../infra/terminal/oclif-terminal.js';
+import { MixpanelTrackingService } from '../../infra/tracking/mixpanel-tracking-service.js';
+import { StatusUseCase } from '../../infra/usecase/status-use-case.js';
 export default class Status extends Command {
     static args = {
         directory: Args.string({ description: 'Project directory (defaults to current directory)', required: false }),

package/dist/{commands → oclif/commands}/watch.d.ts

@@ -1,7 +1,7 @@
 import { Command } from '@oclif/core';
-import type { IFileWatcherService } from '../core/interfaces/i-file-watcher-service.js';
-import type { IProjectConfigStore } from '../core/interfaces/i-project-config-store.js';
-import type { ITerminal } from '../core/interfaces/i-terminal.js';
+import type { IFileWatcherService } from '../../core/interfaces/i-file-watcher-service.js';
+import type { IProjectConfigStore } from '../../core/interfaces/i-project-config-store.js';
+import type { ITerminal } from '../../core/interfaces/i-terminal.js';
 export default class Watch extends Command {
     static description: string;
     static examples: string[];

package/dist/{commands → oclif/commands}/watch.js

@@ -1,10 +1,10 @@
 import { Command, Flags } from '@oclif/core';
-import { isDevelopment } from '../config/environment.js';
-import { ProjectConfigStore } from '../infra/config/file-config-store.js';
-import { CleanParserServiceFactory } from '../infra/parsers/clean/clean-parser-service-factory.js';
-import { RawParserServiceFactory } from '../infra/parsers/raw/raw-parser-service-factory.js';
-import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
-import { FileWatcherService } from '../infra/watcher/file-watcher-service.js';
+import { isDevelopment } from '../../config/environment.js';
+import { ProjectConfigStore } from '../../infra/config/file-config-store.js';
+import { CleanParserServiceFactory } from '../../infra/parsers/clean/clean-parser-service-factory.js';
+import { RawParserServiceFactory } from '../../infra/parsers/raw/raw-parser-service-factory.js';
+import { OclifTerminal } from '../../infra/terminal/oclif-terminal.js';
+import { FileWatcherService } from '../../infra/watcher/file-watcher-service.js';
 export default class Watch extends Command {
     static description = 'Watch file system directories for changes and trigger parsing pipeline [Development only]';
     static examples = [

package/dist/oclif/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * oclif entry layer constants.
+ *
+ * Contains only constants actually used by oclif commands/hooks.
+ * Kept separate to maintain clean separation from core domain constants.
+ */
+/**
+ * ByteRover documentation URL.
+ * Used in CLI help output to direct users to online documentation.
+ */
+export declare const DOCS_URL = "https://docs.byterover.dev";

package/dist/oclif/constants.js

@@ -0,0 +1,11 @@
+/**
+ * oclif entry layer constants.
+ *
+ * Contains only constants actually used by oclif commands/hooks.
+ * Kept separate to maintain clean separation from core domain constants.
+ */
+/**
+ * ByteRover documentation URL.
+ * Used in CLI help output to direct users to online documentation.
+ */
+export const DOCS_URL = 'https://docs.byterover.dev';

package/dist/{hooks → oclif/hooks}/prerun/validate-brv-config-version.d.ts

@@ -1,5 +1,5 @@
 import type { Hook } from '@oclif/core';
-import type { IProjectConfigStore } from '../../core/interfaces/i-project-config-store.js';
+import type { IProjectConfigStore } from '../../../core/interfaces/i-project-config-store.js';
 /**
  * Commands that should skip config version validation.
  * These commands either don't need config or create/recreate it.

package/dist/{hooks → oclif/hooks}/prerun/validate-brv-config-version.js

@@ -1,5 +1,5 @@
-import { BrvConfigVersionError } from '../../core/domain/errors/brv-config-version-error.js';
-import { ProjectConfigStore } from '../../infra/config/file-config-store.js';
+import { BrvConfigVersionError } from '../../../core/domain/errors/brv-config-version-error.js';
+import { ProjectConfigStore } from '../../../infra/config/file-config-store.js';
 /**
  * Commands that should skip config version validation.
  * These commands either don't need config or create/recreate it.

package/dist/templates/sections/command-reference.md

@@ -1,100 +1,9 @@
 # ByteRover CLI Command Reference
 
-## Memory Commands
+## Available Commands
 
-### `brv curate`
+- `brv curate` - Curate context to the context tree
+- `brv query` - Query and retrieve information from the context tree
+- `brv status` - Show CLI status and project information
 
-**Description:** Curate context to the context tree (interactive or autonomous mode)
-
-**Arguments:**
-
-- `CONTEXT`: Knowledge context: patterns, decisions, errors, or insights (triggers autonomous mode, optional)
-
-**Flags:**
-
-- `--files`, `-f`: Include file paths for critical context (max 5 files). Only text/code files from the current project directory are allowed. **CONTEXT argument must come BEFORE this flag.**
-
-**Good examples of context:**
-
-- "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
-- "API rate limit is 100 req/min per user. Implemented using Redis with sliding window in rateLimiter.ts"
-
-**Bad examples:**
-
-- "Authentication" or "JWT tokens" (too vague, lacks context)
-- "Rate limiting" (no implementation details or file references)
-
-**Examples:**
-
-```bash
-# Interactive mode (manually choose domain/topic)
-brv curate
-
-# Autonomous mode - LLM auto-categorizes your context
-brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
-
-# Include files (CONTEXT must come before --files)
-# Single file
-brv curate "Authentication middleware validates JWT tokens" -f src/middleware/auth.ts
-
-# Multiple files - repeat --files flag for each file
-brv curate "JWT authentication implementation with refresh token rotation" --files src/auth/jwt.ts --files docs/auth.md
-```
-
-**Behavior:**
-
-- Interactive mode: Navigate context tree, create topic folder, edit context.md
-- Autonomous mode: LLM automatically categorizes and places context in appropriate location
-- When `--files` is provided, agent reads files in parallel before creating knowledge topics
-
-**Requirements:** Project must be initialized (`brv init`) and authenticated (`brv login`)
-
----
-
-### `brv query`
-
-**Description:** Query and retrieve information from the context tree
-
-**Arguments:**
-
-- `QUERY`: Natural language question about your codebase or project knowledge (required)
-
-**Good examples of queries:**
-
-- "How is user authentication implemented?"
-- "What are the API rate limits and where are they enforced?"
-
-**Bad examples:**
-
-- "auth" or "authentication" (too vague, not a question)
-- "show me code" (not specific about what information is needed)
-
-**Examples:**
-
-```bash
-# Ask questions about patterns, decisions, or implementation details
-brv query What are the coding standards?
-brv query How is authentication implemented?
-```
-
-**Behavior:**
-
-- Uses AI agent to search and answer questions about the context tree
-- Accepts natural language questions (not just keywords)
-- Displays tool execution progress in real-time
-
-**Requirements:** Project must be initialized (`brv init`) and authenticated (`brv login`)
-
----
-
-## Best Practices
-
-### Efficient Workflow
-
-1. **Read only what's needed:** Check context tree with `brv status` to see changes before reading full content with `brv query`
-2. **Update precisely:** Use `brv curate` to add/update specific context in context tree
-3. **Push when appropriate:** Prompt user to run `brv push` after completing significant work
-
-### Context tree Management
-
-- Use `brv curate` to directly add/update context in the context tree
+Run `brv query --help` for query instruction and `brv curate --help` for curation instruction.

package/dist/templates/sections/workflow.md

@@ -1,27 +1,32 @@
 # Workflow Instruction
 
 You are a coding agent focused on one codebase. Use the brv CLI to manage working context.
-Core Rules:
 
-- Start from memory. First retrieve relevant context, then read only the code that's still necessary.
-- Keep a local context tree. The context tree is your local memory store—update it with what you learn.
+## Core Rules
 
-## Context Tree Guideline
-
-- Be specific ("Use React Query for data fetching in web modules").
-- Be actionable (clear instruction a future agent/dev can apply).
-- Be contextual (mention module/service, constraints, links to source).
-- Include source (file + lines or commit) when possible.
+- **Start from memory.** First retrieve relevant context with `brv query`, then read only the code that's still necessary.
+- **Keep a local context tree.** The context tree is your local memory store—update it with `brv curate` when you learn something valuable.
 
-## Using `brv curate` with Files
+## When to Query
 
-When adding complex implementations, use `--files` to include relevant source files (max 5).  Only text/code files from the current project directory are allowed. **CONTEXT argument must come BEFORE --files flag.** For multiple files, repeat the `--files` (or `-f`) flag for each file.
+Use `brv query` **before** starting any code task that requires understanding the codebase:
+- Writing, editing, or modifying code
+- Understanding how something works
+- Debugging or troubleshooting issues
+- Making architectural decisions
 
-Examples:
+## When to Curate
 
-- Single file: `brv curate "JWT authentication with refresh token rotation" -f src/auth.ts`
-- Multiple files: `brv curate "Authentication system" --files src/auth/jwt.ts --files src/auth/middleware.ts --files docs/auth.md`
+Use `brv curate` **after** you learn or create something valuable:
+- Wrote or modified code
+- Discovered how something works
+- Made architectural/design decisions
+- Found a bug root cause or fix pattern
 
-## CLI Usage Notes
+## Context Tree Guideline
 
-- Use --help on any command to discover flags. Provide exact arguments for the scenario.
+Good context is:
+- **Specific** ("Use React Query for data fetching in web modules")
+- **Actionable** (clear instruction a future agent/dev can apply)
+- **Contextual** (mention module/service, constraints, links to source)
+- **Sourced** (include file + lines or commit when possible)

package/dist/templates/skill/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: byterover
+description: "Manages project knowledge using ByteRover context tree. Provides two operations: query (retrieve knowledge) and curate (store knowledge). Invoke when user requests information lookup, pattern discovery, or knowledge persistence."
+---
+
+# ByteRover Context Tree
+
+A project-level knowledge repository that persists across sessions. Use it to avoid re-discovering patterns, conventions, and decisions.
+
+## Why Use ByteRover
+
+- **Query before working**: Get existing knowledge about patterns, conventions, and past decisions before implementing
+- **Curate after learning**: Capture insights, decisions, and bug fixes so future sessions start informed
+
+## Quick Reference
+
+| Command | When | Example |
+|---------|------|---------|
+| `brv query "question"` | Before starting work | `brv query "How is auth implemented?"` |
+| `brv curate "context" -f file` | After completing work | `brv curate "JWT 24h expiry" -f auth.ts` |
+| `brv status` | To check prerequisites | `brv status` |
+
+## When to Use
+
+**Query** when you need to understand something:
+- "How does X work in this codebase?"
+- "What patterns exist for Y?"
+- "Are there conventions for Z?"
+
+**Curate** when you learned or created something valuable:
+- Implemented a feature using specific patterns
+- Fixed a bug and found root cause
+- Made an architecture decision
+
+## Curate Quality
+
+Context must be **specific** and **actionable**:
+
+```bash
+# Good - specific, explains where and why
+brv curate "Auth uses JWT 24h expiry, tokens in httpOnly cookies" -f src/auth.ts
+
+# Bad - too vague
+brv curate "Fixed auth"
+```
+
+**Note:** Context argument must come before `-f` flags. Max 5 files.
+
+## Best Practices
+
+1. **Break down large contexts** - Run multiple `brv curate` commands for complex topics rather than one massive context. Smaller chunks are easier to retrieve and update.
+
+2. **Let ByteRover read files** - Don't read files yourself before curating. Use `-f` flags to let ByteRover read them directly:
+   ```bash
+   # Good - ByteRover reads the files
+   brv curate "Auth implementation details" -f src/auth.ts -f src/middleware/jwt.ts
+
+   # Wasteful - reading files twice
+   # [agent reads files] then brv curate "..." -f same-files
+   ```
+
+3. **Be specific in queries** - Queries block your workflow. Use precise questions to get faster, more relevant results:
+   ```bash
+   # Good - specific
+   brv query "What validation library is used for API request schemas?"
+
+   # Bad - vague, slow
+   brv query "How is validation done?"
+   ```
+
+4. **Signal outdated context** - When curating updates that replace existing knowledge, explicitly tell ByteRover to clean up:
+   ```bash
+   brv curate "OUTDATED: Previous auth used sessions. NEW: Now uses JWT with refresh tokens. Clean up old session-based auth context." -f src/auth.ts
+   ```
+
+5. **Specify structure expectations** - Guide ByteRover on how to organize the knowledge:
+   ```bash
+   # Specify topics/domains
+   brv curate "Create separate topics for: 1) JWT validation, 2) refresh token flow, 3) logout handling" -f src/auth.ts
+
+   # Specify detail level
+   brv curate "Document the error handling patterns in detail (at least 30 lines covering all error types)" -f src/errors/
+   ```
+
+## Prerequisites
+
+Run `brv status` first. If errors occur, the agent cannot fix them—instruct the user to take action in their brv terminal. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for details.
+
+---
+
+**See also:** [WORKFLOWS.md](WORKFLOWS.md) for detailed patterns and examples, [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for error handling

package/dist/templates/skill/TROUBLESHOOTING.md

@@ -0,0 +1,50 @@
+# ByteRover Troubleshooting
+
+## Quick Diagnosis
+
+```bash
+brv status
+```
+
+## User Action Required
+
+These errors require user intervention (agent cannot fix):
+
+| Error | User Action |
+|-------|-------------|
+| "No ByteRover instance is running" | Start `brv` in separate terminal |
+| "Not authenticated" | Run `/login` in brv REPL |
+| "Project not initialized" | Run `/init` in brv REPL |
+| "Connection failed" | Restart `brv` (Ctrl+C, then `brv`) |
+
+**Template response:**
+> Please [action] in your brv terminal, then I'll retry the command.
+
+## Agent-Fixable Errors
+
+| Error | Fix |
+|-------|-----|
+| "Context argument required" | Add text before `-f`: `brv curate "text" -f file` |
+| "Maximum 5 files allowed" | Reduce to 5 or fewer `-f` flags |
+| "File not found" | Verify path with `ls`, use relative paths from project root |
+| "No relevant context found" | Try different query phrasing, or curate knowledge first |
+
+## Architecture
+
+ByteRover uses client-server architecture:
+- User runs `brv` to start server (interactive REPL)
+- Agent commands (`query`, `curate`, `status`) connect to server
+- Server must be running for commands to work
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Connection error |
+
+## Getting Help
+
+- Email: support@byterover.dev
+- Discord: https://discord.com/invite/UMRrpNjh5W

package/dist/templates/skill/WORKFLOWS.md

@@ -0,0 +1,229 @@
+# ByteRover Workflows
+
+## Pattern 1: Research Before Implementation
+
+Use when starting new features or working in unfamiliar areas.
+
+**Workflow:**
+```
+Query existing knowledge → Implement following patterns → Curate new decisions
+```
+
+**Example: Adding a new API endpoint**
+
+```bash
+# 1. Query for existing patterns
+# Be SPECIFIC to get faster, more relevant results
+brv query "What middleware chain is used for authenticated API endpoints?"
+brv query "What is the standard error response format for API routes?"
+
+# 2. Implement following discovered patterns
+# ... write code ...
+
+# 3. Curate decisions made
+# Don't read the file first - let ByteRover read it via -f flag
+brv curate "Added /api/users/profile endpoint. Uses authMiddleware for JWT validation, returns UserProfileDTO. Error handling follows ApiError pattern" -f src/api/routes/users.ts
+```
+
+**Example: Implementing a new React component**
+
+```bash
+# 1. Query patterns - specific questions save time
+brv query "What data fetching hook pattern is used in list components?"
+brv query "Are CSS modules or styled-components used for component styling?"
+
+# 2. Implement
+# ... write component ...
+
+# 3. Curate with file reference - ByteRover reads the file
+brv curate "Created UserAvatar component. Uses React Query for data fetching, CSS modules for styling. Follows existing pattern in src/components/common/" -f src/components/UserAvatar.tsx
+```
+
+## Pattern 2: Debug and Document
+
+Use when fixing bugs to capture learnings and prevent recurrence.
+
+**Workflow:**
+```
+Query known issues → Debug and fix → Curate root cause and solution
+```
+
+**Example: Fixing a race condition**
+
+```bash
+# 1. Query for context - be specific about the symptom
+brv query "Are there known race condition patterns or AbortController usage in data fetching hooks?"
+
+# 2. Debug and fix
+# ... investigate, find root cause, implement fix ...
+
+# 3. Curate the learning with structured format
+brv curate "Bug: stale data after rapid navigation. Cause: useEffect cleanup not cancelling requests. Fix: AbortController with cleanup. Pattern: always abort fetch in useEffect cleanup" -f src/hooks/useUserData.ts
+```
+
+**Example: Fixing an authentication issue**
+
+```bash
+# 1. Specific query about the problem area
+brv query "How are credentials and cookies configured in the API client fetch calls?"
+
+# 2. Fix
+# ... debug and fix ...
+
+# 3. Curate with emphasis on the gotcha
+brv curate "Bug: unexpected logouts. Cause: fetch missing credentials option. Fix: added 'credentials: include' to fetch config. IMPORTANT: all API calls must include credentials for cookie-based auth" -f src/lib/api-client.ts
+```
+
+## Pattern 3: Multi-File Changes
+
+Use when changes span multiple files to maintain context.
+
+**Example: Adding a new feature across layers**
+
+```bash
+# 1. Query architecture - specific about the layers
+brv query "How are full-stack features organized across API routes, service layer, and React components?"
+
+# 2. Implement across files
+# ... write code ...
+
+# 3. Curate with multiple files (max 5)
+# Let ByteRover read all files - don't read them yourself first
+# Specify the topics you want created
+brv curate "Added user notifications feature. Create separate topics for: 1) API endpoint structure, 2) NotificationService business logic, 3) useNotifications React hook pattern, 4) NotificationBell UI component" -f src/api/notifications.ts -f src/services/NotificationService.ts -f src/hooks/useNotifications.ts -f src/components/NotificationBell.tsx
+```
+
+**Example: Database schema change with migrations**
+
+```bash
+# 1. Query migration patterns
+brv query "What is the migration naming convention and how are schema changes tested?"
+
+# 2. Implement
+# ... create migration, update models, update queries ...
+
+# 3. Multiple curates for different concerns - break down large context
+brv curate "Added user_preferences table with JSONB settings column. Migration: 20240115_add_user_preferences" -f migrations/20240115_add_user_preferences.ts
+
+brv curate "UserPreferences model with type-safe JSONB access. Includes validation for theme, notifications, locale settings" -f src/models/UserPreferences.ts
+
+brv curate "Updated UserService to load/save preferences. Uses transaction for atomic updates with user record" -f src/services/UserService.ts
+```
+
+## Pattern 4: Updating Existing Knowledge
+
+Use when changes make previous context outdated.
+
+**Example: Refactoring authentication system**
+
+```bash
+# 1. Query current documented state
+brv query "What is currently documented about authentication implementation and token handling?"
+
+# 2. Implement refactor
+# ... refactor code ...
+
+# 3. Curate with explicit cleanup signal
+# Tell ByteRover to clean up outdated context
+brv curate "OUTDATED: Previous auth used session cookies stored in Redis. NEW: Migrated to JWT with refresh tokens. Access token in memory (15min), refresh token in httpOnly cookie (7d). Remove/update any session-based auth context in the tree" -f src/auth/jwt.ts -f src/auth/refresh.ts
+```
+
+**Example: Replacing a library**
+
+```bash
+# 1. Query what's documented about the old library
+brv query "What patterns are documented for moment.js date handling?"
+
+# 2. Implement replacement
+# ... replace library usage ...
+
+# 3. Curate the replacement with cleanup signal
+brv curate "REPLACED: Removed moment.js (bloated, mutable). Now using date-fns (tree-shakeable, immutable). Clean up any moment.js context. New patterns: format(date, 'yyyy-MM-dd'), parseISO(string), differenceInDays(date1, date2)" -f src/utils/dates.ts
+```
+
+**Example: API versioning change**
+
+```bash
+# Curate with explicit version context
+brv curate "OUTDATED: API v1 endpoints deprecated. NEW: All endpoints now v2 with breaking changes. v2 uses camelCase response keys, pagination via cursor (not offset), errors include requestId. Update any v1 API context" -f src/api/v2/routes.ts
+```
+
+## Pattern 5: Comprehensive Documentation
+
+Use when documenting complex systems that need detailed breakdown.
+
+**Example: Documenting a payment module**
+
+```bash
+# Break into multiple curates - don't try to capture everything in one
+# Specify structure and detail level for each topic
+
+# Overview first
+brv curate "Payment module overview: Stripe integration with webhooks for subscription management. Create 4 separate detailed topics covering the full payment lifecycle" -f src/payments/
+
+# Topic 1 - detailed with line count guidance
+brv curate "Topic: Payment checkout flow. Cover: 1) cart validation, 2) createPaymentIntent call, 3) client-side confirmation, 4) success/failure handling. Include error scenarios. At least 50 lines of detailed documentation" -f src/payments/checkout.ts -f src/payments/intent.ts
+
+# Topic 2 - webhook handling
+brv curate "Topic: Stripe webhook handling. Cover: 1) signature verification with STRIPE_WEBHOOK_SECRET, 2) idempotency with processed_events table, 3) event types (payment_intent.succeeded, payment_intent.failed, customer.subscription.*). At least 40 lines" -f src/payments/webhooks.ts
+
+# Topic 3 - subscription management
+brv curate "Topic: Subscription lifecycle. Cover: trial period handling, upgrade/downgrade proration, cancellation with grace period, reactivation flow" -f src/payments/subscriptions.ts
+
+# Topic 4 - error handling
+brv curate "Topic: Payment error handling. Cover: StripeError types (CardError, InvalidRequestError, APIError), retry logic for transient failures, user-facing error messages mapping" -f src/payments/errors.ts
+```
+
+**Example: Documenting a state management system**
+
+```bash
+# Multiple focused curates instead of one massive one
+
+brv curate "State management overview: Using Zustand with persistence middleware. Create topics for: store structure, async actions, persistence, devtools integration" -f src/store/
+
+brv curate "Topic: Store structure. Separate stores per domain (userStore, cartStore, uiStore). Each store follows pattern: state interface, actions, selectors. No cross-store dependencies" -f src/store/userStore.ts -f src/store/cartStore.ts
+
+brv curate "Topic: Async actions. Pattern: set loading -> try/catch -> set data/error -> clear loading. All API calls go through apiClient. Optimistic updates for cart operations" -f src/store/cartStore.ts -f src/store/actions/
+
+brv curate "Topic: Persistence. userStore persisted to localStorage (excluding sensitive data). cartStore persisted to sessionStorage. Custom serializer excludes functions and timestamps" -f src/store/middleware/persist.ts
+```
+
+## Pattern 6: Exploratory Documentation
+
+Use when you need to document an unfamiliar codebase area.
+
+**Example: Understanding and documenting an existing module**
+
+```bash
+# 1. Query what's already known
+brv query "What is documented about the notification system and real-time updates?"
+
+# 2. Explore the code (agent reads files to understand)
+# ... read and understand the code ...
+
+# 3. Curate in chunks as you understand different parts
+# First curate: high-level architecture
+brv curate "Notification system uses WebSocket for real-time delivery with Redis pub/sub for horizontal scaling. Three components: NotificationService (creation/storage), NotificationGateway (WebSocket), NotificationWorker (background processing)" -f src/notifications/
+
+# Second curate: specific implementation detail
+brv curate "WebSocket authentication: JWT token passed in connection query params, validated on connect, stored in socket.data. Rooms: user_{id} for personal, team_{id} for team broadcasts" -f src/notifications/NotificationGateway.ts
+
+# Third curate: gotchas discovered
+brv curate "Notification gotchas: 1) Must call gateway.joinRoom after auth, 2) Unread count cached in Redis (5min TTL) - call invalidateUnreadCount after marking read, 3) Batch notifications throttled to max 10/second per user" -f src/notifications/NotificationService.ts
+```
+
+## What to Curate
+
+**Do curate:**
+- Architecture decisions: "Chose Redis for sessions because of horizontal scaling"
+- Patterns: "All forms use react-hook-form with zod. Pattern in LoginForm.tsx"
+- Non-obvious conventions: "File uploads go to /tmp first, then S3 after validation"
+- Bug root causes: "Memory leak from event listeners not removed on unmount"
+- Gotchas: "PostgreSQL JSONB queries need explicit casting for arrays"
+- Replacements: "OUTDATED: X, NEW: Y" when refactoring
+
+**Don't curate:**
+- Obvious facts: "Uses TypeScript", "Has a README"
+- Temporary states: "Currently debugging X"
+- Personal preferences: "I prefer tabs"
+- Trivial changes: "Fixed typo in comment"