byterover-cli 3.0.1 → 3.2.0

package/dist/oclif/commands/status.js

@@ -1,6 +1,6 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
-import { StatusEvents } from '../../shared/transport/events/status-events.js';
+import { StatusEvents, } from '../../shared/transport/events/status-events.js';
 import { formatConnectionError, withDaemonRetry } from '../lib/daemon-client.js';
 import { writeJsonResponse } from '../lib/json-response.js';
 export default class Status extends Command {
@@ -13,18 +13,29 @@ export default class Status extends Command {
             description: 'Output format',
             options: ['text', 'json'],
         }),
+        'project-root': Flags.string({
+            description: 'Explicit project root path (overrides auto-detection)',
+            required: false,
+        }),
+        verbose: Flags.boolean({
+            char: 'v',
+            default: false,
+            description: 'Show resolution source and diagnostic info',
+        }),
     };
     async fetchStatus(options) {
+        const request = { cwd: process.cwd(), projectRootFlag: options?.projectRootFlag };
         return withDaemonRetry(async (client) => {
-            const response = await client.requestWithAck(StatusEvents.GET);
+            const response = await client.requestWithAck(StatusEvents.GET, request);
             return response.status;
         }, options);
     }
     async run() {
         const { flags } = await this.parse(Status);
+        const projectRootFlag = flags['project-root'];
         const isJson = flags.format === 'json';
         try {
-            const status = await this.fetchStatus({ projectPath: process.cwd() });
+            const status = await this.fetchStatus({ projectPath: process.cwd(), projectRootFlag });
             if (isJson) {
                 writeJsonResponse({
                     command: 'status',
@@ -33,7 +44,7 @@ export default class Status extends Command {
                 });
             }
             else {
-                this.formatTextOutput(status);
+                this.formatTextOutput(status, flags.verbose);
                 this.logVcHint();
             }
         }
@@ -51,7 +62,7 @@ export default class Status extends Command {
             }
         }
     }
-    formatTextOutput(status) {
+    formatTextOutput(status, verbose = false) {
         this.log(`CLI Version: ${this.config.version}`);
         // Auth status (cloud sync only — not required for local usage)
         switch (status.authStatus) {
@@ -71,7 +82,31 @@ export default class Status extends Command {
                 this.log('Account: Unable to check');
             }
         }
-        this.log(`Current Directory: ${status.currentDirectory}`);
+        this.log(`Project: ${status.projectRoot ?? status.currentDirectory}`);
+        if (status.worktreeRoot && status.worktreeRoot !== status.projectRoot) {
+            this.log(`Worktree: ${status.worktreeRoot} (linked)`);
+        }
+        if (status.resolverError) {
+            this.log(chalk.yellow(`⚠ ${status.resolverError}`));
+        }
+        if (verbose && status.resolutionSource) {
+            this.log(`Resolution: ${status.resolutionSource}`);
+        }
+        // Knowledge sources
+        if (status.sourcesError) {
+            this.log(chalk.yellow(`⚠ ${status.sourcesError}`));
+        }
+        else if (status.sources && status.sources.length > 0) {
+            this.log('Knowledge Sources:');
+            for (const source of status.sources) {
+                if (source.valid) {
+                    this.log(`   ${source.alias} → ${source.projectRoot} ${chalk.green('(valid)')}`);
+                }
+                else {
+                    this.log(`   ${source.alias} → ${source.projectRoot} ${chalk.red(`[BROKEN - run brv source remove ${source.alias}]`)}`);
+                }
+            }
+        }
         // Space
         if (status.teamName && status.spaceName) {
             this.log(`Space: ${status.teamName}/${status.spaceName}`);

package/dist/oclif/commands/worktree/add.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class WorktreeAdd extends Command {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/oclif/commands/worktree/add.js

@@ -0,0 +1,44 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { resolve } from 'node:path';
+import { WorktreeEvents } from '../../../shared/transport/events/worktree-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class WorktreeAdd extends Command {
+    static args = {
+        path: Args.string({
+            description: 'Path to the directory to register as a worktree (relative or absolute)',
+            required: false,
+        }),
+    };
+    static description = 'Register a directory as a worktree of this project';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> packages/api',
+        '<%= config.bin %> <%= command.id %> ../other-checkout',
+        '<%= config.bin %> <%= command.id %>  (auto-detect parent from subdirectory)',
+    ];
+    static flags = {
+        force: Flags.boolean({
+            default: false,
+            description: 'Replace existing .brv/ directory in target with a worktree pointer',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorktreeAdd);
+        const cwd = resolve(process.cwd());
+        const worktreePath = args.path ? resolve(args.path) : cwd;
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(WorktreeEvents.ADD, {
+                force: flags.force,
+                worktreePath,
+            }), { projectPath: cwd });
+            if (result.success) {
+                this.log(result.message);
+            }
+            else {
+                this.error(result.message, { exit: 1 });
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}

package/dist/oclif/commands/worktree/index.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@oclif/core';
+export default class Worktree extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/oclif/commands/worktree/index.js

@@ -0,0 +1,8 @@
+import { Command } from '@oclif/core';
+export default class Worktree extends Command {
+    static description = 'Manage worktree links for subdirectories and sibling checkouts';
+    static examples = ['<%= config.bin %> <%= command.id %> --help'];
+    async run() {
+        await this.config.runCommand('help', ['worktree']);
+    }
+}

package/dist/oclif/commands/worktree/list.d.ts

@@ -0,0 +1,6 @@
+import { Command } from '@oclif/core';
+export default class WorktreeList extends Command {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/oclif/commands/worktree/list.js

@@ -0,0 +1,28 @@
+import { Command } from '@oclif/core';
+import { WorktreeEvents } from '../../../shared/transport/events/worktree-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class WorktreeList extends Command {
+    static description = 'Show the current worktree link and list all registered worktrees';
+    static examples = ['<%= config.bin %> <%= command.id %>'];
+    async run() {
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(WorktreeEvents.LIST), { projectPath: process.cwd() });
+            if (result.source === 'linked') {
+                this.log(`Worktree: ${result.worktreeRoot}`);
+                this.log(`Linked to: ${result.projectRoot}`);
+            }
+            else {
+                this.log(`Project: ${result.projectRoot}`);
+            }
+            if (result.worktrees.length > 0) {
+                this.log('\nRegistered worktrees:');
+                for (const wt of result.worktrees) {
+                    this.log(`   ${wt.name} → ${wt.worktreePath}`);
+                }
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}

package/dist/oclif/commands/worktree/remove.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class WorktreeRemove extends Command {
+    static args: {
+        path: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/oclif/commands/worktree/remove.js

@@ -0,0 +1,35 @@
+import { Args, Command } from '@oclif/core';
+import { resolve } from 'node:path';
+import { WorktreeEvents } from '../../../shared/transport/events/worktree-events.js';
+import { formatConnectionError, withDaemonRetry } from '../../lib/daemon-client.js';
+export default class WorktreeRemove extends Command {
+    static args = {
+        path: Args.string({
+            description: 'Path to the worktree to remove (defaults to cwd)',
+            required: false,
+        }),
+    };
+    static description = 'Remove a worktree registration and its .brv pointer';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>  (remove cwd as worktree)',
+        '<%= config.bin %> <%= command.id %> packages/api  (remove from parent)',
+    ];
+    async run() {
+        const { args } = await this.parse(WorktreeRemove);
+        const targetPath = args.path ? resolve(args.path) : resolve(process.cwd());
+        try {
+            const result = await withDaemonRetry(async (client) => client.requestWithAck(WorktreeEvents.REMOVE, {
+                worktreePath: targetPath,
+            }), { projectPath: process.cwd() });
+            if (result.success) {
+                this.log(result.message);
+            }
+            else {
+                this.error(result.message, { exit: 1 });
+            }
+        }
+        catch (error) {
+            this.error(formatConnectionError(error), { exit: 1 });
+        }
+    }
+}

package/dist/oclif/hooks/init/validate-brv-config.js

@@ -2,6 +2,7 @@ import { BRV_CONFIG_VERSION } from '../../../server/constants.js';
 import { ensureProjectInitialized } from '../../../server/infra/config/auto-init.js';
 import { ProjectConfigStore } from '../../../server/infra/config/file-config-store.js';
 import { FileContextTreeService } from '../../../server/infra/context-tree/file-context-tree-service.js';
+import { isWorktreePointer } from '../../../server/infra/project/resolve-project.js';
 import { syncConfigToXdg } from '../../../server/utils/config-xdg-sync.js';
 /**
  * Commands that should skip auto-init and config version validation.
@@ -22,6 +23,9 @@ const HELP_FLAGS = new Set(['--h', '--help', '-h', '-help']);
 export const validateBrvConfigVersion = async (commandId, configStore, argv = [], autoInitDeps) => {
     if (argv.some((arg) => HELP_FLAGS.has(arg)))
         return;
+    // Skip auto-init if .brv is a pointer file (worktree) — the project lives elsewhere
+    if (isWorktreePointer(process.cwd()))
+        return;
     const exists = await configStore.exists();
     if (!exists && COMMANDS_NEED_AUTO_INIT.has(commandId)) {
         const deps = autoInitDeps ?? {

package/dist/oclif/lib/daemon-client.d.ts

@@ -5,6 +5,8 @@ export interface DaemonClientOptions {
     maxRetries?: number;
     /** Explicit project path — bypasses walk-up discovery. Use for `init` where .brv/ doesn't exist yet. */
     projectPath?: string;
+    /** Explicit --project-root flag value to override auto-detection */
+    projectRootFlag?: string;
     /** Delay between retries in ms. Default: 2000. Set to 0 in tests. */
     retryDelayMs?: number;
     /** Optional transport connector for DI/testing */
@@ -13,14 +15,14 @@ export interface DaemonClientOptions {
 /**
  * Connects to the daemon, auto-starting it if needed.
  */
-export declare function connectToDaemonClient(options?: Pick<DaemonClientOptions, 'transportConnector'>): Promise<ConnectionResult>;
+export declare function connectToDaemonClient(options?: Pick<DaemonClientOptions, 'projectRootFlag' | 'transportConnector'>): Promise<ConnectionResult>;
 /**
  * Executes an operation against the daemon with retry logic.
  *
  * Retries on infrastructure failures (daemon spawn timeout, connection dropped,
  * agent disconnected). Does NOT retry on business errors (auth, validation, etc.).
  */
-export declare function withDaemonRetry<T>(fn: (client: ITransportClient, projectRoot?: string) => Promise<T>, options?: DaemonClientOptions & {
+export declare function withDaemonRetry<T>(fn: (client: ITransportClient, projectRoot?: string, worktreeRoot?: string) => Promise<T>, options?: DaemonClientOptions & {
     /** Called before each retry with attempt number (1-indexed) */
     onRetry?: (attempt: number, maxRetries: number) => void;
 }): Promise<T>;

package/dist/oclif/lib/daemon-client.js

@@ -1,5 +1,6 @@
 import { ConnectionError, ConnectionFailedError, DaemonSpawnError, InstanceCrashedError, NoInstanceRunningError, TransportRequestError, TransportRequestTimeoutError, } from '@campfirein/brv-transport-client';
 import { TaskErrorCode } from '../../server/core/domain/errors/task-error.js';
+import { resolveProject } from '../../server/infra/project/resolve-project.js';
 import { createDaemonAwareConnector } from '../../server/infra/transport/transport-connector.js';
 import { getSandboxEnvironmentName, isSandboxEnvironment, isSandboxNetworkError, } from '../../server/utils/sandbox-detector.js';
 import { VcErrorCode } from '../../shared/transport/events/vc-events.js';
@@ -34,12 +35,22 @@ const USER_FRIENDLY_MESSAGES = {
     // UNCOMMITTED_CHANGES intentionally omitted: fall through to server's detailed message with file paths
     // USER_NOT_CONFIGURED intentionally omitted: fall through to server's specific hint with actual values
 };
+function resolveRequiredProjectPath(projectRootFlag) {
+    const resolution = resolveProject({ projectRootFlag });
+    if (!resolution) {
+        // No .brv found at cwd — fall back to cwd. The daemon will auto-init .brv/ on first connection.
+        const cwd = process.cwd();
+        return { projectRoot: cwd, worktreeRoot: cwd };
+    }
+    return resolution;
+}
 /**
  * Connects to the daemon, auto-starting it if needed.
  */
 export async function connectToDaemonClient(options) {
     const connector = options?.transportConnector ?? createDaemonAwareConnector();
-    return connector();
+    const resolution = resolveRequiredProjectPath(options?.projectRootFlag);
+    return connector(undefined, resolution.projectRoot);
 }
 /**
  * Executes an operation against the daemon with retry logic.
@@ -51,14 +62,19 @@ export async function withDaemonRetry(fn, options) {
     const maxRetries = options?.maxRetries ?? MAX_RETRIES;
     const retryDelayMs = options?.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
     const connector = options?.transportConnector ?? createDaemonAwareConnector(options?.projectPath);
+    // Pre-resolve project (workspace-link-aware) so the connector registers
+    // with the correct projectPath and callers get the resolved worktreeRoot.
+    const resolution = resolveRequiredProjectPath(options?.projectRootFlag);
+    const resolvedProjectPath = resolution.projectRoot;
+    const resolvedWorkspaceRoot = resolution.worktreeRoot;
     let lastError;
     /* eslint-disable no-await-in-loop -- intentional sequential retry loop */
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
         let client;
         try {
-            const { client: connectedClient, projectRoot } = await connector();
+            const { client: connectedClient, projectRoot } = await connector(undefined, resolvedProjectPath);
             client = connectedClient;
-            const value = await fn(client, projectRoot);
+            const value = await fn(client, projectRoot ?? resolvedProjectPath, resolvedWorkspaceRoot);
             await client.disconnect().catch(() => { });
             return value;
         }

package/dist/server/constants.d.ts

@@ -1,6 +1,12 @@
 export declare const BRV_DIR = ".brv";
 export declare const PROJECT_CONFIG_FILE = "config.json";
 export declare const BRV_CONFIG_VERSION = "0.0.1";
+export declare const WORKTREES_DIR = "worktrees";
+export declare const WORKTREE_LINK_METADATA = "link.json";
+export declare const SOURCES_FILE = "sources.json";
+export declare const SHARED_SOURCE_LOCAL_SCORE_BOOST = 0.1;
+export declare const MCP_ASSOCIATE_PROJECT_TIMEOUT_MS = 3000;
+export declare const MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS = 2;
 export declare const GLOBAL_CONFIG_DIR = "brv";
 export declare const GLOBAL_CONFIG_FILE = "config.json";
 export declare const GLOBAL_CONFIG_VERSION = "0.0.1";
@@ -55,6 +61,8 @@ export declare const SUMMARY_INDEX_FILE = "_index.md";
 export declare const ARCHIVE_DIR = "_archived";
 export declare const STUB_EXTENSION = ".stub.md";
 export declare const FULL_ARCHIVE_EXTENSION = ".full.md";
+export declare const ABSTRACT_EXTENSION = ".abstract.md";
+export declare const OVERVIEW_EXTENSION = ".overview.md";
 export declare const MANIFEST_FILE = "_manifest.json";
 export declare const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export declare const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;

package/dist/server/constants.js

@@ -1,6 +1,14 @@
 export const BRV_DIR = '.brv';
 export const PROJECT_CONFIG_FILE = 'config.json';
 export const BRV_CONFIG_VERSION = '0.0.1';
+// Worktree linking (git-style: .brv is a file pointing to parent project)
+export const WORKTREES_DIR = 'worktrees';
+export const WORKTREE_LINK_METADATA = 'link.json';
+// Knowledge sources (read-only references to other projects)
+export const SOURCES_FILE = 'sources.json';
+export const SHARED_SOURCE_LOCAL_SCORE_BOOST = 0.1;
+export const MCP_ASSOCIATE_PROJECT_TIMEOUT_MS = 3000;
+export const MCP_ASSOCIATE_PROJECT_MAX_ATTEMPTS = 2;
 // Global config constants (user-level, stored in XDG config directory)
 export const GLOBAL_CONFIG_DIR = 'brv';
 export const GLOBAL_CONFIG_FILE = 'config.json';
@@ -75,6 +83,8 @@ export const SUMMARY_INDEX_FILE = '_index.md';
 export const ARCHIVE_DIR = '_archived';
 export const STUB_EXTENSION = '.stub.md';
 export const FULL_ARCHIVE_EXTENSION = '.full.md';
+export const ABSTRACT_EXTENSION = '.abstract.md';
+export const OVERVIEW_EXTENSION = '.overview.md';
 export const MANIFEST_FILE = '_manifest.json';
 export const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;

package/dist/server/core/domain/client/client-info.d.ts

@@ -78,5 +78,12 @@ export declare class ClientInfo {
      * Called after MCP initialize handshake provides clientInfo.
      */
     setAgentName(agentName: string): void;
+    /**
+     * Update this client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     *
+     * @returns The previous project path (undefined if not previously associated)
+     */
+    updateProjectPath(projectPath: string): string | undefined;
 }
 export {};

package/dist/server/core/domain/client/client-info.js

@@ -84,4 +84,15 @@ export class ClientInfo {
     setAgentName(agentName) {
         this._agentName = agentName;
     }
+    /**
+     * Update this client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     *
+     * @returns The previous project path (undefined if not previously associated)
+     */
+    updateProjectPath(projectPath) {
+        const oldPath = this._projectPath;
+        this._projectPath = projectPath;
+        return oldPath;
+    }
 }

package/dist/server/core/domain/knowledge/memory-scoring.d.ts

@@ -19,11 +19,11 @@ export declare const ACCESS_IMPORTANCE_BONUS = 3;
 /** Importance bonus per curate update */
 export declare const UPDATE_IMPORTANCE_BONUS = 5;
 /** BM25 relevance weight in compound score */
-export declare const W_RELEVANCE = 1;
+export declare const W_RELEVANCE = 0.6;
 /** Importance weight in compound score */
-export declare const W_IMPORTANCE = 0;
+export declare const W_IMPORTANCE = 0.2;
 /** Recency weight in compound score */
-export declare const W_RECENCY = 0;
+export declare const W_RECENCY = 0.2;
 /** Importance threshold to promote draft -> validated */
 export declare const PROMOTE_TO_VALIDATED = 65;
 /** Importance threshold to promote validated -> core */

package/dist/server/core/domain/knowledge/memory-scoring.js

@@ -21,11 +21,11 @@ export const ACCESS_IMPORTANCE_BONUS = 3;
 /** Importance bonus per curate update */
 export const UPDATE_IMPORTANCE_BONUS = 5;
 /** BM25 relevance weight in compound score */
-export const W_RELEVANCE = 1;
+export const W_RELEVANCE = 0.6;
 /** Importance weight in compound score */
-export const W_IMPORTANCE = 0;
+export const W_IMPORTANCE = 0.2;
 /** Recency weight in compound score */
-export const W_RECENCY = 0;
+export const W_RECENCY = 0.2;
 /** Importance threshold to promote draft -> validated */
 export const PROMOTE_TO_VALIDATED = 65;
 /** Importance threshold to promote validated -> core */
@@ -36,8 +36,8 @@ export const DEMOTE_FROM_CORE = 60;
 export const DEMOTE_FROM_VALIDATED = 35;
 /** Search score multiplier per maturity tier */
 export const TIER_BOOST = {
-    core: 1,
-    draft: 1,
+    core: 1.15,
+    draft: 0.85,
     validated: 1,
 };
 // ---------------------------------------------------------------------------

package/dist/server/core/domain/knowledge/summary-types.d.ts

@@ -41,6 +41,10 @@ export interface ArchiveStubFrontmatter {
     type: 'archive_stub';
 }
 export interface ManifestEntry {
+    /** Relative path to .abstract.md sibling, if it exists */
+    abstractPath?: string;
+    /** Token count of .abstract.md (used for lane budgeting) */
+    abstractTokens?: number;
     /** Importance score from frontmatter (0-100, default 50) */
     importance?: number;
     /** Condensation order (only for summaries) */

package/dist/server/core/domain/project/worktrees-schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Schema for the `.brv` pointer file (when .brv is a FILE, not a directory).
+ * Like git's `.git` file in worktrees: contains a single `projectRoot` field
+ * pointing to the parent project's absolute path.
+ */
+export declare const WorktreePointerSchema: z.ZodObject<{
+    projectRoot: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectRoot: string;
+}, {
+    projectRoot: string;
+}>;
+export type WorktreePointer = z.infer<typeof WorktreePointerSchema>;
+/**
+ * Schema for `.brv/worktrees/<name>/link.json` — metadata about a registered worktree.
+ * Stored in the parent project's `.brv/worktrees/` directory (like `.git/worktrees/`).
+ */
+export declare const WorktreeLinkMetadataSchema: z.ZodObject<{
+    addedAt: z.ZodOptional<z.ZodString>;
+    worktreePath: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    worktreePath: string;
+    addedAt?: string | undefined;
+}, {
+    worktreePath: string;
+    addedAt?: string | undefined;
+}>;
+export type WorktreeLinkMetadata = z.infer<typeof WorktreeLinkMetadataSchema>;

package/dist/server/core/domain/project/worktrees-schema.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * Schema for the `.brv` pointer file (when .brv is a FILE, not a directory).
+ * Like git's `.git` file in worktrees: contains a single `projectRoot` field
+ * pointing to the parent project's absolute path.
+ */
+export const WorktreePointerSchema = z.object({
+    projectRoot: z.string().min(1),
+});
+/**
+ * Schema for `.brv/worktrees/<name>/link.json` — metadata about a registered worktree.
+ * Stored in the parent project's `.brv/worktrees/` directory (like `.git/worktrees/`).
+ */
+export const WorktreeLinkMetadataSchema = z.object({
+    addedAt: z.string().optional(),
+    worktreePath: z.string().min(1),
+});

package/dist/server/core/domain/source/source-operations.d.ts

@@ -0,0 +1,31 @@
+import { type SourceStatus } from './source-schema.js';
+export interface OperationResult {
+    message: string;
+    success: boolean;
+}
+/**
+ * Adds a read-only knowledge source from another project's context tree.
+ *
+ * Validates: target is a brv project, not self, not duplicate, not circular.
+ * Writes to `.brv/sources.json`.
+ */
+export declare function addSource(projectRoot: string, targetPath: string, alias?: string): OperationResult;
+/**
+ * Removes a knowledge source by alias or path.
+ */
+export declare function removeSource(projectRoot: string, aliasOrPath: string): OperationResult;
+export interface ListSourcesResult {
+    error?: string;
+    statuses: SourceStatus[];
+}
+/**
+ * Returns status for all sources in the project.
+ * Surfaces malformed file errors instead of silently returning empty.
+ */
+export declare function listSourceStatuses(projectRoot: string): ListSourcesResult;
+/**
+ * Checks if adding projectRoot → targetRoot would create a circular dependency.
+ * A circular reference exists if the target project already has a source pointing
+ * back to the current project (direct cycle only — no transitive check in v1).
+ */
+export declare function detectCircularSource(projectRoot: string, targetRoot: string): boolean;