@hachej/boring-agent 0.1.41 → 0.1.42

package/dist/shared/index.d.ts

@@ -1,5 +1,5 @@
-import { W as Workspace, S as Sandbox, F as FileSearch, A as AgentTool } from '../agentPluginEvents-CKrZLW3g.js';
-export { a as AgentHarness, C as CommandNotifyPayload, E as Entry, b as ExecOptions, c as ExecResult, I as IsolatedCodeInput, d as IsolatedCodeOutput, J as JSONSchema, R as RunContext, e as SandboxCapability, f as SandboxHandleRecord, g as SandboxHandleStore, h as SendMessageInput, i as Stat, T as TelemetryEvent, j as TelemetrySink, k as ToolExecContext, l as ToolResult, m as WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT, n as WORKSPACE_COMMAND_NOTIFY_EVENT, o as WorkspaceRuntimeContext, p as noopTelemetry, s as safeCapture } from '../agentPluginEvents-CKrZLW3g.js';
+import { W as Workspace, S as Sandbox, F as FileSearch, A as AgentTool } from '../agentPluginEvents-ZoOjcb5J.js';
+export { a as AgentHarness, C as CommandNotifyPayload, E as Entry, b as ExecOptions, c as ExecResult, I as IsolatedCodeInput, d as IsolatedCodeOutput, J as JSONSchema, R as RunContext, e as SandboxCapability, f as SandboxHandleRecord, g as SandboxHandleStore, h as SendMessageInput, i as Stat, T as TelemetryEvent, j as TelemetrySink, k as ToolExecContext, l as ToolResult, m as WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT, n as WORKSPACE_COMMAND_NOTIFY_EVENT, o as WorkspaceRuntimeContext, p as noopTelemetry, s as safeCapture } from '../agentPluginEvents-ZoOjcb5J.js';
 import { B as BoringChatPart, T as ToolUiMetadata } from '../piChatEvent-Ck1BAE_m.js';
 export { A as ApiErrorPayload, a as ApiErrorPayloadSchema, b as ApiErrorResponse, c as ApiErrorResponseSchema, d as BoringChatMessage, C as ChatAttachmentPayload, e as ChatError, f as ChatModelSelection, g as ChatSubmitPayload, h as CommandReceipt, E as ERROR_CODES, i as ErrorCode, j as ErrorLogFields, k as ErrorLogFieldsSchema, F as FollowUpPayload, l as FollowUpReceipt, I as InterruptPayload, m as InterruptReceipt, P as PiChatEvent, n as PiChatHeartbeatFrame, o as PiChatSnapshot, p as PiChatStatus, q as PiChatStreamFrame, r as PromptPayload, s as PromptReceipt, Q as QueueClearPayload, t as QueueClearReceipt, u as QueuedUserMessage, S as StopPayload, v as StopReceipt, w as ThinkingLevel, x as extractToolUiMetadata, y as isToolUiMetadata } from '../piChatEvent-Ck1BAE_m.js';
 export { S as SessionCtx, a as SessionDetail, b as SessionStore, c as SessionSummary } from '../session-BRovhe0D.js';

package/docs/ACCESSIBILITY.md

@@ -1,23 +1,22 @@
 # Accessibility Audit
 
-This document tracks accessibility status for `@boring/agent` UI surfaces.
+This document tracks accessibility status for `@hachej/boring-agent` UI surfaces.
 
-## Scope (boring-ui-v2-cop)
+## Scope
 
-- `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`)
+- `packages/agent/src/front/chat/PiChatPanel.tsx` (the `ChatPanel` export)
+- `packages/agent/src/front/primitives/*` (chat primitives)
+- CI browser check via the `apps/agent-playground` dev frontend
 
 ## Current Coverage
 
 ### Landmarks and live regions
 
-- ChatPanel roots now expose `role="region"` with
-  `aria-label="Agent assistant"` in both front variants.
+- The ChatPanel root exposes `role="region"` with
+  `aria-label="Agent assistant"`.
 - Message streams expose `role="log"` and `aria-live="polite"` as
   `aria-label="Agent conversation"`.
-- Error states are announced with `role="alert"` in both variants.
+- Error states are announced with `role="alert"`.
 
 ### Interactive control names
 
@@ -28,8 +27,7 @@ This document tracks accessibility status for `@boring/agent` UI surfaces.
 ### Automated checks
 
 - Unit checks:
-  - `src/front/__tests__/ChatPanel.test.tsx`
-  - `src/front-shadcn/__tests__/ChatPanel.test.tsx`
+  - `src/front/chat/__tests__/PiChatPanel.test.tsx`
 - Browser axe check:
   - `packages/agent/e2e/a11y.spec.ts`
   - Fails on any **serious** or **critical** violation inside
@@ -44,12 +42,12 @@ This runs in CI automatically through the existing `pnpm e2e` job.
    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`.
+   outside this package and need dedicated coverage in `@hachej/boring-workspace`.
 3. Manual screen-reader validation (VoiceOver/NVDA) is still pending.
 
 ## Next Increment
 
-1. Stand up Storybook for `@boring/agent` primitives.
+1. Stand up Storybook for `@hachej/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

@@ -1,64 +1,91 @@
 # API
 
-This file documents the package API as it exists today in the v2 scaffold.
-Roadmap-only APIs are explicitly marked.
+The package exposes four entry points. Browser code imports the top-level (or
+`/front`) barrel; Node servers import `/server`; both share types from
+`/shared`. The eval toolkit ships under `/eval`.
 
 ## 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.
+| Import | Environment | Source barrel |
+|---|---|---|
+| `@hachej/boring-agent` | Browser | `src/front/index.ts` (alias of `/front`) |
+| `@hachej/boring-agent/front` | Browser | `src/front/index.ts` |
+| `@hachej/boring-agent/front/styles.css` | Browser | precompiled CSS |
+| `@hachej/boring-agent/server` | Node | `src/server/index.ts` |
+| `@hachej/boring-agent/shared` | Any | `src/shared/index.ts` |
+| `@hachej/boring-agent/eval` | Node | `src/eval/index.ts` |
+
+## `@hachej/boring-agent/front`
+
+The styled chat UI and its building blocks. Key exports:
+
+- `ChatPanel` (alias of `PiChatPanel`) — the pane-embeddable chat component.
+  Props include `apiBaseUrl`, `sessionId`, and `toolRenderers`. See
+  `src/front/chat/PiChatPanel.tsx`.
+- `usePiSessions` and session helpers (`readActiveSessionId`,
+  `writeActiveSessionId`, `PiSessionList`, `PiSessionBrowser`).
+- Slash-command surface: `builtinCommands`, `createCommandRegistry`,
+  `parseSlashCommand`, `getAgentCommands`.
+- Tool renderers: `defaultToolRenderers`, `mergeToolRenderers`,
+  `resolveToolRenderer`, `mergeShadcnToolRenderers`, `ToolCallGroup`.
+- Primitives (`Message`, `Conversation`, `Reasoning`, `CodeBlock`,
+  `PromptInput`, …) and the `cn` class helper.
+- `DebugDrawer`, `ChatEmptyState`, `ArtifactOpenProvider`/`useOpenArtifact`,
+  `uploadFile`.
+
+> Note: there is no `useAgentChat` hook. The chat lifecycle lives inside
+> `ChatPanel`/`PiChatPanel` and the `usePiSessions` hook.
+
+## `@hachej/boring-agent/server`
+
+The Node runtime. Key exports:
+
+- `createAgentApp(opts)` — standalone Fastify factory. Zero dependency on
+  `@hachej/boring-core` or `@hachej/boring-workspace`. See
+  `src/server/createAgentApp.ts`.
+- `registerAgentRoutes(app, opts)` — mounts the agent HTTP routes onto an
+  existing Fastify instance (used by `@hachej/boring-workspace`). Paths are
+  absolute under `/api/v1/agent/*`, `/api/v1/files`, etc.
+- Sandbox adapters: `createDirectSandbox`, `createBwrapSandbox`, plus the
+  Vercel sandbox/snapshot helpers (`createVercelSandboxWorkspace`,
+  `bakeSnapshotIfNeeded`, deployment-snapshot providers, `FileHandleStore`).
+- Workspace adapters: `createNodeWorkspace`, `createVercelSandboxWorkspace`.
+- Mode resolution: `autoDetectMode`, `resolveMode`, `hasBwrap`. Custom execution backends are injected via the `runtimeModeAdapter` option — see [runtime.md §Adding a custom runtime mode](./runtime.md#adding-a-custom-runtime-mode).
+- Provisioning: `provisionRuntimeWorkspace`, `provisionWorkspaceRuntime`,
+  `getBoringAgentRuntimePaths`, `getBoringAgentRuntimeEnv`,
+  `createVercelProvisioningAdapter`.
+- HTTP/CSP: `applyCspHeaders`; `fileRoutes` for mounting file routes alone.
+- Harness: `createResourceSettingsManager` and the Pi harness option types.
+- `createLogger`.
+
+## `@hachej/boring-agent/shared`
+
+Platform-agnostic contracts (types + zod schemas). Source of truth for the
+public interfaces:
+
+- `harness.ts` — `AgentHarness`, `SendMessageInput`, `RunContext`,
+  `AgentHarnessFactory`.
+- `tool.ts` / `tool-ui.ts` — `AgentTool`, `ToolExecContext`, `ToolResult`,
+  `JSONSchema`, `ToolUiMetadata`.
+- `workspace.ts` — `Workspace`, `Entry`, `Stat`.
+- `sandbox.ts` — `Sandbox`, `SandboxCapability`, `ExecOptions`, `ExecResult`.
+- `catalog.ts` — `CatalogDeps`, `ToolCatalog`.
+- `session.ts` — `SessionStore`, `SessionSummary`, `SessionDetail`.
+- `config-schema.ts` — `ConfigSchema`, `EnvSchema`, `RuntimeModeSchema`,
+  `validateConfig`.
+- `error-codes.ts` — `ErrorCode`, `ERROR_CODES`, error-envelope schemas
+  (see [ERROR_CODES.md](./ERROR_CODES.md)).
+- `chat.ts` — `BoringChatMessage`, `PiChatEvent`, stream/snapshot frames and
+  their zod schemas.
+- `capabilities.ts`, `telemetry.ts`, `runtime.ts`, `sandbox-handle-store.ts`,
+  `validateTool.ts`, `agentPluginEvents.ts`.
+
+> There is no `ui-bridge.ts` or `message.ts` in `shared/`. UI-bridge tools
+> (`exec_ui`, `get_ui_state`) and their types now live in
+> `@hachej/boring-workspace` — `createAgentApp` ships zero UI tools by design.
+
+## Deferred HTTP Git Surface
+
+`/api/v1/git/*` routes exist but are intentionally thin/minimal: there is no
+first-party git UI consumer in the agent today, so git operations run through
+the `bash` tool. See [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md).

package/docs/CSP.md

@@ -1,6 +1,6 @@
 # CSP Compatibility
 
-`@boring/agent` is compatible with a strict CSP, with one required exception:
+`@hachej/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.
 
@@ -20,13 +20,14 @@ Content-Security-Policy:
 
 - `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`.
+  (`ChatPanel` + example apps).
+- Server helper `applyCspHeaders` lives at `src/server/http/csp.ts` (exported
+  from `@hachej/boring-agent/server`); example servers consume it via
+  `examples/csp.ts`.
 
-## Audited Scope (tv4)
+## Audited Scope
 
-- `src/front/ChatPanel.tsx`
+- `src/front/chat/PiChatPanel.tsx`
 - `examples/with-custom-tool/*`
 - `apps/agent-playground/*`
 
@@ -35,6 +36,6 @@ Content-Security-Policy:
 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.
+style injection across the full stack. The 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

@@ -1,6 +1,6 @@
 # ERROR_CODES
 
-Canonical registry for stable `@boring/agent` error codes.
+Canonical registry for stable `@hachej/boring-agent` error codes.
 
 All API failures must use the response envelope:
 

package/docs/KNOWN_LIMITATIONS.md

@@ -2,7 +2,7 @@
 
 ## Abandoned Vercel sandboxes (xzr)
 
-`@boring/agent` v1 intentionally does **not** implement a session-close release hook.
+`@hachej/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.
 
@@ -68,8 +68,8 @@ 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
+Git HTTP routes are intentionally not shipped in v1. Both `@hachej/boring-agent` v1
+and `@hachej/boring-workspace` v1 dropped git UI consumers, so `/api/v1/git/*` would
 be dead code today.
 
 ### Current v1 behavior

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # MIGRATION
 
 Migration notes for moving from legacy monorepo-integrated agent flows to
-`@boring/agent` in v2.
+`@hachej/boring-agent` in v2.
 
 ## What Changes
 
@@ -14,37 +14,37 @@ v1-style app code typically mixed these concerns in one place:
 
 In v2, split responsibilities are intentional:
 
-- `@boring/agent`: runtime contracts + tool/harness/sandbox layers.
-- `@boring/workspace`: IDE-style layout package (frontend-only).
+- `@hachej/boring-agent`: agent runtime, tool catalog, harness, sandbox/workspace
+  adapters, and the chat UI (`ChatPanel`).
+- `@hachej/boring-workspace`: IDE-style layout/panes plus the UI-bridge tools
+  (`exec_ui`, `get_ui_state`) and `/api/v1/ui/*` routes.
 - 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.
+1. Move chat/runtime logic into `@hachej/boring-agent` integration points.
+2. Keep editor/file-tree/layout code in `@hachej/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`.
+4. Replace ad-hoc shared types with imports from `@hachej/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.
+All three modes ship: `direct`, `local` (`bwrap`), and `vercel-sandbox`. Select
+via `mode` in `createAgentApp` or the `BORING_AGENT_MODE` env var. Keep your
+integration surface mode-agnostic so adapter swaps are non-breaking. See
+[runtime.md](./runtime.md).
 
 ## 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`.
+- Keep session/tool/workspace behavior aligned with `@hachej/boring-agent/shared`.
 
 ## References
 
-- Agent spec + migration design rationale: `docs/plans/agent-package-spec.md`
+- Runtime modes: [runtime.md](./runtime.md)
+- API surface: [API.md](./API.md)
 - README quickstart/context: `../README.md`
+- Historical design notes: `docs/plans/archive/` (archival; not current truth)

package/docs/PERFORMANCE.md

@@ -18,7 +18,7 @@
 Command used:
 
 ```bash
-pnpm --filter @boring/agent run bench:vercel-cold-start -- \
+pnpm --filter @hachej/boring-agent run bench:vercel-cold-start -- \
   --iterations 10 \
   --runtime python3.13 \
   --snapshot-id <snapshot-id>

package/docs/PLUGINS.md

@@ -1,22 +1,27 @@
 # PLUGINS
 
-Plugin and extension notes for `@boring/agent`.
+Plugin and extension notes for `@hachej/boring-agent`.
 
-## Current Status
+## Two extension paths
 
-The full plugin runtime is not shipped yet in this scaffold.
+There are two ways to extend the agent, depending on host integration:
 
-Today:
+1. **Pi-native resources** (`package.json#pi`: `extensions`, `skills`,
+   `prompts`, `systemPrompt`) — discovered by the Pi harness in `direct`/`local`
+   mode and reloadable through `/reload`. This is the right place for portable,
+   hot-reloadable tools and skills. See [tools.md](./tools.md).
+2. **Trusted server plugins** (`@hachej/boring-workspace` `defineServerPlugin`)
+   — static/boot-time `agentTools`, routes, and provisioning declared by trusted
+   server code. See [tools.md](./tools.md) and
+   [runtime-provisioning.md](./runtime-provisioning.md).
 
-- Tool contracts are defined in `src/shared/tool.ts`.
-- Runtime catalog/harness integration is still under active implementation.
+Both paths converge on the same `AgentTool` contract
+(`src/shared/tool.ts`). The standalone `createAgentApp` ships no UI tools;
+`exec_ui`/`get_ui_state` and UI routes are owned by `@hachej/boring-workspace`.
 
-## Planned Integration Model
+## Tool contract
 
-The intended extension seam is "register additional tools into the catalog"
-without modifying core runtime internals.
-
-Each tool should provide:
+Each tool provides:
 
 - Stable `name`
 - Clear `description`
@@ -29,6 +34,22 @@ Each tool should provide:
 - `toolCallId`
 - Optional progress callbacks (`onUpdate`)
 
+Optional fields:
+
+- `readinessRequirements?: ToolReadinessRequirement[]` — gates the tool on
+  runtime readiness. `mergeTools` assigns `['workspace-fs']` to plugin tools
+  that omit it (built-in/`extraTools` tools keep whatever they declare).
+- `promptSnippet?` — extra guidance injected into the system prompt when the
+  tool is registered.
+
+## Trust & runtime modes
+
+Plugin tools' `execute()` run in the **host Node process** and bypass the
+sandbox by design — treat plugin code as trusted local/workspace code. Plugin
+auto-discovery is local-mode-only (see the `vercel-sandbox` caveat below). For
+the full internal-vs-external plugin trust model, see
+`packages/workspace/docs/PLUGIN_SYSTEM.md` §1.1.
+
 ## Safety + Compatibility Rules
 
 - Validate all plugin input against schema before execution.
@@ -63,6 +84,12 @@ previous tool came from built-ins, `extraTools`, or another plugin.
 
 ## Discovery Sources (direct/local)
 
+This section describes **Pi-native resource discovery** at the harness level.
+Workspace runtime/generated plugins are a higher-level package format under
+`.pi/extensions/<id>/package.json` documented in
+`packages/workspace/docs/PLUGIN_SYSTEM.md`; those packages may themselves
+declare `pi.extensions` resources.
+
 In `direct` and `local` mode, plugin discovery can load tools from:
 
 - `~/.pi/agent/extensions/*.js|*.mjs` (global)
@@ -104,5 +131,8 @@ When porting plugins from host modes to `vercel-sandbox`, expect differences:
 
 ## References
 
-- Canonical design: `docs/plans/agent-package-spec.md`
+- Adding tools: [tools.md](./tools.md)
+- Chat `/slash` commands as a plugin surface:
+  `packages/workspace/docs/PLUGIN_SYSTEM.md` §4.7
 - Minimal integration sketch: `examples/with-custom-tool/README.md`
+- Historical design notes: `docs/plans/archive/` (archival; not current truth)

package/docs/README.md

@@ -1,18 +1,95 @@
-# @boring/agent Docs
+# @hachej/boring-agent Docs
 
-This folder contains user-facing package docs for `@boring/agent`.
+`@hachej/boring-agent` is a pane-embeddable coding agent: an LLM agent loop, a
+tool catalog, and a chat UI, with swappable execution backends. The same agent,
+tools, and UI run in three modes — `direct` (host process), `local` (bwrap
+sandbox), and `vercel-sandbox` (Firecracker microVM) — selected at construction.
+It is consumed two ways: standalone via `createAgentApp` (Fastify server +
+`ChatPanel`), or mounted into `@hachej/boring-workspace` for the full IDE shell.
 
-## Start Here
+## Architecture
 
-- [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.
-- [runtime](./runtime.md) — runtime cwd contract, `.boring-agent/` layout, provisioning examples, and doctor diagnostics.
-- [MIGRATION](./MIGRATION.md) — migration guidance for v1-style integrations.
+```
+Chat UI (ChatPanel / front)
+   │  pi-chat SSE stream
+Agent HTTP routes (registerAgentRoutes / createAgentApp)
+   │
+Agent harness (pi-coding-agent loop)  ── Tool catalog (AgentTool[])
+   │                                          │
+Workspace (filesystem)            Sandbox (command execution)
+```
 
-## Scope
+- **front** (`src/front`) — `ChatPanel` (= `PiChatPanel`), primitives, slash
+  commands, tool renderers, session hooks. Browser-only.
+- **server** (`src/server`) — `createAgentApp`, `registerAgentRoutes`, the Pi
+  harness adapter, sandbox/workspace adapters, runtime provisioning, model
+  config, HTTP routes. Node-only.
+- **shared** (`src/shared`) — platform-agnostic contracts and zod schemas
+  (`AgentHarness`, `Workspace`, `Sandbox`, `AgentTool`, `SessionStore`, chat
+  frames, error codes).
+- **eval** (`src/eval`) — agent-behavior evaluation toolkit.
 
-These docs track the implementation status of the v2 scaffold and call out
-roadmap-only APIs explicitly to avoid over-promising.
+Data flow: the browser opens a pi-chat SSE stream; the server drives the
+pi-coding-agent harness; tools resolve filesystem ops through the `Workspace`
+adapter and shell/exec through the `Sandbox` adapter. Workspace + Sandbox must
+target the same filesystem substrate (the mode adapter enforces the pairing).
 
-For canonical design context, see `./plans/agent-package-spec.md`.
+## Key abstractions
+
+The public surfaces a consumer or extender touches (all in
+`@hachej/boring-agent/shared` unless noted):
+
+- `AgentHarness` — the agent loop interface; pi-coding-agent is the v1 impl.
+- `Workspace` / `Sandbox` — filesystem and command-execution adapters, swapped
+  per mode.
+- `AgentTool` + `CatalogDeps` — the tool contract and the deps tools bind to.
+- `SessionStore` — session listing/lifecycle.
+- `createAgentApp` / `registerAgentRoutes` (`/server`) — entry points to run or
+  embed the server.
+- `ChatPanel` (`/front`) — the embeddable UI.
+
+## Architectural decisions
+
+Locked decisions live in the root [`docs/DECISIONS.md`](../../../docs/DECISIONS.md);
+the agent ↔ workspace boundary is in
+[`docs/WORKSPACE_CONTRACT.md`](../../../docs/WORKSPACE_CONTRACT.md). Highlights:
+
+- Standalone CLI-shaped product; same code embeds into a host shell — decision 1.
+- pi-coding-agent as the v1 harness behind a generic `AgentHarness` — decisions 4–5.
+- `mode = direct | local | vercel-sandbox`; Workspace+Sandbox pairing invariant — decisions 7a–7f.
+- Single Anthropic provider by default, but the model layer also supports custom
+  OpenAI-compatible and Infomaniak providers — decision 10.
+- Plugins extend via Pi resources or trusted server plugins, not core edits — decision 8.
+- Four export surfaces: top-level/`front`, `/server`, `/shared`, `/eval` — decision 15.
+
+## Documentation
+
+**Surfaces & integration**
+
+- [API](./API.md) — the four entry points and what each exports.
+- [STYLING](./STYLING.md) — CSS-variable theming contract and public selectors.
+- [UI-SHADCN](./UI-SHADCN.md) — `ChatPanel` styling model and tool-renderer overrides.
+- [tools](./tools.md) — built-in tools, package-added tools, and how to add custom tools.
+- [PLUGINS](./PLUGINS.md) — the two extension paths and tool-collision rules.
+- [MIGRATION](./MIGRATION.md) — moving legacy integrations to the v2 split.
+
+**Runtime & provisioning**
+
+- [runtime](./runtime.md) — the three modes, the cwd invariant, and `.boring-agent/` layout.
+- [runtime-provisioning](./runtime-provisioning.md) — when provisioning runs, package-authoring shape, trusted server provisioning.
+
+**Contracts & operations**
+
+- [ERROR_CODES](./ERROR_CODES.md) — the stable API error-code registry.
+- [CSP](./CSP.md) — Content-Security-Policy compatibility.
+- [ACCESSIBILITY](./ACCESSIBILITY.md) — a11y coverage and known gaps.
+
+**Risk & cost notes**
+
+- [KNOWN_LIMITATIONS](./KNOWN_LIMITATIONS.md) — accepted risks (orphaned sandboxes, deferred git routes).
+- [RISKS-MULTI-TAB](./RISKS-MULTI-TAB.md) — last-write-wins behavior for concurrent edits.
+- [VERCEL_COSTS](./VERCEL_COSTS.md) — Vercel sandbox cost model.
+- [PERFORMANCE](./PERFORMANCE.md) — historical Vercel cold-start benchmark.
+
+Historical plans and specs live under `docs/plans/archive/` — archival context only, not
+current truth; verify against code before relying on them.

package/docs/RISKS-MULTI-TAB.md

@@ -2,7 +2,7 @@
 
 ## Scope
 
-This note documents current `@boring/agent` behavior when two browser tabs
+This note documents current `@hachej/boring-agent` behavior when two browser tabs
 point at the same workspace and edit the same file.
 
 ## Observed Behavior (v1)

package/docs/STYLING.md

@@ -1,6 +1,8 @@
 # STYLING
 
-Styling contract for `@boring/agent` frontend surfaces.
+Styling contract for `@hachej/boring-agent` frontend surfaces. For the full
+agent/workspace Tailwind isolation model, see
+[`docs/TAILWIND-V4-STYLE-ISOLATION.md`](../../../docs/TAILWIND-V4-STYLE-ISOLATION.md).
 
 ## Package CSS
 
@@ -8,12 +10,12 @@ Consumers import the precompiled package stylesheet once, after host/workspace
 base CSS and before app overrides:
 
 ```ts
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
 import "./app.css"
 ```
 
-The published `@boring/agent/front/styles.css` is consumer-safe: it contains no
+The published `@hachej/boring-agent/front/styles.css` is consumer-safe: it contains no
 Tailwind `@source`, no Tailwind imports, and no repo-relative source paths.
 
 ## Public selectors

package/docs/UI-SHADCN.md

@@ -1,14 +1,14 @@
 # Agent UI
 
-`@boring/agent` exports the pane-embeddable `ChatPanel` and its frontend
+`@hachej/boring-agent` exports the pane-embeddable `ChatPanel` and its frontend
 primitives. The default styled surface is packaged with precompiled CSS.
 
 ## Quickstart
 
 ```tsx
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
-import { ChatPanel } from "@boring/agent"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
+import { ChatPanel } from "@hachej/boring-agent"
 
 function App() {
   return <ChatPanel sessionId="my-session" />
@@ -18,8 +18,8 @@ function App() {
 Import app overrides after the package CSS when customizing:
 
 ```ts
-import "@boring/workspace/globals.css"
-import "@boring/agent/front/styles.css"
+import "@hachej/boring-workspace/globals.css"
+import "@hachej/boring-agent/front/styles.css"
 import "./app.css"
 ```
 
@@ -27,7 +27,7 @@ import "./app.css"
 
 | Concern | Contract |
 |---|---|
-| Package CSS | `@boring/agent/front/styles.css` |
+| Package CSS | `@hachej/boring-agent/front/styles.css` |
 | Root selector | `[data-boring-agent]` |
 | Parts | `[data-boring-agent-part="composer"]`, `[data-boring-agent-part="tool-card"]`, etc. |
 | Message role | `[data-boring-agent-message-role="assistant"]` |