brainclaw 0.23.0 → 0.23.1

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from 'node:path';
 import { Command } from 'commander';
 import { runInit } from './commands/init.js';
 import { runSetup } from './commands/setup.js';
@@ -94,15 +95,26 @@ program
     .hook('preAction', (_thisCommand, actionCommand) => {
     const root = actionCommand.optsWithGlobals();
     initLogLevel({ verbose: root.verbose, debug: root.debug });
-    // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
-    const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
-    if (effectiveCwd !== process.cwd()) {
-        // Store resolved cwd so commands can read it via optsWithGlobals().cwd
-        actionCommand.setOptionValue('cwd', effectiveCwd);
+    // Skip effective cwd resolution for commands that create the store
+    const cmdName = actionCommand.name();
+    const skipResolution = cmdName === 'init' || cmdName === 'setup';
+    if (!skipResolution) {
+        // Resolve effective cwd (--cwd > BRAINCLAW_PROJECT > active-project > process.cwd)
+        const effectiveCwd = resolveEffectiveCwd({ explicitCwd: root.cwd });
+        if (effectiveCwd !== process.cwd()) {
+            // Change process.cwd() so all commands resolve the correct store
+            // without needing individual --cwd plumbing
+            process.chdir(effectiveCwd);
+            logger.info(`Resolved effective cwd: ${effectiveCwd}`);
+        }
+        const removed = cleanOrphanFiles(memoryDir());
+        if (removed > 0) {
+            logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir()}`);
+        }
     }
-    const removed = cleanOrphanFiles(memoryDir(effectiveCwd));
-    if (removed > 0) {
-        logger.info(`Cleaned ${removed} orphan lock/tmp file(s) in ${memoryDir(effectiveCwd)}`);
+    else if (root.cwd) {
+        // For init/setup, still respect explicit --cwd but nothing else
+        process.chdir(path.resolve(root.cwd));
     }
 });
 // --- init ---

package/dist/commands/switch.js

@@ -106,8 +106,8 @@ function listProjects(wsRoot, json) {
             });
         }
     }
-    // Discover child projects
-    const children = scanNestedBrainclawProjects(wsRoot, 4);
+    // Discover child projects (depth 7 covers deep workspace layouts like /srv/dev/repos/global/applications/*/...)
+    const children = scanNestedBrainclawProjects(wsRoot, 7);
     for (const child of children) {
         const childPath = path.resolve(child.path);
         if (childPath === wsRoot)

package/docs/architecture/project-refs.md

@@ -257,10 +257,29 @@ Likely persisted fields:
 
 This should stay clearly separate from canonical memory items such as decisions and constraints.
 
+## Current Implementation (v0.23.0)
+
+`brainclaw switch` provides the first layer of project navigation:
+
+- `brainclaw switch <name-or-path>` — set active project by name or relative path
+- `brainclaw switch --list` — discover available projects in workspace
+- `resolveProjectRef()` — shared resolver for CLI and MCP (name, path, registry lookup)
+- `resolveEffectiveCwd()` — single source of truth: `--cwd` > `BRAINCLAW_PROJECT` env > active-project > cwd
+- MCP tools automatically resolve the active project
+
+This covers the most common agent friction (cwd-dependent resolution) without requiring the full `project_ref` model yet.
+
 ## Migration Strategy
 
 The migration should be low-risk and incremental.
 
+Phase 0 (done):
+
+- `brainclaw switch` with name/path resolution
+- global `--cwd` option
+- `BRAINCLAW_PROJECT` environment variable
+- `resolveEffectiveCwd()` used by CLI and MCP
+
 Phase 1:
 
 - introduce `project_ref` in workspace discovery/registry

package/docs/cli.md

@@ -11,6 +11,53 @@ For capable coding agents, prefer MCP for dynamic runtime state:
 
 Use the CLI when a human operator is driving the workflow, when you are scripting setup or release operations, or when MCP is not the integration path.
 
+## Global Options
+
+All commands support these global options:
+
+| Option | Description |
+|---|---|
+| `--cwd <path>` | Override working directory for this invocation. Bypasses active project and env var resolution. |
+| `--verbose` | Show info-level log messages on stderr |
+| `--debug` | Show debug-level log messages on stderr |
+
+**Effective cwd resolution priority** (highest wins):
+
+1. `--cwd` flag
+2. `BRAINCLAW_PROJECT` environment variable (project name or path)
+3. Active project set via `brainclaw switch`
+4. `process.cwd()` (shell working directory)
+
+---
+
+## Multi-Project Navigation
+
+### `brainclaw switch [project]`
+
+Set the active project for subsequent CLI and MCP commands. This eliminates the need to `cd` into a subproject directory in multi-project workspaces. The active project is persisted per-workspace in `.brainclaw/active-project.json`.
+
+| Option | Description |
+|---|---|
+| `--list` | List all available projects in the workspace |
+| `--clear` | Clear the active project (revert to cwd default) |
+| `--json` | Output as JSON |
+
+The `<project>` argument accepts:
+- **Project name** — matched against the global registry and workspace config
+- **Relative path** — resolved from the workspace root (e.g. `apps/lodestar`)
+- **Absolute path** — used directly
+
+```bash
+brainclaw switch --list              # discover available projects
+brainclaw switch lodestar            # switch by project name
+brainclaw switch apps/lodestar       # switch by relative path
+brainclaw switch                     # show current active project
+brainclaw switch --clear             # clear, revert to cwd
+brainclaw --cwd /other/path status   # one-off override without switching
+```
+
+**MCP usage:** The active project also affects MCP tools. When `bclaw_get_context()` is called without an explicit path, it resolves context from the active project's store. Agents can also use `BRAINCLAW_PROJECT=<name>` environment variable for the same effect.
+
 ---
 
 ## Initialize and Inspect

package/docs/concepts/workspace-bootstrapping.md

@@ -38,3 +38,44 @@ If shared memory is absent, that should not always be interpreted as "there is n
 It may simply mean the workspace has not been onboarded yet.
 
 This lets a single machine support multiple very different workspaces without forcing one static instruction layer to fit all of them equally well.
+
+## Multi-project workspaces
+
+A workspace may contain multiple brainclaw-initialized child projects (each with its own `.brainclaw/` store). In this topology:
+
+- The workspace root holds shared instructions, constraints, and coordination state
+- Each child project holds project-specific memory (decisions, traps, plans)
+- The store chain walks upward: child → repo → workspace → user
+
+### Working with child projects
+
+Agents and operators can address child projects without `cd`:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # now targets lodestar's store
+brainclaw switch --clear          # back to workspace root
+```
+
+Or use environment variables:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+brainclaw context                 # resolves lodestar's store
+```
+
+Or one-off overrides:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+### Project discovery
+
+`brainclaw switch --list` discovers child projects via:
+
+1. Global project registry
+2. Workspace config `projects.known`
+3. Filesystem scan for subdirectories containing `.brainclaw/`
+
+The bootstrap analysis (`analyzeRepository`) also detects brainclaw-native workspace complexity (child stores, folder strategy, known projects) alongside classic monorepo markers.

package/docs/integrations/agents.md

@@ -101,6 +101,41 @@ brainclaw adds all generated files to `.gitignore` automatically during init.
 
 Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.
 
+## Multi-project workspaces
+
+When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):
+
+### 1. `brainclaw switch` (persistent)
+
+An operator or agent sets the active project once, and all subsequent commands resolve against it:
+
+```bash
+brainclaw switch apps/lodestar    # set active project
+brainclaw plan list               # targets lodestar
+bclaw_get_context()               # MCP also targets lodestar
+brainclaw switch --clear          # back to workspace root
+```
+
+### 2. `BRAINCLAW_PROJECT` environment variable
+
+Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:
+
+```bash
+export BRAINCLAW_PROJECT=lodestar
+```
+
+### 3. `--cwd` flag (one-off override)
+
+For a single command without changing the active project:
+
+```bash
+brainclaw --cwd apps/lodestar plan list
+```
+
+**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.
+
+**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.
+
 ## Session lifecycle
 
 ### Starting work

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {