brainclaw 0.19.12 → 0.20.0

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/dist/core/workspace-projects.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadGlobalRegistry, scanProject } from './global-registry.js';
+const SKIP_DIRS = new Set([
+    '.brainclaw',
+    '.git',
+    'node_modules',
+    'dist',
+    'dist-test',
+    'build',
+    'coverage',
+    '.venv',
+    'venv',
+    '__pycache__',
+    'target',
+    'vendor',
+    '.next',
+    '.nuxt',
+]);
+export function summarizeWorkspaceProjects(cwd, config) {
+    const configuredProjects = config.projects?.known ?? [];
+    const usesFolderResolution = config.project_mode === 'multi-project' && (config.projects?.strategy ?? 'manual') === 'folder';
+    const discovered = new Map();
+    for (const name of configuredProjects) {
+        const key = `config:${name}`;
+        discovered.set(key, {
+            path: name,
+            relative_path: name,
+            project_name: name,
+            source: 'config',
+        });
+    }
+    if (usesFolderResolution) {
+        for (const project of collectRegistryProjectsUnder(cwd)) {
+            const normalized = path.resolve(project.path);
+            if (normalized === path.resolve(cwd)) {
+                continue;
+            }
+            discovered.set(`path:${normalized}`, {
+                path: normalized,
+                relative_path: path.relative(cwd, normalized) || '.',
+                project_id: project.project_id,
+                project_name: project.project_name,
+                source: 'registry',
+            });
+        }
+        for (const project of scanNestedBrainclawProjects(cwd)) {
+            const normalized = path.resolve(project.path);
+            if (normalized === path.resolve(cwd)) {
+                continue;
+            }
+            if (!discovered.has(`path:${normalized}`)) {
+                discovered.set(`path:${normalized}`, {
+                    path: normalized,
+                    relative_path: path.relative(cwd, normalized) || '.',
+                    project_id: project.project_id,
+                    project_name: project.project_name,
+                    source: 'filesystem',
+                });
+            }
+        }
+    }
+    return {
+        strategy: config.projects?.strategy ?? 'manual',
+        configured_projects: configuredProjects,
+        discovered_projects: [...discovered.values()].sort((a, b) => a.relative_path.localeCompare(b.relative_path)),
+        effective_project_count: discovered.size,
+        uses_folder_resolution: usesFolderResolution,
+    };
+}
+export function scanNestedBrainclawProjects(rootDir, maxDepth = 6) {
+    const resolvedRoot = path.resolve(rootDir);
+    const results = new Map();
+    function walk(dir, depth) {
+        if (depth > maxDepth) {
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            if (entry.name.startsWith('.') && entry.name !== '.brainclaw')
+                continue;
+            const childDir = path.join(dir, entry.name);
+            const maybeProject = scanProject(childDir);
+            if (maybeProject) {
+                results.set(path.resolve(maybeProject.path), maybeProject);
+            }
+            walk(childDir, depth + 1);
+        }
+    }
+    walk(resolvedRoot, 1);
+    return [...results.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function collectRegistryProjectsUnder(rootDir) {
+    const registry = loadGlobalRegistry();
+    if (!registry) {
+        return [];
+    }
+    const resolvedRoot = path.resolve(rootDir);
+    return registry.projects.filter((project) => isWithinRoot(project.path, resolvedRoot));
+}
+function isWithinRoot(candidatePath, rootDir) {
+    const relative = path.relative(rootDir, path.resolve(candidatePath));
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+//# sourceMappingURL=workspace-projects.js.map

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

@@ -60,6 +60,85 @@ brainclaw init --topology sidecar
 brainclaw init --project-mode multi-project --project-strategy folder
 ```
 
+### `brainclaw machine-profile`
+
+Detect and persist machine-level capabilities, including other local AI work surfaces on the same machine.
+
+This is the inventory Brainclaw uses to distinguish coding agents from desktop AI apps or adjacent surfaces such as:
+
+- `ChatGPT Desktop`
+- `Claude Desktop`
+- `Claude Cowork`
+- `Gemini Web`
+- `Gemini CLI / Antigravity`
+
+| Option | Description |
+|---|---|
+| `--refresh` | Force regeneration even if a cached profile already exists |
+| `--json` | Output as JSON |
+
+```bash
+brainclaw machine-profile
+brainclaw machine-profile --refresh
+brainclaw machine-profile --refresh --json
+```
+
+Use this when you want Brainclaw to detect what AI work surfaces are actually available on the current machine before choosing an onboarding path or queueing work for another surface.
+
+### `brainclaw upgrade`
+
+Upgrade the local Brainclaw store layout and refresh managed agent files when a release changes persisted schema or generated workspace integrations.
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `--dry-run` | Preview what would be upgraded without writing |
+
+```bash
+brainclaw upgrade
+brainclaw upgrade --dry-run
+brainclaw upgrade --dry-run --json
+```
+
+`upgrade` only covers store and generated-file migrations. On complex workspaces, it does not refresh machine detection, agent inventory, or brownfield bootstrap state by itself.
+
+### `brainclaw reconcile`
+
+Refresh machine, agent, and bootstrap state after a package update or when onboarding an already-initialized multi-store workspace.
+
+This is the command to use when `brainclaw upgrade` reports no schema migration, but the installed release still introduces new workspace-centric behavior that depends on:
+
+- a refreshed `machine-profile`
+- a refreshed `agent-inventory`
+- refreshed bootstrap state for the current store and any nested Brainclaw stores discovered under a `multi-project` + `folder` workspace
+
+| Option | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `--dry-run` | Preview the reconciliation plan without writing |
+| `--apply-bootstrap` | Apply bootstrap suggestions across all selected stores after refresh |
+| `-y, --yes` | Skip confirmation prompts for multi-store bootstrap apply |
+| `--skip-machine-profile` | Skip machine profile refresh |
+| `--skip-agent-inventory` | Skip agent inventory refresh |
+
+```bash
+brainclaw reconcile --dry-run --json
+brainclaw reconcile
+brainclaw reconcile --apply-bootstrap -y
+```
+
+Recommended post-update flow for an existing complex workspace:
+
+```bash
+brainclaw upgrade --dry-run --json
+brainclaw reconcile --dry-run --json
+brainclaw reconcile --apply-bootstrap -y
+brainclaw context --json
+brainclaw doctor --json
+```
+
+For a `multi-project` workspace using `projects.strategy: folder`, `reconcile` treats the current store as the workspace root and plans refreshes for nested child stores that already contain their own `.brainclaw/` directories.
+
 ### `brainclaw status`
 
 Show the current state of project memory.
@@ -75,6 +154,8 @@ brainclaw status --json
 brainclaw status --markdown
 ```
 
+In `multi-project` mode, status now reports the effective project count resolved for the workspace. With `projects.strategy: folder`, that includes child stores discovered from nested `.brainclaw/` directories even when `config.projects.known` is still empty.
+
 ### `brainclaw doctor`
 
 Run health checks on config, state, and generated views.
@@ -94,6 +175,8 @@ brainclaw doctor --fix-agent-ignore
 
 When Brainclaw detects generated local agent files such as `.mcp.json` or `.claude/settings.local.json` inside a Git repo, `doctor` warns if they are not ignored or are still tracked. `--fix-agent-ignore` only updates `.gitignore`; if a file is already tracked you still need to untrack it with `git rm --cached <path>`.
 
+In `multi-project` mode with `projects.strategy: folder`, `doctor` now checks the effective workspace project set, not just `config.projects.known`. That avoids false positives on workspaces that resolve child stores from the filesystem or global project registry.
+
 ### `brainclaw rebuild`
 
 Regenerate `project.md` from canonical state. No options.
@@ -148,6 +231,54 @@ brainclaw env --agent-tooling
 
 When the project does not pin a local release channel, `brainclaw env` checks the public npm `latest` channel for installable updates. Projects can override that with `brainclaw_update_source`, for example to use `prelaunch` or a local-pack manifest.
 
+### `brainclaw surface-task <subcommand>`
+
+Manage queued tasks for non-editing AI work surfaces such as `ChatGPT Desktop`, `Claude Desktop`, or `Gemini Web`.
+
+This command is useful when the active coding agent should keep building in the repo, but another local AI surface would be a better fit for a related task such as:
+
+- generating a visual asset
+- drafting polished copy
+- writing a release summary
+- doing side research or structured analysis
+
+Supported subcommands:
+
+- `create`
+- `list`
+- `update`
+
+| Option | Description |
+|---|---|
+| `--target <surface>` | Target surface such as `chatgpt`, `claude`, or `gemini` |
+| `--kind <kind>` | `visual_asset`, `draft`, `summary`, `analysis`, `research`, or `custom` |
+| `--instructions <text>` | Detailed task instructions |
+| `--output <paths...>` | Expected output files or deliverables |
+| `--tag <tags...>` | Optional tags |
+| `--path <paths...>` | Related repo paths |
+| `--status <status>` | For `list` filtering or `update`: `queued`, `in_progress`, `completed`, `cancelled`, `failed` |
+| `--result <text>` | Result note when updating a task |
+| `--all` | Include completed, cancelled, and failed tasks in `list` |
+| `--json` | Output as JSON for `list` |
+
+```bash
+brainclaw surface-task create "Generate homepage hero visual" \
+  --target chatgpt \
+  --kind visual_asset \
+  --instructions "Create a lightweight SaaS hero visual in PNG format." \
+  --output assets/hero-home.png \
+  --path src/pages/Home.tsx
+
+brainclaw surface-task list
+
+brainclaw surface-task update ast_12345678 \
+  --status completed \
+  --result "Saved the visual to assets/hero-home.png" \
+  --output assets/hero-home.png
+```
+
+These tasks are local project coordination state. They do not execute automatically yet. The intended model is that Brainclaw can queue work for another local AI surface so that the next session on that surface can pick it up cleanly.
+
 ---
 
 ## Memory Management
@@ -787,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 |
@@ -807,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