brainclaw 0.19.14 → 0.21.0

package/dist/core/setup-flow.js

@@ -0,0 +1,191 @@
+/**
+ * Setup flow logic for the new onboarding experience.
+ *
+ * Two modes:
+ * - Quick: init the current repo (1-2 MCP calls)
+ * - Batch: scan roots and init multiple repos (legacy 4-step flow)
+ *
+ * Quick flow:
+ *   1. Auto-detect repo, agent, nearby stores → ask project type + topology
+ *   2. Init + optional bootstrap → done
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryExists } from './io.js';
+import { detectAiAgent } from './ai-agent-detection.js';
+import { resolveStoreChain } from './store-resolution.js';
+import { analyzeRepository } from './repo-analysis.js';
+import { getAgentCapabilityProfile, getAllAgentCapabilityProfiles } from './agent-capability.js';
+import { describeAgentSurfaces } from './agent-capability.js';
+import { loadState } from './state.js';
+/**
+ * Probe the current working directory to understand what we're working with.
+ * This is the first step of the quick setup flow — no questions yet, just detection.
+ */
+export function probeForQuickSetup(cwd = process.cwd()) {
+    const isGitRepo = fs.existsSync(path.join(cwd, '.git'));
+    const alreadyInitialized = memoryExists(cwd);
+    const repoName = path.basename(cwd);
+    // Detect agent
+    const detectedAi = detectAiAgent();
+    const detectedAgent = detectedAi
+        ? { name: detectedAi.name, profile: getAgentCapabilityProfile(detectedAi.name) }
+        : undefined;
+    // Find other known agent profiles (for info)
+    const otherAgents = detectedAgent
+        ? getAllAgentCapabilityProfiles().filter((p) => p.name !== detectedAgent.name)
+        : getAllAgentCapabilityProfiles();
+    // Scan nearby stores
+    const nearbyStores = resolveStoreChain(cwd);
+    // Has content?
+    const IGNORED = new Set(['.git', '.brainclaw', '.gitignore', '.gitattributes', '.DS_Store', 'Thumbs.db']);
+    let hasContent = false;
+    try {
+        const entries = fs.readdirSync(cwd);
+        hasContent = entries.some((e) => !IGNORED.has(e));
+    }
+    catch {
+        // empty or unreadable
+    }
+    // Analyze repo for project type suggestion
+    let suggestedProjectType = 'standalone';
+    let analysisReasons = [];
+    try {
+        const analysis = analyzeRepository(cwd);
+        if (analysis.recommendedMode === 'multi-project') {
+            suggestedProjectType = 'workspace';
+        }
+        analysisReasons = analysis.reasons;
+    }
+    catch {
+        // analysis failed — default to standalone
+    }
+    // If there are nearby stores, suggest linking
+    const parentStores = nearbyStores.filter((s) => s.depth > 0 && s.role === 'workspace');
+    if (parentStores.length > 0 && !alreadyInitialized) {
+        suggestedProjectType = 'linked';
+    }
+    // Build repo summary
+    const summaryParts = [];
+    if (isGitRepo)
+        summaryParts.push('git repo');
+    if (hasContent)
+        summaryParts.push(`"${repoName}"`);
+    if (analysisReasons.length > 0)
+        summaryParts.push(analysisReasons[0]);
+    const repoSummary = summaryParts.join(', ') || 'empty directory';
+    return {
+        cwd,
+        isGitRepo,
+        alreadyInitialized,
+        repoName,
+        repoSummary,
+        detectedAgent,
+        otherAgents,
+        nearbyStores,
+        hasContent,
+        suggestedProjectType,
+        analysisReasons,
+    };
+}
+/**
+ * Build the structured response for the initial probe step of quick setup.
+ * Returns data the agent can use to present choices to the user.
+ */
+export function buildQuickSetupProbeResponse(probe) {
+    const lines = [];
+    if (probe.alreadyInitialized) {
+        lines.push(`This project (${probe.repoName}) is already initialized with brainclaw.`);
+        lines.push('Use `brainclaw export --detect --write` to regenerate agent files, or `brainclaw upgrade` to migrate.');
+        return {
+            text: lines.join('\n'),
+            structured: {
+                already_initialized: true,
+                cwd: probe.cwd,
+                repo_name: probe.repoName,
+            },
+        };
+    }
+    lines.push(`Detected: ${probe.repoSummary}`);
+    if (probe.detectedAgent) {
+        lines.push(`Agent: ${probe.detectedAgent.name} (${probe.detectedAgent.profile.templateTier === 'A' ? 'full integration' : probe.detectedAgent.profile.templateTier === 'B' ? 'standard integration' : 'limited integration'})`);
+        lines.push(`Surfaces: ${describeAgentSurfaces(probe.detectedAgent.name).join(', ')}`);
+    }
+    if (probe.nearbyStores.length > 0) {
+        lines.push('');
+        lines.push('Nearby brainclaw stores:');
+        for (const store of probe.nearbyStores) {
+            lines.push(`  - ${store.role} at ${store.cwd} (depth ${store.depth})`);
+        }
+    }
+    lines.push('');
+    lines.push('Ask the user:');
+    lines.push('');
+    lines.push('1. What kind of project is this?');
+    lines.push(`   - Standalone project (single .brainclaw/ for the whole repo)${probe.suggestedProjectType === 'standalone' ? ' ← suggested' : ''}`);
+    lines.push(`   - Workspace with sub-projects (monorepo)${probe.suggestedProjectType === 'workspace' ? ' ← suggested' : ''}`);
+    if (probe.nearbyStores.some((s) => s.role === 'workspace')) {
+        lines.push(`   - Linked to an existing workspace${probe.suggestedProjectType === 'linked' ? ' ← suggested' : ''}`);
+    }
+    lines.push('');
+    lines.push('2. Should the memory be shared with the team?');
+    lines.push('   - Yes, shared via git (.brainclaw/ tracked in git) ← recommended');
+    lines.push('   - No, local only (.brainclaw/ gitignored)');
+    return {
+        text: lines.join('\n'),
+        structured: {
+            pending_question: 'quick_init',
+            probe: {
+                cwd: probe.cwd,
+                repo_name: probe.repoName,
+                repo_summary: probe.repoSummary,
+                is_git_repo: probe.isGitRepo,
+                has_content: probe.hasContent,
+                detected_agent: probe.detectedAgent?.name ?? null,
+                agent_surfaces: probe.detectedAgent ? describeAgentSurfaces(probe.detectedAgent.name) : [],
+                nearby_stores: probe.nearbyStores.map((s) => ({ role: s.role, path: s.cwd, depth: s.depth })),
+                suggested_project_type: probe.suggestedProjectType,
+            },
+            choices: {
+                project_type: ['standalone', 'workspace', ...(probe.nearbyStores.some((s) => s.role === 'workspace') ? ['linked'] : [])],
+                topology: ['embedded', 'sidecar'],
+            },
+        },
+    };
+}
+/**
+ * Generate a "moment aha" preview after init — shows what an agent
+ * would see when calling bclaw_get_context on this project.
+ */
+export function buildOnboardingPreview(cwd) {
+    try {
+        const state = loadState(cwd);
+        const constraints = state.active_constraints.filter((c) => c.status === 'active');
+        const traps = state.known_traps.filter((t) => t.visibility === 'shared' && (!t.status || t.status === 'active'));
+        const plans = state.plan_items.filter((p) => p.status === 'in_progress' || p.status === 'todo');
+        if (constraints.length === 0 && traps.length === 0 && plans.length === 0) {
+            return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+        }
+        const lines = ['Here is what your agent will see:'];
+        if (constraints.length > 0) {
+            lines.push(`  Constraints: ${constraints.length} active`);
+            for (const c of constraints.slice(0, 3))
+                lines.push(`    - ${c.text}`);
+        }
+        if (traps.length > 0) {
+            lines.push(`  Traps: ${traps.length} known`);
+            for (const t of traps.slice(0, 3))
+                lines.push(`    - [${t.severity}] ${t.text}`);
+        }
+        if (plans.length > 0) {
+            lines.push(`  Plans: ${plans.length} active`);
+            for (const p of plans.slice(0, 3))
+                lines.push(`    - [${p.status}] ${p.text}`);
+        }
+        return lines.join('\n');
+    }
+    catch {
+        return 'Memory is empty. Run bclaw_bootstrap to extract initial context from this repo.';
+    }
+}
+//# sourceMappingURL=setup-flow.js.map

package/dist/core/setup-state.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeFileAtomic } from './io.js';
+import { ensureMemoryDir, writeFileAtomic } from './io.js';
+import { defaultConfig, saveConfig } from './config.js';
 export function resolveHomeDir(env = process.env) {
     return env.HOME?.trim() || env.USERPROFILE?.trim() || undefined;
 }
@@ -47,4 +48,32 @@ export function hasCompletedSetup(env = process.env) {
     const configPath = userStoreConfigPath(env);
     return configPath ? fs.existsSync(configPath) : false;
 }
+/**
+ * Ensure the user-global store (~/.brainclaw/) exists, creating it implicitly
+ * if absent. This replaces the old "setup required before init" guard —
+ * init can now auto-create the minimal user store on first run.
+ *
+ * Idempotent: returns immediately if the user store already exists.
+ * Non-fatal: logs a warning if creation fails but does not throw.
+ */
+export function ensureUserStore(env = process.env) {
+    const home = resolveHomeDir(env);
+    if (!home)
+        return false;
+    const configPath = path.join(home, '.brainclaw', 'config.yaml');
+    if (fs.existsSync(configPath)) {
+        return true; // already exists
+    }
+    try {
+        ensureMemoryDir(home);
+        const cfg = defaultConfig('user-global');
+        saveConfig(cfg, home);
+        fs.appendFileSync(configPath, 'store_type: user\n');
+        return true;
+    }
+    catch (err) {
+        console.warn(`Warning: could not create user store at ${path.join(home, '.brainclaw')}:`, err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
 //# sourceMappingURL=setup-state.js.map

package/dist/core/store-resolution.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { loadConfig } from './config.js';
 import { MEMORY_DIR } from './io.js';
+import { summarizeWorkspaceProjects } from './workspace-projects.js';
 /**
  * Walk up the filesystem from `cwd`, collecting every `.brainclaw/` directory
  * found along the way, up to (and including) `boundary`.
@@ -82,6 +84,49 @@ export function resolveTargetStore(cwd = process.cwd(), target = 'local', option
     const match = chain.find((s) => s.role === 'user');
     return match?.cwd ?? os.homedir();
 }
+/**
+ * Resolve the most specific child store that should answer a context request.
+ *
+ * This keeps the current cwd by default, but when `target` clearly points inside
+ * a nested Brainclaw project (for example from a workspace root in folder mode),
+ * it returns that child store cwd instead.
+ */
+export function resolveContextStoreCwd(cwd = process.cwd(), target) {
+    const trimmedTarget = target?.trim();
+    if (!trimmedTarget) {
+        return cwd;
+    }
+    const primary = resolvePrimaryStore(cwd);
+    if (!primary) {
+        return cwd;
+    }
+    const absoluteTarget = resolveAbsoluteTargetPath(cwd, trimmedTarget);
+    if (!absoluteTarget) {
+        return cwd;
+    }
+    let config;
+    try {
+        config = loadConfig(primary.cwd);
+    }
+    catch {
+        return cwd;
+    }
+    const summary = summarizeWorkspaceProjects(primary.cwd, config);
+    if (summary.discovered_projects.length === 0) {
+        return cwd;
+    }
+    const candidates = summary.discovered_projects
+        .map((project) => path.resolve(primary.cwd, project.path))
+        .filter((candidatePath) => candidatePath !== primary.cwd)
+        .filter((candidatePath) => fs.existsSync(path.join(candidatePath, MEMORY_DIR)))
+        .sort((a, b) => b.length - a.length);
+    for (const candidate of candidates) {
+        if (isAtOrBelow(absoluteTarget, candidate)) {
+            return candidate;
+        }
+    }
+    return cwd;
+}
 /**
  * Return true if `dir` is at or below `ancestor` in the filesystem hierarchy.
  */
@@ -90,6 +135,19 @@ function isAtOrBelow(dir, ancestor) {
     // If relative path starts with '..', dir is above ancestor
     return !rel.startsWith('..');
 }
+function resolveAbsoluteTargetPath(cwd, target) {
+    if (path.isAbsolute(target)) {
+        return path.resolve(target);
+    }
+    const joined = path.resolve(cwd, target);
+    if (fs.existsSync(joined)) {
+        return joined;
+    }
+    if (target.includes('/') || target.includes('\\') || target.startsWith('.')) {
+        return joined;
+    }
+    return undefined;
+}
 /**
  * Infer the store role from config.yaml store_type field, or fall back to
  * heuristics (presence of .git sibling = repo, no parent store = workspace).

package/docs/architecture/project-refs.md

@@ -0,0 +1,305 @@
+# Project Refs for Multi-Project Navigation
+
+## Goal
+
+In a multi-project workspace, agents should be able to address any known project from anywhere in the workspace without depending on the current working directory.
+
+The core primitive for this is a stable `project_ref`.
+
+Examples:
+
+- `dev/repos/global`
+- `applications/lodestar`
+- `core_services/postgres`
+
+This lets Brainclaw support direct project navigation commands such as:
+
+- `brainclaw projects`
+- `brainclaw project applications/lodestar`
+- `brainclaw context --project applications/lodestar`
+- `brainclaw children dev/repos/global`
+- `brainclaw ancestors applications/lodestar`
+- `brainclaw dependencies applications/lodestar`
+- `brainclaw locate dev/repos/global/applications/lodestar/src/app.ts`
+
+The same addressing model must exist over MCP.
+
+## Why
+
+Current workspace-centric behavior is still too dependent on `cwd` and path heuristics:
+
+- `brainclaw context --for <path>` can help rerank context
+- in folder-mode workspaces it can now resolve a child store for some path-shaped targets
+- but the mental model is still "where am I on disk?"
+
+For agents, this is weaker than "which project am I addressing?"
+
+`project_ref` should become the natural addressing unit for:
+
+- context lookup
+- workspace navigation
+- parent/child traversal
+- dependency traversal
+- future project-scoped MCP tools
+
+## Core Model
+
+Each known project keeps its internal `project_id`.
+
+Each project also gets a stable human-readable `project_ref`:
+
+- derived from the workspace-relative path
+- normalized with forward slashes
+- unique within the workspace
+
+Examples:
+
+- workspace root: `.`
+- child repo: `dev/repos/global`
+- nested project: `dev/repos/global/applications/lodestar`
+
+The registry for a workspace project should expose at least:
+
+- `project_id`
+- `project_ref`
+- `project_name`
+- `relative_path`
+- `absolute_path`
+- `workspace_root`
+- `parent_ref`
+- `aliases`
+- `store_present`
+- `source`
+- `dependencies`
+
+## Naming Rules
+
+Canonical rule:
+
+- `project_ref` is the workspace-relative path to the project root
+
+Short aliases:
+
+- the final path segment may be used as an alias
+- only when unique within the workspace
+- ambiguous aliases must fail with a disambiguation error
+
+Examples:
+
+- `applications/lodestar` may have alias `lodestar`
+- if two projects end with `api`, `brainclaw project api` must fail and suggest full refs
+
+This keeps the model simple:
+
+- canonical ref is always deterministic
+- short names are optional ergonomics, not identity
+
+## Project Resolution
+
+Resolution should work from anywhere in the workspace.
+
+The resolver accepts:
+
+- exact `project_ref`
+- exact `project_id`
+- unique short alias
+- absolute path to a project root
+- absolute or relative path inside a project
+
+The resolver returns:
+
+- the matched project record
+- the resolved project root
+- the matched method: `ref`, `id`, `alias`, or `path`
+
+Resolution priority:
+
+1. exact `project_ref`
+2. exact `project_id`
+3. unique alias
+4. path-to-project containment
+
+If multiple matches remain, Brainclaw must stop and return a clear ambiguity error.
+
+## CLI Surface
+
+The minimal agent-first CLI surface should be:
+
+### `brainclaw projects`
+
+List known projects in the current workspace.
+
+Fields:
+
+- `project_ref`
+- `project_name`
+- `relative_path`
+- `parent_ref`
+- `store_present`
+
+### `brainclaw project <ref>`
+
+Show a compact project card.
+
+Fields:
+
+- `project_id`
+- `project_ref`
+- `aliases`
+- `absolute_path`
+- `parent_ref`
+- `children`
+- `dependencies`
+- store health summary
+
+### `brainclaw context --project <ref>`
+
+Resolve the target project first, then build context from that store.
+
+Notes:
+
+- this is stronger than `context --for`
+- `--for` still helps ranking within the resolved project
+
+Example:
+
+```bash
+brainclaw context --project applications/lodestar --for src/app.ts
+```
+
+### `brainclaw children <ref>`
+
+Return direct child projects.
+
+### `brainclaw ancestors <ref>`
+
+Return the project chain from parent to workspace root.
+
+### `brainclaw dependencies <ref>`
+
+Return declared or detected project dependencies.
+
+### `brainclaw locate <path>`
+
+Resolve any path to the owning project.
+
+This is especially useful for agents:
+
+- start from a changed file
+- ask Brainclaw which project owns it
+- then request context for that project
+
+## MCP Surface
+
+The MCP equivalents should mirror the CLI rather than invent a second addressing model.
+
+Suggested tools:
+
+- `bclaw_list_projects`
+- `bclaw_get_project`
+- `bclaw_get_project_context`
+- `bclaw_list_project_children`
+- `bclaw_list_project_ancestors`
+- `bclaw_list_project_dependencies`
+- `bclaw_locate_project`
+
+All of them should accept `project_ref` as the primary selector.
+
+`bclaw_get_context` may continue to exist, but multi-project agents should prefer `bclaw_get_project_context`.
+
+## Hierarchy Semantics
+
+Hierarchy comes from project roots on disk.
+
+Definitions:
+
+- parent: nearest known project root above the current project
+- child: known project whose nearest known parent is the current project
+- ancestor: repeated parent chain
+
+This is path-derived and deterministic.
+
+## Dependency Semantics
+
+Dependencies are different from hierarchy.
+
+Dependencies should support two sources:
+
+- declared links in Brainclaw metadata
+- detected links from repo/workspace tooling when reliable
+
+Examples:
+
+- monorepo package dependencies
+- service depends on shared database project
+- app depends on auth service
+
+The first iteration should allow declared dependencies first.
+
+Auto-detection can remain additive.
+
+## Storage Direction
+
+This does not require replacing current project ids or store layout.
+
+It requires a workspace project registry that can be rebuilt or refreshed non-destructively.
+
+Likely location:
+
+- workspace-level discovery inventory
+
+Likely persisted fields:
+
+- stable `project_ref`
+- alias set
+- hierarchy links
+- declared dependency links
+
+This should stay clearly separate from canonical memory items such as decisions and constraints.
+
+## Migration Strategy
+
+The migration should be low-risk and incremental.
+
+Phase 1:
+
+- introduce `project_ref` in workspace discovery/registry
+- expose `brainclaw projects`
+- expose `brainclaw locate`
+
+Phase 2:
+
+- add `context --project <ref>`
+- keep current `context --for <path>` behavior
+- when `--project` is present, it wins over cwd heuristics
+
+Phase 3:
+
+- add `children` and `ancestors`
+- add MCP equivalents
+
+Phase 4:
+
+- add declared dependencies
+- optionally add auto-detection
+
+## Non-Goals
+
+This design does not require:
+
+- replacing `project_id`
+- removing cwd-based commands
+- making aliases mandatory
+- making dependency inference perfect in the first release
+
+## Recommendation
+
+The first implementation slice should be:
+
+1. add `project_ref` to workspace project discovery
+2. add a project resolver shared by CLI and MCP
+3. add `brainclaw projects`
+4. add `brainclaw context --project <ref>`
+5. add `brainclaw locate <path>`
+
+That is enough to give agents a stable and simple project-addressing model without a risky refactor.

package/docs/cli.md

@@ -918,7 +918,7 @@ Generate compact, prompt-ready context for agents.
 
 | Option | Description |
 |---|---|
-| `--for <path>` | Scope context to a file or path |
+| `--for <path>` | Scope context to a file or path; in folder-mode workspaces, child project paths resolve the matching nested store automatically |
 | `--project <name>` | Filter by project |
 | `--agent <name>` | Filter by agent |
 | `--host <name>` | Filter by host |
@@ -938,6 +938,7 @@ Generate compact, prompt-ready context for agents.
 
 ```bash
 brainclaw context --for src/auth/routes.ts --digest
+brainclaw context --for applications/lodestar/src/app.ts --json
 brainclaw context --json --max-chars 1200
 brainclaw context --explain
 brainclaw context --since-session --max-items 20