brainclaw 0.19.11 → 0.19.14

package/dist/core/io.js

@@ -30,6 +30,7 @@ const ENTITY_DIR_MAP = {
     'runtime': 'coordination/runtime',
     'runtime-hosts': 'coordination/runtime-hosts',
     'runtime-private': 'coordination/runtime-private',
+    'surface-tasks': 'coordination/surface-tasks',
     // discovery/ — Project entity: what's available
     'bootstrap': 'discovery/bootstrap',
     'bootstrap/seeds': 'discovery/bootstrap/seeds',

package/dist/core/machine-profile.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
 import { MEMORY_DIR } from './io.js';
+import { buildAiSurfaceInventory, renderAiSurfaceSummary } from './ai-surface-inventory.js';
 // ── Detection Functions ────────────────────────────────────────────────────────
 const TOOLCHAINS = [
     { name: 'node', command: 'node', versionArgs: ['--version'] },
@@ -227,7 +228,7 @@ function detectWslDistros() {
  */
 export function buildMachineProfile() {
     return {
-        schema_version: 1,
+        schema_version: 2,
         generated_at: new Date().toISOString(),
         hostname: os.hostname(),
         os_user: os.userInfo().username,
@@ -241,6 +242,7 @@ export function buildMachineProfile() {
         ssh_keys: detectSshKeys(),
         toolchains: detectToolchains(),
         wsl_distros: detectWslDistros(),
+        ai_surfaces: buildAiSurfaceInventory(),
     };
 }
 /**
@@ -283,6 +285,7 @@ export function loadMachineProfile() {
  */
 export function renderMachineProfileSummary(profile) {
     const lines = [];
+    const aiSurfaces = profile.ai_surfaces ?? [];
     lines.push(`Machine: ${profile.hostname} (user: ${profile.os_user})`);
     lines.push(`Home: ${profile.home_dir}`);
     lines.push(`OS: ${profile.os_variant} (${profile.platform} ${profile.os_release}, ${profile.arch})`);
@@ -326,6 +329,9 @@ export function renderMachineProfileSummary(profile) {
             lines.push(`  - ${d.name}${d.default ? ' (default)' : ''}: ${nodeInfo}`);
         }
     }
+    if (aiSurfaces.length > 0) {
+        lines.push(...renderAiSurfaceSummary(aiSurfaces));
+    }
     lines.push(`Profile generated: ${profile.generated_at}`);
     return lines.join('\n');
 }

package/dist/core/migration.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { memoryDir, memoryPath, readFileSync, writeFileAtomic, resolveEntityDir } from './io.js';
-import { BootstrapApplicationReceiptSchema, BootstrapImportPlanDocumentSchema, AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, } from './schema.js';
+import { BootstrapApplicationReceiptSchema, BootstrapImportPlanDocumentSchema, AgentIdentityDocumentSchema, BootstrapProfileDocumentSchema, CandidateSchema, ClaimSchema, ConfigSchema, MemorySeedDocumentSchema, ConstraintSchema, CurrentSessionStateSchema, DecisionSchema, HandoffSchema, InstructionEntrySchema, PlanItemSchema, ProjectIdentityDocumentSchema, RuntimeNoteSchema, SessionSnapshotSchema, TrapSchema, AiSurfaceTaskRequestSchema, } from './schema.js';
 export class MigrationError extends Error {
     kind;
     documentType;
@@ -31,6 +31,7 @@ const registry = {
     plan: createRegistryEntry(PlanItemSchema),
     project_identity: createRegistryEntry(ProjectIdentityDocumentSchema),
     runtime_note: createRegistryEntry(RuntimeNoteSchema),
+    ai_surface_task: createRegistryEntry(AiSurfaceTaskRequestSchema),
     session_snapshot: createRegistryEntry(SessionSnapshotSchema),
     trap: createRegistryEntry(TrapSchema),
 };
@@ -164,6 +165,7 @@ export function scanMigrationStatus(cwd) {
     collectDirectory(entries, resolveEntityDir('runtime', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-hosts', effectiveCwd, 'read'), 'runtime_note', true);
     collectDirectory(entries, resolveEntityDir('runtime-private', effectiveCwd, 'read'), 'runtime_note', true);
+    collectDirectory(entries, resolveEntityDir('surface-tasks', effectiveCwd, 'read'), 'ai_surface_task');
     collectDirectory(entries, resolveEntityDir('instructions', effectiveCwd, 'read'), 'instruction');
     collectDirectory(entries, path.join(resolveEntityDir('bootstrap', effectiveCwd, 'read'), 'seeds'), 'memory_seed');
     collectDirectory(entries, resolveEntityDir('agents', effectiveCwd, 'read'), 'agent_identity');

package/dist/core/schema.js

@@ -344,6 +344,31 @@ export const RuntimeNoteSchema = z.object({
     expires_at: z.string().optional(),
     note_type: z.enum(['observation', 'session_start', 'session_end']).default('observation'),
 });
+// --- AI surface task request schemas ---
+export const AiSurfaceTaskStatusSchema = z.enum(['queued', 'in_progress', 'completed', 'cancelled', 'failed']);
+export const AiSurfaceTaskKindSchema = z.enum(['visual_asset', 'draft', 'summary', 'analysis', 'research', 'custom']);
+export const AiSurfaceTaskRequestSchema = z.object({
+    schema_version: z.number().int().positive().optional(),
+    id: z.string(),
+    short_label: z.string().optional(),
+    title: z.string(),
+    instructions: z.string(),
+    target_surface: z.string(),
+    kind: AiSurfaceTaskKindSchema.default('custom'),
+    created_at: z.string(),
+    updated_at: z.string(),
+    author: z.string(),
+    author_id: z.string().optional(),
+    project_id: z.string().optional(),
+    session_id: z.string().optional(),
+    status: AiSurfaceTaskStatusSchema.default('queued'),
+    requested_outputs: z.array(z.string()).default([]),
+    related_paths: z.array(z.string()).optional(),
+    tags: z.array(z.string()).default([]),
+    claimed_at: z.string().optional(),
+    completed_at: z.string().optional(),
+    result_note: z.string().optional(),
+});
 // --- Runtime event schemas ---
 export const RuntimeEventTypeSchema = z.enum([
     'task_started',

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/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.
@@ -133,7 +216,7 @@ brainclaw bootstrap --apply -y
 
 ### `brainclaw env`
 
-Display environment and tooling detection information.
+Display environment, tooling detection, and installable Brainclaw update information.
 
 | Option | Description |
 |---|---|
@@ -146,6 +229,56 @@ brainclaw env --json
 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
@@ -1253,3 +1386,10 @@ brainclaw version
 brainclaw version --check
 brainclaw version --publish-local --release-notes "Add estimation-report command"
 ```
+
+`brainclaw version --check` now follows this order:
+
+- if `brainclaw_update_source` is configured, use it
+- otherwise, fall back to the public npm channel `brainclaw@latest`
+
+This keeps end-user installs aware of published npm releases without requiring a local tarball channel. To keep beta testers on a different channel, set `brainclaw_update_source` to `type: npm` with a different `dist_tag`, such as `prelaunch`.

package/docs/integrations/mcp.md

@@ -16,16 +16,19 @@ MCP matters because Brainclaw's value is mostly in dynamic state:
 
 Static files still help, but they age immediately. MCP is the stronger path for live coordination.
 
+That now also includes Brainclaw's own install channel state: `bclaw_get_execution_context` surfaces whether a newer npm or local-pack build is available, so the agent can notice upgrades without relying on a human to run `brainclaw version --check`.
+
 ## Recommended Agent Pattern
 
 The default dynamic workflow is:
 
 1. `bclaw_session_start` to open work and get the current board/context
-2. `bclaw_get_context` when the target path or task changes
-3. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
-4. `bclaw_claim` before editing
-5. `bclaw_write_note` for runtime observations
-6. `bclaw_session_end` to close cleanly and hand work off
+2. `bclaw_get_execution_context` early in the session when the agent needs local tooling signals or package update visibility
+3. `bclaw_get_context` when the target path or task changes
+4. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
+5. `bclaw_claim` before editing
+6. `bclaw_write_note` for runtime observations
+7. `bclaw_session_end` to close cleanly and hand work off
 
 This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
 
@@ -35,7 +38,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 |---|---|
 | `bclaw_get_context` | Ranked prompt-ready context, supports `digest: true` |
 | `bclaw_bootstrap` | Derive brownfield bootstrap signals, return adaptive interview prompts, accept structured interview answers, and preview/apply a selective import proposal |
-| `bclaw_get_execution_context` | Inspect local execution context and agent tooling |
+| `bclaw_get_execution_context` | Inspect local execution context, installable update status, and agent tooling |
 | `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
 | `bclaw_read_handoff` | Read active handoffs |
 | `bclaw_get_agent_board` | Coordination snapshot |
@@ -65,6 +68,8 @@ brainclaw mcp
 
 In practice, most agents pick this up through generated MCP config such as `.mcp.json`, `~/.cursor/mcp.json`, or other agent-specific config files written by `brainclaw setup`, `brainclaw init`, or `brainclaw export`.
 
+By default, installable update checks use the public npm channel `brainclaw@latest`. Projects that need a different channel can override `brainclaw_update_source`, for example with `type: npm` and `dist_tag: prelaunch`, or with `type: local-pack` for local tarball workflows.
+
 ## Bootstrap Through MCP
 
 For agent-first onboarding, `bclaw_bootstrap` is the nominal path:

package/docs/quickstart.md

@@ -39,6 +39,7 @@ After the workspace is initialized, the nominal flow is:
 
 ```text
 bclaw_session_start   -> open a session and return current board/context
+bclaw_get_execution_context -> inspect local tooling and notice package updates
 bclaw_get_context     -> fetch fresh prompt-ready context for the target path
 bclaw_list_plans      -> inspect active work
 bclaw_claim           -> claim scope before editing
@@ -48,6 +49,8 @@ bclaw_session_end     -> close session cleanly and hand work off
 
 Use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local workflow guidance, not as the only source of live state.
 
+Unless the project overrides `brainclaw_update_source`, `bclaw_get_execution_context` checks the public npm `latest` channel so the agent can notice when a newer Brainclaw release is available.
+
 ## Path 2: CLI-Oriented Agent Or Fallback Workflow
 
 Use this path when the agent does not have a good MCP integration yet, or when a human needs to drive the workflow directly.
@@ -84,6 +87,43 @@ brainclaw status
 
 Claims reduce collisions, but they are not a substitute for isolated worktrees yet. Use them mainly to coordinate sequential work or human/agent awareness in the same repo.
 
+## Path 2.5: Desktop AI Work Surfaces Around The Repo
+
+Use this path when the active coding agent should stay focused on code, but the project could benefit from another local AI surface on the same machine, such as ChatGPT Desktop or Claude Desktop.
+
+Typical use cases:
+
+- visual asset generation
+- polished copy or release-note drafting
+- synthesis for operators or stakeholders
+- side research that should not consume the coding agent's main context window
+
+### Discover what is available on the machine
+
+```bash
+brainclaw machine-profile --refresh
+```
+
+### Queue work for another local AI surface
+
+```bash
+brainclaw surface-task create "Generate homepage hero visual" \
+  --target chatgpt \
+  --kind visual_asset \
+  --instructions "Create a lightweight product hero visual for the landing page." \
+  --output assets/hero-home.png \
+  --path src/pages/Home.tsx
+```
+
+### Review queued work later
+
+```bash
+brainclaw surface-task list
+brainclaw surface-task list --all --target chatgpt
+```
+
+This queue does not automate the target desktop app yet. It gives the project a clean place to stage work that another local AI surface should pick up during its next session.
+
 ## Path 3: Brownfield Onboarding
 
 Use this path when you are adopting Brainclaw into an existing workspace and do not want to hand-author all memory from scratch.

package/package.json

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