byterover-cli 1.5.0 → 1.7.0

package/dist/server/infra/usecase/space-switch-use-case.js

@@ -0,0 +1,110 @@
+import { BRV_DIR, PROJECT_CONFIG_FILE } from '../../constants.js';
+import { BrvConfig } from '../../core/domain/entities/brv-config.js';
+export class SpaceSwitchUseCase {
+    projectConfigStore;
+    spaceService;
+    teamService;
+    terminal;
+    tokenStore;
+    constructor(deps) {
+        this.projectConfigStore = deps.projectConfigStore;
+        this.spaceService = deps.spaceService;
+        this.teamService = deps.teamService;
+        this.terminal = deps.terminal;
+        this.tokenStore = deps.tokenStore;
+    }
+    async promptForSpaceSelection(spaces) {
+        const selectedSpaceId = await this.terminal.select({
+            choices: spaces.map((space) => ({
+                name: space.getDisplayName(),
+                value: space.id,
+            })),
+            message: 'Select a space',
+        });
+        const selectedSpace = spaces.find((space) => space.id === selectedSpaceId);
+        if (!selectedSpace) {
+            this.terminal.log('Space selection failed');
+            return undefined;
+        }
+        return selectedSpace;
+    }
+    async promptForTeamSelection(teams) {
+        const selectedTeamId = await this.terminal.select({
+            choices: teams.map((team) => ({
+                name: team.name,
+                value: team.id,
+            })),
+            message: 'Select a team',
+        });
+        const selectedTeam = teams.find((team) => team.id === selectedTeamId);
+        if (!selectedTeam) {
+            this.terminal.log('Team selection failed');
+            return undefined;
+        }
+        return selectedTeam;
+    }
+    async run() {
+        // Check project initialization (MUST exist for switch)
+        const currentConfig = await this.projectConfigStore.read();
+        if (!currentConfig) {
+            this.terminal.log('Project not initialized. Please run "/init" first.');
+            return;
+        }
+        // Show current configuration
+        this.terminal.log('Current configuration:');
+        this.terminal.log(`  Team: ${currentConfig.teamName}`);
+        this.terminal.log(`  Space: ${currentConfig.spaceName}`);
+        this.terminal.log();
+        // Validate authentication
+        const token = await this.tokenStore.load();
+        if (!token) {
+            this.terminal.log('Not authenticated. Please run "/login" first.');
+            return;
+        }
+        if (!token.isValid()) {
+            this.terminal.log('Authentication token expired. Please run "/login" again.');
+            return;
+        }
+        // Fetch all teams
+        this.terminal.actionStart('Fetching all teams');
+        const teamResult = await this.teamService.getTeams(token.sessionKey, { fetchAll: true });
+        this.terminal.actionStop();
+        if (teamResult.teams.length === 0) {
+            this.terminal.log('No teams found. Please create a team in the ByteRover dashboard first.');
+            return;
+        }
+        // Prompt for team selection
+        this.terminal.log();
+        const selectedTeam = await this.promptForTeamSelection(teamResult.teams);
+        if (!selectedTeam)
+            return;
+        // Fetch spaces for selected team
+        this.terminal.actionStart('Fetching all spaces');
+        const spaceResult = await this.spaceService.getSpaces(token.sessionKey, selectedTeam.id, {
+            fetchAll: true,
+        });
+        this.terminal.actionStop();
+        if (spaceResult.spaces.length === 0) {
+            this.terminal.log(`No spaces found in team "${selectedTeam.getDisplayName()}". Please create a space in the ByteRover dashboard first.`);
+            return;
+        }
+        // Prompt for space selection
+        this.terminal.log();
+        const selectedSpace = await this.promptForSpaceSelection(spaceResult.spaces);
+        if (!selectedSpace)
+            return;
+        // Update configuration
+        const newConfig = new BrvConfig({
+            ...currentConfig,
+            createdAt: new Date().toISOString(),
+            spaceId: selectedSpace.id,
+            spaceName: selectedSpace.name,
+            teamId: selectedTeam.id,
+            teamName: selectedTeam.name,
+        });
+        await this.projectConfigStore.write(newConfig);
+        // Display success
+        this.terminal.log(`\n✓ Successfully switched to space: ${selectedSpace.getDisplayName()}`);
+        this.terminal.log(`✓ Configuration updated in: ${BRV_DIR}/${PROJECT_CONFIG_FILE}`);
+    }
+}

package/dist/server/infra/usecase/status-use-case.d.ts

@@ -0,0 +1,75 @@
+import { type ConnectionResult } from '@campfirein/brv-transport-client';
+import type { ITokenStore } from '../../core/interfaces/auth/i-token-store.js';
+import type { IContextTreeService } from '../../core/interfaces/context-tree/i-context-tree-service.js';
+import type { IContextTreeSnapshotService } from '../../core/interfaces/context-tree/i-context-tree-snapshot-service.js';
+import type { ITerminal } from '../../core/interfaces/services/i-terminal.js';
+import type { ITrackingService } from '../../core/interfaces/services/i-tracking-service.js';
+import type { IProjectConfigStore } from '../../core/interfaces/storage/i-project-config-store.js';
+import type { IStatusUseCase } from '../../core/interfaces/usecase/i-status-use-case.js';
+/** Type for transport connection function (for DI/testing) */
+export type TransportConnector = (fromDir?: string) => Promise<ConnectionResult>;
+/**
+ * Structured status data for JSON output.
+ */
+export interface StatusData {
+    authStatus: 'expired' | 'logged_in' | 'not_logged_in' | 'unknown';
+    cliVersion: string;
+    contextTreeChanges?: {
+        added: string[];
+        deleted: string[];
+        modified: string[];
+    };
+    contextTreeStatus: 'has_changes' | 'no_changes' | 'not_initialized' | 'unknown';
+    currentDirectory: string;
+    mcpStatus: 'connected' | 'crashed' | 'error' | 'no_instance' | 'not_responsive';
+    projectInitialized: boolean;
+    spaceName?: string;
+    teamName?: string;
+    userEmail?: string;
+}
+export interface StatusUseCaseOptions {
+    contextTreeService: IContextTreeService;
+    contextTreeSnapshotService: IContextTreeSnapshotService;
+    projectConfigStore: IProjectConfigStore;
+    terminal: ITerminal;
+    tokenStore: ITokenStore;
+    trackingService: ITrackingService;
+    /** Optional transport connector for dependency injection (defaults to connectToTransport) */
+    transportConnector?: TransportConnector;
+}
+export declare class StatusUseCase implements IStatusUseCase {
+    private readonly contextTreeService;
+    private readonly contextTreeSnapshotService;
+    private readonly projectConfigStore;
+    private readonly terminal;
+    private readonly tokenStore;
+    private readonly trackingService;
+    private readonly transportConnector;
+    constructor(options: StatusUseCaseOptions);
+    run(options: {
+        cliVersion: string;
+        format?: 'json' | 'text';
+    }): Promise<void>;
+    /**
+     * Checks the MCP connection status by:
+     * 1. Discovering running brv instance and connecting via transport
+     * 2. Verifying bidirectional communication with ping
+     */
+    private checkMcpStatus;
+    /**
+     * Check MCP status and return structured data.
+     */
+    private checkMcpStatusData;
+    /**
+     * Collect all status data into a structured object for JSON output.
+     */
+    private collectStatusData;
+    /**
+     * Output status data as JSON.
+     */
+    private outputJsonStatus;
+    /**
+     * Original text format output.
+     */
+    private runTextFormat;
+}

package/dist/server/infra/usecase/status-use-case.js

@@ -0,0 +1,268 @@
+import { connectToTransport, InstanceCrashedError, NoInstanceRunningError, } from '@campfirein/brv-transport-client';
+import chalk from 'chalk';
+import { join } from 'node:path';
+import { BRV_DIR, CONTEXT_TREE_DIR } from '../../constants.js';
+import { getErrorMessage } from '../../utils/error-helpers.js';
+import { HeadlessTerminal } from '../terminal/headless-terminal.js';
+export class StatusUseCase {
+    contextTreeService;
+    contextTreeSnapshotService;
+    projectConfigStore;
+    terminal;
+    tokenStore;
+    trackingService;
+    transportConnector;
+    constructor(options) {
+        this.contextTreeService = options.contextTreeService;
+        this.contextTreeSnapshotService = options.contextTreeSnapshotService;
+        this.projectConfigStore = options.projectConfigStore;
+        this.terminal = options.terminal;
+        this.tokenStore = options.tokenStore;
+        this.trackingService = options.trackingService;
+        this.transportConnector = options.transportConnector ?? connectToTransport;
+    }
+    async run(options) {
+        const format = options.format ?? 'text';
+        if (format === 'json') {
+            const statusData = await this.collectStatusData(options.cliVersion);
+            this.outputJsonStatus(statusData);
+            return;
+        }
+        // Text format output (original behavior)
+        await this.runTextFormat(options.cliVersion);
+    }
+    /**
+     * Checks the MCP connection status by:
+     * 1. Discovering running brv instance and connecting via transport
+     * 2. Verifying bidirectional communication with ping
+     */
+    async checkMcpStatus() {
+        try {
+            const { client, projectRoot } = await this.transportConnector(process.cwd());
+            try {
+                const isResponsive = await client.isConnected(2000);
+                if (isResponsive) {
+                    this.terminal.log(`MCP Status: ${chalk.green('Connected and responsive')} (${projectRoot})`);
+                }
+                else {
+                    this.terminal.log(`MCP Status: ${chalk.yellow('Connected but not responsive')} (ping timeout)`);
+                }
+            }
+            finally {
+                await client.disconnect();
+            }
+        }
+        catch (error) {
+            if (error instanceof InstanceCrashedError) {
+                this.terminal.log(`MCP Status: ${chalk.red('Instance crashed')} (stale instance file found)`);
+            }
+            else if (error instanceof NoInstanceRunningError) {
+                this.terminal.log(`MCP Status: ${chalk.yellow('No instance running')}`);
+            }
+            else {
+                this.terminal.log(`MCP Status: ${chalk.red('Connection failed')} - ${getErrorMessage(error)}`);
+            }
+        }
+    }
+    /**
+     * Check MCP status and return structured data.
+     */
+    async checkMcpStatusData() {
+        try {
+            const { client } = await this.transportConnector(process.cwd());
+            try {
+                const isResponsive = await client.isConnected(2000);
+                return isResponsive ? 'connected' : 'not_responsive';
+            }
+            finally {
+                await client.disconnect();
+            }
+        }
+        catch (error) {
+            if (error instanceof InstanceCrashedError)
+                return 'crashed';
+            if (error instanceof NoInstanceRunningError)
+                return 'no_instance';
+            return 'error';
+        }
+    }
+    /**
+     * Collect all status data into a structured object for JSON output.
+     */
+    async collectStatusData(cliVersion) {
+        const statusData = {
+            authStatus: 'unknown',
+            cliVersion,
+            contextTreeStatus: 'unknown',
+            currentDirectory: process.cwd(),
+            mcpStatus: 'no_instance',
+            projectInitialized: false,
+        };
+        // Auth status
+        try {
+            const token = await this.tokenStore.load();
+            if (token !== undefined && token.isValid()) {
+                statusData.authStatus = 'logged_in';
+                statusData.userEmail = token.userEmail;
+            }
+            else if (token === undefined) {
+                statusData.authStatus = 'not_logged_in';
+            }
+            else {
+                statusData.authStatus = 'expired';
+            }
+        }
+        catch {
+            statusData.authStatus = 'unknown';
+        }
+        // Project status
+        try {
+            const isInitialized = await this.projectConfigStore.exists();
+            statusData.projectInitialized = isInitialized;
+            if (isInitialized) {
+                const config = await this.projectConfigStore.read();
+                if (config) {
+                    statusData.teamName = config.teamName;
+                    statusData.spaceName = config.spaceName;
+                }
+            }
+        }
+        catch {
+            statusData.projectInitialized = false;
+        }
+        // MCP status
+        statusData.mcpStatus = await this.checkMcpStatusData();
+        // Context tree status
+        try {
+            const contextTreeExists = await this.contextTreeService.exists();
+            if (contextTreeExists) {
+                const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot();
+                if (!hasSnapshot) {
+                    await this.contextTreeSnapshotService.initEmptySnapshot();
+                }
+                const changes = await this.contextTreeSnapshotService.getChanges();
+                const hasChanges = changes.added.length > 0 || changes.modified.length > 0 || changes.deleted.length > 0;
+                if (hasChanges) {
+                    statusData.contextTreeStatus = 'has_changes';
+                    statusData.contextTreeChanges = {
+                        added: changes.added,
+                        deleted: changes.deleted,
+                        modified: changes.modified,
+                    };
+                }
+                else {
+                    statusData.contextTreeStatus = 'no_changes';
+                }
+            }
+            else {
+                statusData.contextTreeStatus = 'not_initialized';
+            }
+        }
+        catch {
+            statusData.contextTreeStatus = 'unknown';
+        }
+        await this.trackingService.track('mem:status');
+        return statusData;
+    }
+    /**
+     * Output status data as JSON.
+     */
+    outputJsonStatus(statusData) {
+        const response = {
+            command: 'status',
+            data: statusData,
+            success: true,
+            timestamp: new Date().toISOString(),
+        };
+        // Write directly to stdout for clean JSON output
+        if (this.terminal instanceof HeadlessTerminal) {
+            this.terminal.writeFinalResponse(response);
+        }
+        else {
+            // Fallback for non-headless terminal
+            this.terminal.log(JSON.stringify(response));
+        }
+    }
+    /**
+     * Original text format output.
+     */
+    async runTextFormat(cliVersion) {
+        this.terminal.log(`CLI Version: ${cliVersion}`);
+        try {
+            const token = await this.tokenStore.load();
+            if (token !== undefined && token.isValid()) {
+                this.terminal.log(`Status: Logged in as ${token.userEmail}`);
+            }
+            else if (token === undefined) {
+                this.terminal.log('Status: Not logged in');
+            }
+            else {
+                this.terminal.log('Status: Session expired (login required)');
+            }
+        }
+        catch (error) {
+            this.terminal.log('Status: Unable to check authentication status');
+            this.terminal.warn(`Warning: ${getErrorMessage(error)}`);
+        }
+        const cwd = process.cwd();
+        this.terminal.log(`Current Directory: ${cwd}`);
+        try {
+            const isInitialized = await this.projectConfigStore.exists();
+            if (isInitialized) {
+                const config = await this.projectConfigStore.read();
+                if (config) {
+                    this.terminal.log(`Project Status: Connected to ${config.teamName}/${config.spaceName}`);
+                }
+                else {
+                    this.terminal.log('Project Status: Configuration file exists but is invalid');
+                }
+            }
+            else {
+                this.terminal.log('Project Status: Not initialized');
+            }
+        }
+        catch (error) {
+            this.terminal.log('Project Status: Unable to read project configuration');
+            this.terminal.warn(`Warning: ${getErrorMessage(error)}`);
+        }
+        // MCP connection status
+        await this.checkMcpStatus();
+        // Context tree status
+        try {
+            const contextTreeExists = await this.contextTreeService.exists();
+            if (!contextTreeExists) {
+                this.terminal.log('Context Tree: Not initialized');
+                return;
+            }
+            const hasSnapshot = await this.contextTreeSnapshotService.hasSnapshot();
+            // Auto-create empty snapshot if none exists (all files will show as "added")
+            if (!hasSnapshot) {
+                await this.contextTreeSnapshotService.initEmptySnapshot();
+            }
+            const changes = await this.contextTreeSnapshotService.getChanges();
+            const hasChanges = changes.added.length > 0 || changes.modified.length > 0 || changes.deleted.length > 0;
+            if (!hasChanges) {
+                this.terminal.log('Context Tree: No changes');
+                return;
+            }
+            const contextTreeRelPath = join(BRV_DIR, CONTEXT_TREE_DIR);
+            const formatPath = (file) => join(contextTreeRelPath, file);
+            // Build unified list with status, sort by path ascending
+            const allChanges = [
+                ...changes.modified.map((f) => ({ color: chalk.red, path: f, status: 'modified:' })),
+                ...changes.added.map((f) => ({ color: chalk.red, path: f, status: 'new file:' })),
+                ...changes.deleted.map((f) => ({ color: chalk.red, path: f, status: 'deleted:' })),
+            ].sort((a, b) => a.path.localeCompare(b.path));
+            this.terminal.log('Context Tree Changes:');
+            for (const change of allChanges) {
+                this.terminal.log(`   ${change.color(`${change.status.padEnd(10)} ${formatPath(change.path)}`)}`);
+            }
+            // Track status
+            await this.trackingService.track('mem:status');
+        }
+        catch (error) {
+            this.terminal.log('Context Tree: Unable to check status');
+            this.terminal.warn(`Warning: ${error instanceof Error ? error.message : 'Context Tree unable to check status'}`);
+        }
+    }
+}

package/dist/server/infra/user/http-user-service.d.ts

@@ -0,0 +1,13 @@
+import type { IUserService, UpdateCurrentUserParams } from '../../core/interfaces/services/i-user-service.js';
+import { User } from '../../core/domain/entities/user.js';
+export type UserServiceConfig = {
+    apiBaseUrl: string;
+    timeout?: number;
+};
+export declare class HttpUserService implements IUserService {
+    private readonly config;
+    constructor(config: UserServiceConfig);
+    getCurrentUser(sessionKey: string): Promise<User>;
+    updateCurrentUser(sessionKey: string, params: UpdateCurrentUserParams): Promise<User>;
+    private mapToUser;
+}

package/dist/server/infra/user/http-user-service.js

@@ -0,0 +1,32 @@
+import { User } from '../../core/domain/entities/user.js';
+import { AuthenticatedHttpClient } from '../http/authenticated-http-client.js';
+export class HttpUserService {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            timeout: config.timeout ?? 10_000, // Default 10 seconds timeout
+        };
+    }
+    async getCurrentUser(sessionKey) {
+        // IMPORTANT: Do not try-catch here - let callers handle errors (e.g., distinguish 401 from network errors)
+        const httpClient = new AuthenticatedHttpClient(sessionKey);
+        const response = await httpClient.get(`${this.config.apiBaseUrl}/user/me`, {
+            timeout: this.config.timeout,
+        });
+        return this.mapToUser(response.data);
+    }
+    async updateCurrentUser(sessionKey, params) {
+        const httpClient = new AuthenticatedHttpClient(sessionKey);
+        const response = await httpClient.put(`${this.config.apiBaseUrl}/user/me`, { hasOnboardedCli: params.hasOnboardedCli }, { timeout: this.config.timeout });
+        return this.mapToUser(response.data);
+    }
+    mapToUser(userData) {
+        return new User({
+            email: userData.email,
+            hasOnboardedCli: userData.hasOnboardedCli,
+            id: userData.id,
+            name: userData.name,
+        });
+    }
+}

package/dist/server/infra/workspace/workspace-detector-service.d.ts

@@ -0,0 +1,57 @@
+import type { Agent } from '../../core/domain/entities/agent.js';
+import type { IWorkspaceDetectorService, WorkspaceInfo } from '../../core/interfaces/services/i-workspace-detector-service.js';
+/**
+ * Service to detect IDE workspaces that contain the current working directory
+ * Supports: VS Code (Github Copilot), Cursor, Claude, and Codex
+ */
+export declare class WorkspaceDetectorService implements IWorkspaceDetectorService {
+    private readonly claudeUserPath;
+    private readonly codexUserPath;
+    private readonly cursorUserPath;
+    private readonly cwd;
+    private readonly vscodeUserPath;
+    constructor(cwd?: string);
+    /**
+     * Detect workspaces for the given IDE
+     *
+     * Supports: Github Copilot (VSCode), Cursor, Claude Code, Codex
+     *
+     * chatLogPath:
+     *   - For Cursor/VSCode: Path to workspace storage folder if workspace.json matches cwd
+     *   - For Claude Code: Path to claude project folder matching cwd (with special naming pattern)
+     *   - For Codex: Direct path to codex sessions folder
+     */
+    detectWorkspaces(agent: Agent): WorkspaceInfo;
+    /**
+     * Convert current working directory to Claude Code folder name format
+     * Example: /Users/datpham/dpmemories/byterover-cli -> -Users-datpham-dpmemories-byterover-cli
+     */
+    private cwdToClaudeFolderName;
+    /**
+     * Detect Claude Code workspaces
+     * Claude Code stores projects in ~/.claude/projects with folder names like "-Users-datpham-dpmemories-byterover-cli"
+     * These folder names are derived from the project path with slashes replaced by dashes
+     */
+    private detectClaudeWorkspaces;
+    /**
+     * Detect Codex workspaces
+     * Codex uses a single sessions folder
+     */
+    private detectCodexWorkspaces;
+    /**
+     * Detect Cursor workspaces
+     */
+    private detectCursorWorkspaces;
+    /**
+     * Detect VSCode workspaces (Github Copilot)
+     */
+    private detectVSCodeWorkspaces;
+    /**
+     * Detect workspaces using workspace.json file (VSCode, Cursor)
+     */
+    private detectWorkspacesByFile;
+    /**
+     * Check if current working directory is within the given workspace folder
+     */
+    private isCurrentDirInWorkspace;
+}

package/dist/server/templates/sections/brv-instructions.md

@@ -0,0 +1,104 @@
+> **⚠️ STOP: Before responding, check if this is a code task.**
+> Code task? → `brv query` FIRST. Wrote code? → `brv curate` BEFORE done.
+
+---
+
+# ByteRover Memory System - MANDATORY
+
+**Note: These rules apply regardless of language. Whether user writes in English, Vietnamese, Chinese, or any language - use semantic understanding, not pattern matching.**
+
+## Decision: When to Query Memory
+
+**PRIMARY RULE - ASK YOURSELF: "Will this task require understanding or modifying THIS codebase?"**
+
+| Answer | Action |
+|--------|--------|
+| **YES** - need to understand/modify codebase | `brv query` FIRST |
+| **NO** - general knowledge, meta tasks, follow-up | Skip query |
+
+**You MUST run `brv query` when task involves:**
+- Writing, editing, deleting, or modifying code in this project
+- Understanding how something works in this codebase
+- Debugging, fixing, or troubleshooting issues
+- Finding where something is located
+- Any architectural or design decisions
+
+Example patterns (ANY language): add, create, build, fix, debug, refactor, update, implement, change, modify, delete, remove, optimize, move, rename, test, "how does X work", "where is X", "explain X in codebase"
+
+**You MUST NOT query when:**
+- General programming concepts (not codebase-specific)
+- Meta tasks: "run tests", "build project", "commit changes", "create PR"
+- Simple clarifications about your previous response (not involving code)
+
+Example patterns: "what is a Promise", "explain async/await", "what do you mean", "which file", "run the tests", "commit this"
+
+**⚠️ CRITICAL - LONG CONVERSATIONS:**
+Even after 10, 50, or 100 prompts in the same conversation - if a NEW code task comes up, you MUST query again. Do NOT skip query just because you queried earlier. Each distinct code task = new query.
+
+```bash
+brv query "What do I need to know about [relevant topic]?"
+```
+
+## Decision: When to Curate
+
+**ASK YOURSELF: "Did I learn or create something valuable for future work?"**
+
+| Answer | Action |
+|--------|--------|
+| **YES** - wrote code, found patterns, made decisions | `brv curate` BEFORE done |
+| **NO** - just answered a question, no new insights | Skip curate |
+
+**MUST curate when you:**
+- Wrote or modified any code
+- Discovered how something works
+- Made architectural/design decisions
+- Found a bug root cause or fix pattern
+
+```bash
+# CONTEXT argument MUST come BEFORE flags
+# Max 5 files per curate with -f flag
+brv curate "Specific insight with details" -f path/to/file.ts
+brv curate "Multi-file insight" -f file1.ts -f file2.ts
+
+# For folder pack (analyze entire folder), use -d or --folder flag
+brv curate "Analyze this module" -d path/to/folder/
+brv curate --folder src/auth/  # folder-only mode
+```
+
+**GOOD:** `brv curate "Auth uses JWT 24h expiry, refresh in httpOnly cookies" -f src/auth.ts`
+**GOOD:** `brv curate "Analyze auth module" -d src/auth/`
+**BAD:** `brv curate "Fixed auth"` (too vague), `brv curate -f file.ts "text"` (wrong order)
+**BAD:** `brv curate -folder src/` (use `-d` or `--folder`, NOT `-folder`)
+
+**⚠️ CRITICAL - LONG CONVERSATIONS:**
+If you modify code 10 times in a conversation, curate 10 times. Do NOT batch or skip. Each code change = immediate curate before moving on.
+
+## Quick Reference Table
+
+| Task Type | Query? | Curate? |
+|-----------|--------|---------|
+| Add/create/implement feature | **MUST** | **MUST** |
+| Fix/debug/resolve bug | **MUST** | **MUST** |
+| Refactor/optimize/move code | **MUST** | **MUST** |
+| Delete/remove functionality | **MUST** | **MUST** |
+| Write/add tests | **MUST** | **MUST** |
+| "How does X work?" (codebase) | **MUST** | Only if insights |
+| "Where is X?" (codebase) | **MUST** | NO |
+| General concept (Promise, async) | NO | NO |
+| Meta task (run tests, build) | NO | NO |
+| Git task (commit, PR, push) | NO | NO |
+| Follow-up code task in same conversation | **MUST** | **MUST** |
+| Clarification ("which file?") | NO | NO |
+
+## WORKFLOW
+
+```
+Code task received → brv query FIRST → Work → brv curate → Done
+Non-code task → Just respond normally
+```
+
+---
+
+> **⚠️ REMINDER: Don't forget!**
+> - `brv query` → BEFORE starting code task
+> - `brv curate` → AFTER each code change (don't batch!)

package/dist/server/utils/environment-detector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Check if running in WSL environment (cached).
+ * Detects both WSL1 and WSL2. Result is cached after first call for performance.
+ */
+export declare function isWsl(): boolean;
+/**
+ * Check if running in headless Linux environment (cached).
+ * Result is cached after first call for performance.
+ */
+export declare function isHeadlessLinux(): boolean;
+/**
+ * Determine if file-based token storage should be used.
+ * Returns true for WSL or headless Linux environments where keychain is unavailable.
+ */
+export declare function shouldUseFileTokenStore(): boolean;
+/**
+ * Reset cached values (for testing only).
+ * @internal
+ */
+export declare function _resetCaches(): void;