@hachej/boring-agent 0.1.17 → 0.1.20

package/dist/shared/index.js

@@ -9,9 +9,10 @@ import {
 import {
   DEFAULT_AGENT_RUNTIME_CAPABILITIES,
   PI_AGENT_RUNTIME_CAPABILITIES,
+  WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT,
   extractToolUiMetadata,
   isToolUiMetadata
-} from "../chunk-F3CE5CNW.js";
+} from "../chunk-B5JECXMG.js";
 
 // src/shared/config-schema.ts
 import { z } from "zod";
@@ -77,6 +78,7 @@ export {
   ErrorLogFieldsSchema,
   PI_AGENT_RUNTIME_CAPABILITIES,
   RuntimeModeSchema,
+  WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT,
   extractToolUiMetadata,
   isToolUiMetadata,
   validateConfig,

package/dist/tool-ui-DIFNGwYd.d.ts

@@ -0,0 +1,20 @@
+interface ToolUiMetadata {
+    /** Renderer key registered by the app shell, e.g. `pi-subagent`. */
+    rendererId?: string;
+    /** Optional grouping label for future tool timelines/summaries. */
+    displayGroup?: string;
+    /** Optional icon hint. Frontends decide whether/how to honor it. */
+    icon?: string;
+    /** Renderer-specific structured data. */
+    details?: unknown;
+}
+declare function isToolUiMetadata(value: unknown): value is ToolUiMetadata;
+/**
+ * Extract structured UI metadata from a ToolResult-like output.
+ *
+ * Shape:
+ *   output.details.ui = { rendererId, displayGroup, icon, details }
+ */
+declare function extractToolUiMetadata(output: unknown): ToolUiMetadata | undefined;
+
+export { type ToolUiMetadata as T, extractToolUiMetadata as e, isToolUiMetadata as i };

package/docs/ACCESSIBILITY.md

@@ -0,0 +1,55 @@
+# Accessibility Audit
+
+This document tracks accessibility status for `@boring/agent` UI surfaces.
+
+## Scope (boring-ui-v2-cop)
+
+- `packages/agent/src/front/ChatPanel.tsx`
+- `packages/agent/src/front-shadcn/ChatPanel.tsx`
+- `packages/agent/src/front-shadcn/primitives/*` (chat primitives)
+- CI browser check for the default agent app (`packages/agent/app`)
+
+## Current Coverage
+
+### Landmarks and live regions
+
+- ChatPanel roots now expose `role="region"` with
+  `aria-label="Agent assistant"` in both front variants.
+- Message streams expose `role="log"` and `aria-live="polite"` as
+  `aria-label="Agent conversation"`.
+- Error states are announced with `role="alert"` in both variants.
+
+### Interactive control names
+
+- Icon-only conversation controls expose explicit names:
+  - `Scroll to latest message`
+  - `Download conversation`
+
+### Automated checks
+
+- Unit checks:
+  - `src/front/__tests__/ChatPanel.test.tsx`
+  - `src/front-shadcn/__tests__/ChatPanel.test.tsx`
+- Browser axe check:
+  - `packages/agent/e2e/a11y.spec.ts`
+  - Fails on any **serious** or **critical** violation inside
+    `[data-boring-agent]`.
+
+This runs in CI automatically through the existing `pnpm e2e` job.
+
+## Known Gaps
+
+1. Storybook a11y pipeline is not present yet.
+   There is no `.storybook` config, no `@storybook/addon-a11y`, and no
+   story-level axe scan.
+2. Current automated axe gate targets the shipped chat surface only.
+   Workspace pane-level a11y checks (file tree, editor panes, dock tabs) are
+   outside this package and need dedicated coverage in `@boring/workspace`.
+3. Manual screen-reader validation (VoiceOver/NVDA) is still pending.
+
+## Next Increment
+
+1. Stand up Storybook for `@boring/agent` primitives.
+2. Enable addon-a11y and add story-level CI checks.
+3. Extend browser axe checks to `workspace-playground` once pane a11y owners
+   land stable selectors/landmarks.

package/docs/API.md

@@ -0,0 +1,64 @@
+# API
+
+This file documents the package API as it exists today in the v2 scaffold.
+Roadmap-only APIs are explicitly marked.
+
+## Entry Points
+
+`@boring/agent` currently maps to the frontend entry (`dist/front.js`).
+
+Additional subpath exports:
+
+- `@boring/agent/front`
+- `@boring/agent/shared`
+- `@boring/agent/server`
+
+## Current Runtime Surface
+
+### `@boring/agent/server`
+
+Currently exported:
+
+- `createDirectSandbox` from `src/server/sandbox/direct/createDirectSandbox.ts`
+
+Notes:
+
+- This is the only runtime mode implementation currently available.
+- Local `bwrap` and remote `vercel-sandbox` adapters are planned.
+
+### `@boring/agent/shared`
+
+Current contract files:
+
+- `harness.ts` — `AgentHarness`, streaming event contracts.
+- `tool.ts` — `AgentTool`, `ToolExecContext`, `ToolResult`.
+- `workspace.ts` — platform-agnostic filesystem contract.
+- `sandbox.ts` — command execution contract.
+- `session.ts` — `SessionStore` and session models.
+- `ui-bridge.ts` — `UiBridge`, `UiCommand`, `CommandResult`.
+- `catalog.ts`, `file-search.ts`, `message.ts`, `sandbox-handle-store.ts`.
+
+These files are the source of truth for TypeScript interfaces while higher-level
+helpers are still being implemented.
+
+## Shipped High-Level API
+
+- `createAgentApp(config)` — standalone Fastify factory. Zero dependency on `@boring/core`. Powers `npx @boring/agent`. See `packages/agent/src/server/createAgentApp.ts`.
+- `ChatPanel` — React component exported from `@boring/agent/front` (and top-level barrel). See `packages/agent/src/front/index.ts:2`.
+- `useAgentChat(...)` — React hook, same export surface.
+
+## Planned High-Level API (Not Implemented Yet)
+
+- `registerAgentRoutes(app, opts)` — new Fastify plugin export for embedding into a core-built server. Lands in agent M4 alongside core's integration milestone. Paths are absolute (`/api/v1/agent/*`); no `prefix` option.
+
+Track implementation progress in `docs/plans/agent-package-spec.md` and beads.
+
+## Deferred HTTP Git Surface (v1.x)
+
+`/api/v1/git/*` routes are intentionally not part of agent v1.
+
+- Reason: there is no first-party git UI consumer in agent/workspace v1, so
+  these routes would be dead code.
+- Current behavior: use the `bash` tool for git commands.
+- Activation point: when git UI returns (status/diff/badges), add the routes as
+  thin wrappers over sandbox git execution.

package/docs/CSP.md

@@ -0,0 +1,40 @@
+# CSP Compatibility
+
+`@boring/agent` is compatible with a strict CSP, with one required exception:
+`style-src` must allow inline styles for editor/runtime integrations that do
+not support nonces end-to-end.
+
+## Recommended Policy
+
+```http
+Content-Security-Policy:
+  default-src 'self';
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  connect-src 'self';
+  img-src 'self' data: blob:;
+  font-src 'self';
+```
+
+## Notes
+
+- `script-src` does **not** require `'unsafe-eval'`.
+- No `eval()` or `new Function()` usage is expected in audited agent UI surfaces
+  (shadcn ChatPanel + example apps).
+- Shared helper lives at `src/server/http/csp.ts`; example servers consume it
+  via `examples/csp.ts`.
+
+## Audited Scope (tv4)
+
+- `src/front/ChatPanel.tsx`
+- `examples/with-custom-tool/*`
+- `apps/agent-playground/*`
+
+## Remaining Caveat
+
+Even with this cleanup, downstream consumers that enable rich editor stacks
+(for example CodeMirror/Tiptap integrations in workspace-oriented shells) should
+keep `style-src 'unsafe-inline'` until upstream libraries expose nonce-safe
+style injection across the full stack. The default non-shadcn primitive
+stack (`src/front/primitives/*`) also still relies on inline style attributes,
+so `style-src 'unsafe-inline'` remains required there as well.

package/docs/ERROR_CODES.md

@@ -0,0 +1,54 @@
+# ERROR_CODES
+
+Canonical registry for stable `@boring/agent` error codes.
+
+All API failures must use the response envelope:
+
+```json
+{
+  "error": {
+    "code": "PATH_ESCAPE",
+    "message": "Path '../secrets' escapes workspace root",
+    "details": {
+      "path": "../secrets",
+      "workspaceRoot": "/tmp/ws"
+    }
+  }
+}
+```
+
+## Registry
+
+| Code | When it fires | HTTP status | Suggested client action | Log level | Stability |
+| --- | --- | --- | --- | --- | --- |
+| `MISSING_API_KEY` | Required provider API key missing from runtime config | 500 | report-bug | error | stable (public API) |
+| `INVALID_API_KEY` | Provider rejects API key as malformed/invalid | 401 | re-auth | warn | stable (public API) |
+| `OIDC_REFRESH_FAILED` | OIDC refresh token exchange fails | 401 | re-auth | warn | stable (public API) |
+| `VERCEL_AUTH_FAILED` | Vercel sandbox auth/token request fails | 401 | re-auth | warn | stable (public API) |
+| `CONFIG_INVALID` | Runtime config fails schema validation | 500 | report-bug | error | stable (public API) |
+| `PATH_ESCAPE` | Relative path escapes workspace root | 403 | user-fix | warn | stable (public API) |
+| `PATH_ABSOLUTE` | Absolute path rejected where relative path is required | 400 | user-fix | warn | stable (public API) |
+| `PATH_NULL_BYTE` | Path contains a null byte | 400 | user-fix | warn | stable (public API) |
+| `PATH_SYMLINK_ESCAPE` | Realpath resolves outside workspace root | 403 | user-fix | warn | stable (public API) |
+| `PATH_NOT_FOUND` | Read/stat/load targets missing path | 404 | user-fix | warn | stable (public API) |
+| `PATH_NOT_WRITABLE` | Path parent missing or write denied | 403 | user-fix | warn | stable (public API) |
+| `WORKSPACE_UNINITIALIZED` | Workspace adapter/store not initialized yet | 503 | retry | warn | stable (public API) |
+| `BWRAP_UNAVAILABLE` | `bwrap` binary not found | 500 | report-bug | error | stable (public API) |
+| `BWRAP_TIMEOUT` | Sandbox command exceeded timeout | 408 | retry | warn | stable (public API) |
+| `OUTPUT_TRUNCATED` | Max output bytes reached; output was clipped | 200 | user-fix | warn | stable (public API) |
+| `SANDBOX_NOT_READY` | Remote sandbox cold start / provisioning | 503 | retry | warn | stable (public API) |
+| `SANDBOX_EXPIRED` | Remote sandbox TTL elapsed | 410 | retry | warn | stable (public API) |
+| `VERCEL_API_ERROR` | Generic upstream Vercel SDK/API failure | 502 | retry | error | stable (public API) |
+| `CIRCUIT_OPEN` | Circuit breaker open; request fast-failed | 503 | retry | warn | stable (public API) |
+| `ABORTED` | Request cancelled via `AbortSignal` | 499 | retry | warn | stable (public API) |
+| `SESSION_NOT_FOUND` | Session id does not exist | 404 | user-fix | warn | stable (public API) |
+| `SESSION_LOCKED` | Session currently locked by concurrent writer | 409 | retry | warn | stable (public API) |
+| `STREAM_BUFFER_EVICTED` | Resume cursor evicted from in-memory stream buffer | 410 | retry | warn | stable (public API) |
+| `CURSOR_OUT_OF_RANGE` | Resume cursor invalid/out of range | 416 | user-fix | warn | stable (public API) |
+| `BRIDGE_COMMAND_INVALID` | UI bridge command kind/params invalid | 400 | user-fix | warn | stable (public API) |
+| `TOOL_NOT_FOUND` | Requested tool name not present in catalog | 404 | user-fix | warn | stable (public API) |
+| `TOOL_INVALID_INPUT` | Tool input fails schema validation | 400 | user-fix | warn | stable (public API) |
+| `TOOL_EXECUTION_ERROR` | Tool threw or returned execution failure | 500 | report-bug | error | stable (public API) |
+| `PLUGIN_LOAD_FAILED` | Plugin failed to load/register | 500 | report-bug | error | stable (public API) |
+| `PLUGIN_NAME_COLLISION` | Plugin name collides with existing tool/plugin | 409 | user-fix | warn | stable (public API) |
+| `INTERNAL_ERROR` | Catch-all internal failure | 500 | report-bug | error | internal (may change) |

package/docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,100 @@
+# Known Limitations
+
+## Abandoned Vercel sandboxes (xzr)
+
+`@boring/agent` v1 intentionally does **not** implement a session-close release hook.
+If a process crashes or a client disappears before cleanup, the sandbox may remain
+alive until Vercel timeout/TTL.
+
+### Failure modes that can orphan a sandbox
+
+- Backend crash or `kill -9` before cleanup path runs.
+- Cross-process/session abort where the owning process never executes `stop()`.
+- Browser tab close/network drop where `beforeunload` is unreliable.
+- Multi-process deployments where one worker creates sandboxes and a different
+  worker handles later traffic.
+
+### Cost exposure (from `4vl` model)
+
+See [VERCEL_COSTS.md](./VERCEL_COSTS.md) for full assumptions.
+
+| Policy / behavior | Estimated cost per workspace per day |
+|---|---:|
+| Stop on session end | `$0.0822` |
+| Idle-stop after 60 min | `$0.1246` |
+| No explicit stop (5h timeout) | `$0.4638` |
+| Pinned 24h workspace | `$2.0750` |
+
+Implication: memory wall-clock billing dominates. Orphans are tolerable at low
+volume but become expensive if idle lifetimes grow.
+
+### v1 monitoring + operations guidance
+
+- Set Vercel spend/budget alerts on the team account (monthly threshold chosen
+  by owner; start low and tighten with observed traffic).
+- Use `[sandbox]` logs for daily create/stop drift checks.
+  - Create log: `"[sandbox] created"` with `workspaceId`, `sandboxId`,
+    `estimatedAbandonedSessionCostUsd`.
+  - Stop log (orphan guard): `"[sandbox] stopped"` with
+    `reason: "orphan-guard-idle"`.
+- Compare create vs stop counts in logs:
+
+```bash
+grep -c "\\[sandbox\\] created" /var/log/boring-agent.log
+grep -c "\\[sandbox\\] stopped" /var/log/boring-agent.log
+```
+
+- Manual cleanup workflow:
+
+```bash
+vercel sandbox list --team <team-id>
+vercel sandbox stop <sandbox-id> --team <team-id>
+```
+
+### Trigger to build full mitigation
+
+Implement release-on-close lifecycle when either trigger is hit:
+
+1. First user reports unexpected Vercel bill attributable to orphaned sandboxes.
+2. Monitoring shows `> 10` apparently abandoned sandboxes at peak.
+
+### Pre-designed mitigation path (deferred)
+
+1. Browser `beforeunload` best-effort call to release endpoint.
+2. Backend idle timer (`~10 min`) that calls `sandbox.stop()` when no traffic.
+3. Explicit CLI/server flag for forced idle-stop policy.
+
+v1 status: **accepted risk**, documented and monitored.
+
+## GitHub Connect + `/api/v1/git/*` deferred to v1.x (nfx)
+
+Git HTTP routes are intentionally not shipped in v1. Both `@boring/agent` v1
+and `@boring/workspace` v1 dropped git UI consumers, so `/api/v1/git/*` would
+be dead code today.
+
+### Current v1 behavior
+
+- Git operations run through the existing `bash` tool (`git status`, `git add`,
+  `git commit`, etc.).
+- No GitHub Connect token flow is wired into agent HTTP routes yet.
+
+### Why this is deferred
+
+- No first-party UI consumer exists yet (status bar, diff pane, git badges).
+- The design is non-trivial enough to avoid shipping unused backend surface.
+- Deferring keeps v1 smaller while preserving a clear activation path.
+
+### Planned migration path once a consumer lands
+
+1. Add `/api/v1/git/*` thin wrappers over `sandbox.exec('git ...')` with output
+   parsing.
+2. Add GitHub Connect credential injection for remote mode
+   (`https://x-access-token:$TOKEN@github.com/...`).
+3. Emit `data-git-changed` SSE invalidation events after write operations.
+4. Seed git config (`user.name`, `user.email`) when a sandbox workspace is
+   created.
+
+### Trigger to implement
+
+Ship when any UI consumer lands (agent v1.x git status/diff UI, or workspace
+reintroducing git badges/panels).

package/docs/MIGRATION.md

@@ -0,0 +1,50 @@
+# MIGRATION
+
+Migration notes for moving from legacy monorepo-integrated agent flows to
+`@boring/agent` in v2.
+
+## What Changes
+
+v1-style app code typically mixed these concerns in one place:
+
+- Chat UI
+- Tool catalog wiring
+- Filesystem behavior
+- Sandbox/process execution
+
+In v2, split responsibilities are intentional:
+
+- `@boring/agent`: runtime contracts + tool/harness/sandbox layers.
+- `@boring/workspace`: IDE-style layout package (frontend-only).
+- App shell: final composition, mode selection, and product policy.
+
+## Practical Migration Steps
+
+1. Move chat/runtime logic into `@boring/agent` integration points.
+2. Keep editor/file-tree/layout code in `@boring/workspace` or your own UI.
+3. Route all filesystem and command execution through runtime mode adapters.
+4. Replace ad-hoc shared types with imports from `@boring/agent/shared`.
+5. Keep server-only code in server entry points; avoid server imports in
+   frontend/shared paths.
+
+## Runtime Mode Migration
+
+Current scaffold status:
+
+- `direct` mode is available.
+- `local` (`bwrap`) and `vercel-sandbox` are planned.
+
+If you are migrating today, target `direct` first and keep your integration
+surface mode-agnostic so later adapter swaps are non-breaking.
+
+## Contract Hygiene Checklist
+
+- No `node:*` imports in `src/shared/**`.
+- No `Buffer` in shared contracts (`Uint8Array` only).
+- Keep UI commands flowing through `UiBridge.postCommand`.
+- Keep session/tool/workspace behavior aligned with `@boring/agent/shared`.
+
+## References
+
+- Agent spec + migration design rationale: `docs/plans/agent-package-spec.md`
+- README quickstart/context: `../README.md`

package/docs/PERFORMANCE.md

@@ -0,0 +1,68 @@
+# Performance
+
+## Vercel Sandbox cold-start benchmark (2026-04-23)
+
+> **Note:** The benchmark harness script has been removed from the repository. The results below are preserved for historical reference.
+
+### Method
+
+- Region: `iad1` (Vercel default for this team/project).
+- Runtime: `python3.13`.
+- Iterations: `10` per scenario.
+- Readiness metric: elapsed time from `Sandbox.create(...)` start to first successful `runCommand('echo hi')`.
+- Scenarios:
+  - `source: empty`
+  - `source: tarball` (small npm tarball URL)
+  - `source: snapshot` (pre-baked snapshot)
+
+Command used:
+
+```bash
+pnpm --filter @boring/agent run bench:vercel-cold-start -- \
+  --iterations 10 \
+  --runtime python3.13 \
+  --snapshot-id <snapshot-id>
+```
+
+### Results (clean sample set)
+
+The clean rollup uses `empty` + `tarball` from the full run and `snapshot`
+from a dedicated snapshot-only rerun, because the first full run hit a Vercel
+creation API throttle (`429`, 10-minute retry-after) on snapshot iteration 1.
+
+#### Time to ready (`create` + first command)
+
+| Scenario | p50 | p95 | p99 |
+|---|---:|---:|---:|
+| source: empty | 398 ms | 680 ms | 680 ms |
+| source: tarball | 715 ms | 880 ms | 880 ms |
+| source: snapshot | 1.81 s | 2.19 s | 2.19 s |
+
+#### `Sandbox.create(...)` only
+
+| Scenario | p50 | p95 | p99 |
+|---|---:|---:|---:|
+| source: empty | 216 ms | 499 ms | 499 ms |
+| source: tarball | 542 ms | 696 ms | 696 ms |
+| source: snapshot | 200 ms | 357 ms | 357 ms |
+
+### Conclusion
+
+- Snapshot creation itself is faster than tarball creation (`create` p50: 200 ms
+  vs 542 ms), but end-to-end readiness is slower in this run (`ready` p50:
+  1.81 s vs 715 ms), so the expected “snapshot is 10x faster” effect was not
+  observed.
+- Against the UX budget rule for cold start (`p95 > 3s => async polling UI`):
+  measured cold-start p95 values are all `< 3s`, so a standard spinner is
+  sufficient for nominal startup latency.
+- Independent of cold-start latency, the platform creation rate limit can add
+  multi-minute waits (`429` with `Retry-After: 600`), so the UI should still
+  handle long provisioning states gracefully when API throttling occurs.
+
+### Follow-up
+
+- Re-run this benchmark on the recommended three windows (morning, afternoon,
+  evening UTC) to check diurnal variance and confirm whether snapshot readiness
+  remains slower than tarball readiness in steady state.
+- If this pattern persists, revisit the M2 vercel-sandbox design assumption
+  that snapshot boot is the fastest production path for first-command latency.

package/docs/PLUGINS.md

@@ -0,0 +1,108 @@
+# PLUGINS
+
+Plugin and extension notes for `@boring/agent`.
+
+## Current Status
+
+The full plugin runtime is not shipped yet in this scaffold.
+
+Today:
+
+- Tool contracts are defined in `src/shared/tool.ts`.
+- Runtime catalog/harness integration is still under active implementation.
+
+## Planned Integration Model
+
+The intended extension seam is "register additional tools into the catalog"
+without modifying core runtime internals.
+
+Each tool should provide:
+
+- Stable `name`
+- Clear `description`
+- JSON-schema `parameters`
+- Async `execute(params, ctx)` implementation
+
+`ctx` is expected to carry:
+
+- `abortSignal`
+- `toolCallId`
+- Optional progress callbacks (`onUpdate`)
+
+## Safety + Compatibility Rules
+
+- Validate all plugin input against schema before execution.
+- Return deterministic, serializable output structures for reliable rendering.
+- Keep plugin-side filesystem and process behavior behind the selected runtime
+  mode adapter (do not bypass the agent runtime boundary).
+- Avoid `node:*` imports in shared/frontend code paths.
+
+## Tool Name Collisions
+
+Collision precedence is explicit: last-registered wins.
+
+- Built-in catalog tools are registered first.
+- App `extraTools` are registered next.
+- Plugin tools are registered last.
+
+If a plugin reuses an existing tool name (for example `bash`), the plugin tool
+replaces the earlier one and a warning is logged:
+
+`[catalog] Tool "bash" overridden by plugin <name>`
+
+### Plugin vs Plugin collisions
+
+If two plugins register the same tool name:
+
+- the later plugin registration wins
+- a warning is logged for the override
+- startup does **not** fail; no hard error is thrown
+
+The rule is implemented in `mergeTools` and is applied uniformly whether the
+previous tool came from built-ins, `extraTools`, or another plugin.
+
+## Discovery Sources (direct/local)
+
+In `direct` and `local` mode, plugin discovery can load tools from:
+
+- `~/.pi/agent/extensions/*.js|*.mjs` (global)
+- `<workspace>/.pi/extensions/*.js|*.mjs` (local)
+- `<workspace>/node_modules/pi-plugin-*` packages
+- `<workspace>/.pi/extensions.json` `npm` entries (if installed in `node_modules`)
+
+## `vercel-sandbox` Mode Caveat
+
+`createAgentApp` disables automatic plugin loading when runtime mode is
+`vercel-sandbox`. This is intentional: plugin files are discovered via host
+Node filesystem access, while sandbox workspace/exec are remote.
+
+Practical effect:
+
+- Plugin auto-discovery is enabled in `direct` and `local`.
+- Plugin auto-discovery is disabled in `vercel-sandbox`.
+
+## Manual Packaging Pattern For `vercel-sandbox`
+
+If you still need extension-like behavior in `vercel-sandbox`, package files
+manually into the workspace image/template used to create the sandbox:
+
+- include `.pi/extensions/*` in your source template
+- ensure files exist at `/vercel/sandbox/.pi/extensions/` in the remote workspace
+- load/register tools through your app-shell bootstrap (not package auto-discovery)
+
+Use the same template-seeding concept as local provisioning (for example
+`templatePath`/`BORING_AGENT_TEMPLATE_PATH` workflows), but apply it when you
+build the sandbox source/snapshot consumed by Vercel.
+
+## Environment Differences
+
+When porting plugins from host modes to `vercel-sandbox`, expect differences:
+
+- available binaries and OS tools can differ from host machine
+- root/path assumptions differ (`/vercel/sandbox` workspace root)
+- process/network policy can differ from local development
+
+## References
+
+- Canonical design: `docs/plans/agent-package-spec.md`
+- Minimal integration sketch: `examples/with-custom-tool/README.md`

package/docs/README.md

@@ -0,0 +1,17 @@
+# @boring/agent Docs
+
+This folder contains user-facing package docs for `@boring/agent`.
+
+## Start Here
+
+- [API](./API.md) — current export surface and contract status.
+- [STYLING](./STYLING.md) — CSS-variable theming contract and guardrails.
+- [PLUGINS](./PLUGINS.md) — extension model and runtime-mode caveats.
+- [MIGRATION](./MIGRATION.md) — migration guidance for v1-style integrations.
+
+## Scope
+
+These docs track the implementation status of the v2 scaffold and call out
+roadmap-only APIs explicitly to avoid over-promising.
+
+For canonical design context, see `./plans/agent-package-spec.md`.

package/docs/RISKS-MULTI-TAB.md

@@ -0,0 +1,46 @@
+# Multi-Tab Concurrency Risk
+
+## Scope
+
+This note documents current `@boring/agent` behavior when two browser tabs
+point at the same workspace and edit the same file.
+
+## Observed Behavior (v1)
+
+- There is no workspace-level lock and no per-file lock.
+- `POST /api/v1/files` performs an unconditional write.
+- There is no optimistic concurrency precondition (no ETag/version check,
+  no `If-Match` handling).
+- Result: writes are silent last-write-wins. A stale tab can overwrite a newer
+  edit without a conflict response.
+
+This is visible in route code:
+- [file.ts](../src/server/http/routes/file.ts) calls `workspace.writeFile(...)`
+  directly.
+- [createNodeWorkspace.ts](../src/server/workspace/createNodeWorkspace.ts)
+  calls Node `writeFile(...)` without revision guards.
+
+Behavior is exercised by:
+- [file.test.ts](../src/server/http/routes/__tests__/file.test.ts)
+  `multi-tab stale write overwrites newer content (last write wins)`.
+
+## Session Semantics
+
+- Tabs are not treated as exclusive owners of a workspace.
+- Session identity is driven by `sessionId`; multiple tabs can operate against
+  the same workspace concurrently.
+
+## Known User Impact
+
+- Lost-update risk for simultaneous edits on the same path.
+- No explicit error or merge prompt when overwrite happens.
+
+## Future Mitigation Seam
+
+Introduce optimistic write preconditions:
+
+1. `GET /api/v1/files` returns a version token (for example ETag/content hash +
+   mtime).
+2. `POST /api/v1/files` accepts `If-Match` and rejects mismatched versions with
+   `409 Conflict`.
+3. Frontend handles `409` with refresh/retry UX instead of silent overwrite.