byterover-cli 3.2.0 → 3.4.0

package/dist/server/templates/skill/SKILL.md

@@ -34,7 +34,27 @@ Knowledge is stored in `.brv/context-tree/` as human-readable Markdown files.
 brv query "How is authentication implemented?"
 ```
 
-### 2. Curate Context
+### 2. Search Context Tree
+**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.
+
+**Use this skill when:**
+- You need file paths to read rather than a synthesized answer
+- You want fast, cheap retrieval with no LLM overhead
+- You're in an automated pipeline that consumes structured results
+
+**Do NOT use this skill when:**
+- You need a natural-language answer synthesized from multiple files — use `brv query` instead
+- The information is already present in your current context
+
+```bash
+brv search "authentication patterns"
+brv search "JWT tokens" --limit 5 --scope "auth/"
+brv search "auth" --format json
+```
+
+**Flags:** `--limit N` (1-50, default 10), `--scope "domain/"` (path prefix filter), `--format json` (structured output for automation).
+
+### 3. Curate Context
 **Overview:** Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.
 
 **Use this skill when:**
@@ -79,7 +99,7 @@ brv curate view --since 1h --status completed
 brv curate view --help
 ```
 
-### 3. Review Pending Changes
+### 4. Review Pending Changes
 **Overview:** After a curate operation, some changes may require human review before being applied. Use `brv review` to list, approve, or reject pending operations.
 
 **Use this when:**
@@ -142,7 +162,7 @@ brv review approve <taskId> --format json
 brv review reject <taskId> --format json
 ```
 
-### 4. LLM Provider Setup
+### 5. LLM Provider Setup
 `brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):
 
 ```bash
@@ -156,7 +176,7 @@ brv providers list
 brv providers connect openai --api-key sk-xxx --model gpt-4.1
 ```
 
-### 5. Project Locations
+### 6. Project Locations
 **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.
 
 **Use this when:**
@@ -174,7 +194,7 @@ brv locations -f json
 
 JSON fields: `projectPath`, `contextTreePath`, `isCurrent`, `isActive`, `isInitialized`.
 
-### 6. Version Control
+### 7. Version Control
 **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.
 
 **Use this when:**
@@ -290,6 +310,169 @@ brv vc push -u origin main       # push and set upstream tracking
 brv vc clone https://byterover.dev/<team>/<space>.git
 ```
 
+### 8. Swarm Query
+**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.
+
+**Use this skill when:**
+- You need to search across multiple knowledge sources at once
+- The user has configured multiple memory providers (check with `brv swarm status`)
+- You want results from Obsidian notes, GBrain entities, or wiki pages alongside ByteRover context
+
+**Do NOT use this skill when:**
+- The user only has ByteRover configured — use `brv query` instead (it synthesizes via LLM)
+- You need an LLM-synthesized answer — `brv swarm query` returns raw search results, not synthesized text
+
+```bash
+brv swarm query "How does JWT refresh work?"
+```
+
+Output:
+```
+Swarm Query: "How does JWT refresh work?"
+Type: factual | Providers: 4 queried | Latency: 398ms
+──────────────────────────────────────────────────
+1. [memory-wiki] sources/jwt-token-lifecycle.md    score: 0.0150  [keyword]
+   # JWT Token Lifecycle ...
+2. [obsidian] SwarmTestData/Authentication System.md    score: 0.0142  [keyword]
+   # Authentication System ...
+3. [gbrain] alex-chen    score: 0.0117  [semantic]
+   # Alex Chen — Senior Backend Engineer ...
+```
+
+**With explain mode** (shows classification, provider selection, enrichment):
+```bash
+brv swarm query "authentication patterns" --explain
+```
+
+Output:
+```
+Classification: factual
+Provider selection: 4 of 4 available
+  ✓ byterover    (healthy, selected, 0 results, 14ms)
+  ✓ obsidian    (healthy, selected, 5 results, 91ms)
+  ✓ memory-wiki    (healthy, selected, 2 results, 15ms)
+  ✓ gbrain    (healthy, selected, 1 results, 260ms)
+Enrichment:
+  byterover → obsidian
+  byterover → memory-wiki
+Results: 8 raw → 7 after RRF fusion + precision filtering
+```
+
+**JSON output:**
+```bash
+brv swarm query "rate limiting" --format json
+```
+
+Output:
+```json
+{
+  "meta": {
+    "queryType": "factual",
+    "totalLatencyMs": 340,
+    "providers": {
+      "byterover": { "selected": true, "resultCount": 0 },
+      "obsidian": { "selected": true, "resultCount": 5 },
+      "gbrain": { "selected": true, "resultCount": 1 },
+      "memory-wiki": { "selected": true, "resultCount": 1 }
+    }
+  },
+  "results": [
+    { "provider": "memory-wiki", "providerType": "memory-wiki", "score": 0.015, "content": "# Rate Limiting ..." }
+  ]
+}
+```
+
+**Limit results:**
+```bash
+brv swarm query "testing strategy" -n 5
+```
+
+**Flags:** `--explain` (show routing details), `--format json` (structured output), `-n <value>` (max results).
+
+### 9. Swarm Curate
+**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.
+
+**Use this skill when:**
+- You want to store knowledge in an external provider (GBrain, Local Markdown, Memory Wiki)
+- The user has configured writable swarm providers
+
+**Do NOT use this skill when:**
+- You want to store in ByteRover's context tree specifically — use `brv curate` instead
+- No swarm providers are configured — use `brv curate` instead
+
+```bash
+brv swarm curate "Jane Smith is the CTO of TechCorp"
+```
+
+Output:
+```
+Stored to gbrain as concept/jane-smith-cto
+```
+
+**Target a specific provider:**
+```bash
+brv swarm curate "meeting notes: decided on JWT" --provider local-markdown:notes
+```
+
+Output:
+```
+Stored to local-markdown:notes as note-1776052527043.md
+```
+
+```bash
+brv swarm curate "Architecture uses event sourcing" --provider gbrain
+```
+
+Output:
+```
+Stored to gbrain as concept/event-sourcing-architecture
+```
+
+**JSON output:**
+```bash
+brv swarm curate "Test content" --format json
+```
+
+Output:
+```json
+{
+  "id": "note-1776052594462.md",
+  "provider": "local-markdown:project-docs",
+  "success": true,
+  "latencyMs": 1
+}
+```
+
+**Flags:** `--provider <id>` (target specific provider), `--format json` (structured output).
+
+### 10. Swarm Status
+**Overview:** Check provider health and write targets before running swarm query or curate. Use this to verify which providers are available and operational.
+
+**Use this skill when:**
+- Before running `brv swarm query` or `brv swarm curate` to check available providers
+- Diagnosing why swarm results are missing from a specific provider
+
+```bash
+brv swarm status
+```
+
+Output:
+```
+Memory Swarm Health Check
+════════════════════════════════════════
+  ✓ ByteRover       context-tree (always on)
+  ✓ Obsidian        /Users/you/Documents/MyObsidian
+  ✓ Local .md       1 folder(s)
+  ✓ GBrain          /Users/you/workspaces/gbrain
+  ✓ Memory Wiki     /Users/you/.openclaw/wiki/main
+
+Write Targets:
+  gbrain (entity, general)
+  local-markdown:project-docs (note, general)
+
+Swarm is operational (5/5 providers configured).
+```
+
 ## Data Handling
 
 **Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.

package/dist/server/utils/gitignore.d.ts

@@ -7,3 +7,4 @@
  * is a convenience feature that should never block the caller.
  */
 export declare function ensureGitignoreEntries(directory: string): Promise<void>;
+export declare function ensureContextTreeGitignore(contextTreeDir: string): Promise<void>;

package/dist/server/utils/gitignore.js

@@ -1,5 +1,6 @@
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { CONTEXT_TREE_GITIGNORE_HEADER, CONTEXT_TREE_GITIGNORE_PATTERNS } from '../constants.js';
 const GITIGNORE_ENTRIES = `# ByteRover — .brv/context-tree/ contains a nested .git managed by brv vc.
 # Without these entries, \`git add .\` fails with "does not have a commit checked out".
 .brv/
@@ -14,10 +15,8 @@ const GITIGNORE_ENTRIES = `# ByteRover — .brv/context-tree/ contains a nested
  */
 export async function ensureGitignoreEntries(directory) {
     try {
-        const dir = directory;
-        // Only add entries in git repositories
-        await access(join(dir, '.git'));
-        const gitignorePath = join(dir, '.gitignore');
+        await access(join(directory, '.git'));
+        const gitignorePath = join(directory, '.gitignore');
         let existing = '';
         try {
             existing = await readFile(gitignorePath, 'utf8');
@@ -45,3 +44,36 @@ export async function ensureGitignoreEntries(directory) {
         // Best-effort — gitignore failure should not block the caller
     }
 }
+export async function ensureContextTreeGitignore(contextTreeDir) {
+    try {
+        const gitignorePath = join(contextTreeDir, '.gitignore');
+        let existing = '';
+        try {
+            existing = await readFile(gitignorePath, 'utf8');
+        }
+        catch {
+            // File doesn't exist — will create with full content
+        }
+        if (existing.length === 0) {
+            await writeFile(gitignorePath, CONTEXT_TREE_GITIGNORE_HEADER + '\n' + CONTEXT_TREE_GITIGNORE_PATTERNS.join('\n') + '\n', 'utf8');
+            return;
+        }
+        const existingLines = existing.split('\n').map((l) => l.trim());
+        const toAppend = [];
+        if (!existingLines.includes(CONTEXT_TREE_GITIGNORE_HEADER)) {
+            toAppend.push(CONTEXT_TREE_GITIGNORE_HEADER);
+        }
+        for (const pattern of CONTEXT_TREE_GITIGNORE_PATTERNS) {
+            if (existingLines.some((el) => el.includes(pattern)))
+                continue;
+            toAppend.push(pattern);
+        }
+        if (toAppend.length === 0)
+            return;
+        const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+        await writeFile(gitignorePath, existing + separator + toAppend.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // Best-effort — gitignore sync should never block the caller
+    }
+}

package/dist/shared/transport/search-content.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Encode/decode helpers for search task content payloads.
+ *
+ * The transport layer's TaskCreateRequest has a single `content: string`
+ * field. For search tasks, we pack {query, limit?, scope?} as JSON so
+ * the agent process can reconstruct the structured options.
+ *
+ * Lives in shared/ because both the CLI (encoder) and the daemon
+ * agent-process (decoder) depend on it. Keeping it in oclif/ would
+ * create a circular dependency (server → oclif).
+ */
+/**
+ * Encode search options as JSON content payload for the transport layer.
+ */
+export declare function encodeSearchContent(options: {
+    limit?: number;
+    query: string;
+    scope?: string;
+}): string;
+/**
+ * Parse a JSON-encoded search content payload back into options.
+ * Falls back to treating the entire string as a plain query if parsing fails.
+ */
+export declare function decodeSearchContent(content: string): {
+    limit?: number;
+    query: string;
+    scope?: string;
+};

package/dist/shared/transport/search-content.js

@@ -0,0 +1,38 @@
+/**
+ * Encode/decode helpers for search task content payloads.
+ *
+ * The transport layer's TaskCreateRequest has a single `content: string`
+ * field. For search tasks, we pack {query, limit?, scope?} as JSON so
+ * the agent process can reconstruct the structured options.
+ *
+ * Lives in shared/ because both the CLI (encoder) and the daemon
+ * agent-process (decoder) depend on it. Keeping it in oclif/ would
+ * create a circular dependency (server → oclif).
+ */
+/**
+ * Encode search options as JSON content payload for the transport layer.
+ */
+export function encodeSearchContent(options) {
+    return JSON.stringify({
+        limit: options.limit,
+        query: options.query,
+        scope: options.scope,
+    });
+}
+/**
+ * Parse a JSON-encoded search content payload back into options.
+ * Falls back to treating the entire string as a plain query if parsing fails.
+ */
+export function decodeSearchContent(content) {
+    try {
+        const parsed = JSON.parse(content);
+        return {
+            limit: typeof parsed.limit === 'number' ? parsed.limit : undefined,
+            query: typeof parsed.query === 'string' ? parsed.query : content,
+            scope: typeof parsed.scope === 'string' ? parsed.scope : undefined,
+        };
+    }
+    catch {
+        return { query: content };
+    }
+}

package/dist/shared/transport/types/dto.d.ts

@@ -133,7 +133,7 @@ export interface StatusDTO {
     contextTreeDir?: string;
     /** Relative path to the context tree directory from project root (e.g., '.brv/context-tree') */
     contextTreeRelativeDir?: string;
-    contextTreeStatus: 'git_vc' | 'has_changes' | 'no_changes' | 'not_initialized' | 'unknown';
+    contextTreeStatus: 'git_vc' | 'has_changes' | 'no_changes' | 'no_vc' | 'not_initialized' | 'unknown';
     /** @deprecated Use projectRoot instead. Kept for backward compatibility. */
     currentDirectory: string;
     /** Number of files with pending HITL review (0 if none or unavailable). */

package/dist/tui/features/status/utils/format-status.js

@@ -76,6 +76,10 @@ export function formatStatus(status, version) {
             lines.push('Context Tree: No changes');
             break;
         }
+        case 'no_vc': {
+            lines.push('Context Tree: Managed by Byterover version control (use /vc commands)');
+            break;
+        }
         case 'not_initialized': {
             lines.push('Context Tree: Not initialized');
             break;
@@ -89,5 +93,6 @@ export function formatStatus(status, version) {
         lines.push(chalk.yellow(`Pending Reviews: ${status.pendingReviewCount} ${fileLabel} need review`) +
             (status.reviewUrl ? `\n  Review: ${chalk.blue(status.reviewUrl)}` : ''));
     }
+    lines.push('', 'Tip: Version control is now available for your context tree.', 'Learn more: https://docs.byterover.dev/git-semantic/overview');
     return lines.join('\n');
 }

package/dist/tui/utils/error-messages.js

@@ -9,20 +9,20 @@
 const USER_FRIENDLY_MESSAGES = {
     ERR_AGENT_NOT_INITIALIZED: "Agent failed to initialize. Run 'brv restart' to force a clean restart.",
     ERR_CONTEXT_TREE_NOT_INIT: 'Context tree not initialized.',
+    ERR_LEGACY_SYNC_UNAVAILABLE: 'Legacy cloud sync (push/pull) is not available for this project. Use /vc init to start using version control. Learn more: https://docs.byterover.dev/git-semantic/overview',
     ERR_LOCAL_CHANGES_EXIST: 'You have local changes. Run /push to save your changes before pulling.',
     ERR_NOT_AUTHENTICATED: 'Not authenticated. This is required for cloud sync. Run /login to connect your account.',
     ERR_OAUTH_REFRESH_FAILED: 'OAuth token refresh failed. Run /providers to reconnect your provider.',
     ERR_OAUTH_TOKEN_EXPIRED: 'OAuth token has expired. Run /providers to reconnect your provider.',
     ERR_PROJECT_NOT_INIT: "Project not initialized. Run 'brv restart' to reinitialize.",
     ERR_PROVIDER_NOT_CONFIGURED: 'No provider connected. Run /providers connect byterover to use the free built-in provider, or connect another provider.',
-    ERR_SPACE_NOT_CONFIGURED: 'No space configured. Run /space switch to select a space first.',
     ERR_SPACE_NOT_FOUND: 'Space not found. Check your configuration.',
     ERR_VC_AUTH_FAILED: 'Authentication failed. Run /login.',
     ERR_VC_BRANCH_ALREADY_EXISTS: 'Branch already exists.',
     ERR_VC_CANNOT_DELETE_CURRENT_BRANCH: 'Cannot delete the currently checked-out branch.',
     ERR_VC_CONFIG_KEY_NOT_SET: 'Config key is not set.',
     ERR_VC_CONFLICT_MARKERS_PRESENT: 'Conflict markers detected. Run /vc conflicts to view them. Resolve conflicts and run /vc add before pushing.',
-    ERR_VC_GIT_INITIALIZED: 'ByteRover version control is active. Use /vc commands instead of legacy sync commands.',
+    ERR_VC_GIT_INITIALIZED: 'ByteRover version control is active. Use /vc commands instead of legacy sync commands. Learn more: https://docs.byterover.dev/git-semantic/overview',
     ERR_VC_GIT_NOT_INITIALIZED: 'ByteRover version control not initialized. Run /vc init first.',
     ERR_VC_INVALID_ACTION: 'Invalid action.',
     // ERR_VC_INVALID_BRANCH_NAME intentionally omitted: fall through to server's message with actual branch name