brainclaw 1.8.0 → 1.9.1

package/docs/concepts/workspace-bootstrapping.md

@@ -1,81 +1,142 @@
-# Workspace Bootstrapping
-
-brainclaw is workspace-aware.
-Shared memory is not assumed to exist everywhere by default.
-
-## Why bootstrap exists
-
-A workspace may be:
-
-- already initialized
-- known to the agent integration layer but not initialized locally
-- entirely new
-
-Bootstrap is the process that turns a workspace into a brainclaw-aware workspace.
-
-## What bootstrap does
-
-Bootstrap is more than creating a folder.
-It establishes the first shared memory foundation for the workspace:
-
-- inspects the repository structure
-- detects the AI coding agent environment
-- seeds stable workspace identity (`project_id`, `agent_id`)
-- creates the initial storage structure
-- writes to the detected agent's native instruction file (Cursor, Claude Code, Windsurf, etc.)
-- creates `AGENTS.md` and `.github/copilot-instructions.md`
-
-## Good integration pattern
-
-1. check whether the workspace is initialized
-2. if yes, retrieve fresh memory
-3. if not, bootstrap when allowed
-4. then use shared memory normally
-
-## Why this matters for agents
-
-If shared memory is absent, that should not always be interpreted as "there is no relevant context".
-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.
+# Workspace Bootstrapping
+
+brainclaw is workspace-aware.
+Shared memory is not assumed to exist everywhere by default.
+
+## Why bootstrap exists
+
+A workspace may be:
+
+- already initialized
+- known to the agent integration layer but not initialized locally
+- entirely new
+
+Bootstrap is the process that turns a workspace into a brainclaw-aware workspace.
+
+## What bootstrap does
+
+Bootstrap is more than creating a folder.
+It establishes the first shared memory foundation for the workspace:
+
+- inspects the repository structure
+- detects the AI coding agent environment
+- seeds stable workspace identity (`project_id`, `agent_id`)
+- creates the initial storage structure
+- writes to the detected agent's native instruction file (Cursor, Claude Code, Windsurf, etc.)
+- creates `AGENTS.md` and `.github/copilot-instructions.md`
+
+## Empty memory: one rule
+
+"Bootstrap" historically named three different systems (init scaffolding, the
+`bclaw_bootstrap` brownfield extractor, and the bootstrap ideation loop). When
+the memory store is empty, every surface — the `bclaw_work` hint, the
+`bclaw_setup` quick-init preview, and the `brainclaw init` preflight — now
+emits the same decision rule (`resolveEmptyMemoryRecommendation`):
+
+- **Repo with existing content** → run `bclaw_bootstrap` (CLI: `brainclaw bootstrap`)
+  to extract initial context from docs, manifests, native agent files, and git
+  history.
+- **Greenfield repo** (nothing to extract) → open a bootstrap loop to ideate
+  the project vision: `bclaw_coordinate(intent='ideate', preset='bootstrap')`
+  (CLI: `brainclaw bootstrap-loop`).
+
+The two routes are chainable in either order: extract first, then open a loop
+for whatever vision the docs could not provide — or ideate first, then extract
+once content exists. On greenfield, the brownfield preflight scan is skipped
+entirely (there is nothing to harvest yet).
+
+## Good integration pattern
+
+1. check whether the workspace is initialized
+2. if yes, retrieve fresh memory
+3. if not, bootstrap when allowed
+4. then use shared memory normally
+
+## Why this matters for agents
+
+If shared memory is absent, that should not always be interpreted as "there is no relevant context".
+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.
+
+## init = single project entry point
+
+`brainclaw init` is the single code path for turning a project into a
+brainclaw-aware workspace, whether invoked from a terminal, from the
+`bclaw_setup` MCP tool's quick-init step, or from a multi-repo
+`brainclaw setup`. After detecting the local AI agent, init runs the
+per-agent slice of the machine prerequisites (the same writes `setup`
+performs at machine scope, scoped to the detected agent) so an agent
+landing in the carte-blanche / fresh-repo case does not need a separate
+shell-out + session reload. The slice is idempotent — each `ensure*`
+function returns "skipped" when the agent's user-scope config doesn't
+exist, and the writes are short-circuited in `BRAINCLAW_TEST_MODE` or
+when `--skip-agent-bootstrap` is passed. `setup` is rescoped to
+multi-repo / machine-bootstrap; `setup-machine` is the explicit
+machine-only path.
+
+### `init --force`
+
+`--force` rebuilds managed identity fields (project_id, current_agent,
+storage_dir, topology) but **merges through the existing config** so
+curator personalisations (redaction patterns, sensitive paths,
+governance overrides, claim TTL, cross-project links, custom markdown
+caps) survive the reset. Before any write, a sibling backup is taken at
+`.brainclaw.bak-<timestamp>/` — the standard recovery-backups pattern
+used by `brainclaw upgrade`. Recovery: `brainclaw upgrade --rollback`.
+
+## Solo-agent fresh defaults
+
+A fresh `brainclaw init` seeds `governance.curators` with the human
+running init. Without this, the default `approval_policy: 'review'`
+combined with `curators: []` trapped every reflective note in pending
+forever — a surprise that doesn't show up until enough memory has
+accumulated to notice. The merge logic preserves any explicit curator
+list on an existing store, so this only takes effect on fresh installs.
+
+On an empty store, `bclaw_work` carries an explicit
+`bclaw_create(entity='plan')` hint in `next_actions` alongside the
+bootstrap recommendation: the bootstrap covers *vision*, the plan
+affordance covers *work* itself. The two are independent — both can
+appear simultaneously.
+
+## 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/context-format-changelog.md

@@ -1,35 +1,35 @@
-# Context Format Changelog
-
-## 1.3 (planned / not yet emitted as `context_schema`)
-
-- Added `available_capabilities` field to structured context containing registered project capabilities with metadata (id, name, category)
-- Added `available_tools` field to structured context containing registered project tools with metadata (id, name, type)
-- Enhanced text output to include "Available Capabilities" and "Available Tools" sections when metadata is present
-- Added discovery hints pointing users to `bclaw_get_capabilities`, `bclaw_list_tools`, and `bclaw_search_tools` MCP tools
-- These fields are currently additive enrichments around the `1.2` contract; update `CONTEXT_SCHEMA_VERSION` before treating this section as the shipped schema version
-
-## 1.2
-
-- Added `context_diff` to expose compact memory deltas since a session started.
-- Clarified the public contract for contradiction-aware session context refreshes.
-- Kept the contract additive and backward-compatible with `1.1`.
-
-## 1.1
-
-- Added explicit `context_schema` rendering in markdown and template outputs.
-- Added `agent_tooling.agents_rules`.
-- Added skill metadata flags: `scripts_present`, `references_present`, `assets_present`.
-- Added MCP inventory metadata: `availability`, `source`.
-- Kept the contract additive and backward-compatible with `1.0`.
-
-## 1.0
-
-- Baseline contract introduced with:
-  - `digest`
-  - `memory_density`
-  - `bootstrap_available`
-  - `derived_signals`
-  - `execution_context`
-  - `agent_tooling`
-  - `scoped_activity`
-  - `selected`
+# Context Format Changelog
+
+## 1.3 (planned / not yet emitted as `context_schema`)
+
+- Added `available_capabilities` field to structured context containing registered project capabilities with metadata (id, name, category)
+- Added `available_tools` field to structured context containing registered project tools with metadata (id, name, type)
+- Enhanced text output to include "Available Capabilities" and "Available Tools" sections when metadata is present
+- Added discovery hints pointing users to `bclaw_get_capabilities`, `bclaw_list_tools`, and `bclaw_search_tools` MCP tools
+- These fields are currently additive enrichments around the `1.2` contract; update `CONTEXT_SCHEMA_VERSION` before treating this section as the shipped schema version
+
+## 1.2
+
+- Added `context_diff` to expose compact memory deltas since a session started.
+- Clarified the public contract for contradiction-aware session context refreshes.
+- Kept the contract additive and backward-compatible with `1.1`.
+
+## 1.1
+
+- Added explicit `context_schema` rendering in markdown and template outputs.
+- Added `agent_tooling.agents_rules`.
+- Added skill metadata flags: `scripts_present`, `references_present`, `assets_present`.
+- Added MCP inventory metadata: `availability`, `source`.
+- Kept the contract additive and backward-compatible with `1.0`.
+
+## 1.0
+
+- Baseline contract introduced with:
+  - `digest`
+  - `memory_density`
+  - `bootstrap_available`
+  - `derived_signals`
+  - `execution_context`
+  - `agent_tooling`
+  - `scoped_activity`
+  - `selected`

package/docs/context-format.md

@@ -1,48 +1,48 @@
-# Context Format
-
-`brainclaw context` (CLI) and `bclaw_context` (MCP) expose a versioned public contract for agent consumers.
-
-Current version: `1.2`
-
-## Stable top-level fields
-
-- `context_schema`
-- `digest`
-- `memory_density`
-- `bootstrap_available`
-- `derived_signals`
-- `execution_context`
-- `agent_tooling`
-- `scoped_activity`
-- `context_diff`
-- `selected`
-
-## Compatibility policy
-
-- Additive changes bump the minor version.
-- Breaking changes bump the major version.
-- Fields listed above are treated as public and stable for agent consumers.
-- Future enrichments should prefer optional fields over reshaping existing ones.
-
-## `1.2` additions over `1.1`
-
-- `context_diff` is available for session-aware deltas through `brainclaw context --since-session` (CLI) and `bclaw_context(kind="delta", since=<session_id>)` (MCP).
-- `context_schema: 1.2` is emitted across JSON, markdown, template, and MCP structured content.
-
-## `1.1` additions over `1.0`
-
-- `context_schema` is now explicitly surfaced in markdown and template renders.
-- `agent_tooling` includes `agents_rules`.
-- `agent_tooling.skills[]` includes bounded capability markers:
-  - `scripts_present`
-  - `references_present`
-  - `assets_present`
-- `agent_tooling.mcp_servers[]` includes:
-  - `availability`
-  - `source`
-
-## Semantics
-
-- `execution_context` and `agent_tooling` are opportunistic and may be omitted when not useful.
-- `derived_signals` are non-canonical bootstrap hints, not accepted project memory.
-- `agent_tooling` inventories local capabilities and constraints; it does not imply project decisions.
+# Context Format
+
+`brainclaw context` (CLI) and `bclaw_context` (MCP) expose a versioned public contract for agent consumers.
+
+Current version: `1.2`
+
+## Stable top-level fields
+
+- `context_schema`
+- `digest`
+- `memory_density`
+- `bootstrap_available`
+- `derived_signals`
+- `execution_context`
+- `agent_tooling`
+- `scoped_activity`
+- `context_diff`
+- `selected`
+
+## Compatibility policy
+
+- Additive changes bump the minor version.
+- Breaking changes bump the major version.
+- Fields listed above are treated as public and stable for agent consumers.
+- Future enrichments should prefer optional fields over reshaping existing ones.
+
+## `1.2` additions over `1.1`
+
+- `context_diff` is available for session-aware deltas through `brainclaw context --since-session` (CLI) and `bclaw_context(kind="delta", since=<session_id>)` (MCP).
+- `context_schema: 1.2` is emitted across JSON, markdown, template, and MCP structured content.
+
+## `1.1` additions over `1.0`
+
+- `context_schema` is now explicitly surfaced in markdown and template renders.
+- `agent_tooling` includes `agents_rules`.
+- `agent_tooling.skills[]` includes bounded capability markers:
+  - `scripts_present`
+  - `references_present`
+  - `assets_present`
+- `agent_tooling.mcp_servers[]` includes:
+  - `availability`
+  - `source`
+
+## Semantics
+
+- `execution_context` and `agent_tooling` are opportunistic and may be omitted when not useful.
+- `derived_signals` are non-canonical bootstrap hints, not accepted project memory.
+- `agent_tooling` inventories local capabilities and constraints; it does not imply project decisions.

package/docs/index.md

@@ -1,69 +1,69 @@
-# Documentation Index
-
-Use this page as the entry point into the packaged Markdown documentation.
-
-## Getting Started
-
-- [quickstart.md](quickstart.md) — fastest onboarding path for a new project (greenfield)
-- [quickstart-existing-project.md](quickstart-existing-project.md) — joining a project that already has `.brainclaw/`
-- [server-operations.md](server-operations.md) — remote server, DGX, SSH, and multi-project operator workflow
-- [integrations/overview.md](integrations/overview.md) — integration model by agent surface
-
-## Guides
-
-- [integrations/mcp.md](integrations/mcp.md) — recommended runtime path for MCP-capable agents
-- [integrations/agents.md](integrations/agents.md) — agent integration principles and setup details
-- [release-maintenance.md](release-maintenance.md) — release checklist for CLI/MCP/context-schema changes
-- [review.md](review.md) — reflective workflow and candidate promotion
-- [storage.md](storage.md) — storage model and canonical vs derived state
-- [security.md](security.md) — security model and guardrails
-
-## Concepts
-
-- [concepts/memory.md](concepts/memory.md)
-- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
-- [concepts/runtime-notes.md](concepts/runtime-notes.md)
-- [concepts/coordination.md](concepts/coordination.md)
-- [concepts/multi-agent-workflows.md](concepts/multi-agent-workflows.md)
-- [concepts/workspace-bootstrapping.md](concepts/workspace-bootstrapping.md)
-- [concepts/troubleshooting.md](concepts/troubleshooting.md) — runbook for degraded coordination state
-- [concepts/memory-staleness.md](concepts/memory-staleness.md)
-- [concepts/loop-engine.md](concepts/loop-engine.md)
-- [concepts/ideation-loop.md](concepts/ideation-loop.md) — memory-confrontation ideation loop (v1.5.0+)
-- [concepts/mcp-governance.md](concepts/mcp-governance.md)
-
-## Reference
-
-- [cli.md](cli.md) — CLI reference
-- [context-format.md](context-format.md) — public context contract
-- [context-format-changelog.md](context-format-changelog.md)
-- [mcp-schema-changelog.md](mcp-schema-changelog.md)
-
-## Agent-Specific Notes
-
-- [integrations/claude-code.md](integrations/claude-code.md)
-- [integrations/codex.md](integrations/codex.md)
-- [integrations/cursor.md](integrations/cursor.md)
-- [integrations/copilot.md](integrations/copilot.md)
-- [integrations/continue.md](integrations/continue.md)
-- [integrations/roo.md](integrations/roo.md)
-- [integrations/windsurf.md](integrations/windsurf.md)
-- [integrations/opencode.md](integrations/opencode.md)
+# Documentation Index
+
+Use this page as the entry point into the packaged Markdown documentation.
+
+## Getting Started
+
+- [quickstart.md](quickstart.md) — fastest onboarding path for a new project (greenfield)
+- [quickstart-existing-project.md](quickstart-existing-project.md) — joining a project that already has `.brainclaw/`
+- [server-operations.md](server-operations.md) — remote server, DGX, SSH, and multi-project operator workflow
+- [integrations/overview.md](integrations/overview.md) — integration model by agent surface
+
+## Guides
+
+- [integrations/mcp.md](integrations/mcp.md) — recommended runtime path for MCP-capable agents
+- [integrations/agents.md](integrations/agents.md) — agent integration principles and setup details
+- [release-maintenance.md](release-maintenance.md) — release checklist for CLI/MCP/context-schema changes
+- [review.md](review.md) — reflective workflow and candidate promotion
+- [storage.md](storage.md) — storage model and canonical vs derived state
+- [security.md](security.md) — security model and guardrails
+
+## Concepts
+
+- [concepts/memory.md](concepts/memory.md)
+- [concepts/plans-and-claims.md](concepts/plans-and-claims.md)
+- [concepts/runtime-notes.md](concepts/runtime-notes.md)
+- [concepts/coordination.md](concepts/coordination.md)
+- [concepts/multi-agent-workflows.md](concepts/multi-agent-workflows.md)
+- [concepts/workspace-bootstrapping.md](concepts/workspace-bootstrapping.md)
+- [concepts/troubleshooting.md](concepts/troubleshooting.md) — runbook for degraded coordination state
+- [concepts/memory-staleness.md](concepts/memory-staleness.md)
+- [concepts/loop-engine.md](concepts/loop-engine.md)
+- [concepts/ideation-loop.md](concepts/ideation-loop.md) — memory-confrontation ideation loop (v1.5.0+)
+- [concepts/mcp-governance.md](concepts/mcp-governance.md)
+
+## Reference
+
+- [cli.md](cli.md) — CLI reference
+- [context-format.md](context-format.md) — public context contract
+- [context-format-changelog.md](context-format-changelog.md)
+- [mcp-schema-changelog.md](mcp-schema-changelog.md)
+
+## Agent-Specific Notes
+
+- [integrations/claude-code.md](integrations/claude-code.md)
+- [integrations/codex.md](integrations/codex.md)
+- [integrations/cursor.md](integrations/cursor.md)
+- [integrations/copilot.md](integrations/copilot.md)
+- [integrations/continue.md](integrations/continue.md)
+- [integrations/roo.md](integrations/roo.md)
+- [integrations/windsurf.md](integrations/windsurf.md)
+- [integrations/opencode.md](integrations/opencode.md)
 - [integrations/kilocode.md](integrations/kilocode.md)
 - [integrations/mistral-vibe.md](integrations/mistral-vibe.md)
 - [integrations/hermes.md](integrations/hermes.md)
 - [integrations/openclaw.md](integrations/openclaw.md)
-
-## Audience Design Constraints
-
-Internal design reference — constraints that guide brainclaw development per target audience.
-
-- [playbooks/productivity/](playbooks/productivity/index.md) — end-users & solo devs
-- [playbooks/team/](playbooks/team/index.md) — teams & ops
-- [playbooks/integration/](playbooks/integration/index.md) — AI builders
-
-## Design And Proposals
-
-- [architecture/project-refs.md](architecture/project-refs.md) — target navigation model, not the fully shipped surface
-- [product/positioning.md](product/positioning.md)
-- [adapters/openclaw.md](adapters/openclaw.md)
+
+## Audience Design Constraints
+
+Internal design reference — constraints that guide brainclaw development per target audience.
+
+- [playbooks/productivity/](playbooks/productivity/index.md) — end-users & solo devs
+- [playbooks/team/](playbooks/team/index.md) — teams & ops
+- [playbooks/integration/](playbooks/integration/index.md) — AI builders
+
+## Design And Proposals
+
+- [architecture/project-refs.md](architecture/project-refs.md) — target navigation model, not the fully shipped surface
+- [product/positioning.md](product/positioning.md)
+- [adapters/openclaw.md](adapters/openclaw.md)