{"id":"f4e321e7-fb08-444a-a47a-725c3c99da1a","entityType":"agent","slug":"clawhub-byteroverinc-byterover-2","name":"ByteRover","canonicalUrl":"https://www.xpersona.co/agent/clawhub-byteroverinc-byterover-2","canonicalPath":"/agent/clawhub-byteroverinc-byterover-2","generatedAt":"2026-10-09T09:14:45.734Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":null},"description":"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, dec... Skill: ByteRover Owner: byteroverinc Summary: You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use brv to store and retrieve project patterns, dec... Tags: latest:3.3.0 Version history: v3.3.0 | 2026-04-18T11:37:07.733Z | user v3.3.0 Added - Added section 11 \"Query and Curate History\" with Overview, Use/Do-NOT-use blocks, and both brv curate view and brv query-lo","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 37.5K downloads reported by the source. Last updated 5/16/2026.","installCommand":"clawhub skill install s17ah4kx6arxz6q7gebwr8k6jx83h7cg:byterover","sourceUrl":"https://clawhub.ai/byteroverinc/byterover","homepage":"https://clawhub.ai/byteroverinc/byterover","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/byteroverinc/byterover","kind":"source"}],"safetyScore":84,"overallRank":62,"popularityScore":91,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, dec..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":null},"stars":null,"forks":null,"downloads":37474,"packageName":null,"latestVersion":"3.3.0","tractionLabel":"37.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-05-16T06:11:56.021Z","emptyReason":null},"lastUpdatedAt":"2026-05-16T06:11:56.099Z","lastCrawledAt":"2026-05-16T06:11:56.021Z","lastIndexedAt":null,"nextCrawlAt":"2026-05-17T06:11:56.021Z","lastVerifiedAt":null,"highlights":[{"version":"3.3.0","createdAt":"2026-04-18T11:37:07.733Z","changelog":"# v3.3.0 ## Added - Added section 11 \"Query and Curate History\" with Overview, Use/Do-NOT-use blocks, and both brv curate view and brv query-log view command references - Removed the curate history block from section 3. ## Unchanged - All existing commands (query, search, curate, review, providers, locations, vc, swarm) remain unchanged from v3.2.0.","fileCount":2,"zipByteSize":7388},{"version":"3.2.0","createdAt":"2026-04-14T13:38:13.350Z","changelog":"# v3.2.0 ## Added - **Swarm Query** (`brv swarm query`) — Search across all configured memory providers at once (ByteRover, Obsidian, GBrain, Local Markdown, Memory Wiki). Results are fused via Reciprocal Rank Fusion and ranked by relevance. Supports `--explain` mode to show query classification, provider selection, and enrichment flow. Supports `--format json` and `-n` for result limits. - **Swarm Curate** (`brv swarm curate`) — Store knowledge in external memory providers with automatic content-type routing: entities to GBrain, notes to Local Markdown, general to first writable provider. Falls back to ByteRover context tree if no external provider is available. Supports `--provider` to target a specific provider and `--format json`. - **Swarm Status** (`brv swarm status`) — Check health and availability of all configured swarm providers. Shows provider status, write targets, and enrichment topology. Use before swarm query/curate to verify operational state. ## Unchanged - All existing commands (query, search, curate, review, providers, locations, vc) remain unchanged from v3.1.0.","fileCount":2,"zipByteSize":6832},{"version":"3.1.0","createdAt":"2026-04-11T13:27:40.291Z","changelog":"ByteRover 3.1.0 adds fast file-based search alongside LLM-powered query. - New: Added brv search for ranked, BM25-based keyword search across context-tree files, with JSON output and filtering options. No LLM required. - All major commands are now clearly organized for structured automation and natural-user workflows. - brv search enables agents to quickly locate files for downstream tasks or pipeline integration, reducing latency and LLM usage. - Documentation reorganized to clarify when to use search vs. query. - No breaking changes to existing query, curate, review, locations, or version control functionality.","fileCount":2,"zipByteSize":5149},{"version":"3.0.0","createdAt":"2026-04-08T03:00:47.622Z","changelog":"ByteRover 3.0.0 introduces local, git-based version control and a new review process for curations. - Added `brv vc` commands for full git-style version control on project context trees (branching, commits, local/remote sync). - Introduced `brv review` workflow: review, approve, or reject pending curate operations before they are applied. - Deprecated legacy cloud sync commands (`brv push/pull/space`); replaced by `brv vc push/pull/clone/remote`. - All version control operations can be performed locally without authentication; login required only for remote sync. - Enhanced guidance on usage boundaries for query, curate, review, and version control commands.","fileCount":2,"zipByteSize":4814},{"version":"2.1.0","createdAt":"2026-03-17T09:22:37.372Z","changelog":"**New feature: Project location management** - Added `brv locations` command to list registered projects and their context tree paths. - JSON output option (`-f json`) now available for project metadata. - Documentation expanded to describe when and how to use project location features. - No other functional or behavioral changes.","fileCount":2,"zipByteSize":3227},{"version":"2.0.0","createdAt":"2026-03-02T03:24:31.970Z","changelog":"Version 2.0.0 - Major overhaul of documentation: unified guidance, streamlined explanations, and revised quick reference. - Removed separate troubleshooting and workflow files; key guides are now integrated directly into SKILL.md. - Expanded usage scenarios, best practices, and error handling within the main documentation. - Added clear step-by-step setup, command usage, and context management workflows. - Clarified local vs. cloud features and authentication requirements for all commands.","fileCount":2,"zipByteSize":2987},{"version":"1.2.2","createdAt":"2026-01-27T15:05:52.095Z","changelog":"- Added author and version metadata to the SKILL.md file. - Updated description to include developer attribution and website link: ByteRover Inc. (https://byterover.dev/). - No changes to functionality or file structure.","fileCount":4,"zipByteSize":7121},{"version":"1.2.1","createdAt":"2026-01-27T10:13:25.216Z","changelog":"ByteRover Agent Skill change summary: - Added comprehensive SKILL.md documentation covering query and curate operations, usage scenarios, quality guidelines, and best practices. - Included examples and command references for improved onboarding and usage clarity. - Outlined context curation standards and troubleshooting instructions. - Linked to additional resources for workflows and troubleshooting.","fileCount":4,"zipByteSize":7065}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ah4kx6arxz6q7gebwr8k6jx83h7cg:byterover","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T09:14:45.732Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-byteroverinc-byterover-2/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":null},"readme":"Skill: ByteRover\n\nOwner: byteroverinc\n\nSummary: You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, dec...\n\nTags: latest:3.3.0\n\nVersion history:\n\nv3.3.0 | 2026-04-18T11:37:07.733Z | user\n\n# v3.3.0\n\n## Added\n\n- Added section 11 \"Query and Curate History\" with Overview, Use/Do-NOT-use blocks, and both brv curate view and brv query-log view command references\n- Removed the curate history block from section 3.\n\n## Unchanged\n\n- All existing commands (query, search, curate, review, providers, locations, vc, swarm) remain unchanged from v3.2.0.\n\nv3.2.0 | 2026-04-14T13:38:13.350Z | user\n\n# v3.2.0\n\n## Added\n\n- **Swarm Query** (`brv swarm query`) — Search across all configured memory providers at once (ByteRover, Obsidian, GBrain, Local Markdown, Memory Wiki). Results are fused via Reciprocal Rank Fusion and ranked by relevance. Supports `--explain` mode to show query classification, provider selection, and enrichment flow. Supports `--format json` and `-n` for result limits.\n\n- **Swarm Curate** (`brv swarm curate`) — Store knowledge in external memory providers with automatic content-type routing: entities to GBrain, notes to Local Markdown, general to first writable provider. Falls back to ByteRover context tree if no external provider is available. Supports `--provider` to target a specific provider and `--format json`.\n\n- **Swarm Status** (`brv swarm status`) — Check health and availability of all configured swarm providers. Shows provider status, write targets, and enrichment topology. Use before swarm query/curate to verify operational state.\n\n## Unchanged\n\n- All existing commands (query, search, curate, review, providers, locations, vc) remain unchanged from v3.1.0.\n\nv3.1.0 | 2026-04-11T13:27:40.291Z | user\n\nByteRover 3.1.0 adds fast file-based search alongside LLM-powered query.\n\n- New: Added brv search for ranked, BM25-based keyword search across context-tree files, with JSON output and filtering options. No LLM required.\n- All major commands are now clearly organized for structured automation and natural-user workflows.\n- brv search enables agents to quickly locate files for downstream tasks or pipeline integration, reducing latency and LLM usage.\n- Documentation reorganized to clarify when to use search vs. query.\n- No breaking changes to existing query, curate, review, locations, or version control functionality.\n\nv3.0.0 | 2026-04-08T03:00:47.622Z | user\n\nByteRover 3.0.0 introduces local, git-based version control and a new review process for curations.\n\n- Added `brv vc` commands for full git-style version control on project context trees (branching, commits, local/remote sync).\n- Introduced `brv review` workflow: review, approve, or reject pending curate operations before they are applied.\n- Deprecated legacy cloud sync commands (`brv push/pull/space`); replaced by `brv vc push/pull/clone/remote`.\n- All version control operations can be performed locally without authentication; login required only for remote sync.\n- Enhanced guidance on usage boundaries for query, curate, review, and version control commands.\n\nv2.1.0 | 2026-03-17T09:22:37.372Z | user\n\n**New feature: Project location management**\n\n- Added `brv locations` command to list registered projects and their context tree paths.\n- JSON output option (`-f json`) now available for project metadata.\n- Documentation expanded to describe when and how to use project location features.\n- No other functional or behavioral changes.\n\nv2.0.0 | 2026-03-02T03:24:31.970Z | user\n\nVersion 2.0.0\n\n- Major overhaul of documentation: unified guidance, streamlined explanations, and revised quick reference.\n- Removed separate troubleshooting and workflow files; key guides are now integrated directly into SKILL.md.\n- Expanded usage scenarios, best practices, and error handling within the main documentation.\n- Added clear step-by-step setup, command usage, and context management workflows.\n- Clarified local vs. cloud features and authentication requirements for all commands.\n\nv1.2.2 | 2026-01-27T15:05:52.095Z | user\n\n- Added author and version metadata to the SKILL.md file.\n- Updated description to include developer attribution and website link: ByteRover Inc. (https://byterover.dev/).\n- No changes to functionality or file structure.\n\nv1.2.1 | 2026-01-27T10:13:25.216Z | user\n\nByteRover Agent Skill change summary:\n- Added comprehensive SKILL.md documentation covering query and curate operations, usage scenarios, quality guidelines, and best practices.\n- Included examples and command references for improved onboarding and usage clarity.\n- Outlined context curation standards and troubleshooting instructions.\n- Linked to additional resources for workflows and troubleshooting.\n\nArchive index:\n\nArchive v3.3.0: 2 files, 7388 bytes\n\nFiles: SKILL.md (20422b), _meta.json (128b)\n\nFile v3.3.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query`, `brv curate`, and `brv vc` (local version control) work out of the box. Login is only required for remote sync (`brv vc push`/`brv vc pull`).\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Search Context Tree\n**Overview:** Retrieve a ranked list of matching files from `.brv/context-tree/` via pure BM25 lookup. Unlike `brv query`, this does NOT call an LLM — no synthesis, no token cost, no provider setup needed. Returns structured results with paths, scores, and excerpts.\n\n**Use this skill when:**\n- You need file paths to read rather than a synthesized answer\n- You want fast, cheap retrieval with no LLM overhead\n- You're in an automated pipeline that consumes structured results\n\n**Do NOT use this skill when:**\n- You need a natural-language answer synthesized from multiple files — use `brv query` instead\n- The information is already present in your current context\n\n```bash\nbrv search \"authentication patterns\"\nbrv search \"JWT tokens\" --limit 5 --scope \"auth/\"\nbrv search \"auth\" --format json\n```\n\n**Flags:** `--limit N` (1-50, default 10), `--scope \"domain/\"` (path prefix filter), `--format json` (structured output for automation).\n\n### 3. Curate Context\n**Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n### 4. Review Pending Changes\n**Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.\n\n**Use this when:**\n- A curate operation reports pending reviews (shown in curate output)\n- The user wants to check, approve, or reject pending changes\n\n**Do NOT use this skill when:**\n- There are no pending reviews (check with `brv review pending` first)\n\n**Commands:**\n\nList all pending reviews for the current project:\n```bash\nbrv review pending\n```\n\nSample output:\n```\n2 operations pending review\n\n  Task: ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  [UPSERT · HIGH IMPACT] - path: architecture/context/context_compression_pipeline.md\n  Why:    Documenting switch to token-budget sliding window\n  After:  Context compression pipeline switching from reactive-overflow to token-budget sliding window in src/agent/infra/llm/context/compression/\n\n  [UPSERT · HIGH IMPACT] - path: architecture/tools/agent_tool_registry.md\n  Why:    Documenting tool registry rewrite with capability-based permissions\n  After:  Agent tool registry rewrite in src/agent/infra/tools/tool-registry.ts using capability-based permissions\n\n  To approve all:  brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  To reject all:   brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  Per file:        brv review ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file [--file ]\n```\n\nEach pending task shows: operation type (ADD/UPDATE/DELETE/MERGE/UPSERT), file path, reason, and before/after summaries. High-impact operations are flagged.\n\nApprove all operations for a task (applies the changes):\n```bash\nbrv review approve \n```\n\nReject all operations for a task (discards pending changes; restores backup for UPDATE/DELETE operations):\n```bash\nbrv review reject \n```\n\nApprove or reject specific files within a task:\n```bash\nbrv review approve --file --file \nbrv review reject --file \n```\nFile paths are relative to context tree (as shown in `brv review pending` output).\n\n**Note**: Always ask the user before approving or rejecting critical changes.\n\n**JSON output** (useful for agent-driven workflows):\n```bash\nbrv review pending --format json\nbrv review approve --format json\nbrv review reject --format json\n```\n\n### 5. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 6. Project Locations\n**Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.\n\n**Use this when:**\n- You need to find a project's context tree path\n- You need to check which projects are registered\n- You need to verify if a project is initialized\n\n**Do NOT use this when:**\n- You already know the project path from your current context\n- You need project content rather than metadata — use `brv query` instead\n\n```bash\nbrv locations -f json\n```\n\nJSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.\n\n### 7. Version Control\n**Overview:** `brv vc` provides git-based version control for your context tree. It uses standard git semantics — branching, committing, merging, history, and conflict resolution — all working locally with no authentication required. Remote sync with a team is optional. The legacy `brv push`, `brv pull`, and `brv space` commands are deprecated — use `brv vc push`, `brv vc pull`, and `brv vc clone`/`brv vc remote add` instead.\n\n**Use this when:**\n- The user wants to track, commit, or inspect changes to the knowledge base\n- The user wants to branch, merge, or undo knowledge changes\n- The user wants to sync knowledge with a team (push/pull)\n- The user wants to connect to or clone a team space\n- The user asks about knowledge history or diffs\n\n**Do NOT use this when:**\n- The user wants to query or curate knowledge — use `brv query`/`brv curate` instead\n- The user wants to review pending curate operations — use `brv review` instead\n- Version control is not initialized and the user didn't ask to set it up\n\n**Commands:**\n\nAvailable commands: `init`, `status`, `add`, `commit`, `reset`, `log`, `branch`, `checkout`, `merge`, `config`, `clone`, `remote`, `fetch`, `push`, `pull`.\n\n#### First-Time Setup\n\n**Setup — local (no auth needed):**\n```bash\nbrv vc init\nbrv vc config user.name \"Your Name\"\nbrv vc config user.email \"you@example.com\"\n```\n\n**Setup — clone a team space (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc clone https://byterover.dev//.git\n```\n\n**Setup — connect existing project to a remote (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc remote add origin https://byterover.dev//.git\n```\n\n#### Local Workflow\n\n**Check status:**\n```bash\nbrv vc status\n```\n\n**Stage and commit:**\n```bash\nbrv vc add . # stage all\nbrv vc add notes.md docs/ # stage specific files\nbrv vc commit -m \"add authentication patterns\"\n```\n\n**View history:**\n```bash\nbrv vc log\nbrv vc log --limit 20\nbrv vc log --all\n```\n\n**Unstage or undo:**\n```bash\nbrv vc reset # unstage all files\nbrv vc reset # unstage a specific file\nbrv vc reset --soft HEAD~1 # undo last commit, keep changes staged\nbrv vc reset --hard HEAD~1 # discard last commit and changes\n```\n\n#### Branch Management\n\n```bash\nbrv vc branch # list branches\nbrv vc branch feature/auth # create a branch\nbrv vc branch -a # list all (including remote-tracking)\nbrv vc branch -d feature/auth # delete a branch\nbrv vc checkout feature/auth # switch branch\nbrv vc checkout -b feature/new # create and switch\n```\n\n**Merge:**\n```bash\nbrv vc merge feature/auth # merge into current branch\nbrv vc merge --continue # continue after resolving conflicts\nbrv vc merge --abort # abort a conflicted merge\n```\n\n**Set upstream tracking:**\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n#### Cloud Sync (Remote Operations)\n\nRequires ByteRover authentication (`brv login`) and a configured remote.\n\n**Manage remotes:**\n```bash\nbrv vc remote # show current remote\nbrv vc remote add origin # add a remote\nbrv vc remote set-url origin # update remote URL\n```\n\n**Fetch, pull, and push:**\n```bash\nbrv vc fetch # fetch remote refs\nbrv vc pull # fetch + merge remote commits\nbrv vc push # push commits to cloud\nbrv vc push -u origin main # push and set upstream tracking\n```\n\n**Clone a space:**\n```bash\nbrv vc clone https://byterover.dev//.git\n```\n\n### 8. Swarm Query\n**Overview:** Search across all active memory providers simultaneously — ByteRover context tree, Obsidian vault, Local Markdown folders, GBrain, and Memory Wiki. Results are fused via Reciprocal Rank Fusion (RRF) and ranked by provider weight and relevance. No LLM call — pure algorithmic search.\n\n**Use this skill when:**\n- You need to search across multiple knowledge sources at once\n- The user has configured multiple memory providers (check with `brv swarm status`)\n- You want results from Obsidian notes, GBrain entities, or wiki pages alongside ByteRover context\n\n**Do NOT use this skill when:**\n- The user only has ByteRover configured — use `brv query` instead (it synthesizes via LLM)\n- You need an LLM-synthesized answer — `brv swarm query` returns raw search results, not synthesized text\n\n```bash\nbrv swarm query \"How does JWT refresh work?\"\n```\n\nOutput:\n```\nSwarm Query: \"How does JWT refresh work?\"\nType: factual | Providers: 4 queried | Latency: 398ms\n──────────────────────────────────────────────────\n1. [memory-wiki] sources/jwt-token-lifecycle.md score: 0.0150 [keyword]\n # JWT Token Lifecycle ...\n2. [obsidian] SwarmTestData/Authentication System.md score: 0.0142 [keyword]\n # Authentication System ...\n3. [gbrain] alex-chen score: 0.0117 [semantic]\n # Alex Chen — Senior Backend Engineer ...\n```\n\n**With explain mode** (shows classification, provider selection, enrichment):\n```bash\nbrv swarm query \"authentication patterns\" --explain\n```\n\nOutput:\n```\nClassification: factual\nProvider selection: 4 of 4 available\n ✓ byterover (healthy, selected, 0 results, 14ms)\n ✓ obsidian (healthy, selected, 5 results, 91ms)\n ✓ memory-wiki (healthy, selected, 2 results, 15ms)\n ✓ gbrain (healthy, selected, 1 results, 260ms)\nEnrichment:\n byterover → obsidian\n byterover → memory-wiki\nResults: 8 raw → 7 after RRF fusion + precision filtering\n```\n\n**JSON output:**\n```bash\nbrv swarm query \"rate limiting\" --format json\n```\n\nOutput:\n```json\n{\n \"meta\": {\n \"queryType\": \"factual\",\n \"totalLatencyMs\": 340,\n \"providers\": {\n \"byterover\": { \"selected\": true, \"resultCount\": 0 },\n \"obsidian\": { \"selected\": true, \"resultCount\": 5 },\n \"gbrain\": { \"selected\": true, \"resultCount\": 1 },\n \"memory-wiki\": { \"selected\": true, \"resultCount\": 1 }\n }\n },\n \"results\": [\n { \"provider\": \"memory-wiki\", \"providerType\": \"memory-wiki\", \"score\": 0.015, \"content\": \"# Rate Limiting ...\" }\n ]\n}\n```\n\n**Limit results:**\n```bash\nbrv swarm query \"testing strategy\" -n 5\n```\n\n**Flags:** `--explain` (show routing details), `--format json` (structured output), `-n ` (max results).\n\n### 9. Swarm Curate\n**Overview:** Store knowledge in the best available external memory provider. ByteRover automatically classifies the content type and routes accordingly: entities (people, orgs) go to GBrain, notes (meeting notes, TODOs) go to Local Markdown, general content goes to the first writable provider. Falls back to ByteRover context tree if no external providers are available.\n\n**Use this skill when:**\n- You want to store knowledge in an external provider (GBrain, Local Markdown, Memory Wiki)\n- The user has configured writable swarm providers\n\n**Do NOT use this skill when:**\n- You want to store in ByteRover's context tree specifically — use `brv curate` instead\n- No swarm providers are configured — use `brv curate` instead\n\n```bash\nbrv swarm curate \"Jane Smith is the CTO of TechCorp\"\n```\n\nOutput:\n```\nStored to gbrain as concept/jane-smith-cto\n```\n\n**Target a specific provider:**\n```bash\nbrv swarm curate \"meeting notes: decided on JWT\" --provider local-markdown:notes\n```\n\nOutput:\n```\nStored to local-markdown:notes as note-1776052527043.md\n```\n\n```bash\nbrv swarm curate \"Architecture uses event sourcing\" --provider gbrain\n```\n\nOutput:\n```\nStored to gbrain as concept/event-sourcing-architecture\n```\n\n**JSON output:**\n```bash\nbrv swarm curate \"Test content\" --format json\n```\n\nOutput:\n```json\n{\n \"id\": \"note-1776052594462.md\",\n \"provider\": \"local-markdown:project-docs\",\n \"success\": true,\n \"latencyMs\": 1\n}\n```\n\n**Flags:** `--provider ` (target specific provider), `--format json` (structured output).\n\n### 10. Swarm Status\n**Overview:** Check provider health and write targets before running swarm query or curate. Use this to verify which providers are available and operational.\n\n**Use this skill when:**\n- Before running `brv swarm query` or `brv swarm curate` to check available providers\n- Diagnosing why swarm results are missing from a specific provider\n\n```bash\nbrv swarm status\n```\n\nOutput:\n```\nMemory Swarm Health Check\n════════════════════════════════════════\n ✓ ByteRover context-tree (always on)\n ✓ Obsidian /Users/you/Documents/MyObsidian\n ✓ Local .md 1 folder(s)\n ✓ GBrain /Users/you/workspaces/gbrain\n ✓ Memory Wiki /Users/you/.openclaw/wiki/main\n\nWrite Targets:\n gbrain (entity, general)\n local-markdown:project-docs (note, general)\n\nSwarm is operational (5/5 providers configured).\n```\n\n### 11. Query and Curate History\n**Overview:** Inspect past query and curate operations. Use `brv query-log view` to review query history, `brv curate view` to review curate history, and `brv query-log summary` to see aggregated recall metrics. Supports filtering by time, status, tier, and detailed per-operation output.\n\n**Use this skill when:**\n- You want to review what was queried or curated previously\n- You need to inspect a specific operation by logId\n- You want to filter history by time window or completion status\n- You want to collect data for analysis or debugging\n- You want to know what knowledge was added, updated, or deleted over time\n- You want aggregated metrics on query recall, cache hit rate, or knowledge gaps\n\n**Do NOT use this skill when:**\n- You want to run a new query — use `brv query` instead\n- You want to curate new knowledge — use `brv curate` instead\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view --detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed --limit 1000\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n**View query history:** to check past queries\n- Show recent entries (last 10)\n```bash\nbrv query-log view\n```\n- Full detail for a specific entry: matched docs and search metadata (logId is printed by `brv query` on completion, e.g. `qry-1739700001000`)\n```bash\nbrv query-log view qry-1739700001000\n```\n- List entries with matched docs visible (no logId needed)\n```bash\nbrv query-log view --detail\n```\n- Filter by time, status, or resolution tier (0=exact cache, 1=fuzzy cache, 2=direct search, 3=optimized LLM, 4=full agentic)\n```bash\nbrv query-log view --since 1h --status completed --limit 1000\nbrv query-log view --tier 0 --tier 1\n```\n- For all filter options\n```bash\nbrv query-log view --help\n```\n\n**View query recall metrics:** to see aggregated stats across recent queries\n- Summary for the last 24 hours (default)\n```bash\nbrv query-log summary\n```\n- Summary for a specific time window\n```bash\nbrv query-log summary --last 7d\nbrv query-log summary --since 2026-04-01 --before 2026-04-03\n```\n- Narrative format (human-readable prose report)\n```bash\nbrv query-log summary --format narrative\n```\n- For all options\n```bash\nbrv query-log summary --help\n```\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv vc push`.\n\n**Cloud sync**: `brv vc push` and `brv vc pull` require authentication (`brv login`) and sync knowledge with ByteRover's cloud service via git. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v3.3.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"3.3.0\",\n \"publishedAt\": 1776512227733\n}\n\nArchive v3.2.0: 2 files, 6832 bytes\n\nFiles: SKILL.md (18359b), _meta.json (128b)\n\nFile v3.2.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query`, `brv curate`, and `brv vc` (local version control) work out of the box. Login is only required for remote sync (`brv vc push`/`brv vc pull`).\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Search Context Tree\n**Overview:** Retrieve a ranked list of matching files from `.brv/context-tree/` via pure BM25 lookup. Unlike `brv query`, this does NOT call an LLM — no synthesis, no token cost, no provider setup needed. Returns structured results with paths, scores, and excerpts.\n\n**Use this skill when:**\n- You need file paths to read rather than a synthesized answer\n- You want fast, cheap retrieval with no LLM overhead\n- You're in an automated pipeline that consumes structured results\n\n**Do NOT use this skill when:**\n- You need a natural-language answer synthesized from multiple files — use `brv query` instead\n- The information is already present in your current context\n\n```bash\nbrv search \"authentication patterns\"\nbrv search \"JWT tokens\" --limit 5 --scope \"auth/\"\nbrv search \"auth\" --format json\n```\n\n**Flags:** `--limit N` (1-50, default 10), `--scope \"domain/\"` (path prefix filter), `--format json` (structured output for automation).\n\n### 3. Curate Context\n**Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n### 4. Review Pending Changes\n**Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.\n\n**Use this when:**\n- A curate operation reports pending reviews (shown in curate output)\n- The user wants to check, approve, or reject pending changes\n\n**Do NOT use this skill when:**\n- There are no pending reviews (check with `brv review pending` first)\n\n**Commands:**\n\nList all pending reviews for the current project:\n```bash\nbrv review pending\n```\n\nSample output:\n```\n2 operations pending review\n\n  Task: ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  [UPSERT · HIGH IMPACT] - path: architecture/context/context_compression_pipeline.md\n  Why:    Documenting switch to token-budget sliding window\n  After:  Context compression pipeline switching from reactive-overflow to token-budget sliding window in src/agent/infra/llm/context/compression/\n\n  [UPSERT · HIGH IMPACT] - path: architecture/tools/agent_tool_registry.md\n  Why:    Documenting tool registry rewrite with capability-based permissions\n  After:  Agent tool registry rewrite in src/agent/infra/tools/tool-registry.ts using capability-based permissions\n\n  To approve all:  brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  To reject all:   brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  Per file:        brv review ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file [--file ]\n```\n\nEach pending task shows: operation type (ADD/UPDATE/DELETE/MERGE/UPSERT), file path, reason, and before/after summaries. High-impact operations are flagged.\n\nApprove all operations for a task (applies the changes):\n```bash\nbrv review approve \n```\n\nReject all operations for a task (discards pending changes; restores backup for UPDATE/DELETE operations):\n```bash\nbrv review reject \n```\n\nApprove or reject specific files within a task:\n```bash\nbrv review approve --file --file \nbrv review reject --file \n```\nFile paths are relative to context tree (as shown in `brv review pending` output).\n\n**Note**: Always ask the user before approving or rejecting critical changes.\n\n**JSON output** (useful for agent-driven workflows):\n```bash\nbrv review pending --format json\nbrv review approve --format json\nbrv review reject --format json\n```\n\n### 5. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 6. Project Locations\n**Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.\n\n**Use this when:**\n- You need to find a project's context tree path\n- You need to check which projects are registered\n- You need to verify if a project is initialized\n\n**Do NOT use this when:**\n- You already know the project path from your current context\n- You need project content rather than metadata — use `brv query` instead\n\n```bash\nbrv locations -f json\n```\n\nJSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.\n\n### 7. Version Control\n**Overview:** `brv vc` provides git-based version control for your context tree. It uses standard git semantics — branching, committing, merging, history, and conflict resolution — all working locally with no authentication required. Remote sync with a team is optional. The legacy `brv push`, `brv pull`, and `brv space` commands are deprecated — use `brv vc push`, `brv vc pull`, and `brv vc clone`/`brv vc remote add` instead.\n\n**Use this when:**\n- The user wants to track, commit, or inspect changes to the knowledge base\n- The user wants to branch, merge, or undo knowledge changes\n- The user wants to sync knowledge with a team (push/pull)\n- The user wants to connect to or clone a team space\n- The user asks about knowledge history or diffs\n\n**Do NOT use this when:**\n- The user wants to query or curate knowledge — use `brv query`/`brv curate` instead\n- The user wants to review pending curate operations — use `brv review` instead\n- Version control is not initialized and the user didn't ask to set it up\n\n**Commands:**\n\nAvailable commands: `init`, `status`, `add`, `commit`, `reset`, `log`, `branch`, `checkout`, `merge`, `config`, `clone`, `remote`, `fetch`, `push`, `pull`.\n\n#### First-Time Setup\n\n**Setup — local (no auth needed):**\n```bash\nbrv vc init\nbrv vc config user.name \"Your Name\"\nbrv vc config user.email \"you@example.com\"\n```\n\n**Setup — clone a team space (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc clone https://byterover.dev//.git\n```\n\n**Setup — connect existing project to a remote (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc remote add origin https://byterover.dev//.git\n```\n\n#### Local Workflow\n\n**Check status:**\n```bash\nbrv vc status\n```\n\n**Stage and commit:**\n```bash\nbrv vc add . # stage all\nbrv vc add notes.md docs/ # stage specific files\nbrv vc commit -m \"add authentication patterns\"\n```\n\n**View history:**\n```bash\nbrv vc log\nbrv vc log --limit 20\nbrv vc log --all\n```\n\n**Unstage or undo:**\n```bash\nbrv vc reset # unstage all files\nbrv vc reset # unstage a specific file\nbrv vc reset --soft HEAD~1 # undo last commit, keep changes staged\nbrv vc reset --hard HEAD~1 # discard last commit and changes\n```\n\n#### Branch Management\n\n```bash\nbrv vc branch # list branches\nbrv vc branch feature/auth # create a branch\nbrv vc branch -a # list all (including remote-tracking)\nbrv vc branch -d feature/auth # delete a branch\nbrv vc checkout feature/auth # switch branch\nbrv vc checkout -b feature/new # create and switch\n```\n\n**Merge:**\n```bash\nbrv vc merge feature/auth # merge into current branch\nbrv vc merge --continue # continue after resolving conflicts\nbrv vc merge --abort # abort a conflicted merge\n```\n\n**Set upstream tracking:**\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n#### Cloud Sync (Remote Operations)\n\nRequires ByteRover authentication (`brv login`) and a configured remote.\n\n**Manage remotes:**\n```bash\nbrv vc remote # show current remote\nbrv vc remote add origin # add a remote\nbrv vc remote set-url origin # update remote URL\n```\n\n**Fetch, pull, and push:**\n```bash\nbrv vc fetch # fetch remote refs\nbrv vc pull # fetch + merge remote commits\nbrv vc push # push commits to cloud\nbrv vc push -u origin main # push and set upstream tracking\n```\n\n**Clone a space:**\n```bash\nbrv vc clone https://byterover.dev//.git\n```\n\n### 8. Swarm Query\n**Overview:** Search across all active memory providers simultaneously — ByteRover context tree, Obsidian vault, Local Markdown folders, GBrain, and Memory Wiki. Results are fused via Reciprocal Rank Fusion (RRF) and ranked by provider weight and relevance. No LLM call — pure algorithmic search.\n\n**Use this skill when:**\n- You need to search across multiple knowledge sources at once\n- The user has configured multiple memory providers (check with `brv swarm status`)\n- You want results from Obsidian notes, GBrain entities, or wiki pages alongside ByteRover context\n\n**Do NOT use this skill when:**\n- The user only has ByteRover configured — use `brv query` instead (it synthesizes via LLM)\n- You need an LLM-synthesized answer — `brv swarm query` returns raw search results, not synthesized text\n\n```bash\nbrv swarm query \"How does JWT refresh work?\"\n```\n\nOutput:\n```\nSwarm Query: \"How does JWT refresh work?\"\nType: factual | Providers: 4 queried | Latency: 398ms\n──────────────────────────────────────────────────\n1. [memory-wiki] sources/jwt-token-lifecycle.md score: 0.0150 [keyword]\n # JWT Token Lifecycle ...\n2. [obsidian] SwarmTestData/Authentication System.md score: 0.0142 [keyword]\n # Authentication System ...\n3. [gbrain] alex-chen score: 0.0117 [semantic]\n # Alex Chen — Senior Backend Engineer ...\n```\n\n**With explain mode** (shows classification, provider selection, enrichment):\n```bash\nbrv swarm query \"authentication patterns\" --explain\n```\n\nOutput:\n```\nClassification: factual\nProvider selection: 4 of 4 available\n ✓ byterover (healthy, selected, 0 results, 14ms)\n ✓ obsidian (healthy, selected, 5 results, 91ms)\n ✓ memory-wiki (healthy, selected, 2 results, 15ms)\n ✓ gbrain (healthy, selected, 1 results, 260ms)\nEnrichment:\n byterover → obsidian\n byterover → memory-wiki\nResults: 8 raw → 7 after RRF fusion + precision filtering\n```\n\n**JSON output:**\n```bash\nbrv swarm query \"rate limiting\" --format json\n```\n\nOutput:\n```json\n{\n \"meta\": {\n \"queryType\": \"factual\",\n \"totalLatencyMs\": 340,\n \"providers\": {\n \"byterover\": { \"selected\": true, \"resultCount\": 0 },\n \"obsidian\": { \"selected\": true, \"resultCount\": 5 },\n \"gbrain\": { \"selected\": true, \"resultCount\": 1 },\n \"memory-wiki\": { \"selected\": true, \"resultCount\": 1 }\n }\n },\n \"results\": [\n { \"provider\": \"memory-wiki\", \"providerType\": \"memory-wiki\", \"score\": 0.015, \"content\": \"# Rate Limiting ...\" }\n ]\n}\n```\n\n**Limit results:**\n```bash\nbrv swarm query \"testing strategy\" -n 5\n```\n\n**Flags:** `--explain` (show routing details), `--format json` (structured output), `-n ` (max results).\n\n### 9. Swarm Curate\n**Overview:** Store knowledge in the best available external memory provider. ByteRover automatically classifies the content type and routes accordingly: entities (people, orgs) go to GBrain, notes (meeting notes, TODOs) go to Local Markdown, general content goes to the first writable provider. Falls back to ByteRover context tree if no external providers are available.\n\n**Use this skill when:**\n- You want to store knowledge in an external provider (GBrain, Local Markdown, Memory Wiki)\n- The user has configured writable swarm providers\n\n**Do NOT use this skill when:**\n- You want to store in ByteRover's context tree specifically — use `brv curate` instead\n- No swarm providers are configured — use `brv curate` instead\n\n```bash\nbrv swarm curate \"Jane Smith is the CTO of TechCorp\"\n```\n\nOutput:\n```\nStored to gbrain as concept/jane-smith-cto\n```\n\n**Target a specific provider:**\n```bash\nbrv swarm curate \"meeting notes: decided on JWT\" --provider local-markdown:notes\n```\n\nOutput:\n```\nStored to local-markdown:notes as note-1776052527043.md\n```\n\n```bash\nbrv swarm curate \"Architecture uses event sourcing\" --provider gbrain\n```\n\nOutput:\n```\nStored to gbrain as concept/event-sourcing-architecture\n```\n\n**JSON output:**\n```bash\nbrv swarm curate \"Test content\" --format json\n```\n\nOutput:\n```json\n{\n \"id\": \"note-1776052594462.md\",\n \"provider\": \"local-markdown:project-docs\",\n \"success\": true,\n \"latencyMs\": 1\n}\n```\n\n**Flags:** `--provider ` (target specific provider), `--format json` (structured output).\n\n### 10. Swarm Status\n**Overview:** Check provider health and write targets before running swarm query or curate. Use this to verify which providers are available and operational.\n\n**Use this skill when:**\n- Before running `brv swarm query` or `brv swarm curate` to check available providers\n- Diagnosing why swarm results are missing from a specific provider\n\n```bash\nbrv swarm status\n```\n\nOutput:\n```\nMemory Swarm Health Check\n════════════════════════════════════════\n ✓ ByteRover context-tree (always on)\n ✓ Obsidian /Users/you/Documents/MyObsidian\n ✓ Local .md 1 folder(s)\n ✓ GBrain /Users/you/workspaces/gbrain\n ✓ Memory Wiki /Users/you/.openclaw/wiki/main\n\nWrite Targets:\n gbrain (entity, general)\n local-markdown:project-docs (note, general)\n\nSwarm is operational (5/5 providers configured).\n```\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv vc push`.\n\n**Cloud sync**: `brv vc push` and `brv vc pull` require authentication (`brv login`) and sync knowledge with ByteRover's cloud service via git. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v3.2.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"3.2.0\",\n \"publishedAt\": 1776173893350\n}\n\nArchive v3.1.0: 2 files, 5149 bytes\n\nFiles: SKILL.md (13101b), _meta.json (128b)\n\nFile v3.1.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query`, `brv curate`, and `brv vc` (local version control) work out of the box. Login is only required for remote sync (`brv vc push`/`brv vc pull`).\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Search Context Tree\n**Overview:** Retrieve a ranked list of matching files from `.brv/context-tree/` via pure BM25 lookup. Unlike `brv query`, this does NOT call an LLM — no synthesis, no token cost, no provider setup needed. Returns structured results with paths, scores, and excerpts.\n\n**Use this skill when:**\n- You need file paths to read rather than a synthesized answer\n- You want fast, cheap retrieval with no LLM overhead\n- You're in an automated pipeline that consumes structured results\n\n**Do NOT use this skill when:**\n- You need a natural-language answer synthesized from multiple files — use `brv query` instead\n- The information is already present in your current context\n\n```bash\nbrv search \"authentication patterns\"\nbrv search \"JWT tokens\" --limit 5 --scope \"auth/\"\nbrv search \"auth\" --format json\n```\n\n**Flags:** `--limit N` (1-50, default 10), `--scope \"domain/\"` (path prefix filter), `--format json` (structured output for automation).\n\n### 3. Curate Context\n**Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n### 4. Review Pending Changes\n**Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.\n\n**Use this when:**\n- A curate operation reports pending reviews (shown in curate output)\n- The user wants to check, approve, or reject pending changes\n\n**Do NOT use this skill when:**\n- There are no pending reviews (check with `brv review pending` first)\n\n**Commands:**\n\nList all pending reviews for the current project:\n```bash\nbrv review pending\n```\n\nSample output:\n```\n2 operations pending review\n\n  Task: ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  [UPSERT · HIGH IMPACT] - path: architecture/context/context_compression_pipeline.md\n  Why:    Documenting switch to token-budget sliding window\n  After:  Context compression pipeline switching from reactive-overflow to token-budget sliding window in src/agent/infra/llm/context/compression/\n\n  [UPSERT · HIGH IMPACT] - path: architecture/tools/agent_tool_registry.md\n  Why:    Documenting tool registry rewrite with capability-based permissions\n  After:  Agent tool registry rewrite in src/agent/infra/tools/tool-registry.ts using capability-based permissions\n\n  To approve all:  brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  To reject all:   brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  Per file:        brv review ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file [--file ]\n```\n\nEach pending task shows: operation type (ADD/UPDATE/DELETE/MERGE/UPSERT), file path, reason, and before/after summaries. High-impact operations are flagged.\n\nApprove all operations for a task (applies the changes):\n```bash\nbrv review approve \n```\n\nReject all operations for a task (discards pending changes; restores backup for UPDATE/DELETE operations):\n```bash\nbrv review reject \n```\n\nApprove or reject specific files within a task:\n```bash\nbrv review approve --file --file \nbrv review reject --file \n```\nFile paths are relative to context tree (as shown in `brv review pending` output).\n\n**Note**: Always ask the user before approving or rejecting critical changes.\n\n**JSON output** (useful for agent-driven workflows):\n```bash\nbrv review pending --format json\nbrv review approve --format json\nbrv review reject --format json\n```\n\n### 5. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 6. Project Locations\n**Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.\n\n**Use this when:**\n- You need to find a project's context tree path\n- You need to check which projects are registered\n- You need to verify if a project is initialized\n\n**Do NOT use this when:**\n- You already know the project path from your current context\n- You need project content rather than metadata — use `brv query` instead\n\n```bash\nbrv locations -f json\n```\n\nJSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.\n\n### 7. Version Control\n**Overview:** `brv vc` provides git-based version control for your context tree. It uses standard git semantics — branching, committing, merging, history, and conflict resolution — all working locally with no authentication required. Remote sync with a team is optional. The legacy `brv push`, `brv pull`, and `brv space` commands are deprecated — use `brv vc push`, `brv vc pull`, and `brv vc clone`/`brv vc remote add` instead.\n\n**Use this when:**\n- The user wants to track, commit, or inspect changes to the knowledge base\n- The user wants to branch, merge, or undo knowledge changes\n- The user wants to sync knowledge with a team (push/pull)\n- The user wants to connect to or clone a team space\n- The user asks about knowledge history or diffs\n\n**Do NOT use this when:**\n- The user wants to query or curate knowledge — use `brv query`/`brv curate` instead\n- The user wants to review pending curate operations — use `brv review` instead\n- Version control is not initialized and the user didn't ask to set it up\n\n**Commands:**\n\nAvailable commands: `init`, `status`, `add`, `commit`, `reset`, `log`, `branch`, `checkout`, `merge`, `config`, `clone`, `remote`, `fetch`, `push`, `pull`.\n\n#### First-Time Setup\n\n**Setup — local (no auth needed):**\n```bash\nbrv vc init\nbrv vc config user.name \"Your Name\"\nbrv vc config user.email \"you@example.com\"\n```\n\n**Setup — clone a team space (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc clone https://byterover.dev//.git\n```\n\n**Setup — connect existing project to a remote (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc remote add origin https://byterover.dev//.git\n```\n\n#### Local Workflow\n\n**Check status:**\n```bash\nbrv vc status\n```\n\n**Stage and commit:**\n```bash\nbrv vc add . # stage all\nbrv vc add notes.md docs/ # stage specific files\nbrv vc commit -m \"add authentication patterns\"\n```\n\n**View history:**\n```bash\nbrv vc log\nbrv vc log --limit 20\nbrv vc log --all\n```\n\n**Unstage or undo:**\n```bash\nbrv vc reset # unstage all files\nbrv vc reset # unstage a specific file\nbrv vc reset --soft HEAD~1 # undo last commit, keep changes staged\nbrv vc reset --hard HEAD~1 # discard last commit and changes\n```\n\n#### Branch Management\n\n```bash\nbrv vc branch # list branches\nbrv vc branch feature/auth # create a branch\nbrv vc branch -a # list all (including remote-tracking)\nbrv vc branch -d feature/auth # delete a branch\nbrv vc checkout feature/auth # switch branch\nbrv vc checkout -b feature/new # create and switch\n```\n\n**Merge:**\n```bash\nbrv vc merge feature/auth # merge into current branch\nbrv vc merge --continue # continue after resolving conflicts\nbrv vc merge --abort # abort a conflicted merge\n```\n\n**Set upstream tracking:**\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n#### Cloud Sync (Remote Operations)\n\nRequires ByteRover authentication (`brv login`) and a configured remote.\n\n**Manage remotes:**\n```bash\nbrv vc remote # show current remote\nbrv vc remote add origin # add a remote\nbrv vc remote set-url origin # update remote URL\n```\n\n**Fetch, pull, and push:**\n```bash\nbrv vc fetch # fetch remote refs\nbrv vc pull # fetch + merge remote commits\nbrv vc push # push commits to cloud\nbrv vc push -u origin main # push and set upstream tracking\n```\n\n**Clone a space:**\n```bash\nbrv vc clone https://byterover.dev//.git\n```\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv vc push`.\n\n**Cloud sync**: `brv vc push` and `brv vc pull` require authentication (`brv login`) and sync knowledge with ByteRover's cloud service via git. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v3.1.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"3.1.0\",\n \"publishedAt\": 1775914060291\n}\n\nArchive v3.0.0: 2 files, 4814 bytes\n\nFiles: SKILL.md (12133b), _meta.json (128b)\n\nFile v3.0.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query`, `brv curate`, and `brv vc` (local version control) work out of the box. Login is only required for remote sync (`brv vc push`/`brv vc pull`).\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Curate Context\n**Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n### 3. Review Pending Changes\n**Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.\n\n**Use this when:**\n- A curate operation reports pending reviews (shown in curate output)\n- The user wants to check, approve, or reject pending changes\n\n**Do NOT use this skill when:**\n- There are no pending reviews (check with `brv review pending` first)\n\n**Commands:**\n\nList all pending reviews for the current project:\n```bash\nbrv review pending\n```\n\nSample output:\n```\n2 operations pending review\n\n  Task: ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  [UPSERT · HIGH IMPACT] - path: architecture/context/context_compression_pipeline.md\n  Why:    Documenting switch to token-budget sliding window\n  After:  Context compression pipeline switching from reactive-overflow to token-budget sliding window in src/agent/infra/llm/context/compression/\n\n  [UPSERT · HIGH IMPACT] - path: architecture/tools/agent_tool_registry.md\n  Why:    Documenting tool registry rewrite with capability-based permissions\n  After:  Agent tool registry rewrite in src/agent/infra/tools/tool-registry.ts using capability-based permissions\n\n  To approve all:  brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  To reject all:   brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  Per file:        brv review ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file [--file ]\n```\n\nEach pending task shows: operation type (ADD/UPDATE/DELETE/MERGE/UPSERT), file path, reason, and before/after summaries. High-impact operations are flagged.\n\nApprove all operations for a task (applies the changes):\n```bash\nbrv review approve \n```\n\nReject all operations for a task (discards pending changes; restores backup for UPDATE/DELETE operations):\n```bash\nbrv review reject \n```\n\nApprove or reject specific files within a task:\n```bash\nbrv review approve --file --file \nbrv review reject --file \n```\nFile paths are relative to context tree (as shown in `brv review pending` output).\n\n**Note**: Always ask the user before approving or rejecting critical changes.\n\n**JSON output** (useful for agent-driven workflows):\n```bash\nbrv review pending --format json\nbrv review approve --format json\nbrv review reject --format json\n```\n\n### 4. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 5. Project Locations\n**Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.\n\n**Use this when:**\n- You need to find a project's context tree path\n- You need to check which projects are registered\n- You need to verify if a project is initialized\n\n**Do NOT use this when:**\n- You already know the project path from your current context\n- You need project content rather than metadata — use `brv query` instead\n\n```bash\nbrv locations -f json\n```\n\nJSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.\n\n### 6. Version Control\n**Overview:** `brv vc` provides git-based version control for your context tree. It uses standard git semantics — branching, committing, merging, history, and conflict resolution — all working locally with no authentication required. Remote sync with a team is optional. The legacy `brv push`, `brv pull`, and `brv space` commands are deprecated — use `brv vc push`, `brv vc pull`, and `brv vc clone`/`brv vc remote add` instead.\n\n**Use this when:**\n- The user wants to track, commit, or inspect changes to the knowledge base\n- The user wants to branch, merge, or undo knowledge changes\n- The user wants to sync knowledge with a team (push/pull)\n- The user wants to connect to or clone a team space\n- The user asks about knowledge history or diffs\n\n**Do NOT use this when:**\n- The user wants to query or curate knowledge — use `brv query`/`brv curate` instead\n- The user wants to review pending curate operations — use `brv review` instead\n- Version control is not initialized and the user didn't ask to set it up\n\n**Commands:**\n\nAvailable commands: `init`, `status`, `add`, `commit`, `reset`, `log`, `branch`, `checkout`, `merge`, `config`, `clone`, `remote`, `fetch`, `push`, `pull`.\n\n#### First-Time Setup\n\n**Setup — local (no auth needed):**\n```bash\nbrv vc init\nbrv vc config user.name \"Your Name\"\nbrv vc config user.email \"you@example.com\"\n```\n\n**Setup — clone a team space (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc clone https://byterover.dev//.git\n```\n\n**Setup — connect existing project to a remote (requires `brv login`):**\n```bash\nbrv login --api-key sample-key-string\nbrv vc remote add origin https://byterover.dev//.git\n```\n\n#### Local Workflow\n\n**Check status:**\n```bash\nbrv vc status\n```\n\n**Stage and commit:**\n```bash\nbrv vc add . # stage all\nbrv vc add notes.md docs/ # stage specific files\nbrv vc commit -m \"add authentication patterns\"\n```\n\n**View history:**\n```bash\nbrv vc log\nbrv vc log --limit 20\nbrv vc log --all\n```\n\n**Unstage or undo:**\n```bash\nbrv vc reset # unstage all files\nbrv vc reset # unstage a specific file\nbrv vc reset --soft HEAD~1 # undo last commit, keep changes staged\nbrv vc reset --hard HEAD~1 # discard last commit and changes\n```\n\n#### Branch Management\n\n```bash\nbrv vc branch # list branches\nbrv vc branch feature/auth # create a branch\nbrv vc branch -a # list all (including remote-tracking)\nbrv vc branch -d feature/auth # delete a branch\nbrv vc checkout feature/auth # switch branch\nbrv vc checkout -b feature/new # create and switch\n```\n\n**Merge:**\n```bash\nbrv vc merge feature/auth # merge into current branch\nbrv vc merge --continue # continue after resolving conflicts\nbrv vc merge --abort # abort a conflicted merge\n```\n\n**Set upstream tracking:**\n```bash\nbrv vc branch --set-upstream-to origin/main\n```\n\n#### Cloud Sync (Remote Operations)\n\nRequires ByteRover authentication (`brv login`) and a configured remote.\n\n**Manage remotes:**\n```bash\nbrv vc remote # show current remote\nbrv vc remote add origin # add a remote\nbrv vc remote set-url origin # update remote URL\n```\n\n**Fetch, pull, and push:**\n```bash\nbrv vc fetch # fetch remote refs\nbrv vc pull # fetch + merge remote commits\nbrv vc push # push commits to cloud\nbrv vc push -u origin main # push and set upstream tracking\n```\n\n**Clone a space:**\n```bash\nbrv vc clone https://byterover.dev//.git\n```\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv vc push`.\n\n**Cloud sync**: `brv vc push` and `brv vc pull` require authentication (`brv login`) and sync knowledge with ByteRover's cloud service via git. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v3.0.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"3.0.0\",\n \"publishedAt\": 1775617247622\n}\n\nArchive v2.1.0: 2 files, 3227 bytes\n\nFiles: SKILL.md (7081b), _meta.json (128b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query` and `brv curate` work out of the box. Login is only required for cloud sync (`push`/`pull`/`space`) — ignore those if you don't need cloud features.\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Curate Context\n**Overview**: Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n### 3. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 4. Project Locations\n**Overview:** List registered projects and their context tree paths. Returns project metadata including initialization status and active state. Use `-f json` for machine-readable output.\n\n**Use this when:**\n- You need to find a project's context tree path\n- You need to check which projects are registered\n- You need to verify if a project is initialized\n\n**Do NOT use this when:**\n- You already know the project path from your current context\n- You need project content rather than metadata — use `brv query` instead\n\n```bash\nbrv locations -f json\n```\n\nJSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.\n\n### 5. Cloud Sync (Optional)\n**Overview:** Sync your local knowledge with a team via ByteRover's cloud service. Requires ByteRover authentication.\n\n**Setup steps:**\n1. Log in: Get an API key from your ByteRover account and authenticate:\n```bash\nbrv login --api-key sample-key-string\n```\n2. List available spaces:\n```bash\nbrv space list\n```\nSample output:\n```\nbrv space list\n1. human-resources-team (team)\n - a-department (space)\n - b-department (space)\n2. marketing-team (team)\n - c-department (space)\n - d-department (space)\n```\n3. Connect to a space:\n```bash\nbrv space switch --team human-resources-team --name a-department\n```\n\n**Cloud sync commands:**\nOnce connected, `brv push` and `brv pull` sync with that space.\n```bash\n# Pull team updates\nbrv pull\n\n# Push local changes\nbrv push\n```\n\n**Switching spaces:**\n- Push local changes first (`brv push`) — switching is blocked if unsaved changes exist.\n- Then switch:\n```bash\nbrv space switch --team marketing-team --name d-department\n```\n- The switch automatically pulls context from the new space.\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv push`.\n\n**Cloud sync**: `brv push` and `brv pull` require authentication (`brv login`) and send knowledge to ByteRover's cloud service. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v2.1.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"2.1.0\",\n \"publishedAt\": 1773739357372\n}\n\nArchive v2.0.0: 2 files, 2987 bytes\n\nFiles: SKILL.md (6410b), _meta.json (128b)\n\nFile v2.0.0:SKILL.md\n\n---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query` and `brv curate` work out of the box. Login is only required for cloud sync (`push`/`pull`/`space`) — ignore those if you don't need cloud features.\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Curate Context\n**Overview**: Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or what decisions and actions you have taken\n\n**Do NOT use this skill when:**\n- The information is already stored and unchanged\n- The information is transient or only relevant to the current task, or just general knowledge\n\n```bash\nbrv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\"\n```\n\n**Include source files** (max 5, project-scoped only):\n\n```bash\nbrv curate \"Authentication middleware details\" -f src/middleware/auth.ts\n```\n\n**View curate history:** to check past curations\n- Show recent entries (last 10)\n```bash\nbrv curate view\n```\n- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)\n```bash\nbrv curate view cur-1739700001000\n```\n- List entries with file operations visible (no logId needed)\n```bash\nbrv curate view detail\n```\n- Filter by time and status\n```bash\nbrv curate view --since 1h --status completed\n```\n- For all filter options\n```bash\nbrv curate view --help\n```\n\n### 3. LLM Provider Setup\n`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):\n\n```bash\nbrv providers connect byterover\n```\n\nTo use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:\n\n```bash\nbrv providers list\nbrv providers connect openai --api-key sk-xxx --model gpt-4.1\n```\n\n### 4. Cloud Sync (Optional)\n**Overview:** Sync your local knowledge with a team via ByteRover's cloud service. Requires ByteRover authentication.\n\n**Setup steps:**\n1. Log in: Get an API key from your ByteRover account and authenticate:\n```bash\nbrv login --api-key sample-key-string\n```\n2. List available spaces:\n```bash\nbrv space list\n```\nSample output:\n```\nbrv space list\n1. human-resources-team (team)\n - a-department (space)\n - b-department (space)\n2. marketing-team (team)\n - c-department (space)\n - d-department (space)\n```\n3. Connect to a space:\n```bash\nbrv space switch --team human-resources-team --name a-department\n```\n\n**Cloud sync commands:**\nOnce connected, `brv push` and `brv pull` sync with that space.\n```bash\n# Pull team updates\nbrv pull\n\n# Push local changes\nbrv push\n```\n\n**Switching spaces:**\n- Push local changes first (`brv push`) — switching is blocked if unsaved changes exist.\n- Then switch:\n```bash\nbrv space switch --team marketing-team --name d-department\n```\n- The switch automatically pulls context from the new space.\n\n## Data Handling\n\n**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.\n\n**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.\n\n**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv push`.\n\n**Cloud sync**: `brv push` and `brv pull` require authentication (`brv login`) and send knowledge to ByteRover's cloud service. All other commands operate without ByteRover authentication.\n\n## Error Handling\n**User Action Required:**\nYou MUST show this troubleshooting guide to users when errors occur.\n\n\"Not authenticated\" | Run `brv login --help` for more details.\n\"No provider connected\" | Run `brv providers connect byterover` (free, no key needed).\n\"Connection failed\" / \"Instance crashed\" | User should kill brv process.\n\"Token has expired\" / \"Token is invalid\" | Run `brv login` again to re-authenticate.\n\"Billing error\" / \"Rate limit exceeded\" | User should check account credits or wait before retrying.\n\n**Agent-Fixable Errors:**\nYou MUST handle these errors gracefully and retry the command after fixing.\n\n\"Missing required argument(s).\" | Run `brv --help` to see usage instructions.\n\"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags per curate.\n\"File does not exist\" | Verify path with `ls`, use relative paths from project root.\n\"File type not supported\" | Only text, image, PDF, and office files are supported.\n\n### Quick Diagnosis\nRun `brv status` to check authentication, project, and provider state.\n\nFile v2.0.0:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"2.0.0\",\n \"publishedAt\": 1772421871970\n}\n\nArchive v1.2.2: 4 files, 7121 bytes\n\nFiles: SKILL.md (3708b), TROUBLESHOOTING.md (1360b), WORKFLOWS.md (10495b), _meta.json (128b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: byterover\ndescription: \"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. Developed by ByteRover Inc. (https://byterover.dev/)\"\nmetadata:\n author: ByteRover Inc. (https://byterover.dev/)\n version: \"1.2.1\"\n---\n\n# ByteRover Context Tree\n\nA project-level knowledge repository that persists across sessions. Use it to avoid re-discovering patterns, conventions, and decisions.\n\n## Why Use ByteRover\n\n- **Query before working**: Get existing knowledge about patterns, conventions, and past decisions before implementing\n- **Curate after learning**: Capture insights, decisions, and bug fixes so future sessions start informed\n\n## Quick Reference\n\n| Command | When | Example |\n|---------|------|---------|\n| `brv query \"question\"` | Before starting work | `brv query \"How is auth implemented?\"` |\n| `brv curate \"context\" -f file` | After completing work | `brv curate \"JWT 24h expiry\" -f auth.ts` |\n| `brv status` | To check prerequisites | `brv status` |\n\n## When to Use\n\n**Query** when you need to understand something:\n- \"How does X work in this codebase?\"\n- \"What patterns exist for Y?\"\n- \"Are there conventions for Z?\"\n\n**Curate** when you learned or created something valuable:\n- Implemented a feature using specific patterns\n- Fixed a bug and found root cause\n- Made an architecture decision\n\n## Curate Quality\n\nContext must be **specific** and **actionable**:\n\n```bash\n# Good - specific, explains where and why\nbrv curate \"Auth uses JWT 24h expiry, tokens in httpOnly cookies\" -f src/auth.ts\n\n# Bad - too vague\nbrv curate \"Fixed auth\"\n```\n\n**Note:** Context argument must come before `-f` flags. Max 5 files.\n\n## Best Practices\n\n1. **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.\n\n2. **Let ByteRover read files** - Don't read files yourself before curating. Use `-f` flags to let ByteRover read them directly:\n ```bash\n # Good - ByteRover reads the files\n brv curate \"Auth implementation details\" -f src/auth.ts -f src/middleware/jwt.ts\n\n # Wasteful - reading files twice\n # [agent reads files] then brv curate \"...\" -f same-files\n ```\n\n3. **Be specific in queries** - Queries block your workflow. Use precise questions to get faster, more relevant results:\n ```bash\n # Good - specific\n brv query \"What validation library is used for API request schemas?\"\n\n # Bad - vague, slow\n brv query \"How is validation done?\"\n ```\n\n4. **Signal outdated context** - When curating updates that replace existing knowledge, explicitly tell ByteRover to clean up:\n ```bash\n 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\n ```\n\n5. **Specify structure expectations** - Guide ByteRover on how to organize the knowledge:\n ```bash\n # Specify topics/domains\n brv curate \"Create separate topics for: 1) JWT validation, 2) refresh token flow, 3) logout handling\" -f src/auth.ts\n\n # Specify detail level\n brv curate \"Document the error handling patterns in detail (at least 30 lines covering all error types)\" -f src/errors/\n ```\n\n## Prerequisites\n\nRun `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.\n\n---\n\n**See also:** [WORKFLOWS.md](WORKFLOWS.md) for detailed patterns and examples, [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for error handling\n\nFile v1.2.2:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"1.2.2\",\n \"publishedAt\": 1769526352095\n}\n\nFile v1.2.2:TROUBLESHOOTING.md\n\n# ByteRover Troubleshooting\n\n## Quick Diagnosis\n\n```bash\nbrv status\n```\n\n## User Action Required\n\nThese errors require user intervention (agent cannot fix):\n\n| Error | User Action |\n|-------|-------------|\n| \"No ByteRover instance is running\" | Start `brv` in separate terminal |\n| \"Not authenticated\" | Run `/login` in brv REPL |\n| \"Project not initialized\" | Run `/init` in brv REPL |\n| \"Connection failed\" | Restart `brv` (Ctrl+C, then `brv`) |\n\n**Template response:**\n> Please [action] in your brv terminal, then I'll retry the command.\n\n## Agent-Fixable Errors\n\n| Error | Fix |\n|-------|-----|\n| \"Context argument required\" | Add text before `-f`: `brv curate \"text\" -f file` |\n| \"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags |\n| \"File not found\" | Verify path with `ls`, use relative paths from project root |\n| \"No relevant context found\" | Try different query phrasing, or curate knowledge first |\n\n## Architecture\n\nByteRover uses client-server architecture:\n- User runs `brv` to start server (interactive REPL)\n- Agent commands (`query`, `curate`, `status`) connect to server\n- Server must be running for commands to work\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Connection error |\n\n## Getting Help\n\n- Email: support@byterover.dev\n- Discord: https://discord.com/invite/UMRrpNjh5W\n\nFile v1.2.2:WORKFLOWS.md\n\n# ByteRover Workflows\n\n## Pattern 1: Research Before Implementation\n\nUse when starting new features or working in unfamiliar areas.\n\n**Workflow:**\n```\nQuery existing knowledge → Implement following patterns → Curate new decisions\n```\n\n**Example: Adding a new API endpoint**\n\n```bash\n# 1. Query for existing patterns\n# Be SPECIFIC to get faster, more relevant results\nbrv query \"What middleware chain is used for authenticated API endpoints?\"\nbrv query \"What is the standard error response format for API routes?\"\n\n# 2. Implement following discovered patterns\n# ... write code ...\n\n# 3. Curate decisions made\n# Don't read the file first - let ByteRover read it via -f flag\nbrv curate \"Added /api/users/profile endpoint. Uses authMiddleware for JWT validation, returns UserProfileDTO. Error handling follows ApiError pattern\" -f src/api/routes/users.ts\n```\n\n**Example: Implementing a new React component**\n\n```bash\n# 1. Query patterns - specific questions save time\nbrv query \"What data fetching hook pattern is used in list components?\"\nbrv query \"Are CSS modules or styled-components used for component styling?\"\n\n# 2. Implement\n# ... write component ...\n\n# 3. Curate with file reference - ByteRover reads the file\nbrv 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\n```\n\n## Pattern 2: Debug and Document\n\nUse when fixing bugs to capture learnings and prevent recurrence.\n\n**Workflow:**\n```\nQuery known issues → Debug and fix → Curate root cause and solution\n```\n\n**Example: Fixing a race condition**\n\n```bash\n# 1. Query for context - be specific about the symptom\nbrv query \"Are there known race condition patterns or AbortController usage in data fetching hooks?\"\n\n# 2. Debug and fix\n# ... investigate, find root cause, implement fix ...\n\n# 3. Curate the learning with structured format\nbrv 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\n```\n\n**Example: Fixing an authentication issue**\n\n```bash\n# 1. Specific query about the problem area\nbrv query \"How are credentials and cookies configured in the API client fetch calls?\"\n\n# 2. Fix\n# ... debug and fix ...\n\n# 3. Curate with emphasis on the gotcha\nbrv 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\n```\n\n## Pattern 3: Multi-File Changes\n\nUse when changes span multiple files to maintain context.\n\n**Example: Adding a new feature across layers**\n\n```bash\n# 1. Query architecture - specific about the layers\nbrv query \"How are full-stack features organized across API routes, service layer, and React components?\"\n\n# 2. Implement across files\n# ... write code ...\n\n# 3. Curate with multiple files (max 5)\n# Let ByteRover read all files - don't read them yourself first\n# Specify the topics you want created\nbrv 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\n```\n\n**Example: Database schema change with migrations**\n\n```bash\n# 1. Query migration patterns\nbrv query \"What is the migration naming convention and how are schema changes tested?\"\n\n# 2. Implement\n# ... create migration, update models, update queries ...\n\n# 3. Multiple curates for different concerns - break down large context\nbrv curate \"Added user_preferences table with JSONB settings column. Migration: 20240115_add_user_preferences\" -f migrations/20240115_add_user_preferences.ts\n\nbrv curate \"UserPreferences model with type-safe JSONB access. Includes validation for theme, notifications, locale settings\" -f src/models/UserPreferences.ts\n\nbrv curate \"Updated UserService to load/save preferences. Uses transaction for atomic updates with user record\" -f src/services/UserService.ts\n```\n\n## Pattern 4: Updating Existing Knowledge\n\nUse when changes make previous context outdated.\n\n**Example: Refactoring authentication system**\n\n```bash\n# 1. Query current documented state\nbrv query \"What is currently documented about authentication implementation and token handling?\"\n\n# 2. Implement refactor\n# ... refactor code ...\n\n# 3. Curate with explicit cleanup signal\n# Tell ByteRover to clean up outdated context\nbrv 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\n```\n\n**Example: Replacing a library**\n\n```bash\n# 1. Query what's documented about the old library\nbrv query \"What patterns are documented for moment.js date handling?\"\n\n# 2. Implement replacement\n# ... replace library usage ...\n\n# 3. Curate the replacement with cleanup signal\nbrv 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\n```\n\n**Example: API versioning change**\n\n```bash\n# Curate with explicit version context\nbrv 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\n```\n\n## Pattern 5: Comprehensive Documentation\n\nUse when documenting complex systems that need detailed breakdown.\n\n**Example: Documenting a payment module**\n\n```bash\n# Break into multiple curates - don't try to capture everything in one\n# Specify structure and detail level for each topic\n\n# Overview first\nbrv curate \"Payment module overview: Stripe integration with webhooks for subscription management. Create 4 separate detailed topics covering the full payment lifecycle\" -f src/payments/\n\n# Topic 1 - detailed with line count guidance\nbrv 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\n\n# Topic 2 - webhook handling\nbrv 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\n\n# Topic 3 - subscription management\nbrv curate \"Topic: Subscription lifecycle. Cover: trial period handling, upgrade/downgrade proration, cancellation with grace period, reactivation flow\" -f src/payments/subscriptions.ts\n\n# Topic 4 - error handling\nbrv 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\n```\n\n**Example: Documenting a state management system**\n\n```bash\n# Multiple focused curates instead of one massive one\n\nbrv curate \"State management overview: Using Zustand with persistence middleware. Create topics for: store structure, async actions, persistence, devtools integration\" -f src/store/\n\nbrv 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\n\nbrv 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/\n\nbrv 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\n```\n\n## Pattern 6: Exploratory Documentation\n\nUse when you need to document an unfamiliar codebase area.\n\n**Example: Understanding and documenting an existing module**\n\n```bash\n# 1. Query what's already known\nbrv query \"What is documented about the notification system and real-time updates?\"\n\n# 2. Explore the code (agent reads files to understand)\n# ... read and understand the code ...\n\n# 3. Curate in chunks as you understand different parts\n# First curate: high-level architecture\nbrv 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/\n\n# Second curate: specific implementation detail\nbrv 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\n\n# Third curate: gotchas discovered\nbrv 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\n```\n\n## What to Curate\n\n**Do curate:**\n- Architecture decisions: \"Chose Redis for sessions because of horizontal scaling\"\n- Patterns: \"All forms use react-hook-form with zod. Pattern in LoginForm.tsx\"\n- Non-obvious conventions: \"File uploads go to /tmp first, then S3 after validation\"\n- Bug root causes: \"Memory leak from event listeners not removed on unmount\"\n- Gotchas: \"PostgreSQL JSONB queries need explicit casting for arrays\"\n- Replacements: \"OUTDATED: X, NEW: Y\" when refactoring\n\n**Don't curate:**\n- Obvious facts: \"Uses TypeScript\", \"Has a README\"\n- Temporary states: \"Currently debugging X\"\n- Personal preferences: \"I prefer tabs\"\n- Trivial changes: \"Fixed typo in comment\"\n\nArchive v1.2.1: 4 files, 7065 bytes\n\nFiles: SKILL.md (3576b), TROUBLESHOOTING.md (1360b), WORKFLOWS.md (10495b), _meta.json (128b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: byterover\ndescription: \"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.\"\n---\n\n# ByteRover Context Tree\n\nA project-level knowledge repository that persists across sessions. Use it to avoid re-discovering patterns, conventions, and decisions.\n\n## Why Use ByteRover\n\n- **Query before working**: Get existing knowledge about patterns, conventions, and past decisions before implementing\n- **Curate after learning**: Capture insights, decisions, and bug fixes so future sessions start informed\n\n## Quick Reference\n\n| Command | When | Example |\n|---------|------|---------|\n| `brv query \"question\"` | Before starting work | `brv query \"How is auth implemented?\"` |\n| `brv curate \"context\" -f file` | After completing work | `brv curate \"JWT 24h expiry\" -f auth.ts` |\n| `brv status` | To check prerequisites | `brv status` |\n\n## When to Use\n\n**Query** when you need to understand something:\n- \"How does X work in this codebase?\"\n- \"What patterns exist for Y?\"\n- \"Are there conventions for Z?\"\n\n**Curate** when you learned or created something valuable:\n- Implemented a feature using specific patterns\n- Fixed a bug and found root cause\n- Made an architecture decision\n\n## Curate Quality\n\nContext must be **specific** and **actionable**:\n\n```bash\n# Good - specific, explains where and why\nbrv curate \"Auth uses JWT 24h expiry, tokens in httpOnly cookies\" -f src/auth.ts\n\n# Bad - too vague\nbrv curate \"Fixed auth\"\n```\n\n**Note:** Context argument must come before `-f` flags. Max 5 files.\n\n## Best Practices\n\n1. **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.\n\n2. **Let ByteRover read files** - Don't read files yourself before curating. Use `-f` flags to let ByteRover read them directly:\n ```bash\n # Good - ByteRover reads the files\n brv curate \"Auth implementation details\" -f src/auth.ts -f src/middleware/jwt.ts\n\n # Wasteful - reading files twice\n # [agent reads files] then brv curate \"...\" -f same-files\n ```\n\n3. **Be specific in queries** - Queries block your workflow. Use precise questions to get faster, more relevant results:\n ```bash\n # Good - specific\n brv query \"What validation library is used for API request schemas?\"\n\n # Bad - vague, slow\n brv query \"How is validation done?\"\n ```\n\n4. **Signal outdated context** - When curating updates that replace existing knowledge, explicitly tell ByteRover to clean up:\n ```bash\n 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\n ```\n\n5. **Specify structure expectations** - Guide ByteRover on how to organize the knowledge:\n ```bash\n # Specify topics/domains\n brv curate \"Create separate topics for: 1) JWT validation, 2) refresh token flow, 3) logout handling\" -f src/auth.ts\n\n # Specify detail level\n brv curate \"Document the error handling patterns in detail (at least 30 lines covering all error types)\" -f src/errors/\n ```\n\n## Prerequisites\n\nRun `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.\n\n---\n\n**See also:** [WORKFLOWS.md](WORKFLOWS.md) for detailed patterns and examples, [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for error handling\n\nFile v1.2.1:_meta.json\n\n{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"1.2.1\",\n \"publishedAt\": 1769508805216\n}\n\nFile v1.2.1:TROUBLESHOOTING.md\n\n# ByteRover Troubleshooting\n\n## Quick Diagnosis\n\n```bash\nbrv status\n```\n\n## User Action Required\n\nThese errors require user intervention (agent cannot fix):\n\n| Error | User Action |\n|-------|-------------|\n| \"No ByteRover instance is running\" | Start `brv` in separate terminal |\n| \"Not authenticated\" | Run `/login` in brv REPL |\n| \"Project not initialized\" | Run `/init` in brv REPL |\n| \"Connection failed\" | Restart `brv` (Ctrl+C, then `brv`) |\n\n**Template response:**\n> Please [action] in your brv terminal, then I'll retry the command.\n\n## Agent-Fixable Errors\n\n| Error | Fix |\n|-------|-----|\n| \"Context argument required\" | Add text before `-f`: `brv curate \"text\" -f file` |\n| \"Maximum 5 files allowed\" | Reduce to 5 or fewer `-f` flags |\n| \"File not found\" | Verify path with `ls`, use relative paths from project root |\n| \"No relevant context found\" | Try different query phrasing, or curate knowledge first |\n\n## Architecture\n\nByteRover uses client-server architecture:\n- User runs `brv` to start server (interactive REPL)\n- Agent commands (`query`, `curate`, `status`) connect to server\n- Server must be running for commands to work\n\n## Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Connection error |\n\n## Getting Help\n\n- Email: support@byterover.dev\n- Discord: https://discord.com/invite/UMRrpNjh5W\n\nFile v1.2.1:WORKFLOWS.md\n\n# ByteRover Workflows\n\n## Pattern 1: Research Before Implementation\n\nUse when starting new features or working in unfamiliar areas.\n\n**Workflow:**\n```\nQuery existing knowledge → Implement following patterns → Curate new decisions\n```\n\n**Example: Adding a new API endpoint**\n\n```bash\n# 1. Query for existing patterns\n# Be SPECIFIC to get faster, more relevant results\nbrv query \"What middleware chain is used for authenticated API endpoints?\"\nbrv query \"What is the standard error response format for API routes?\"\n\n# 2. Implement following discovered patterns\n# ... write code ...\n\n# 3. Curate decisions made\n# Don't read the file first - let ByteRover read it via -f flag\nbrv curate \"Added /api/users/profile endpoint. Uses authMiddleware for JWT validation, returns UserProfileDTO. Error handling follows ApiError pattern\" -f src/api/routes/users.ts\n```\n\n**Example: Implementing a new React component**\n\n```bash\n# 1. Query patterns - specific questions save time\nbrv query \"What data fetching hook pattern is used in list components?\"\nbrv query \"Are CSS modules or styled-components used for component styling?\"\n\n# 2. Implement\n# ... write component ...\n\n# 3. Curate with file reference - ByteRover reads the file\nbrv 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\n```\n\n## Pattern 2: Debug and Document\n\nUse when fixing bugs to capture learnings and prevent recurrence.\n\n**Workflow:**\n```\nQuery known issues → Debug and fix → Curate root cause and solution\n```\n\n**Example: Fixing a race condition**\n\n```bash\n# 1. Query for context - be specific about the symptom\nbrv query \"Are there known race condition patterns or AbortController usage in data fetching hooks?\"\n\n# 2. Debug and fix\n# ... investigate, find root cause, implement fix ...\n\n# 3. Curate the learning with structured format\nbrv 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\n```\n\n**Example: Fixing an authentication issue**\n\n```bash\n# 1. Specific query about the problem area\nbrv query \"How are credentials and cookies configured in the API client fetch calls?\"\n\n# 2. Fix\n# ... debug and fix ...\n\n# 3. Curate with emphasis on the gotcha\nbrv 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\n```\n\n## Pattern 3: Multi-File Changes\n\nUse when changes span multiple files to maintain context.\n\n**Example: Adding a new feature across layers**\n\n```bash\n# 1. Query architecture - specific about the layers\nbrv query \"How are full-stack features organized across API routes, service layer, and React components?\"\n\n# 2. Implement across files\n# ... write code ...\n\n# 3. Curate with multiple files (max 5)\n# Let ByteRover read all files - don't read them yourself first\n# Specify the topics you want created\nbrv 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\n```\n\n**Example: Database schema change with migrations**\n\n```bash\n# 1. Query migration patterns\nbrv query \"What is the migration naming convention and how are schema changes tested?\"\n\n# 2. Implement\n# ... create migration, update models, update queries ...\n\n# 3. Multiple curates for different concerns - break down large context\nbrv curate \"Added user_preferences table with JSONB settings column. Migration: 20240115_add_user_preferences\" -f migrations/20240115_add_user_preferences.ts\n\nbrv curate \"UserPreferences model with type-safe JSONB access. Includes validation for theme, notifications, locale settings\" -f src/models/UserPreferences.ts\n\nbrv curate \"Updated UserService to load/save preferences. Uses transaction for atomic updates with user record\" -f src/services/UserService.ts\n```\n\n## Pattern 4: Updating Existing Knowledge\n\nUse when changes make previous context outdated.\n\n**Example: Refactoring authentication system**\n\n```bash\n# 1. Query current documented state\nbrv query \"What is currently documented about authentication implementation and token handling?\"\n\n# 2. Implement refactor\n# ... refactor code ...\n\n# 3. Curate with explicit cleanup signal\n# Tell ByteRover to clean up outdated context\nbrv 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\n```\n\n**Example: Replacing a library**\n\n```bash\n# 1. Query what's documented about the old library\nbrv query \"What patterns are documented for moment.js date handling?\"\n\n# 2. Implement replacement\n# ... replace library usage ...\n\n# 3. Curate the replacement with cleanup signal\nbrv 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\n```\n\n**Example: API versioning change**\n\n```bash\n# Curate with explicit version context\nbrv 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\n```\n\n## Pattern 5: Comprehensive Documentation\n\nUse when documenting complex systems that need detailed breakdown.\n\n**Example: Documenting a payment module**\n\n```bash\n# Break into multiple curates - don't try to capture everything in one\n# Specify structure and detail level for each topic\n\n# Overview first\nbrv curate \"Payment module overview: Stripe integration with webhooks for subscription management. Create 4 separate detailed topics covering the full payment lifecycle\" -f src/payments/\n\n# Topic 1 - detailed with line count guidance\nbrv 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\n\n# Topic 2 - webhook handling\nbrv 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\n\n# Topic 3 - subscription management\nbrv curate \"Topic: Subscription lifecycle. Cover: trial period handling, upgrade/downgrade proration, cancellation with grace period, reactivation flow\" -f src/payments/subscriptions.ts\n\n# Topic 4 - error handling\nbrv 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\n```\n\n**Example: Documenting a state management system**\n\n```bash\n# Multiple focused curates instead of one massive one\n\nbrv curate \"State management overview: Using Zustand with persistence middleware. Create topics for: store structure, async actions, persistence, devtools integration\" -f src/store/\n\nbrv 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\n\nbrv 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/\n\nbrv 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\n```\n\n## Pattern 6: Exploratory Documentation\n\nUse when you need to document an unfamiliar codebase area.\n\n**Example: Understanding and documenting an existing module**\n\n```bash\n# 1. Query what's already known\nbrv query \"What is documented about the notification system and real-time updates?\"\n\n# 2. Explore the code (agent reads files to understand)\n# ... read and understand the code ...\n\n# 3. Curate in chunks as you understand different parts\n# First curate: high-level architecture\nbrv 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/\n\n# Second curate: specific implementation detail\nbrv 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\n\n# Third curate: gotchas discovered\nbrv 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\n```\n\n## What to Curate\n\n**Do curate:**\n- Architecture decisions: \"Chose Redis for sessions because of horizontal scaling\"\n- Patterns: \"All forms use react-hook-form with zod. Pattern in LoginForm.tsx\"\n- Non-obvious conventions: \"File uploads go to /tmp first, then S3 after validation\"\n- Bug root causes: \"Memory leak from event listeners not removed on unmount\"\n- Gotchas: \"PostgreSQL JSONB queries need explicit casting for arrays\"\n- Replacements: \"OUTDATED: X, NEW: Y\" when refactoring\n\n**Don't curate:**\n- Obvious facts: \"Uses TypeScript\", \"Has a README\"\n- Temporary states: \"Currently debugging X\"\n- Personal preferences: \"I prefer tabs\"\n- Trivial changes: \"Fixed typo in comment\"","readmeExcerpt":"Skill: ByteRover Owner: byteroverinc Summary: You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use brv to store and retrieve project patterns, dec... Tags: latest:3.3.0 Version history: v3.3.0 | 2026-04-18T11:37:07.733Z | user v3.3.0 Added - Added section 11 \"Query and Curate History\" with Overview, Use/Do-NOT-use blocks, and both brv curate view and brv query-lo","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"brv query \"How is authentication implemented?\""},{"language":"bash","snippet":"brv search \"authentication patterns\"\nbrv search \"JWT tokens\" --limit 5 --scope \"auth/\"\nbrv search \"auth\" --format json"},{"language":"bash","snippet":"brv curate \"Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts\""},{"language":"bash","snippet":"brv curate \"Authentication middleware details\" -f src/middleware/auth.ts"},{"language":"bash","snippet":"brv review pending"},{"language":"text","snippet":"2 operations pending review\n\n  Task: ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  [UPSERT · HIGH IMPACT] - path: architecture/context/context_compression_pipeline.md\n  Why:    Documenting switch to token-budget sliding window\n  After:  Context compression pipeline switching from reactive-overflow to token-budget sliding window in src/agent/infra/llm/context/compression/\n\n  [UPSERT · HIGH IMPACT] - path: architecture/tools/agent_tool_registry.md\n  Why:    Documenting tool registry rewrite with capability-based permissions\n  After:  Agent tool registry rewrite in src/agent/infra/tools/tool-registry.ts using capability-based permissions\n\n  To approve all:  brv review approve ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  To reject all:   brv review reject ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3\n  Per file:        brv review ddcb3dc6-d957-4a56-b9c3-d0bdc04317f3 --file [--file ]"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: byterover\ndescription: \"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, decisions, and architectural rules in .brv/context-tree. Uses a configured LLM provider (default: ByteRover, no API key needed) for query and curate operations.\"\n---\n\n# ByteRover Knowledge Management\n\nUse the `brv` CLI to manage your project's long-term memory.\nInstall: `npm install -g byterover-cli`\nKnowledge is stored in `.brv/context-tree/` as human-readable Markdown files.\n\n**No authentication needed.** `brv query`, `brv curate`, and `brv vc` (local version control) work out of the box. Login is only required for remote sync (`brv vc push`/`brv vc pull`).\n\n## Workflow\n1. **Before Thinking:** Run `brv query` to understand existing patterns.\n2. **After Implementing:** Run `brv curate` to save new patterns/decisions.\n\n## Commands\n\n### 1. Query Knowledge\n**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.\n\n**Use this skill when:**\n- The user wants you to recall something\n- Your context does not contain information you need\n- You need to recall your capabilities or past actions\n- Before performing any action, to check for relevant rules, criteria, or preferences\n\n**Do NOT use this skill when:**\n- The information is already present in your current context\n- The query is about general knowledge, not stored memory\n\n```bash\nbrv query \"How is authentication implemented?\"\n```\n\n### 2. Search Context Tree\n**Overview:** Retrieve a ranked list of matching files from `.brv/context-tree/` via pure BM25 lookup. Unlike `brv query`, this does NOT call an LLM — no synthesis, no token cost, no provider setup needed. Returns structured results with paths, scores, and excerpts.\n\n**Use this skill when:**\n- You need file paths to read rather than a synthesized answer\n- You want fast, cheap retrieval with no LLM overhead\n- You're in an automated pipeline that consumes structured results\n\n**Do NOT use this skill when:**\n- You need a natural-language answer synthesized from multiple files — use `brv query` instead\n- The information is already present in your current context\n\n```bash\nbrv search \"authentication patterns\"\nbrv search \"JWT tokens\" --limit 5 --scope \"auth/\"\nbrv search \"auth\" --format json\n```\n\n**Flags:** `--limit N` (1-50, default 10), `--scope \"domain/\"` (path prefix filter), `--format json` (structured output for automation).\n\n### 3. Curate Context\n**Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.\n\n**Use this skill when:**\n- The user wants you to remember something\n- The user intentionally curates memory or knowledge\n- There are meaningful memories from user interactions that should be persisted\n- There are important facts about what you do, what you know, or "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn73aw5gqbhxdqygjachxpd401800y76\",\n \"slug\": \"byterover\",\n \"version\": \"3.3.0\",\n \"publishedAt\": 1776512227733\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use `brv` to store and retrieve project patterns, dec... Skill: ByteRover Owner: byteroverinc Summary: You MUST use this for gathering contexts before any work. This is a Knowledge management for AI agents. Use brv to store and retrieve project patterns, dec... Tags: latest:3.3.0 Version history: v3.3.0 | 2026-04-18T11:37:07.733Z | user v3.3.0 Added - Added section 11 \"Query and Curate History\" with Overview, Use/Do-NOT-use blocks, and both brv curate view and brv query-lo","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1376,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-05-16T06:11:56.099Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T09:14:45.734Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}