diff --git a/acp.mdx b/acp.mdx
index afd0a97..936234c 100644
--- a/acp.mdx
+++ b/acp.mdx
@@ -14,9 +14,9 @@ it, watch its tool calls and approve them from the editor's agent panel.
 ## The command
 
 ```bash
-npx lousho acp agent.yaml                          # a spec file
-npx lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
+npx @linuxdevil/lousho acp agent.yaml                          # a spec file
+npx @linuxdevil/lousho acp ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho acp src/agent.ts                        # a .ts/.js module (createAgent() options or an agent)
 ```
 
 ```text
@@ -122,7 +122,7 @@ It resolves once `input` ends, after aborting any running turn.
 
 ```ts
 import * as readline from 'node:readline';
-import { createAgent, serveAcp } from 'lousho';
+import { createAgent, serveAcp } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding assistant.' });
 
diff --git a/agent-directories.mdx b/agent-directories.mdx
index 542975d..f21a211 100644
--- a/agent-directories.mdx
+++ b/agent-directories.mdx
@@ -14,7 +14,7 @@ code at any time without a rewrite.
 > implied; the files run with your process's full permissions.
 
 ```ts
-import { loadAgentDir } from 'lousho';
+import { loadAgentDir } from '@linuxdevil/lousho';
 
 const agent = await loadAgentDir('./my-agent');
 const { text } = await agent.send('Hello!');
@@ -111,7 +111,7 @@ rule decides.
 
 ```ts
 // hooks.ts — the default export is a hook or a list of them
-import type { AgentHook } from 'lousho';
+import type { AgentHook } from '@linuxdevil/lousho';
 const audit: AgentHook = {
   name: 'audit',
   postToolCall(ctx) {
@@ -123,7 +123,7 @@ export default audit;
 
 ```ts
 // approve.ts — the default export decides every `ask`ed call
-import type { ApproveToolCall } from 'lousho';
+import type { ApproveToolCall } from '@linuxdevil/lousho';
 const approve: ApproveToolCall = ({ args }) => !String(args.path ?? '').endsWith('.test.js');
 export default approve;
 ```
@@ -148,7 +148,7 @@ that exports no tool at all is an error, as are two tools with the same name
 ```ts
 // tools/send_email.ts
 import { z } from 'zod';
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 
 export default defineTool({
   name: 'send_email',
@@ -239,7 +239,7 @@ internal helper of the generated bundle); with your own server, use
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels, resolveAgentDir } from 'lousho';
+import { createAgent, mountChannels, resolveAgentDir } from '@linuxdevil/lousho';
 
 // channels/support.ts: export default webhookChannel({ secret: process.env.HOOK_SECRET ?? '' })
 const { config, channels } = await resolveAgentDir('./my-agent');
@@ -262,7 +262,7 @@ naming the file. A `memory` override passed to `loadAgentDir(dir, { overrides })
 is merged with the directory's slots by name: the override wins a name clash.
 
 ```ts
-import { defineMemory, fileMemory, resolveAgentDir } from 'lousho';
+import { defineMemory, fileMemory, resolveAgentDir } from '@linuxdevil/lousho';
 
 // memory/notes.ts: export default { scope: 'global', provider: fileMemory({ dir: './.lousho/memory' }) }
 const { manifest } = await resolveAgentDir('./my-agent', {
@@ -276,7 +276,7 @@ A relative `dir` in a `memory/*.ts` file resolves against the process working di
 ```ts
 // memory/notes.ts
 import { fileURLToPath } from 'node:url';
-import { fileMemory } from 'lousho';
+import { fileMemory } from '@linuxdevil/lousho';
 
 export default {
   scope: 'global',
@@ -300,7 +300,7 @@ The path follows the module: a copied or bundled build keeps its memory next to
 handy for tests and tooling:
 
 ```ts
-import { resolveAgentDir, createAgent } from 'lousho';
+import { resolveAgentDir, createAgent } from '@linuxdevil/lousho';
 
 const { config, manifest } = await resolveAgentDir('./my-agent');
 console.log(manifest.tools, manifest.skills, manifest.subagents);
@@ -320,8 +320,8 @@ declares (`guardrails`, `onEvent`, `retry`, `reasoning`, `redactContent`,
 `output`, ...). Use it to swap the model in tests:
 
 ```ts
-import { loadAgentDir } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { loadAgentDir } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = await loadAgentDir('./my-agent', { provider: mockModel(['Hi there.']) });
 ```
@@ -352,7 +352,7 @@ says so. Compile the directory first, or use `.js`/`.mjs` tools with an
 ## Run it with `lousho dev`
 
 ```bash
-npx lousho dev ./my-agent
+npx @linuxdevil/lousho dev ./my-agent
 ```
 
 Serves the chat UI and `POST /chat` for the directory and reloads it when
@@ -371,7 +371,7 @@ dev](/schedules#in-lousho-dev)).
 ## Deploy it with `lousho build`
 
 ```bash
-npx lousho build ./my-agent --target=node-server    # or docker
+npx @linuxdevil/lousho build ./my-agent --target=node-server    # or docker
 ```
 
 The agent directory is the unit of deployment: the built server loads it with
diff --git a/agent-forge.mdx b/agent-forge.mdx
index 5f60db7..e85d14e 100644
--- a/agent-forge.mdx
+++ b/agent-forge.mdx
@@ -1,77 +1,224 @@
 ---
-title: "Agent Forge"
+title: "Lousho Studio"
+description: "Lousho Studio is a local web app for building, testing and watching every agent across your projects."
 ---
-{/* Generated from docs/agent-forge.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/agent-forge.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
-Agent Forge (`apps/agent-forge`, also called the Studio) is this SDK's
-companion dashboard: one app with a left navigation to build and run agents,
-try prompts, and read what your agents did from the observe daemon. Build an
-agent's graph on a canvas, run it, chat with it and author sandboxed
-pre/post hooks (all reading and writing the same `AgentSpec` YAML that
-`lousho dev` and `lousho build` use), try prompts in a playground, and read
-the [observe daemon](/observability#the-observe-daemon)'s traces,
-threads, fleet monitoring, eval scores, datasets, annotation queues, prompt
-registry and context hub. It's launched with one command,
-`lousho studio`, and ships as part of this SDK's npm package.
+It is a separate npm package, `@linuxdevil/studio` — the SDK (`@linuxdevil/lousho`)
+does not contain it. One Studio server shows every agent you have: the spec-v2
+graph agents saved in your project folders, code agents Studio finds by scanning
+a workspace, and agents running anywhere that report to the observe collector.
 
-This doc covers: installation, the `lousho studio` quickstart, the
-[navigation and screens](#navigation), a first-agent walkthrough, hook
-authoring, time travel (replaying a run from a past step), the playground
-endpoint, and how settings/secrets/deploy wiring works.
+This page covers installing and starting Studio, workspaces, which SDK runs a
+workspace's agents (and what each banner means), the collector, and how agents
+deployed on other machines show up here. [Using Studio](#using-studio) covers
+the builder, the playground, traces and the rest of the app; the builder,
+Author and lifecycle screens have their own pages: [the visual
+builder](/forge-builder), [the Agent
+Author](/forge-author) and [versions, triggers and
+publishing](/forge-lifecycle).
 
-![The Agents screen: nav, agent rail, the fitted canvas with the Inspector folded, and the bottom drawer](/images/studio-agents.png)
+## Install and start
 
-## Installation
+Any of these works:
 
-Agent Forge ships inside `lousho` itself - there's no
-separate package to install:
+```bash
+npx @linuxdevil/studio
+```
 
 ```bash
-npm install lousho
+npm i -g @linuxdevil/studio
+lousho-studio
 ```
 
-That's it. `lousho studio` (below) runs a pre-built copy of the app; you
-don't need `apps/agent-forge`'s own source or its devDependencies (Vite,
-`tsx`, etc.) to use it.
+Or, inside a project that already has `@linuxdevil/lousho` installed, the SDK's
+launcher finds the installed Studio and opens this folder as a workspace:
 
-If you're working inside this SDK's own monorepo instead (contributing to
-Agent Forge itself), see [Dev mode](#dev-mode) below.
+```bash
+lousho studio
+```
 
-## Quickstart
+When no Studio is installed the launcher says so instead of bundling one:
 
-```bash
-npx lousho studio
 ```
+Studio is a separate install: npx @linuxdevil/studio
+```
+
+`lousho studio` accepts `--port` and `--host` and passes them through; run
+`lousho studio --help` for its options. `--prod` and `--dev` only apply inside
+the SDK's own repository checkout (see [Dev mode](#dev-mode)).
 
-This starts one local server and prints its URL (default
-`http://127.0.0.1:4750/?token=<random>`). Open that exact URL in a browser.
-It lands on the Agents screen (`#/agents`): the left navigation, the build
-toolbar (the agent's name and run status, the model badge, then Debug, Stop,
-Run, Import, Export and Save), the
-agent rail (your saved agents plus a node/hook palette), the canvas, the
-Inspector (right), and a bottom drawer with Chat, Logs, Trace, Output,
-History and Settings tabs. An agent opens with nothing selected and the
-whole graph fitted in view; the Inspector stays folded away until you
-select a node, or press the **Inspector** button at the canvas's
-top-right (its accessible name is "Show inspector"), which is remembered. The other screens are one click away in the
-navigation; see [Navigation](#navigation).
+`lousho-studio` (and `npx @linuxdevil/studio`) take the same flags:
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--workspace <dir>` | the current folder | A project folder to open; it is added to your workspaces. |
+| `--port N` | `4750` | The port to listen on. |
+| `--host H` | `127.0.0.1` | The interface to bind to. |
+
+The server prints its URL, `http://127.0.0.1:4750/?token=<random>`. The
+`?token=` is a per-launch access token: the page keeps it for that tab and
+sends it on every API call, so open the printed URL, not the bare host (see
+[Access token](#access-token)).
+
+Opening Studio lands on the Agents list (`#/agents`): your saved agents as
+cards, plus a **New agent** menu. Opening or creating one takes you to its
+Canvas tab — the builder: the build toolbar (the agent's name and run
+status, the model badge, then Debug, Stop, Run, Import, Export and Save),
+the agent rail (your saved agents plus a node/hook palette), the canvas, the
+Inspector (right), and a bottom drawer with Test, Problems, Logs, Trace,
+Output, History and Settings tabs. An agent opens with nothing selected and
+the whole graph fitted in view; the Inspector stays folded away until you
+select a node, or press the **Inspector** button at the canvas's top-right
+(its accessible name is "Show inspector"), which is remembered. The other
+screens are one click away in the navigation; see [Navigation](#navigation).
 
 Below 860px wide the navigation becomes a drawer opened from the
 **Navigation** (menu) button at the top; picking a screen, the scrim or Esc
-closes it. On the Agents screen the agent rail and the Inspector become
+closes it. On the builder the agent rail and the Inspector become
 slide-over panels you open from the top bar; Run (or Stop) and Save stay in
 the bar, and Debug, Import, Export and the model badge move into its **More
 actions** (`⋯`) menu.
 
-Useful flags:
+## Workspaces
+
+A workspace is a project folder on disk. The folder you launch Studio from is
+added automatically; add more with **Add workspace → folder path** (or the
+**Add workspace…** entry in the switcher).
+
+The switcher at the top of the nav lists **All workspaces**, each workspace,
+and **Add workspace…**. `#/agents` is the all-workspaces list; an agent route
+is `#/w/<workspace>/agents/<id>/<tab>`.
+
+Things live in three places:
+
+| Where | What |
+| --- | --- |
+| `~/.lousho/studio/` | Studio-wide state: the workspace registry, settings, secrets, assistant sessions, pass spend, inbox alerts. Shared across workspaces. |
+| `<workspace>/.lousho/agents/` | The project's agents: spec, metadata, layout, working copy, versions, drafts, suggestions, traces, chats, approvals, checkpoints. Travels with the project. |
+| `~/.lousho/observe.db` | The observe collector's database (traces, scores, sessions). |
+
+On first launch after the split, if a workspace still has a project-level
+`.lousho/settings.json` or `.lousho/secrets.json`, Studio offers **Import
+settings and keys from &lt;workspace>** once, copies them into
+`~/.lousho/studio/`, and leaves the originals alone.
+
+## Three kinds of agent
+
+The all-workspaces agent list mixes three kinds:
+
+| Kind | Source | What you can do |
+| --- | --- | --- |
+| Workspace agent | `<workspace>/.lousho/agents/<id>.yaml` (Agent spec v2) | Everything: canvas, Author, versions, test, publish. |
+| Code agent | An agent directory or `agent.ts` found by scanning a workspace | Read-only canvas, traces, runs. |
+| Observed agent | Any agent reporting to the observe collector (`GET /api/v1/agents`): deployed workers, CI, other machines | Read-only card: name, project, instances, last seen, traces, scores, evals. |
+
+Observed agents whose collector `project` matches a workspace id appear under
+that workspace (see [See agents running elsewhere](#see-agents-running-elsewhere)).
+The rest are grouped under **Elsewhere**.
+
+## Which SDK runs your agents
+
+For each workspace Studio picks how agent processes run:
+
+- **Bridge** — the normal case. Studio spawns `lousho bridge` from the SDK
+  installed in that project (`@linuxdevil/lousho`), so runs use the project's
+  own SDK version. This matters because a project's `{ file }` tools and
+  skills import that project's dependencies, which only resolve inside the
+  project.
+- **In-process** — Studio's own built-in SDK, used when the project has no
+  SDK installed or its checkout is not built.
+- **Read-only** — the project's SDK is too old or speaks a protocol this
+  Studio does not know, so edits are refused until it is fixed.
+
+Each non-default state shows a banner at the top of the workspace's pages:
+
+| Banner | What to do |
+| --- | --- |
+| `This project has no @linuxdevil/lousho installed. Runs use Studio's built-in SDK <version>.` | Runs still work on Studio's SDK. Install `@linuxdevil/lousho` in the project to run its own version. |
+| `This SDK checkout is not built, so runs use Studio's built-in SDK <version>. Run npm run build to use it.` | Inside the SDK repository: run `npm run build` in the checkout. |
+| `Update @linuxdevil/lousho in this project to <minimum> or later to edit agents here.` | The project's SDK is older than this Studio understands. The workspace is read-only: update `@linuxdevil/lousho` in the project to edit. |
+| `This project's @linuxdevil/lousho <version> is newer than this Studio understands. Update Studio to edit agents here.` | The project has a newer SDK than this Studio was built for. Update Studio (`npm i -g @linuxdevil/studio@latest`) to edit. |
+| `This project's agent process keeps stopping. Check the Studio terminal for its output, then restart it.` | The bridge process crashed repeatedly. Its output is in the terminal that started Studio; use **Restart** on the banner to try again. |
+
+While a workspace is read-only, writes under its agents (saves, drafts, runs,
+deploys) are refused; reads still work.
+
+A few features still need Studio's built-in SDK and are unavailable on
+bridge workspaces:
+
+- Flow runs: `Flow runs need Studio's built-in SDK for now. Remove the project's SDK from this workspace or run the flow from code.`
+- Breakpoints: `Breakpoints need Studio's built-in SDK for now.`
+- Time travel: `Time travel is not available yet for projects that run their own SDK.`
+
+## The collector
+
+Everything under Observe, Evaluate and Assets — and run reporting — reads the
+observe collector. On boot Studio probes the configured URL (default
+`http://127.0.0.1:7777`):
+
+- **Attached** — a `lousho observe` daemon is already running there; Studio
+  uses it.
+- **Started** — none answered on loopback, so Studio started its own and
+  stops it on exit. It never stops a daemon it did not start.
+- **Remote** — a non-loopback URL (team or hosted collector); Studio probes
+  it but does not start or stop anything there.
+- **Down** — nothing answers; daemon screens show the start command instead
+  of data and recover on their own.
+
+The collector card at the bottom of the nav shows the mode (`Attached to
+<url>`, `Started by Studio on <url>`, `Remote collector at <url>`, `Not
+reachable: <error>`). **Settings → Collector** sets a remote URL and bearer
+token; create a token with `lousho observe token create --project <name>`.
+`LOUSHO_OBSERVE_URL` and `LOUSHO_OBSERVE_TOKEN` in Studio's own environment
+override the stored setting, and `LOUSHO_STUDIO_COLLECTOR=0` stops Studio
+from auto-starting a local daemon.
+
+## See agents running elsewhere
+
+An agent deployed on another machine — a server, CI, a teammate's laptop —
+shows up in Studio once it reports to a collector Studio can read. Reporting
+is pure SDK configuration; nothing in the agent is Studio-specific:
+
+```ts
+import { createAgent } from '@linuxdevil/lousho';
+
+// LOUSHO_OBSERVE, LOUSHO_OBSERVE_TOKEN and LOUSHO_OBSERVE_PROJECT are read
+// from the environment - no Studio-specific code.
+export const agent = createAgent({ model: 'openai/gpt-4.1-mini' });
+```
+
+Set these in the deployed environment:
+
+| Variable | Meaning |
+| --- | --- |
+| `LOUSHO_OBSERVE` | The collector URL, e.g. `http://127.0.0.1:7777` or a tunnel/remote URL. `1`/`true` uses the default. |
+| `LOUSHO_OBSERVE_TOKEN` | Bearer token, when the collector requires one (`lousho observe token create`). |
+| `LOUSHO_OBSERVE_PROJECT` | The workspace id to group the agent under — shown in **Settings → Workspaces**. Without it the project name is the package name and the agent appears under **Elsewhere**. |
+
+Point Studio at the same collector under **Settings → Collector** (or with
+`LOUSHO_OBSERVE_URL`/`LOUSHO_OBSERVE_TOKEN` in Studio's environment), and the
+deployed agent's traces, scores and sessions appear in Studio's Observe
+screens.
+
+## Updating
+
+Studio (`@linuxdevil/studio`) and the SDK (`@linuxdevil/lousho`) are separate
+packages and update independently:
 
 ```bash
-npx lousho studio --port 5000       # pick a different port
-npx lousho studio --host 0.0.0.0    # bind to all interfaces
-npx lousho studio --prod            # force production mode (see below)
-npx lousho studio --dev             # force dev mode (monorepo only)
+npm i -g @linuxdevil/studio@latest   # Studio itself
+npm i @linuxdevil/lousho@latest      # inside each project, its SDK
 ```
 
+A workspace's agents edit only when the project's SDK is at least
+`MIN_BRIDGE_SDK_VERSION` — the SDK version this Studio was built against. Older
+SDKs get the read-only banner above; newer ones get the "update Studio" banner.
+Bridge workspaces also need `lousho bridge` in the project's SDK, which speaks
+bridge protocol `1`.
+
+## Using Studio
+
 ### Access token
 
 The studio can store provider keys, start runs and execute hook code, so its
@@ -103,40 +250,38 @@ without the CLI:
 
 ### Where agents live
 
-Agent specs and run state are stored under `.lousho/` in the directory you
-ran `lousho studio` from (agent YAML files under `.lousho/agents/`,
-checkpoints and approvals alongside them) - the same `.lousho/` layout
-`lousho dev`/`lousho build` use. Those YAML files are
-[Agent spec v2](/agent-spec) documents, which that page explains field
-by field.
-
-The Agents screen's agent rail lists exactly the agents in that `.lousho/agents/`: a YAML
-file you add there shows up, and an agent you create in the studio is
-written there at once (autosave and **Save** both write the file), so it
-can be chatted with straight away. Another project, opened in its own
-`lousho studio`, shows only its own agents. The browser keeps nothing but a
-draft of an edit that could not reach the server (it is pushed on the next
-load), stored per workspace directory. A file in `.lousho/agents/` that no
-longer parses is skipped with a warning in the server log.
+Each workspace's agent specs and run state live under `.lousho/` in that
+project folder (agent YAML files under `.lousho/agents/`, checkpoints and
+approvals alongside them) - the same `.lousho/` layout `lousho dev`/`lousho
+build` use, so the files travel with the project and stay diffable.
+Studio-wide state (settings, secrets, the workspace registry) lives in
+`~/.lousho/studio/` instead; see [Workspaces](#workspaces). Those YAML files
+are [Agent spec v2](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-spec.md) documents, which that page explains
+field by field.
+
+The Agents screen's agent rail lists exactly the agents in that workspace's
+`.lousho/agents/`: a YAML file you add there shows up, and an agent you
+create in the studio is written there at once (autosave and **Save** both
+write the file), so it can be chatted with straight away. Another workspace
+shows only its own agents. The browser keeps nothing but a draft of an edit
+that could not reach the server (it is pushed on the next load), stored per
+workspace directory. A file in `.lousho/agents/` that no longer parses is
+skipped with a warning in the server log.
 
 ### Production vs. dev mode
 
-`lousho studio` has two modes, and picks the right one automatically:
-
-- **Production** (the default once Agent Forge has been built): a single
-  Express server serves both the REST/WebSocket API *and* the pre-built
-  client (React app) as static files, on one port. This is what runs when
-  you `npm install` the published package - there's no separate Vite dev
-  server and no TypeScript loader involved.
-- **Dev** (falls back to this if the build hasn't been run yet, i.e. inside
-  a source checkout of this monorepo): the API server runs straight off
-  its TypeScript source via `tsx`, alongside a real Vite dev server (with
-  hot-module reload) that proxies API requests to it. Two processes, two
-  ports internally, one command.
+An installed Studio (`lousho-studio`, `npx @linuxdevil/studio`, or
+`lousho studio` finding it) is always production mode: a single Express
+server serves both the REST/WebSocket API *and* the pre-built client (React
+app) as static files, on one port. There is no separate Vite dev server and
+no TypeScript loader involved.
 
-`--prod`/`--dev` force one or the other; run without either flag and
-`lousho studio` auto-detects based on whether `apps/agent-forge/dist-server`
-exists.
+Dev mode - the API server running from TypeScript via `tsx` next to a Vite
+dev server with hot-module reload - exists only inside the SDK's own
+repository checkout, for people contributing to Studio itself. There
+`lousho studio --dev` (or `--prod` to force the built bundle) picks the mode;
+run without either flag it auto-detects based on whether
+`apps/agent-forge/dist-server` exists. See [Dev mode](#dev-mode).
 
 ## Navigation
 
@@ -144,8 +289,11 @@ The left navigation lists every screen, grouped:
 
 | Group | Item | Screen |
 | --- | --- | --- |
-| Build | **Agents** | The builder: canvas, Inspector, bottom drawer. The build toolbar (Run, Stop, Debug, Import, Export, Save, model badge) shows only here. |
+| Build | **Agents** | The agents list; an agent opens on tabs — Canvas (the builder), Overview, Configure, Code, Runs, Versions, Suggestions. The build toolbar (Run, Stop, Debug, Import, Export, Save, model badge) shows on the Canvas tab. |
+| Build | **Inbox** | Pending approvals, questions, drafts, suggestions and notices, one row each with inline actions. |
+| Build | **Templates** | Agent templates you can start from. |
 | Build | **Playground** | Try messages against a model without editing an agent. |
+| Build | **Workspaces** | Workspaces in this project: their pages, problems, drafts and revisions. |
 | Observe | **Traces** | Every run the observe daemon holds, filtered and sorted; a row opens the trace. |
 | Observe | **Threads** | Sessions (conversations): one row per session, one turn per run. |
 | Observe | **Monitoring** | The fleet's health and charts over a time window. |
@@ -154,7 +302,7 @@ The left navigation lists every screen, grouped:
 | Assets | **Context Hub** | Shared key-values agents publish to the daemon. |
 | | **Settings** | Appearance, provider keys, settings profiles, deploy, collector and shortcuts. |
 
-Off the Agents screen a page header names the screen and keeps the live run
+Off the builder a page header names the screen and keeps the live run
 status pill at the end of its title row, after any chips the screen adds (a
 prompt's labels, say). Under Settings, a small card shows the collector status (see
 [The collector](#the-collector-observe-daemon)). The button beside the
@@ -175,7 +323,9 @@ unknown hash goes to `#/agents` (the `?token=` stays).
 
 | Route | Screen | Query keys |
 | --- | --- | --- |
-| `#/agents`, `#/agents/<agent id>` | Agents, with that agent open | |
+| `#/agents` | Agents list | |
+| `#/agents/<agent id>/canvas` | The builder for that agent | |
+| `#/agents/<agent id>/<tab>` | One agent tab: `overview`, `configure`, `code`, `runs`, `versions`, `suggestions` | |
 | `#/playground` | Playground | `trace` + `fromObs`, or `prompt` (see [Playground](#playground)) |
 | `#/traces` | Traces list | `agent`, `status`, `model`, `project`, `q`, `prompt` (`<name>` or `<name>@<version>`), `from` + `to` (ms epoch, half-open), `sort` (`duration`, `tokens`, `cost`) + `order` (`asc`, `desc`), `offset` |
 | `#/traces/<trace id>` | One trace | `obs` (the selected step) |
@@ -189,6 +339,8 @@ unknown hash goes to `#/agents` (the `?token=` stays).
 | `#/prompts` | Prompt registry | |
 | `#/prompts/<name>`, `#/prompts/<name>@<version or label>` | One prompt (latest version by default) | `diff=<a>,<b>` |
 | `#/hub`, `#/hub/<namespace>` | Context Hub | `agent` (the "Viewing as" agent), `scope` (`private`, `fleet`) |
+| `#/workspaces` | Workspaces list | `q` (filters name, id, domain) |
+| `#/workspaces/<id>`, `#/workspaces/<id>/<section>` | One workspace; section is `overview`, `main-agent`, `pages`, `agents`, `runs`, `improve` or `revisions` | |
 | `#/settings` | Settings | |
 
 A time range picked from a preset other than the default is written as
@@ -211,6 +363,9 @@ browser); type to filter. Paste a trace id (8 or more hex digits and
 dashes) and the first entry is **Open trace** for it. Arrow keys move,
 Enter runs.
 
+The builder's own shortcuts — save version, undo/redo, palette search,
+node delete — are listed in [the visual builder](/forge-builder#keyboard-shortcuts).
+
 ![The command palette over the Traces screen](/images/studio-command-palette.png)
 
 In an annotation queue's review, Enter submits the scores and `S` skips
@@ -231,40 +386,43 @@ Every status in the Studio is the same pill:
 
 ### The collector (observe daemon)
 
-Everything under Observe, Evaluate and Assets reads the observe daemon
-(`lousho observe start`) through the Studio server's `/observe` proxy. The
-proxy reads only `LOUSHO_OBSERVE_URL` (default `http://127.0.0.1:7777`);
-`LOUSHO_OBSERVE` does not change where the screens read (it only picks where
-builder runs report, see the [walkthrough](#first-agent-walkthrough)). When
-`LOUSHO_OBSERVE_TOKEN` is set, the proxy sends it to the daemon as the bearer
-token on every read and write (as run reporting and the judge evaluators do),
-so the screens also work against a daemon started with `--require-token`.
-Without it, such a daemon answers `401` to every `/api/` read and the screens
-show that error instead of data (`/health` still answers, so the collector
-card says running). The browser's own credentials (the Studio token, cookies,
-`Authorization`) are never passed on. The proxy only forwards reads plus the
-writes the screens make (feedback scores, new prompt versions from the
-Playground, prompt label moves, hub entry edits, dataset and example writes,
-annotation queue writes, evaluator rule writes); every other write, ingest
-above all, is refused with `405`. It always calls the daemon at
-`LOUSHO_OBSERVE_URL`, whatever host the request line names.
-
-The collector card at the bottom of the nav says whether the daemon answers:
-**Checking collector…** until the first probe, then **Collector running**
-or **Collector unreachable**, with the daemon URL underneath. The probe keeps polling. While the daemon is down, each
-daemon screen shows the command to start it instead of an error, keeps its
-URL, and swaps the data back in by itself once the daemon answers. The
-Agents screen and Playground runs do not need the daemon.
+Everything under Observe, Evaluate and Assets reads the observe collector
+through the Studio server's `/observe` proxy, which calls whatever URL the
+collector manager resolved (see [The collector](#the-collector)). The proxy
+forwards reads plus the writes the screens make (feedback scores, new prompt
+versions from the Playground, prompt label moves, hub entry edits, dataset
+and example writes, annotation queue writes, evaluator rule writes); every
+other write, ingest above all, is refused with `405`. When a bearer token is
+configured the proxy sends it to the collector on every read and write (as
+run reporting and the judge evaluators do), so the screens also work against
+a collector started with `--require-token`. Without it, such a collector
+answers `401` to every `/api/` read and the screens show that error instead
+of data (`/health` still answers, so the collector card says running). The
+browser's own credentials (the Studio token, cookies, `Authorization`) are
+never passed on.
+
+The collector card at the bottom of the nav shows the resolved mode —
+**Attached to \&lt;url\>**, **Started by Studio on \&lt;url\>**, **Remote collector
+at \&lt;url\>** or **Not reachable: \&lt;error\>** — and keeps polling. While the
+collector is down, each daemon screen shows the command to start it instead
+of an error, keeps its URL, and swaps the data back in by itself once it
+answers. The Agents screen and Playground runs do not need the collector.
 
 ## Screens
 
 ### Agents
 
-The builder: see the [First-agent walkthrough](#first-agent-walkthrough).
-`#/agents/<id>` opens that agent; leaving the screen (or switching agents)
-with unsaved changes asks first. Runs started here report to the observe
-daemon, and the Run status pill's **Open trace** link opens the run on the
-Trace screen.
+`#/agents` is the agents list: a card per agent in `.lousho/agents/`, a
+**New agent** menu (**Blank agent**, **From template**,
+**Describe with AI** — see [the Agent Author](/forge-author) — or
+**Import from file…**), and search and label filters.
+Opening a card goes to its Canvas tab, the builder — see
+[the visual builder](/forge-builder) and the
+[first-agent walkthrough](#first-agent-walkthrough). `#/agents/<id>` (the
+legacy builder URL) redirects to `#/agents/<id>/canvas`. Leaving the
+builder with unsaved changes asks first. Runs started there report to the
+observe daemon, and the Run status pill's **Open trace** link opens the
+run on the Trace screen.
 
 ### Playground
 
@@ -301,6 +459,24 @@ says so and keeps an empty editor, and runs still work. Runs go through the
 [playground run endpoint](#playground-run-endpoint) and report as agent
 `playground`.
 
+### Workspaces
+
+`#/workspaces` lists the workspaces the typed workspaces API knows: name and
+domain, page count, a `Valid`/`Invalid (n)` badge from the workspace's
+problems, the live revision and a last-run column (filled in by a later
+ticket). `#/workspaces/<id>` opens one workspace with a header that carries
+the live revision, the problems badge, an **Draft open** badge while a draft
+exists, and disabled **Run**/**Chat** actions; a left nav switches between
+the `overview`, `main-agent`, `pages`, `agents`, `runs`, `improve` and
+`revisions` sections, the ones not built yet naming their ticket. Every edit
+is a typed authoring operation sent through `ApiClient.call('applyOps', …)`
+into a draft with `expectedRevision`; the draft is applied or discarded
+later. When the live revision moved under an open screen the operation gets a
+409, the latest revision reloads and a toast says "This workspace changed
+since you opened it." The screens call only the workspaces API
+(`/api/workspaces`, mounted by a later ticket), through an injected
+`ApiClient`, so they run on fixtures today and move to the Next.js app later.
+
 ### Traces
 
 ![The Traces list](/images/studio-traces.png)
@@ -443,7 +619,7 @@ filter (agent, status `ok` or `error`, name contains), and the kind:
   the provider's environment variable where the Studio runs (the stored key
   wins); the provider list offers the providers that have either, plus
   `ollama` and `mock`. With no key at all the judge option is disabled, with
-  a link to Settings. Judges run only while `lousho studio` is running; until
+  a link to Settings. Judges run only while Studio is running; until
   then their jobs wait in the daemon (see
   [Judge rules](/observability#judge-rules-through-agent-forge)). Set
   `LOUSHO_STUDIO_JUDGE=0` on the Studio server to turn its judge loop off.
@@ -513,27 +689,28 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
 
 ## First-agent walkthrough
 
-1. **Create an agent.** In the agent rail's **Agents** tab, click
-   **New agent**, give it a name, and pick a starting template - **Blank graph** (a single
-   LLM node using the built-in `mock` provider) is the fastest way to try
-   things out without any API keys. Agent Forge creates the agent under that
-   name (`.lousho/agents/<name>.yaml`, with `name: <name>` in the spec) and
+1. **Create an agent.** On the agents list (`#/agents`) click **New agent**
+   and pick **Blank agent** - it starts from an empty canvas, which is the
+   fastest way to try things out without any API keys (**From template**
+   offers ready-made starting points instead). Agent Forge creates the agent
+   (`.lousho/agents/<id>.yaml`, with `name:` in the spec) and
    opens it on the canvas. The open agent's card has **Rename** and
    **Delete**. Rename moves the spec to the new name; earlier chats, traces
    and checkpoints stay under the old one.
-2. **Look at the graph.** A blank agent is one `llm` node. Drag more nodes
-   in from the rail's **Nodes** tab (**Trigger**, **LLM step**, **Tool
-   call**, **Approval gate**, **Response / output**), or click (or press
+2. **Look at the graph.** A blank agent is a single agent node. Drag more
+   nodes in from the rail's **Nodes** tab (a **Tool**, an **MCP server**,
+   a **Guardrail**, a **Chat** trigger, an **Output schema** — the full
+   list is in [the visual builder](/forge-builder#the-canvas)), or
+   click (or press
    Enter on) a Nodes item to add it at the centre of the canvas, and
    connect them by
-   dragging between their handles. Each node card shows its name, an LLM
-   node's `provider/model` chip and tool count, and the node's status in the
+   dragging between their handles. Each node card shows its name, an agent
+   node's `provider/model` chip, and the node's status in the
    current run (`idle` until a run reaches it). Click a node to edit its
-   settings (prompt, provider/model, tools, breakpoints) in the Inspector on
-   the right; its **Node**, **Debug** and **Hooks** sections collapse, and
-   each stays the way you left it. An agent whose canvas has no nodes shows
-   the templates on the canvas: choosing one fills the canvas (unsaved until
-   it autosaves, like any edit) and keeps the agent's name.
+   settings in the Inspector on
+   the right; its **Problems**, **Settings** and **Debug** sections
+   collapse, and
+   each stays the way you left it.
 3. **Run it.** Click **Run** in the top bar. With the `mock` provider
    there's nothing to configure - it returns deterministic canned output,
    which is exactly the point for trying the rest of the UI without needing
@@ -542,12 +719,12 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    `awaiting approval`), and once the run's trace id is known an **Open
    trace** link next to it opens the run at `#/traces/<traceId>` (in the
    narrow layout it is in the **More** menu). Builder runs report to the
-   observe daemon as agent `<agent id>`, the same way the Playground does:
-   when `LOUSHO_OBSERVE` is set its reporter is used (nothing is reported
-   twice), a daemon that is down only drops events and never fails the run,
-   and message content is sent only to a loopback daemon (never to the
+   observe collector as agent `<agent id>`, the same way the Playground
+   does (see [The collector](#the-collector)): a collector that is down
+   only drops events and never fails the run, and message content is sent
+   only to a loopback collector (never to the
    trace files or the live Trace tab). Run sends a fixed
-   prompt, which the Chat tab shows
+   prompt, which the Test tab's chat shows
    as a **Run input** bubble instead of a message from you. If the studio
    server goes away, a banner says the connection was lost and the studio
    reconnects when it is back.
@@ -576,9 +753,9 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    live. Selecting a step highlights its node on the canvas. The list
    refreshes when a run ends. The files are the ones `lousho traces` reads, in
    `.lousho/agents/<agent id>/traces/<day>/<trace id>.jsonl` under the
-   directory `lousho studio` was started in (see
+   workspace folder (see
    [Local traces](/observability#local-traces)):
-   `npx lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
+   `npx @linuxdevil/lousho traces --dir .lousho/agents/<agent id>/traces` shows the same
    runs in the terminal, and deleting the agent's folder deletes its traces.
    The tab shows what the spans hold: model and tool names, token counts,
    cost, durations and error messages, and in the inspector's Input,
@@ -586,52 +763,53 @@ and deploy cards; see [Settings, secrets and deploy wiring](#settings-secrets-an
    tool content. The server reads traces only from that folder (an id with
    a path separator is a 400) and never sends the file path to the browser.
    Keep `.lousho/` out of version control.
-5. **Chat with it.** The **Chat** tab is a separate conversational
+5. **Chat with it.** The chat in the bottom drawer's **Test** tab is a
+   separate conversational
    transport (`POST /agents/:id/message`, streamed back over the same
    WebSocket as everything else) - send it a message and it replies in the
    thread, independent of the graph "Run" button above. Each agent keeps
    its own chat history (`+ New chat` starts a fresh session; old ones stay
    browsable).
-6. **Approve a paused tool call.** Add a **Tool call** node, open it in the
+6. **Approve a paused tool call.** Add a **Tool** node, open it in the
    Inspector, and pick a tool - some tools (or an agent's own policy) can
    require human approval before running. When a run or chat hits one, an
    inline approval card appears (in the top bar for a graph run, or as a
-   message bubble in the Chat thread) showing the tool name and its
+   message bubble in the chat thread) showing the tool name and its
    arguments. Click **Approve** to let it proceed or **Reject** to abort
    that call; the run resumes automatically either way.
 
 ## Hooks
 
 Hooks are small, sandboxed functions that run immediately before or
-after a tool call or an LLM `generate` - the same mechanism the SDK core
+after a tool call or a model call - the same mechanism the SDK core
 exposes as `HookRegistry`/`AgentHook` (see
-[API Overview](/api-overview)), but authored visually and attached to a
-specific canvas node.
-
-To attach one:
-
-1. Select an `llm` or `tool` node on the canvas (hooks only apply to these -
-   they're the two points `AgentExecutor` actually calls out to).
-2. Open the Inspector's **Hooks** section. Drag a **Pre-hook** or
-   **Post-hook** entry from the rail's **Nodes** tab onto the node (or drop
-   it directly in the Hooks section), or click the palette entry while the
-   node is selected, to attach a new one; you'll get a
-   choice of starter templates (`redact-pii`, `rate-limit`, `audit-log`,
-   `inject-context`) as an editable starting point.
-3. Click the hook's chip to select it, then edit its code in the CodeMirror
-   editor. The code is the **body** of an async function invoked as
+[API Overview](/api-overview)), authored visually as `hooks[]` entries
+on the agent.
+
+To add one:
+
+1. Drag a **Hook** entry from the rail's **Nodes** tab (Safety group) onto
+   the canvas, or click it while the agent is open; it attaches to the
+   agent as a node. Each spec `hooks` entry is one node.
+2. Click the hook node and edit its fields in the Inspector: an id, a
+   name, the **Source** (**Code here** for an inline body, or **File** for
+   a `.ts`/`.js` file inside the agent folder), the **Runs** point -
+   *Before/After each tool call* or *Before/After each model call* - the
+   on switch, and the code itself in a CodeMirror editor, with starter
+   templates (`redact-pii`, `rate-limit`, `audit-log`, `inject-context`)
+   filtered to the current point.
+3. The code is the **body** of an async function invoked as
    `hook(ctx)` inside a sandboxed subprocess (`server/hookSandbox.ts`) -
    never in the browser or the API server process itself:
-   - For a tool-call hook, `ctx` is `{ toolName, args, result?, error? }`.
+   - For a tool-call point, `ctx` is `{ toolName, args, result?, error? }`.
      A pre-hook can mutate `ctx.args`; a post-hook can inspect/mutate
      `ctx.result`/`ctx.error`. Return `ctx`.
-   - For an LLM-generate hook, `ctx` is `{ messages, model }`. Mutate/push
+   - For a model-call point, `ctx` is `{ messages, model }`. Mutate/push
      onto `ctx.messages` and return `ctx`.
    - **Throwing aborts the step** - a rate-limit hook, for example, throws
      to block the tool call outright rather than letting it run.
-4. Toggle the switch on a hook's chip to enable/disable it without removing
-   it, or use its **x** to remove it entirely. Only enabled hooks are
-   compiled into the run.
+4. Switch a hook off without removing it, or delete its node; only enabled
+   hooks are compiled into the run.
 
 Example: a redact-PII pre-hook on a tool node (this is the `redact-pii`
 starter template) -
@@ -646,7 +824,7 @@ for (const key of Object.keys(ctx.args || {})) {
 return ctx;
 ```
 
-Saving the agent persists these as `spec.policy.hooks` in the agent's YAML;
+Saving the agent persists these as `hooks` entries in the agent's YAML;
 the server compiles enabled hooks into a real `HookRegistry` for the run
 (`server/compileHooks.ts`), routed through the same `SandboxAdapter` a
 sandboxed tool uses.
@@ -665,7 +843,7 @@ and replay it next to the original, with
 
 ### The History tab
 
-1. Run the agent (Topbar **Run**, or a Chat message).
+1. Run the agent (Topbar **Run**, or a chat message).
 2. Open the bottom drawer's **History** tab. It lists the run's steps:
    step number, status, the model's finish reason, the tool calls made,
    and the tokens and cost of the step's model call when known.
@@ -760,36 +938,36 @@ Every stream ends with exactly one `done` or `error`, even a run that stops
 without a result. `usage` has the `run.done` event's usage shape
 (`AgentEventUsage`).
 
-Closing the connection aborts the run. Every run reports to the observe
-daemon the Studio reads (`LOUSHO_OBSERVE_URL`, default
-`http://127.0.0.1:7777`, or `LOUSHO_OBSERVE` when set) as agent
+Closing the connection aborts the run. Every run reports to the collector
+the Studio reads (see [The collector](#the-collector)) as agent
 `playground`, with `lousho.prompt.ref` on the run's root span when
-`promptRef` is given. `LOUSHO_OBSERVE_TOKEN` is sent as the bearer token, for a
-daemon bound beyond loopback. A daemon that is down does not slow or fail the run.
+`promptRef` is given. A bearer token is sent when one is configured, for a
+collector bound beyond loopback. A collector that is down does not slow or
+fail the run.
 
 ## Settings, secrets and deploy wiring
 
 The Settings screen (`#/settings`, the last screen in the nav) and the builder
 drawer's **Settings** tab share three parts: provider API keys
-(OpenAI and Anthropic, stored encrypted under `.lousho/` and never shown
+(OpenAI and Anthropic, stored encrypted under `~/.lousho/studio/` and never shown
 again; each key shows **Set** with its masked last characters, **From
 environment** when only `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` is set, or
 **Not set**), named settings profiles (provider, deploy adapter, hook timeout,
-OpenTelemetry toggle; kept in `.lousho/settings.json`, which holds no
+OpenTelemetry toggle; kept in `~/.lousho/studio/settings.json`, which holds no
 secrets), and a **Deploy** section that picks an adapter (`node-server`,
 `docker` or `cloudflare-worker`) and runs `lousho build` for the selected
 agent. Other providers still read their environment variables, the same way
 `lousho dev`/`lousho build` do (see [Configuration](/configuration)), and
 the `mock` provider needs no credentials.
 
-Stored keys are encrypted with AES-256-GCM in `.lousho/secrets.json`. The
-encryption key is generated on first use and kept next to it in
-`.lousho/secrets.key` (both `0600` on POSIX). This keeps keys out of
+Stored keys are encrypted with AES-256-GCM in `~/.lousho/studio/secrets.json`.
+The encryption key is generated on first use and kept next to it in
+`~/.lousho/studio/secrets.key` (both `0600` on POSIX). This keeps keys out of
 anything that copies the ciphertext alone - a backup, a zip of the project,
 a shared agent YAML - but anyone who can read both files as your user can
-decrypt them. It is not an OS keychain. Keep `.lousho/` out of version
-control and out of shared archives, and prefer environment variables on
-shared machines.
+decrypt them. It is not an OS keychain. Keep `~/.lousho/studio/` out of
+version control and out of shared archives, and prefer environment variables
+on shared machines.
 
 An agent whose provider has no key (no stored key and no environment
 variable) does not run. **Run** and **Chat** fail with
@@ -801,16 +979,18 @@ mock agent carries a **MOCK** badge.
 
 ## Dev mode
 
-If you're working inside this SDK's own monorepo (contributing to Agent
-Forge itself, not just using it), `lousho studio` falls back to dev mode
-automatically as long as `apps/agent-forge/dist-server` hasn't been built
-yet:
+Dev mode exists only for people contributing to Studio inside the SDK's own
+monorepo - an installed Studio is always the production bundle (see
+[Production vs. dev mode](#production-vs-dev-mode)). From a checkout of this
+repository, `lousho studio` detects the Studio source and falls back to dev
+mode automatically as long as `apps/agent-forge/dist-server` hasn't been
+built yet:
 
 ```bash
 git clone https://github.com/LinuxDevil/lousho.git
 cd agent-sdk
 npm install
-npx lousho studio --dev   # or just `npx lousho studio` before building
+node bin/lousho.js studio --dev   # or just `node bin/lousho.js studio` before building
 ```
 
 This runs the API server straight from TypeScript (`tsx`) and a real Vite
@@ -822,7 +1002,7 @@ is pinned to port 5173 and the API server accepts that origin. To build the prod
 ```bash
 npm run build:studio   # builds apps/agent-forge/dist (client) and
                         # apps/agent-forge/dist-server (bundled server)
-npx lousho studio       # now runs in production mode
+node bin/lousho.js studio       # now runs in production mode
 ```
 
 `npm run build:studio` also runs automatically as part of the root
@@ -839,7 +1019,7 @@ at a server-local `demo-approval` tool (always `needsApproval: true` -
 see `server/buildAgent.ts`'s doc comment for why this exists, since none
 of the SDK's spec-resolvable built-in tools require approval), sends it a
 chat message that triggers the mock provider's tool-call heuristic, waits
-for the run to pause on the approval gate, approves it via the Chat tab's
+for the run to pause on the approval gate, approves it via the Test tab's
 inline approval card, and asserts the run completes. Run it with:
 
 ```bash
diff --git a/ai-sdk-ui.mdx b/ai-sdk-ui.mdx
index 20dee65..6dc1396 100644
--- a/ai-sdk-ui.mdx
+++ b/ai-sdk-ui.mdx
@@ -22,7 +22,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 // The store must outlive the request: without one, every `agent.session({ id })`
 // gets a fresh in-memory transcript and the next turn would start empty.
@@ -159,5 +159,5 @@ kept: a `system` message (or any other role, or an entry that is not a message)
 is dropped, so a caller cannot add instructions to the agent's prompt. Set
 instructions on the agent (`createAgent({ instructions })`), not in the request.
 
-A dedicated `lousho/ai-sdk-ui` subpath may follow; for now the
+A dedicated `@linuxdevil/lousho/ai-sdk-ui` subpath may follow; for now the
 functions come from the package root.
diff --git a/api-overview.mdx b/api-overview.mdx
index 3052a56..84159f6 100644
--- a/api-overview.mdx
+++ b/api-overview.mdx
@@ -45,9 +45,9 @@ How the pieces fit:
 | Export                        | Description                                                                 |
 | ----------------------------- | --------------------------------------------------------------------------- |
 | `createAgent(config)`         | Zero-config `{ send(message) }` agent from a `model` string or provider (+ instructions, tools). |
-| `AgentBuilder` (from `lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](/executor-api). |
-| `AgentExecutor.execute(opts)` (from `lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](/executor-api). |
-| `resumeAfterApproval()` (from `lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](/executor-api). |
+| `AgentBuilder` (from `@linuxdevil/lousho/executor`) | Fluent builder for an `AgentConfig` (`AgentBuilder.create().setName(...)...build()`). Advanced: see [the executor API](/executor-api). |
+| `AgentExecutor.execute(opts)` (from `@linuxdevil/lousho/executor`) | Static executor: runs an agent (LLM + tool-calling loop) and resolves to an `ExecutionResult`. Advanced: see [the executor API](/executor-api). |
+| `resumeAfterApproval()` (from `@linuxdevil/lousho/executor`) | Resume an execution paused for human approval. Advanced: see [the executor API](/executor-api). |
 | `InMemoryApprovalStore`       | Process-local `ApprovalStore`; the default store of `createAgent()` agents. |
 | `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` (from `/utils`) | File-backed approval and checkpoint stores over a `StorageService` (see [Approvals](/approvals), [Durable execution](/durable-execution)). |
 | `SqliteStore` (from `/sqlite`) | Sessions, checkpoints and approvals in one SQLite file (see [Sessions](/sessions#choosing-a-store)). |
@@ -75,8 +75,8 @@ resolves with the task prompt as `input` and the lead run's `sessionId`,
 `metadata` and `principal`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({ name: 'refund', description: 'Refunds an order', input: z.object({ orderId: z.string() }), execute: async () => 'ok' });
@@ -105,14 +105,14 @@ when it is created.
 
 ### UI bindings
 
-`lousho/react` exports `useLoushoAgent(source, options?)`, a
+`@linuxdevil/lousho/react` exports `useLoushoAgent(source, options?)`, a
 React hook that runs an agent in process (`{ agent, sessionId? }`) or over HTTP
 (`{ url }`) and returns `messages`, `status`, `pendingApproval`,
 `send()`, `stop()`, `approve()` and `reject()`. Its framework-neutral parts,
 `reduceAgentEvents()` and `parseEventStream()`, are exported too. See
-[React](/react). `lousho/vue` exports the same
+[React](/react). `@linuxdevil/lousho/vue` exports the same
 `useLoushoAgent()` as a Vue 3 composable, with the state as refs. See
-[Vue](/vue). `lousho/svelte` exports `loushoAgent()`, the
+[Vue](/vue). `@linuxdevil/lousho/svelte` exports `loushoAgent()`, the
 same state and actions as a Svelte store (`$agent`). See [Svelte](/svelte).
 
 ### Sub-agents
@@ -210,7 +210,7 @@ See [Providers](/providers) for how a model string is resolved and which model r
 
 ## Testing
 
-Exported from `lousho/testing` (see [Testing agents](/testing)).
+Exported from `@linuxdevil/lousho/testing` (see [Testing agents](/testing)).
 
 | Export                | Description                                                                              |
 | --------------------- | ---------------------------------------------------------------------------------------- |
@@ -223,18 +223,18 @@ Exported from `lousho/testing` (see [Testing agents](/testing)).
 | -------------------------------------------- | --------------------------------------------- |
 | `defineTool({ name, description, input, execute, ... })` | Define a tool; `execute`/`needsApproval` args are inferred from the zod `input`. Accepted by `createAgent({ tools: [...] })`, `ToolRegistry.register(tool)` and `AgentBuilder.addTool(tool)`. |
 | `ToolInput<typeof t>`, `ToolOutput<typeof t>` | Argument and result types of a defined tool. |
-| `ToolRegistry` (from `lousho/tools` or `lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
+| `ToolRegistry` (from `@linuxdevil/lousho/tools` or `@linuxdevil/lousho/executor`) | Holds the tools an agent config refers to (advanced: `register(tool)` or `register(name, descriptor)`). |
 | `httpTool`, `currentDateTool`, `dayNameTool` | Built-in tools.                               |
 | `createFsTools(fs, options?)`, `createShellTool(shell, options?)` | Workspace tools (`read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `shell`) over an `FsProvider` / `ShellProvider`. See [Workspace tools](/workspace-tools). |
 | `NodeWorkspace`, `MemoryWorkspace`, `SandboxShell` | Workspace providers: a real directory (paths confined to `root`, minimal shell env), an in-memory tree with a scripted `exec` for tests, and a `ShellProvider` over a `SandboxAdapter` (Docker). |
 | `createTodoTools({ store?, onChange? })`     | `todo_write` / `todo_read` tools (plus `getTodos()`) so agents can plan and track multi-step work; see [Todo tools](/tools#todo-tools). |
 | `connectMcp(servers, options?)`             | Connect MCP servers from config (stdio or HTTP) and load their tools; see [Share servers with `connectMcp()`](/mcp-integration#share-servers-with-connectmcp). |
-| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `lousho/tools`, and `lousho/mcp`. |
+| `loadMcpTools(client, connectionName)`       | Load a connected MCP server's tools as `ToolDescriptor`s. Available from the package root, `@linuxdevil/lousho/tools`, and `@linuxdevil/lousho/mcp`. |
 
 See [Tools](/tools) for a guide to defining and registering tools.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -260,7 +260,7 @@ execute }`) is legacy, still built for compatibility, and used only for
 descriptors that do not set `inputSchema` / `execute`.
 
 ```ts
-import { loadMcpTools } from 'lousho/mcp';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 ```
@@ -287,7 +287,7 @@ warning naming the server, the tool and the reason, and `onSkip` to collect
 what was left out:
 
 ```ts
-import { loadMcpTools, type SkippedMcpTool } from 'lousho/mcp';
+import { loadMcpTools, type SkippedMcpTool } from '@linuxdevil/lousho/mcp';
 
 const skipped: SkippedMcpTool[] = [];
 const tools = await loadMcpTools(mcpClient, 'my-server', {
@@ -316,13 +316,13 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 
 ## Flows, evals, observability and security
 
-- `FlowBuilder` / `FlowExecutor` (`lousho/flows`) - multi-step
+- `FlowBuilder` / `FlowExecutor` (`@linuxdevil/lousho/flows`) - multi-step
   workflow graphs; see [Flows](/flows).
-- `TriggerAdapter` and `TriggerRegistry` (`lousho/triggers`) -
+- `TriggerAdapter` and `TriggerRegistry` (`@linuxdevil/lousho/triggers`) -
   the extension point for your own wake-up mechanism, plus `verifySlackSignature()`,
   `parseCronExpression()` and the `WebhookAuth` helpers; see [Triggers](/triggers).
 - `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`
-  (`lousho/auth`) - route auth as an ordered list; the caller
+  (`@linuxdevil/lousho/auth`) - route auth as an ordered list; the caller
   it accepts reaches the run as `principal`; see [Route auth and principals](/auth).
 - `defineEval()`, scorers such as `exactMatch`, `toolCallOrder` and `budget`, checks such
   as `includes` and `atLeast`, and `llmJudge()` - agent evals run under vitest
@@ -330,7 +330,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
 - `withSpan()` and `TraceExporter` - tracing for `AgentExecutor.execute()`.
   `TraceExporter` is a bring-your-own-exporter interface (no exporter
   ships by default); for real OpenTelemetry spans, import
-  `createOtelTraceExporter()` from the `lousho/otel`
+  `createOtelTraceExporter()` from the `@linuxdevil/lousho/otel`
   subpath (requires the optional peer dependency `@opentelemetry/api`)
   instead of hand-rolling the OTel bridge - see
   `examples/tracing/run-otel.ts`. Spans follow the OpenTelemetry GenAI
@@ -344,7 +344,7 @@ Token estimates, the model price table, and the usage and cost of a run: see [Mo
   `GenerateHookContext` - hooks that observe, deny, rewrite or redact tool calls
   and model calls. See [Hooks](/hooks).
 - `EncryptionUtils`, `sha256`, `StorageService`
-  (`lousho/utils`) - supporting utilities; see
+  (`@linuxdevil/lousho/utils`) - supporting utilities; see
   [Utilities](/utilities).
 
 ## Deployment
diff --git a/approvals.mdx b/approvals.mdx
index 0bc6de7..56a58f5 100644
--- a/approvals.mdx
+++ b/approvals.mdx
@@ -13,7 +13,7 @@ See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutori
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `emailTool` is a tool built with `defineTool()`; `storage` is a `StorageService`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -39,7 +39,7 @@ if (paused.finishReason === 'awaiting-approval') {
 arguments, typed from the tool's zod `input`:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -92,7 +92,7 @@ error. `allow(tools)`, `deny(tools, reason?)` and `ask(tools)` build the
 common rules.
 
 ```ts
-import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from 'lousho';
+import { allow, ask, createAgent, defineTool, deny, type PermissionRule } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -171,7 +171,7 @@ session, each `send()` is its own transcript. Compacting away that message
 makes the tool ask again.
 
 ```ts
-import { createAgent, defineTool, once } from 'lousho';
+import { createAgent, defineTool, once } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const askOnce = once();
@@ -237,8 +237,8 @@ restart, give the agent a durable store, such as the SQLite one (see
 [Choosing a store](/sessions#choosing-a-store)):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const agent = createAgent({ provider, tools: [emailTool], store }); // or approvalStore: store.approvals
@@ -272,7 +272,7 @@ The step's calls that need no approval do not wait: they run when the step
 does, before the pause.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' /* , tools: [payInvoice, archiveThread] */ });
 const paused = await agent.send('Pay the invoice and archive the thread');
@@ -314,7 +314,7 @@ decided.
   `approved: false`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [emailTool] });
 const support = agent.session({ id: 'support-42' });
@@ -341,7 +341,7 @@ approval. There is no option on `resolve()` that ends the run. To stop that:
   model gets the reason and answers:
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
 
 const noRefile: AgentHook = {
   name: 'no-refile',
@@ -372,7 +372,7 @@ is only on the audit entry (`onPermissionDecision`). An expired pause resolved
 with `approved: true` does not run the tool.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -439,7 +439,7 @@ Its argument's `principal` is whose call it is, and
 tool's `ctx.approval.by` (see [auth](/auth#who-approved)).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const trusted = createAgent({
   provider,
@@ -448,6 +448,69 @@ const trusted = createAgent({
 });
 ```
 
+### Model-decided approvals
+
+`createAutoApprove` wraps a cheap model as the `approve` callback: calls an
+`auto` permission rule matched get a 0–1 safety score, and a score at or
+above 0.8 (within 8 s) runs the tool unreviewed. Everything else — a lower
+score, a timeout, a model error, arguments too long to judge — defers to a
+human exactly like `'defer'`. It never denies a call on its own.
+
+```ts
+import { ask, createAgent, createAutoApprove, modelAutoApprover } from '@linuxdevil/lousho';
+
+declare const issueTool: any;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
+
+const agent = createAgent({
+  provider,
+  tools: [issueTool, emailTool],
+  permissions: [ask(['create_issue'])],
+  approve: createAutoApprove({
+    autoApprover: modelAutoApprover({ provider: cheapProvider }),
+    isAuto: (toolName) => toolName === 'create_issue',
+    // fallback: the agent's own approve, asked for non-auto and escalated calls
+    onDecision: (d) => console.log(d.toolName, d.outcome, d.cause),
+  }),
+});
+```
+
+`modelAutoApprover` asks the provider for `{"safety": <0..1>, "reason":
+"..."}` at temperature 0; `createAutoApprove` clips long arguments before
+they reach the model and reports every decision through `onDecision`. Pass a
+`fallback` approve callback to keep a second line of defense for escalated
+calls.
+
+An AgentSpec v2 wires the same machinery from a permission rule: `action:
+'auto'` compiles to `ask`, and a host that supplies `autoApprover` (and
+optionally `onAutoApproval`) gets the model-scored callback for exactly
+those rules — first match still wins, so an `allow` listed before an `auto`
+rule means the model is never consulted.
+
+```yaml
+permissions:
+  - id: p1
+    tool: github_create_issue
+    action: auto
+```
+
+```ts
+import { modelAutoApprover, specV2ToAgent } from '@linuxdevil/lousho';
+
+declare const spec: import('@linuxdevil/lousho').AgentSpecV2;
+declare const baseDir: string;
+declare const cheapProvider: import('@linuxdevil/lousho').LLMProvider;
+
+const agent = await specV2ToAgent(spec, {
+  baseDir,
+  autoApprover: modelAutoApprover({ provider: cheapProvider }),
+  onAutoApproval: (d) => console.log(d.toolName, d.outcome, d.cause),
+});
+```
+
+With no `autoApprover` on the host, `action: 'auto'` behaves exactly like
+`ask`.
+
 ### Streaming the continued run
 
 `agent.approvals.streamResolve(decision, { signal })` and
@@ -463,7 +526,7 @@ is what `resolve()` resolves with. A continuation that pauses again ends with
 continues in that session, and `run.done` comes once the transcript is saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, tools: [emailTool] });
 const paused = await agent.send('Email Sam the report');
@@ -500,7 +563,7 @@ approval: in sessions, in durable stores and across a restart.
   in tests and scripted agents.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Plan the trip with the user.', provider, askQuestion: true });
 
@@ -537,8 +600,8 @@ tool. Resume later, after a real restart if you like, with
 `resumeAfterApproval()`:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
-import { StorageServiceApprovalStore } from 'lousho/utils';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
+import { StorageServiceApprovalStore } from '@linuxdevil/lousho/utils';
 
 const approvalStore = new StorageServiceApprovalStore(storage);
 
diff --git a/ar/cli.mdx b/ar/cli.mdx
index 76565bb..6fcea0e 100644
--- a/ar/cli.mdx
+++ b/ar/cli.mdx
@@ -14,7 +14,7 @@ title: "CLI"
 | `lousho acp <path>` | يقدّم ملف spec أو مجلد agent أو agent مكتوب بـ TS لمحرر (Zed وغيره من ACP clients) عبر Agent Client Protocol على stdio. | [ACP](/ar/acp) |
 | `lousho add <name>` | يثبّت tool أو skill أو channel أو schedule أو memory slot من JSON registry داخل مجلد agent، بعد أن يعرض الـ permission manifest ويفحص الكود مقابله. | [Registry](/ar/registry) |
 | `lousho mcp <spec>` | يقدّم الـ agent كسيرفر MCP (stdio، أو HTTP مع `--http`). | [MCP](/ar/mcp-integration#تشغيل-agent-كسيرفر-mcp) |
-| `lousho eval [globs...]` | يشغّل ملفات `*.eval.ts` تحت vitest؛ ويطبع ملخصًا ويكتب تقارير JUnit/JSON. | [Evals](/ar/evals#lousho-eval) |
+| `lousho eval [globs...]` | يشغّل ملفات `*.eval.ts` تحت vitest؛ ويطبع ملخصًا ويكتب تقارير JUnit/JSON. | [Evals](/ar/evals#حدود-الوقت) |
 | `lousho traces [id]` | يعرض آخر runs حفظها `fileTraceExporter()` (المدة، والـ model والـ tool calls، والـ tokens، والتكلفة)، أو يطبع run واحد كشجرة spans. | [Observability](/ar/observability#local-traces) |
 | `lousho build --target=<t> --agent=<spec>` | يبني سيرفر Node أو Docker image أو Cloudflare Worker جاهزًا للنشر. | [النشر](/ar/deployment) |
 | `lousho studio` | يفتح Agent Forge، الـ dashboard المرئية، على port محلي واحد. | [Agent Forge](/ar/agent-forge) |
diff --git a/ar/flows.mdx b/ar/flows.mdx
index fbf41d1..d40aa5a 100644
--- a/ar/flows.mdx
+++ b/ar/flows.mdx
@@ -339,7 +339,7 @@ const result = await FlowExecutor.execute(flow, { agent: { name: 'report' }, pro
 
 استخدم flow إذا كان الـpipeline معروفاً مسبقاً. استخدم [sub-agents](/ar/sub-agents) عندما تريد أن يقرر الـmodel نفسه ما يفوّضه، و[skills](/ar/skills) عندما يحتاج الـagent نفسه تعليمات إضافية لبعض المهام فقط. راجع [sub-agent أم skill أم flow؟](/ar/sub-agents#sub-agent-أم-skill-أم-flow؟).
 
-الـtracing يغطي الـflows مثل أي run للـagent (راجع [Tracing والـobservability](/ar/observability#flows)).
+الـtracing يغطي الـflows مثل أي run للـagent (راجع [Tracing والـobservability](/ar/observability#الأخطاء)).
 
 ## تعبيرات الـflow
 
diff --git a/ar/forge-author.mdx b/ar/forge-author.mdx
new file mode 100644
index 0000000..db7de94
--- /dev/null
+++ b/ar/forge-author.mdx
@@ -0,0 +1,8 @@
+---
+title: "The Agent Author"
+---
+
+{/* pending-translation */}
+<Note>
+هذه الصفحة لم تُترجَم إلى العربية بعد. اقرأ [النسخة الإنجليزية](/forge-author).
+</Note>
diff --git a/ar/forge-builder.mdx b/ar/forge-builder.mdx
new file mode 100644
index 0000000..21124e6
--- /dev/null
+++ b/ar/forge-builder.mdx
@@ -0,0 +1,8 @@
+---
+title: "The visual builder"
+---
+
+{/* pending-translation */}
+<Note>
+هذه الصفحة لم تُترجَم إلى العربية بعد. اقرأ [النسخة الإنجليزية](/forge-builder).
+</Note>
diff --git a/ar/forge-lifecycle.mdx b/ar/forge-lifecycle.mdx
new file mode 100644
index 0000000..86a874c
--- /dev/null
+++ b/ar/forge-lifecycle.mdx
@@ -0,0 +1,8 @@
+---
+title: "Versions, triggers and publishing"
+---
+
+{/* pending-translation */}
+<Note>
+هذه الصفحة لم تُترجَم إلى العربية بعد. اقرأ [النسخة الإنجليزية](/forge-lifecycle).
+</Note>
diff --git a/ar/hosted-tools.mdx b/ar/hosted-tools.mdx
index f9a312d..7b4aacd 100644
--- a/ar/hosted-tools.mdx
+++ b/ar/hosted-tools.mdx
@@ -56,7 +56,7 @@ console.log(result.text, result.usage.hostedToolCalls); // { web_search: 1 }
 
 في OpenRouter، `webSearch()` تضيف الـ server tool الخاصة بـ OpenRouter، وهي `openrouter:web_search`، إلى الطلب. يجري البحث على جهة OpenRouter لأي model. OpenRouter هو من يختار محرك البحث: بحث الـ model نفسه إن كان عنده، وإلا Exa. ويحاسبك على كل بحث فوق الـ tokens بالأسعار الموجودة في [صفحة أسعار OpenRouter](https://openrouter.ai/pricing). راجع [دليل web search](https://openrouter.ai/docs/guides/features/server-tools/web-search) لتفاصيل المحركات. ولأن السيرفر ينفّذ البحث داخل الطلب، الـ model لا يبلّغ عن أي tool call. بدلها يبلّغ الـ SDK عن hosted call واحدة لكل model step بحث فيها، ويقرأها من ردّ OpenRouter: `name: 'web_search'`، و`args` فارغة، والروابط المستشهد بها من `url_citation` annotations تصبح `sources`، و`result: { requests }` إذا بلّغ OpenRouter عن `usage.server_tool_use.web_search_requests` (وإلا `result` تكون `{}`؛ الاختبار الحي لم يستلم عددًا). الاستعلام الذي بحث عنه الـ model لا يُبلَّغ عنه.
 
-أي توليفة غير مدعومة ترفض الـ run قبل أول model call بخطأ [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](/ar/errors#lousho_hosted_tool_unsupported) يذكر الـ provider والـ tool وما الذي سيشتغل.
+أي توليفة غير مدعومة ترفض الـ run قبل أول model call بخطأ [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](/ar/errors#lousho_unsupported_content) يذكر الـ provider والـ tool وما الذي سيشتغل.
 
 الـ `LLMProvider` المخصّص يعلن عمّا يستطيع إرساله عبر `supportsHostedTool(type)` — قيمة `type` هي `'web_search'` أو `'code_interpreter'` أو `'file_search'` أو `'custom'` لـ `hostedTool()` — ويستلم الـ tools في `GenerateOptions.hostedTools`. الـ provider الذي لا يملك هذه الدالة لا يدعم أي hosted tool. و`withRetry()` و`withFallback()` تسألان الـ provider المغلَّف (الأول).
 
diff --git a/ar/mcp-integration.mdx b/ar/mcp-integration.mdx
index 1d84303..7c35eb2 100644
--- a/ar/mcp-integration.mdx
+++ b/ar/mcp-integration.mdx
@@ -49,9 +49,9 @@ await agent.close();
 أي متغير آخر يحتاجه السيرفر (API key، أو `NODE_ENV`، أو إعداد proxy)
 لا يُورَّث إلا إذا ذكرته: `env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }`. الـ tool call
 الفاشل (السيرفر خرج، أو انتهت مهلته، أو ردّ بخطأ في البروتوكول)
-يُرفض بـ[`LOUSHO_MCP_CALL_FAILED`](/ar/errors#lousho_mcp_call_failed) مع ذكر
+يُرفض بـ[`LOUSHO_MCP_CALL_FAILED`](/ar/errors#lousho_approval_not_found) مع ذكر
 `<server>__<tool>`. والسيرفر الذي لا يبدأ يفشل بـ
-[`LOUSHO_MCP_START_FAILED`](/ar/errors#lousho_mcp_start_failed)، ورسالته
+[`LOUSHO_MCP_START_FAILED`](/ar/errors#lousho_approval_store_missing)، ورسالته
 فيها exit code وآخر الأسطر التي كتبتها العملية على stderr.
 `stderr: 'forward'` (الافتراضي) ينسخ أيضًا stderr العملية إلى stderr العملية الحالية،
 و`'capture'` يحتفظ بآخر الأسطر فقط، و`'inherit'` / `'ignore'` لا يحتفظان بشيء.
diff --git a/ar/pending.json b/ar/pending.json
index fe51488..27f8904 100644
--- a/ar/pending.json
+++ b/ar/pending.json
@@ -1 +1,5 @@
-[]
+[
+  "forge-builder",
+  "forge-author",
+  "forge-lifecycle"
+]
diff --git a/ar/schedules.mdx b/ar/schedules.mdx
index d2c7f73..c9b923d 100644
--- a/ar/schedules.mdx
+++ b/ar/schedules.mdx
@@ -28,7 +28,7 @@ const running = startSchedules(agent, [morning, cleanup]);
 await running.stop();
 ```
 
-- `cron`: خمسة حقول (`minute hour day-of-month month day-of-week`) أو `@hourly` أو `@daily` أو `@weekly` أو `@monthly`، ويُحسَب في `timezone` (اسم IANA، والافتراضي منطقة الجهاز الزمنية). إذا كان التعبير غير صالح، أو حدّدت `prompt` و`run` معًا، أو ما حدّدت أي واحد منهما، `defineSchedule()` يرمي `LOUSHO_SCHEDULE_INVALID` مباشرة — لا عند أول firing. راجع [الأخطاء](/ar/errors#lousho_schedule_invalid).
+- `cron`: خمسة حقول (`minute hour day-of-month month day-of-week`) أو `@hourly` أو `@daily` أو `@weekly` أو `@monthly`، ويُحسَب في `timezone` (اسم IANA، والافتراضي منطقة الجهاز الزمنية). إذا كان التعبير غير صالح، أو حدّدت `prompt` و`run` معًا، أو ما حدّدت أي واحد منهما، `defineSchedule()` يرمي `LOUSHO_SCHEDULE_INVALID` مباشرة — لا عند أول firing. راجع [الأخطاء](/ar/errors#السجل).
 - `run` تستقبل `{ agent, firedAt, name }`.
 
 `startSchedules(agent, schedules, { now?, setTimer?, onError?, keepAlive? })` يحتفظ بمؤقّت واحد لكل schedule. أي run يرمي خطأ يذهب إلى `onError` (الافتراضي: `console.error`) ولا يوقّف باقي الـ schedules أبدًا. والـ turn الخاص بـ prompt schedule إذا انتهى بأي `finishReason` غير `'stop'` يُعتبَر run فاشلًا أيضًا: `onError` يستقبل خطأ `LOUSHO_SCHEDULE_RUN_INCOMPLETE` يذكر السبب، مثلًا `'awaiting-approval'` (مع id الـ approval المعلّقة، وتبقى معلّقة إلى أن تحسمها بـ `agent.approvals.resolve()`)، أو `'output-invalid'` أو `'max-steps'`. الـ schedule لا يتداخل مع نفسه: لو الـ firing السابق ما زال شغّالًا، يُتخطّى الإطلاق التالي ويُبلَّغ به `onError`. والـ fires التي فاتت أثناء تعليق العملية تُتخطّى بدل إعادة تشغيلها. `now` و`setTimer` قابلان للحقن حتى لا تنام الاختبارات أبدًا.
diff --git a/ar/triggers.mdx b/ar/triggers.mdx
index 7b3edb8..be032a3 100644
--- a/ar/triggers.mdx
+++ b/ar/triggers.mdx
@@ -91,7 +91,7 @@ webhookChannel({
 
 ## تواقيع طلبات Slack
 
-`slackChannel()` يتحقق من كل طلب نيابةً عنك (راجع [Slack في Channels](/ar/channels#slack)). أما في الـhandler الخاص بك (slash commands والتفاعلات)، فتحقّق من الـbody الخام بـ`verifySlackSignature()`: HMAC-SHA256 على `v0:{X-Slack-Request-Timestamp}:{raw body}`، يُقارَن في زمن ثابت مع `X-Slack-Signature` (`v0=<hex>`). الطلبات الأقدم من خمس دقائق، أو التي تسبق الوقت المحلي بأكثر من دقيقة، تُرفَض (الـtimestamp بالثواني، كما ترسله Slack). راجع [توثيق Slack](https://docs.slack.dev/authentication/verifying-requests-from-slack).
+`slackChannel()` يتحقق من كل طلب نيابةً عنك (راجع [Slack في Channels](/ar/channels#discord)). أما في الـhandler الخاص بك (slash commands والتفاعلات)، فتحقّق من الـbody الخام بـ`verifySlackSignature()`: HMAC-SHA256 على `v0:{X-Slack-Request-Timestamp}:{raw body}`، يُقارَن في زمن ثابت مع `X-Slack-Signature` (`v0=<hex>`). الطلبات الأقدم من خمس دقائق، أو التي تسبق الوقت المحلي بأكثر من دقيقة، تُرفَض (الـtimestamp بالثواني، كما ترسله Slack). راجع [توثيق Slack](https://docs.slack.dev/authentication/verifying-requests-from-slack).
 
 ```ts
 import { verifySlackSignature } from 'lousho/triggers';
diff --git a/ar/troubleshooting.mdx b/ar/troubleshooting.mdx
index efe6769..a141e56 100644
--- a/ar/troubleshooting.mdx
+++ b/ar/troubleshooting.mdx
@@ -17,13 +17,13 @@ title: "حل المشاكل"
 
 - **السبب:** متغير مفتاح الـ provider (`OPENAI_API_KEY` أو `ANTHROPIC_API_KEY` أو `OPENROUTER_API_KEY`) غير موجود في بيئة العملية التي تشغّل الـ agent (`LOUSHO_PROVIDER_MISSING_API_KEY`).
 - **الحل:** اضبطه، أو مرّر instance جاهز من الـ provider. `npx lousho doctor` يطبع `set` أو `not set` لكل مفتاح، ولا يطبع القيمة أبدًا. بادئة `vendor/` في اسم الـ model هي التي تختار الـ provider؛ مع OpenRouter استخدم `openrouter/<vendor>/<model>` (مثال `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` يحتاج `OPENAI_API_KEY` حتى لو `OPENROUTER_API_KEY` هو الوحيد المضبوط.
-- **للمزيد:** [الخطأ](/ar/errors#lousho_provider_missing_api_key).
+- **للمزيد:** [الخطأ](/ar/errors#lousho_provider_request_failed).
 
 ### "Cannot find package `@ai-sdk/openai`" أو "install the optional peer"
 
 - **السبب:** كل provider يعتمد على حزمة اختيارية تُحمَّل عند أول استخدام، بإصدار رئيسي يقابل إصدار `ai` الرئيسي عندك (`LOUSHO_PEER_MISSING`). نفس الخطأ يغطي باقي الـ peer dependencies الاختيارية، مثل `dockerode` و`@modelcontextprotocol/sdk`.
 - **الحل:** نفّذ أمر `npm install` الموجود في الرسالة (موجود أيضًا في `error.installCommand`)، أو ابحث عن إصدار `ai` الرئيسي عندك في جدول الاقتران.
-- **للمزيد:** [حزم الـ providers](/ar/installation#حزم-الـ-providers)، [الـ peer dependencies الاختيارية](/ar/installation#optional-peers)، [الخطأ](/ar/errors#lousho_peer_missing).
+- **للمزيد:** [حزم الـ providers](/ar/installation#حزم-الـ-providers)، [الـ peer dependencies الاختيارية](/ar/installation#optional-peers)، [الخطأ](/ar/errors#lousho_hosted_tool_unsupported).
 
 ### "`ai` 5 is installed"
 
@@ -73,7 +73,7 @@ title: "حل المشاكل"
 
 - **السبب:** الـ session الموقوفة على approval لا تقبل مدخل جديد (`LOUSHO_SESSION_AWAITING_APPROVAL`)؛ أو أن `session.compact()` أو `session.clear()` استُدعيت وفي turn شغّال أو في الطابور (`LOUSHO_SESSION_BUSY`).
 - **الحل:** حسم الـ approval ثم أرسل مجددًا؛ أو انتظر `send()` الخاصة بالـ turn (أو ألغِها)، ثم استدعِ من جديد.
-- **للمزيد:** [بانتظار الـ approval](/ar/errors#lousho_session_awaiting_approval)، [مشغولة](/ar/errors#lousho_session_busy).
+- **للمزيد:** [بانتظار الـ approval](/ar/errors#lousho_session_turn_pending)، [مشغولة](/ar/errors#lousho_session_step_not_found).
 
 ## Tools
 
@@ -93,7 +93,7 @@ title: "حل المشاكل"
 
 - **السبب:** الـ model أرسل arguments لا تطابق الـ input schema للـ tool. داخل الـ run ترجع له الـ issues كنتيجة ويقدر يعيد المحاولة، فنادرًا ما ينتهي run بسببه.
 - **الحل:** إذا الـ model يغلط في نفس الحقل، خلّ نص `.describe()` أوضح. وإذا إنت استدعيت الـ tool بنفسك، صحّح الـ arguments المذكورة في الرسالة.
-- **للمزيد:** [الخطأ](/ar/errors#lousho_tool_args_invalid).
+- **للمزيد:** [الخطأ](/ar/errors#الـ-approvals-والـ-sessions).
 
 ## Providers و models
 
@@ -101,7 +101,7 @@ title: "حل المشاكل"
 
 - **السبب:** الـ provider طبّق rate limit على الاستدعاء (`LOUSHO_PROVIDER_RATE_LIMITED`) أو فشل فشلًا عابرًا.
 - **الحل:** `createAgent()` أصلًا تعيد الاستدعاء الفاشل مرتين — لكن فقط لـ model مُمرّر كسلسلة `provider/model` أو محلول من البيئة؛ أما `provider` instance تمرّره إنت فلا تُعاد محاولاته إلا إذا ضبطت `retry`. ارفعها بـ `retry: { maxRetries: 3 }`، واضبط `fallbackModels` للانتقال إلى الـ model التالي إذا الاستدعاء ظل يفشل.
-- **للمزيد:** [إعادة المحاولة و fallback models](/ar/providers#retry-ونماذج-fallback)، [الخطأ](/ar/errors#lousho_provider_rate_limited).
+- **للمزيد:** [إعادة المحاولة و fallback models](/ar/providers#retry-ونماذج-fallback)، [الخطأ](/ar/errors#lousho_peer_missing).
 
 ### الـ model لا يقرأ ملفاتي
 
@@ -121,7 +121,7 @@ title: "حل المشاكل"
 
 - **السبب:** `SubprocessSandbox` مع `network: { allow }` و`broker` يحتاج أن يكون الـ broker المخرج الوحيد للحاوية. Docker Desktop وrootless Docker وdaemon على جهاز آخر وEngine أقدم من 25.0.5 كلها لا تستطيع أن تعطيك هذا، فلا تبدأ أي حاوية (`LOUSHO_SANDBOX_EGRESS_UNSUPPORTED`). الرفض مقصود، بدل فتح egress مفتوح.
 - **الحل:** شغّل الـ agent على Linux host عليه Docker Engine 25.0.5 أو أحدث، أو استخدم `network: 'none'`.
-- **للمزيد:** [Sandboxed shell](/ar/workspace-tools#sandboxed-shell-sandboxshell)، [الخطأ](/ar/errors#lousho_sandbox_egress_unsupported).
+- **للمزيد:** [Sandboxed shell](/ar/workspace-tools#sandboxed-shell-sandboxshell)، [الخطأ](/ar/errors#lousho_flow_invalid).
 
 ### أدوات سيرفر MCP لا تظهر
 
diff --git a/auth.mdx b/auth.mdx
index b9e3d32..eb88a5c 100644
--- a/auth.mdx
+++ b/auth.mdx
@@ -4,7 +4,7 @@ title: "Route auth and principals"
 {/* Generated from docs/auth.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 An agent served over HTTP needs to know two things about each request: may it
-call at all, and who is it. `lousho/auth` answers both. You
+call at all, and who is it. `@linuxdevil/lousho/auth` answers both. You
 give a route an ordered list of auth entries (`jwt()`, `oidc()`, `basic()`,
 `apiToken()`, `anonymous()` or your own function); the first entry that
 accepts the request returns a **principal**, and that principal goes into the
@@ -12,9 +12,9 @@ run, where your `model` / `instructions` / `tools` functions and memory scopes
 can read it.
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
-import { apiToken, jwt } from 'lousho/auth';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
+import { apiToken, jwt } from '@linuxdevil/lousho/auth';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({
   provider: mockModel(['Hello!']),
@@ -86,7 +86,7 @@ exactly one key source:
 | `jwksUrl` | a JWKS endpoint (https, or http on localhost) | `RS256`, `ES256` by default; RSA and EC keys only |
 
 ```ts
-import { jwt } from 'lousho/auth';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const fromOurAuthServer = jwt({
   jwksUrl: 'https://auth.example.com/.well-known/jwks.json',
@@ -126,7 +126,7 @@ or http on `localhost` / `127.0.0.1` / `[::1]` — the same rule as `jwt()`'s
 `jwksUrl`). Algorithms default to `RS256` and `ES256`; HMAC is not allowed.
 
 ```ts
-import { oidc } from 'lousho/auth';
+import { oidc } from '@linuxdevil/lousho/auth';
 
 const google = oidc({ issuer: 'https://accounts.google.com', audience: process.env.GOOGLE_CLIENT_ID ?? 'client-id' });
 ```
@@ -142,7 +142,7 @@ carries `WWW-Authenticate: Basic realm="<realm>", charset="UTF-8"` so browsers
 show their login prompt.
 
 ```ts
-import { basic } from 'lousho/auth';
+import { basic } from '@linuxdevil/lousho/auth';
 
 const operators = basic({ users: { ops: process.env.OPS_PASSWORD! }, realm: 'agent' });
 // Or check against your own store (compare in constant time there):
@@ -171,7 +171,7 @@ Any function of the `Request` is an entry. Declare the challenges it answers a
 `401` with, or it advertises `Bearer`:
 
 ```ts
-import { AuthError, type AuthFn } from 'lousho/auth';
+import { AuthError, type AuthFn } from '@linuxdevil/lousho/auth';
 
 const tenantKey: AuthFn = async (request) => {
   const key = request.headers.get('x-tenant-key');
@@ -231,7 +231,7 @@ In an [agent directory](/agent-directories), put the list in `auth.ts` (or
 
 ```ts
 // my-agent/auth.ts
-import { apiToken, oidc } from 'lousho/auth';
+import { apiToken, oidc } from '@linuxdevil/lousho/auth';
 
 export default [
   oidc({ issuer: 'https://login.example.com', audience: 'agent-api' }),
@@ -261,8 +261,8 @@ The principal is on the run context next to `sessionId` and `metadata`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const notes = defineMemory({
   name: 'notes',
@@ -346,7 +346,7 @@ none in any of these places.
 ### In a tool
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const myOrders = defineTool({
@@ -367,8 +367,8 @@ from the request body or the model, and a tool cannot change it.
 ### Approval policies and permission rules
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const deploy = defineTool({
@@ -396,8 +396,8 @@ A decision can name who made it. The approved tool sees the decider as
 `ctx.approval.by`, next to `ctx.approval.note`:
 
 ```ts
-import { createAgent, defineTool, type Principal } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type Principal } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -467,8 +467,8 @@ see the example under [Who may decide an approval](#who-may-decide-an-approval))
 caller keeps the check stateless:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 // The user id a session id starts with: everything before its last `-`. A prefix match would let
@@ -524,7 +524,7 @@ Behind a reverse proxy:
   rewrites `Host`, list the upstream name the proxy sends, not the public one.
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -554,8 +554,8 @@ customer can no longer approve their own refund, and a supervisor can read any
 session (to see what they are approving) and decide in it:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -577,8 +577,8 @@ claims, a manager decides them, and nobody approves their own:
 
 ```ts
 // my-agent/auth.ts
-import { apiToken } from 'lousho/auth';
-import type { ApprovalAccessRequest, SessionAccessRequest } from 'lousho';
+import { apiToken } from '@linuxdevil/lousho/auth';
+import type { ApprovalAccessRequest, SessionAccessRequest } from '@linuxdevil/lousho';
 
 export default [
   apiToken(process.env.ALICE_TOKEN!, { id: 'alice' }),
diff --git a/build-a-coding-agent.mdx b/build-a-coding-agent.mdx
index 47503b7..b28c5db 100644
--- a/build-a-coding-agent.mdx
+++ b/build-a-coding-agent.mdx
@@ -20,7 +20,7 @@ file system and a shell for it, and `createFsTools()` and `createShellTool()`
 turn it into tools.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const tools = [...createFsTools(workspace), createShellTool(workspace)];
@@ -45,7 +45,7 @@ per-tool map. For the shell, pass a predicate over the command string and gate
 only the commands you consider risky.
 
 ```ts
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -77,7 +77,7 @@ written and `tool.start` announces each tool call (see
 [Streaming](/streaming)).
 
 ```ts
-import { NodeWorkspace, createAgent, createFsTools, createShellTool } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: process.cwd() });
 const agent = createAgent({
@@ -114,7 +114,7 @@ the rest of the work. That run can pause again, so loop until there is no
 
 ```ts
 import { createInterface } from 'node:readline/promises';
-import { createAgent, type AgentRun } from 'lousho';
+import { createAgent, type AgentRun } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are a coding agent.' });
 const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -169,7 +169,7 @@ same pause handling.
 // coding.ts
 // Run: OPENAI_API_KEY=... npx tsx coding.ts "Fix the failing test"
 import { createInterface } from 'node:readline/promises';
-import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from 'lousho';
+import { NodeWorkspace, createAgent, createFsTools, createShellTool, type AgentRun } from '@linuxdevil/lousho';
 
 const DESTRUCTIVE = /\b(rm|mv|chmod|chown|git\s+(push|reset|clean|checkout))\b|>/;
 
@@ -253,8 +253,8 @@ memory and takes a scripted `exec` for the shell, and `mockModel` plays the
 model. Assert on `workspace.snapshot()` and `workspace.commands`.
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'math.js': 'exports.add = (a, b) => a - b;\n' },
@@ -281,8 +281,8 @@ To test the approval path, gate `write_file` the way the real agent does.
 runs the write and finishes the turn.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.txt': 'old\n' } });
 const agent = createAgent({
diff --git a/changelog.mdx b/changelog.mdx
index fdab60e..c907767 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -6,6 +6,120 @@ description: "Every notable change to lousho, newest first."
 
 ## [Unreleased]
 
+- **Breaking:** the package is renamed from `lousho` to `@linuxdevil/lousho`. Update imports from `'lousho'` / `'lousho/…'` to `'@linuxdevil/lousho'` / `'@linuxdevil/lousho/…'` and dependencies from `"lousho"` to `"@linuxdevil/lousho"`. The `lousho` binary name is unchanged, so `npx @linuxdevil/lousho …` and `lousho …` commands keep working.
+- Docs: `docs/agent-forge.md` is retitled **Lousho Studio** and now documents installing the separate `@linuxdevil/studio` package, workspaces, which SDK runs a workspace's agents (with each banner), the collector, and reporting deployed agents via `LOUSHO_OBSERVE_PROJECT`.
+- **Breaking:** Studio is now the separate package `@linuxdevil/studio`; the SDK tarball no longer contains `apps/agent-forge`. `lousho studio` finds an installed `@linuxdevil/studio` (local, next to the SDK, or global) and opens the current folder as a workspace, or prints `Studio is a separate install: npx @linuxdevil/studio` when it is missing. Inside the SDK checkout it keeps its dev/prod modes (`--prod`/`--dev`). Install Studio with `npm i -g @linuxdevil/studio` (or `npx @linuxdevil/studio`).
+- Studio: the Code tab gains "Eject to project" (`POST /agents/:id/eject`), which writes the agent-directory form (`specToAgentDir`) to `agents/<id>/` in the workspace after a confirm dialog, with an explicit overwrite step when the folder already exists.
+- New `@linuxdevil/lousho/observe` subpath: `startObserveDaemon`, `probeHealth`, `isObserveDaemon`, `defaultDbPath`, `OBSERVE_DEFAULT_PORT` and the daemon option/retention defaults, so a host process (Studio) can run and probe the collector through public exports.
+- Install docs use the public npm packages again (`npm install @linuxdevil/lousho`, `npm create lousho`).
+- `@linuxdevil/lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md).
+- `lousho bridge`: a new command that speaks Studio's bridge protocol (NDJSON on stdin/stdout, protocol 1) so Lousho Studio can build and run a project's agents with that project's own SDK and dependencies. It answers `hello`, `catalog`, `compile` and `shutdown`, and runs agents: `run`/`chat` start a run or chat turn, `steer`/`abort` control it, `resolveApproval`/`answerQuestion` resume a paused run, and every `AgentEvent`, trace span, steer join and run settle arrives as a pushed event (flows are refused with `LOUSHO_HOST_UNSUPPORTED`).
+- Model strings resolve any official AI SDK provider: `mistral/...`, `groq/...`, `xai/...`, `bedrock/...`, `vertex/...`, `azure/...` and 13 more load `@ai-sdk/<vendor>` on the first call, and `ai-sdk/<vendor>/<model>` loads any other `@ai-sdk/*` package. The package reads its own credentials. See [Providers](/providers#any-ai-sdk-vendor-by-name).
+
+## [1.0.0-alpha.117] - 2026-11-09
+
+## [1.0.0-alpha.116] - 2026-11-09
+
+## [1.0.0-alpha.115] - 2026-11-09
+
+## [1.0.0-alpha.114] - 2026-11-09
+
+## [1.0.0-alpha.113] - 2026-11-09
+
+## [1.0.0-alpha.112] - 2026-11-09
+
+## [1.0.0-alpha.111] - 2026-11-09
+
+## [1.0.0-alpha.110] - 2026-11-09
+
+## [1.0.0-alpha.109] - 2026-11-09
+
+## [1.0.0-alpha.108] - 2026-11-09
+
+## [1.0.0-alpha.107] - 2026-11-09
+
+## [1.0.0-alpha.106] - 2026-11-09
+
+## [1.0.0-alpha.105] - 2026-11-09
+
+## [1.0.0-alpha.104] - 2026-11-09
+
+## [1.0.0-alpha.103] - 2026-11-08
+
+## [1.0.0-alpha.102] - 2026-11-08
+
+## [1.0.0-alpha.101] - 2026-11-08
+
+## [1.0.0-alpha.100] - 2026-11-08
+
+## [1.0.0-alpha.99] - 2026-11-08
+
+## [1.0.0-alpha.98] - 2026-11-08
+
+## [1.0.0-alpha.97] - 2026-11-08
+
+## [1.0.0-alpha.96] - 2026-11-08
+
+## [1.0.0-alpha.95] - 2026-11-08
+
+## [1.0.0-alpha.94] - 2026-11-08
+
+## [1.0.0-alpha.93] - 2026-11-08
+
+## [1.0.0-alpha.92] - 2026-11-08
+
+## [1.0.0-alpha.91] - 2026-11-08
+
+## [1.0.0-alpha.90] - 2026-11-08
+
+## [1.0.0-alpha.89] - 2026-11-08
+
+## [1.0.0-alpha.88] - 2026-11-08
+
+## [1.0.0-alpha.87] - 2026-11-08
+
+## [1.0.0-alpha.86] - 2026-11-08
+
+## [1.0.0-alpha.85] - 2026-11-08
+
+## [1.0.0-alpha.84] - 2026-11-08
+
+## [1.0.0-alpha.83] - 2026-11-08
+
+## [1.0.0-alpha.82] - 2026-11-08
+
+## [1.0.0-alpha.81] - 2026-11-08
+
+## [1.0.0-alpha.80] - 2026-11-08
+
+## [1.0.0-alpha.79] - 2026-11-08
+
+## [1.0.0-alpha.78] - 2026-11-08
+
+## [1.0.0-alpha.77] - 2026-11-08
+
+## [1.0.0-alpha.76] - 2026-11-08
+
+## [1.0.0-alpha.75] - 2026-11-08
+
+## [1.0.0-alpha.74] - 2026-11-08
+
+## [1.0.0-alpha.73] - 2026-11-08
+
+## [1.0.0-alpha.72] - 2026-11-08
+
+## [1.0.0-alpha.71] - 2026-11-08
+
+## [1.0.0-alpha.70] - 2026-11-08
+
+## [1.0.0-alpha.69] - 2026-11-08
+
+## [1.0.0-alpha.68] - 2026-11-08
+
+## [1.0.0-alpha.67] - 2026-11-08
+
+## [1.0.0-alpha.66] - 2026-11-08
+
 ## [1.0.0-alpha.65] - 2026-11-08
 
 ## [1.0.0-alpha.64] - 2026-11-08
@@ -74,8 +188,8 @@ description: "Every notable change to lousho, newest first."
 
 ## [1.0.0-alpha.32] - 2026-11-07
 
-- Install docs use the public npm packages again (`npm install lousho`, `npm create lousho`).
-- `lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](/improve).
+- Install docs use the public npm packages again (`npm install @linuxdevil/lousho`, `npm create lousho`).
+- `@linuxdevil/lousho/improve` (experimental): `improveAgent()` proposes tested edits to an agent's instructions and skills, offline, gated against the current harness and held-out cases. It applies nothing. See [Improving an agent](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md).
 - `agent.recover({ retryWithDiagnosis: true })` gives a run that reached `maxAttempts` one fork told why it failed, before quarantining it. `createOutputCheck()` is a new hook that runs your check after a tool succeeds and tells the model what it found. A fork no longer inherits `lastError` and `attempts` from its source.
 - **Behavior change:** `agent.recover()` no longer resumes a failing run forever. It backs off exponentially from the last failure (up to 15 minutes) and stops after `maxAttempts` failures in a row (default 10), calling the new `onQuarantined(run)` once. `agent.resume()` still runs a quarantined run. Pass a larger `maxAttempts` to keep retrying longer.
 - `lousho observe failures` also lists runs whose process died and scores below `--min-score` (default 0.5).
@@ -86,7 +200,7 @@ description: "Every notable change to lousho, newest first."
 
 ## [1.0.0-alpha.31] - 2026-11-01
 
-- **Behavior change:** the package is renamed from `@lousho/build-ai-agent` to `lousho`, and the scaffolder from `create-lousho-agent` to `create-lousho` (`npm create lousho`). Update imports from `@lousho/build-ai-agent` to `lousho` (subpaths such as `lousho/testing` keep their names). Install with `npm install lousho` or `npm create lousho` (no token needed). The packages are also mirrored to GitHub Packages as `@linuxdevil/lousho` and `@linuxdevil/create-lousho` for the repository's Packages tab.
+- **Behavior change:** the package is renamed from `@lousho/build-ai-agent` to `@linuxdevil/lousho`, and the scaffolder from `create-lousho-agent` to `create-lousho` (`npm create lousho`). Update imports from `@lousho/build-ai-agent` to `@linuxdevil/lousho` (subpaths such as `@linuxdevil/lousho/testing` keep their names). Install with `npm install @linuxdevil/lousho` or `npm create lousho` (no token needed). The packages are also mirrored to GitHub Packages as `@linuxdevil/lousho` and `@linuxdevil/create-lousho` for the repository's Packages tab.
 
 ## [1.0.0-alpha.30] - 2026-10-31
 
@@ -228,7 +342,7 @@ opt-out.
 - A decision on an approval whose winning decision is still streaming is a `409` (`LOUSHO_APPROVAL_CONFLICT`), as docs/auth.md says, instead of a `404`.
 - The session routes' `400` bodies carry a `code`: `LOUSHO_REQUEST_INVALID` (invalid JSON, missing or empty fields), `LOUSHO_APPROVAL_DECISION_INVALID` (an approval body with neither `approved` nor `answer`), `LOUSHO_SESSION_ID_INVALID`.
 - `lousho chat` prints a failed turn with its error code, the provider's failure category and HTTP status, and the fix (`error: User not found. (auth-failure, HTTP 401)` then `[LOUSHO_PROVIDER_REQUEST_FAILED] ...`), as docs/cli.md says, instead of the bare provider message. The terminal chat of a project scaffolded by `lousho init` / `create-lousho-agent` does the same.
-- A `.env` saved with a UTF-8 byte order mark (PowerShell 5.1's `Set-Content -Encoding utf8`) no longer loses its first variable: the `lousho` commands and the scaffolded `src/index.ts` drop the mark before parsing. Variables already set in the environment still win.
+- A `.env` saved with a UTF-8 byte order mark (PowerShell 5.1's `Set-Content -Encoding utf8`) no longer loses its first variable: the `@linuxdevil/lousho` commands and the scaffolded `src/index.ts` drop the mark before parsing. Variables already set in the environment still win.
 - `lousho doctor src/agent.ts` loads a `.ts`/`.js` agent module the way `lousho dev` does instead of failing with `LOUSHO_SPEC_UNSUPPORTED_FORMAT`, and a missing key for the module's provider is a failure. A scaffolded project's `npm run doctor` now runs `lousho doctor src/agent.ts`, so it fails when the agent's key is missing.
 - `lousho doctor --ping` checks OpenRouter at `/api/v1/key`, which needs the key (its `/models` answers without one, so a wrong key passed); a key the provider rejects is now a failure, and a ping of a custom `OPENAI_BASE_URL` says it shows reachability only.
 - `lousho doctor` fix lines use PowerShell syntax (`$env:NAME="<your key>"`) on Windows.
@@ -439,7 +553,7 @@ create-lousho-agent 0.1.2-alpha.5.
 - A run that re-pauses on several approvals after a resume persists every pending approval id in its checkpoint: `markAwaitingApproval()` wrote only `approvalId`, so durable discovery (`pausedApprovalIds`, `agent.approvals.list()`) named 1 of N approvals; it now carries the group's `approvalIds` like `markGroupPending()` does.
 - The `inbox-triage` registry kit loads under `lousho dev`, `chat`, `acp`, `mcp` and `doctor`: its relative imports carry the `.ts` extension Node's type stripping needs (only bundlers resolved them). A test now installs every registry kit and loads it in a plain `node` process, as the CLI does. An extensionless relative import in an agent directory gets a hint naming the specifier to write (`'./lib/store.ts'`), and on a Node without built-in type stripping (before 22.18) the `.ts` load error says Node 22.19+ is required.
 - `OPENAI_BASE_URL` (and `ANTHROPIC_BASE_URL`) is used with `@ai-sdk/openai` 1.x (`@ai-sdk/anthropic` 1.x), the line that pairs with `ai` 4: the provider passes it when no `baseURL` is configured. Before, `model: 'openai/...'` called api.openai.com while `lousho doctor --ping` reported the custom endpoint.
-- `PropagatingToolError`, `McpToolError` and `WorkspaceError` pass `instanceof` across the ESM and CJS copies of the SDK, so a `.cjs` tool's "do not retry" error stops the run under the ESM `lousho` CLI instead of being handed to the model (and retried).
+- `PropagatingToolError`, `McpToolError` and `WorkspaceError` pass `instanceof` across the ESM and CJS copies of the SDK, so a `.cjs` tool's "do not retry" error stops the run under the ESM `@linuxdevil/lousho` CLI instead of being handed to the model (and retried).
 - `lousho dev` re-evaluates the local helper files an edited tool or agent module imports (the `?t=` cache-bust is passed on to relative imports), instead of logging "reloaded" while serving the stale helper; editor temp files no longer show in the "changed:" list.
 - `lousho eval`: a case that vitest fails after the case finished (it ran past its time limit) is reported as that case failing, not as a pass plus an extra `vitest` row; a run that records no case at all (a mistyped `--tag`) exits 1 like a glob that matches nothing.
 - The yarn scaffold's `yarn test` works: the templates list `vite`, vitest's peer, which yarn 1 does not install. The README's "Next 3 commands" lists three, and the tools template's README counts its three tools.
@@ -546,7 +660,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 - Permission modes: `createAgent({ permissionMode })`, `send()` / `stream()` `{ permissionMode }`, `agent.session({ permissionMode })` and `session.setPermissionMode()` put an agent in `'plan'` (only read-only tools run; everything else is refused with `kind: 'denied'`, also when an `allow` rule matched, and a run that starts in plan mode gets one system-prompt paragraph saying so), `'acceptEdits'` (file edits that would ask run without asking) or `'dontAsk'` (a call that would ask is refused; nothing pauses). The modes are presets applied after hooks, permission rules, tool guardrails and `needsApproval`, so no mode turns a deny into a run. A function mode, and a session's mode, are read at every tool call, so a switch applies from the next call, also mid-turn and in a paused turn continued by `agent.approvals.resolve()`. Sub-agents run under the lead's mode unless it is `'default'`; a remote sub-agent is refused in plan mode. Audit: under a mode other than `'default'` every call is audited, `PermissionDecisionEntry.mode` says when the mode changed the outcome, and the new `onPermissionModeChange` records each switch. New: `PermissionMode` and `PermissionModeChange` types, `defineTool({ editsFiles })` (`metadata.editsFiles`, set on `write_file` and `edit_file`), `readOnlyHint: true` on `load_skill`, `recall_<name>`, `agent_status` and `agent_await`. The mode is not saved in checkpoints. Example: `examples/plan-mode`. See [Permission modes](/permission-modes).
 - Semantic recall: a memory slot can recall by meaning. New `EmbeddingProvider` (`{ id, embed(texts) }`) and `aiSdkEmbedder(model, { id?, maxBatch? })`, which wraps any AI SDK embedding model through `embedMany` from the installed `ai` (4, 6 or 7; `ai` is loaded on first use, no new dependency), and two providers that rank by cosine similarity: `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` from the root and `sqliteVectorMemory(store, options)` from `@lousho/build-ai-agent/sqlite` (a new `memory_vectors` table, added to an existing database file on open; `memory_items` and `sqliteMemory()` are unchanged). With a query, `list()` returns the scope key's items by score (floor `minScore`, default 0.2; score in `metadata.score`); without one it lists the newest first. Items embedded by another embedder id are skipped when ranking until `provider.reindex(scopeKey?)` re-embeds them. A `MemoryProvider` may set `ranking: 'relevance'`, which makes the `recall_<name>` tool say "by meaning, most relevant first". `hashEmbedder({ dimensions? })` from `@lousho/build-ai-agent/testing` is a deterministic offline embedder for tests. `describeMemoryProviderContract` takes `{ query: 'filter' | 'rank' }`. docs/memory.md has a new `## Semantic recall` section at the end.
 - `teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? })`: an agent behind an Azure Bot in Microsoft Teams, mounted like the other channels (`POST <basePath>/teams`). The inbound Bot Framework token is verified with the auth module (`oidc()`: RS256, the key set of the fixed Bot Framework OpenID metadata, issuer `https://api.botframework.com`, audience `appId`, 5-minute tolerance) before the body is parsed, and its `serviceurl` claim must equal the activity's `serviceUrl`; replies go only to that service URL (https). Personal chats always reach the agent, group chats and channels only on an `@mention` (stripped from the text); one session per conversation; Markdown replies split at 25,000 characters; tool approvals are Adaptive Cards with Approve and Deny buttons (`approvers` as on the other channels; the card updates to "Approved by..." and names its conversation, so a copied or replayed reference decides nothing); `ask_question` is answered by the next message, also after a restart with durable stores. No `node:*` import. Telegram and GitHub now set the sender as the run's `principal` too (`authenticator: 'telegram'` with the user id, `'github'` with the login), as Slack and Discord do. See docs/channels.md#microsoft-teams.
-- Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): `npx lousho build./my-agent --target=cloudflare-worker`. The build reads the directory on Node and generates `agent.module.ts` (static imports of `tools/*` and of an `agent.ts` config; `instructions.md`, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of `resolveAgentDir()` (the config check and the tool-export rules now live in Node-free modules both use). The config's `model` must name a Worker provider, or `agent.ts` sets a `provider` instance. `subagents/`, `schedules/`, `channels/`, `memory/`, `projectInstructions` and an unsupported provider are rejected with `LOUSHO_DEPLOY_FAILED`, naming what to remove. In a Worker build, an agent file's `@lousho/build-ai-agent` import resolves to a Worker-safe subset (`defineTool`, `defineSkill`, the Worker providers, `fromAiSdk`, errors,...); another name fails the build with the list. The leak check now names the file that imported a Node builtin (`"node:fs" imported by my-agent/tools/files.ts`) instead of failing with esbuild's "Could not resolve". Tools run in the Worker's isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
+- Cloudflare Worker target builds agent directories (config, instructions, TypeScript tools, skills): `npx @linuxdevil/lousho build./my-agent --target=cloudflare-worker`. The build reads the directory on Node and generates `agent.module.ts` (static imports of `tools/*` and of an `agent.ts` config; `instructions.md`, a JSON/YAML config and the skills embedded as JSON), and the Worker builds the agent with the rules of `resolveAgentDir()` (the config check and the tool-export rules now live in Node-free modules both use). The config's `model` must name a Worker provider, or `agent.ts` sets a `provider` instance. `subagents/`, `schedules/`, `channels/`, `memory/`, `projectInstructions` and an unsupported provider are rejected with `LOUSHO_DEPLOY_FAILED`, naming what to remove. In a Worker build, an agent file's `@lousho/build-ai-agent` import resolves to a Worker-safe subset (`defineTool`, `defineSkill`, the Worker providers, `fromAiSdk`, errors,...); another name fails the build with the list. The leak check now names the file that imported a Node builtin (`"node:fs" imported by my-agent/tools/files.ts`) instead of failing with esbuild's "Could not resolve". Tools run in the Worker's isolate with its rights: see docs/cloudflare-workers.md#build-and-deploy.
 - Workspace rewind: `createFsTools(fs, { checkpoints })` with a new `WorkspaceCheckpoints` backs up every file `write_file` and `edit_file` change (content and, where the provider has the new optional `FsProvider.getMode` / `chmod`, permission bits), grouped by session and turn. `checkpoints.list({ sessionId })` shows the changed paths per turn; `checkpoints.rewind(toTurn, { sessionId, dryRun, force })` restores every file changed in that turn or later, deletes files the agent created, and skips files changed since by something else (`'changed-since'`), files over `maxFileBytes` (`'too-large'`) and paths that are no longer files. Every path is checked before anything is written, and restores go through the provider, so `NodeWorkspace` keeps them inside its root. Retention: the newest `maxTurns` turns per session (default 20), the old content only for a turn's first write of a path, rewound turns dropped, `clear({ sessionId })`. Stores: `MemoryWorkspaceCheckpointStore` (default) and `FileWorkspaceCheckpointStore(dir)` (one JSON file per session, atomic writes). `NodeWorkspace` gains `getMode()` and `chmod()`. Without `checkpoints` the tools behave as before. See [Workspace tools](/workspace-tools#the-tools).
 - Route auth and principals: a new subpath, `@lousho/build-ai-agent/auth`, with `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` and `routeAuth()`. A route takes an ordered list of entries: the first one that returns a `Principal` accepts the request, `null` skips to the next, `AuthError(401 | 403)` stops; when every entry skips the answer is a generic `401` with one `WWW-Authenticate` header per challenge (`Bearer`, `Basic realm="..."`), and the body never says which check failed. JWTs are verified with Web Crypto only (no new dependency, no `node:` import, so the helpers run on Workers and edge routes): `alg: none`, algorithms outside the configured list, a `crit` header and algorithm confusion (an HS token checked against a public key) are refused; `exp` is required, `nbf` / `iat` honored, `iss` / `aud` checked, with a clock tolerance of 60 s (at most 300); JWKS key sets are cached for 10 minutes and refetched at most once per 30 s, and a key-set URL is never taken from a token. `oidc()` uses the configured issuer's discovery document and requires it to name the same issuer. `basic()` and `apiToken()` compare in constant time. `createRouteHandler({ auth })` and `createDeployedServer(agent, { auth })` take the list (a token string and a boolean function work as before); the node server appends `apiToken(LOUSHO_API_TOKEN)` when that variable is set; an agent directory's `auth.ts` is bundled by `lousho build --target=node-server` / `docker` and guards the built server (`resolveAgentDir()` returns it as `auth`, the manifest has `auth: true`). The accepted principal reaches the run: `send()` / `stream()` / session turns take `principal`, and `RunConfigContext` (the `model` / `instructions` / `tools` functions) and `MemoryScopeContext` (memory scopes) carry it; Slack and Discord channels set the sender as the principal. `Principal` is also exported from the root. Bad helper options throw the new error code `LOUSHO_AUTH_CONFIG_INVALID` when the helper is created. `createRouteHandler()` without `auth` logs one warning when `NODE_ENV` is `production`. Route auth does not check session ownership, the principal does not reach tools or approval policies yet, and the Cloudflare Worker target keeps the `LOUSHO_API_TOKEN` token only. See [Route auth and principals](/auth).
 - OAuth token storage: `AgentStore` gains a fourth optional part, `tokens` (`OAuthTokenStore`: `get` / `set` / `delete` / `list` per provider and credential owner, single-use pending sign-ins with `putPending` / `takePending`, and `getClient` / `setClient` for dynamically registered clients). Owners are `{ owner: 'app' }` or `{ owner: 'user', principalId, issuer? }`; `tokenStoreKey(provider, owner)` is the stable, percent-encoded record key (`<provider>|app`, `<provider>|user|<issuer>|<principalId>`). `memoryStore()` keeps tokens in process memory; `fileStore(dir)`, `SqliteStore` and `KVStore` encrypt every record with AES-256-GCM (Web Crypto, a fresh 12-byte IV per write, the record key as additional authenticated data) under a 32-byte key the application supplies as `tokenKey` or `LOUSHO_TOKEN_KEY`; there is no default key. Several keys (newest first, or comma-separated in the variable) rotate: writes use the first, reads try each. New error codes `LOUSHO_TOKEN_KEY_MISSING` (first write, or a read of an existing record, without a key) and `LOUSHO_TOKEN_DECRYPT_FAILED` (wrong key or a changed record; names the provider, never the token). `list()` returns metadata only. `generateTokenKey()` makes a key. SQLite: schema migration 4 adds the `oauth_tokens` and `oauth_pending` tables, and `prune()` also deletes expired pending sign-ins (its result gains `oauthPending`). KV: keys under `<prefix>oauth/`, pending sign-ins written with an `expirationTtl`; `KVBinding` gains an optional `list()` (used only by `tokens.list()`), and `KVListOptions` / `KVListResult` are exported from `/kv`. The generated Cloudflare Worker passes its `LOUSHO_TOKEN_KEY` secret to `KVStore`. Nothing signs in yet; the sign-in flow follows. New page [OAuth](/oauth); new `## OAuth` section at the end of docs/errors.md.
@@ -562,7 +676,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 - `web_fetch` built-in tool: `webFetchTool` / `createWebFetchTool(options)`, and `web-fetch` in spec files. It `GET`s one public web page and returns `{ url, finalUrl, status, contentType, content, truncated }`: HTML converted to text by a small built-in converter (scripts and styles dropped, link URLs kept, entities decoded), JSON and `text/*` as sent, a note for other types; a 4xx/5xx is returned with its body. Loopback, private and link-local destinations are refused on every hop with the connection pinned to the checked address; redirects (10), bytes read (2 MiB), characters returned (50 000) and time (30 s) are capped; `allowedHosts` / `blockedHosts` are checked before DNS and `allowPrivate` exempts named hosts. Node only. See docs/tools.md#built-in-tools.
 - `src/security/privateAddress.ts` (internal): `isPrivateAddress()` and `pinnedLookup()`, shared by the credential broker, `http_request` and `web_fetch`. The credential broker uses it instead of its own list, so it also refuses `192.0.0.0/24`, `198.18.0.0/15`, NAT64 and 6to4 addresses.
 - Slack and Discord: a pending `ask_question` survives a restart. Given durable stores for sessions, checkpoints and approvals, the next message in the Slack thread (or the next `/ask` in the Discord channel) after a restart is still the answer: the turn continues, the reply is posted, and the question, the answer and the reply are appended to the session transcript (before, the answer became a new turn and the question was orphaned). A message in a conversation that waits on a tool approval still does not decide it. New `ChannelContext.pendingQuestion(sessionKey)` for custom channels: the id of the `ask_question` that key's session waits on, also one asked before a restart (it binds the approval to the session, so the continuation is recorded); handed out once until that answer has run. A channel's answer and click continuations now run one at a time with the session's turns. Supporting additions: `Checkpoint.approvalKind`, `PendingTurn.approvalKind` (`session.pending()`) and `SessionAwaitingApprovalError.approvalKind` are `'question'` for a turn paused on an `ask_question`. Slack thread replies that answer a pending question no longer need a saved transcript first (a first turn paused on a question with checkpoints has none yet). See docs/channels.md.
-- Local traces and `lousho traces`: `createAgent({ exporter, captureContent })` traces every run of the agent (`send()`, `stream()`, session turns, `agent.resume()` and runs continued by `agent.approvals.resolve()`; sub-agents join the lead's trace). The new subpath `@lousho/build-ai-agent/traces` exports `fileTraceExporter({ dir })`, which writes each run as JSON Lines to `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (default `.lousho/traces`; one finished span per line; a write error warns once and never fails the run), and `listTraces()` / `readTrace()` to read them. `npx lousho traces [--dir D] [--limit N] [--json]` lists recent runs with duration, model and tool calls, tokens and cost; `npx lousho traces <id|prefix> [--json] [--content]` prints one run as a span tree with duration bars. Projects made by `lousho init` now ignore `.lousho/`. See docs/observability.md#local-traces.
+- Local traces and `lousho traces`: `createAgent({ exporter, captureContent })` traces every run of the agent (`send()`, `stream()`, session turns, `agent.resume()` and runs continued by `agent.approvals.resolve()`; sub-agents join the lead's trace). The new subpath `@lousho/build-ai-agent/traces` exports `fileTraceExporter({ dir })`, which writes each run as JSON Lines to `<dir>/<YYYY-MM-DD>/<traceId>.jsonl` (default `.lousho/traces`; one finished span per line; a write error warns once and never fails the run), and `listTraces()` / `readTrace()` to read them. `npx @linuxdevil/lousho traces [--dir D] [--limit N] [--json]` lists recent runs with duration, model and tool calls, tokens and cost; `npx @linuxdevil/lousho traces <id|prefix> [--json] [--content]` prints one run as a span tree with duration bars. Projects made by `lousho init` now ignore `.lousho/`. See docs/observability.md#local-traces.
 - `openApiTools(document, options)`: an OpenAPI 3.0 / 3.1 document (object, JSON or YAML string, or https URL) becomes one typed tool per operation, exported from the root and `./tools`. Names come from `operationId` (or `<method>_<path>`); the input has path, query, header and cookie parameters plus an `application/json` `body`, with `$ref`s resolved; every HTTP response is returned as `{ status, statusText, body }`. GET, HEAD and OPTIONS run and other methods ask for approval by default (`approval`), with read-only / destructive annotations. Options: `baseUrl`, `include`, `exclude`, `prefix`, `headers`, `bearerToken`, `providedArguments` (removed from the model's schema), `timeoutMs`, `maxResponseChars`, `fetch`. The base URL must be https (http only for loopback), credentials never reach events or the transcript, and redirects are followed only on the base origin. Swagger 2.0, multipart bodies and remote `$ref`s are refused. `jsonSchemaToZod(schema, root?)` takes an optional root for `$ref` resolution. New page docs/openapi-tools.md.
 - Built-in OpenAI, Anthropic and OpenRouter providers send PDF file parts on `ai` 6 and 7 (Anthropic also `text/plain`); `ai` 4 and Ollama keep the text note. A provider subclass opts more media types in with `fileMediaTypes()` (`acceptsFileParts = true` still sends every type). The text-note warning is now once per provider and media type and names the type and the `ai` major. Added `npm run test:live` (`vitest.live.config.ts`) for `*.live.test.ts` files, which the default suite excludes. See docs/providers.md#multimodal-input.
 - Principals in tools, approval policies and permissions: the run's principal reaches a tool's `execute(args, ctx)` as `ctx.principal`, `needsApproval` functions (`ApprovalCheckContext.principal`), permission rules' `when(args, ctx)` (`PermissionContext.principal`), `preToolCall` / `postToolCall` hooks (`ToolCallHookContext.principal`), `onPermissionDecision`'s new second argument (`PermissionAuditContext`), pending approvals (`PendingApproval.principal`, seen by `approve` and by a channel's `approvers` function as `request.principal`) and in-process sub-agents (`task`, background tasks, `createDelegateTool()`; `remoteAgent()` does not forward it). New `ExecuteOptions.principal`, set by `createAgent()` for `send()`, `stream()`, session turns and channel turns. It is saved in checkpoints (`Checkpoint.principal`) and approval snapshots (`ExecutionSnapshot.principal`), so a static or dynamic run resumed after an approval or a crash acts for the same caller. `agent.approvals.resolve()` / `answer()` / `streamResolve()` / `streamAnswer()` take `{ principal }` (new `ResolveApprovalOptions`) for who decides, and the approved tool sees it as `ctx.approval.by`; `resumeAfterApproval()` takes it as `executeOptions.approver`. The approvals route (`POST /chat/:sessionId/approvals/:id`) passes the caller route auth accepted, and `mountChannels()` the clicking user (`{ id, type: 'user', authenticator: <channel name> }`) or, for a question answered by a message, its sender. `agent.fork()` keeps the source run's principal; `session.fork()` copies only the conversation. The principal is not added to events, spans or trace files. See [Principals in tools and approvals](/auth#principals-in-tools-and-approvals).
@@ -571,7 +685,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 - `SlackTriggerAdapter`, `CronTriggerAdapter` and `WebhookTriggerAdapter` (`@lousho/build-ai-agent/triggers`) are deprecated and will be removed in a future major version. Use `slackChannel()` for Slack (sessions per thread, approval buttons), `defineSchedule()` with `startSchedules()` for cron (or `schedules/` in an agent directory, or cron triggers in a spec file), and `webhookChannel()` for webhooks, each mounted with `mountChannels()`. `verifySlackSignature()`, the `WebhookAuth` helpers, `parseCronExpression()`, `TriggerAdapter` and `TriggerRegistry` are not deprecated. Their options types (`SlackTriggerAdapterOptions`, `CronTriggerAdapterOptions` with `CronIntervalOptions` and `CronExpressionOptions`, `WebhookTriggerAdapterOptions`) and `WebhookTriggerHandle` carry `@deprecated` too. Nothing changes at run time. See docs/triggers.md.
 
 ### Fixed
-- `lousho` CLI surface: `lousho dev`/`lousho chat --traces` now writes traces for a `.ts`/`.js` module that exports an already-built `createAgent()` agent - the module's export could not take the flag's exporter after the fact, so nothing was written. `createAgent()` remembers the config it was built with (readable via the internal `createAgentConfigOf()`), and the loader rebuilds the agent with the flag's exporter (the module's own `exporter` is replaced while the flag is set; a module exporting an agent not made by `createAgent()` prints a warning and keeps its own). A spec path that does not exist (e.g. `lousho chat missing.yaml`) now fails with the coded `LOUSHO_SPEC_NOT_FOUND` instead of a raw ENOENT. `lousho add --dry-run` no longer fails when a target file already exists; it prints the file list with an "(exists - a real install needs --overwrite)" marker and exits 0 (the symlink checks still run). Top-level `lousho --help` lists the implemented flags again: `--no-schedules`/`--traces` on `dev` and `chat`, `eval`'s record/replay/drift/`--config` flags, `init`'s `--sdk-path`, and `build`'s positional form.
+- `@linuxdevil/lousho` CLI surface: `lousho dev`/`lousho chat --traces` now writes traces for a `.ts`/`.js` module that exports an already-built `createAgent()` agent - the module's export could not take the flag's exporter after the fact, so nothing was written. `createAgent()` remembers the config it was built with (readable via the internal `createAgentConfigOf()`), and the loader rebuilds the agent with the flag's exporter (the module's own `exporter` is replaced while the flag is set; a module exporting an agent not made by `createAgent()` prints a warning and keeps its own). A spec path that does not exist (e.g. `lousho chat missing.yaml`) now fails with the coded `LOUSHO_SPEC_NOT_FOUND` instead of a raw ENOENT. `lousho add --dry-run` no longer fails when a target file already exists; it prints the file list with an "(exists - a real install needs --overwrite)" marker and exits 0 (the symlink checks still run). Top-level `lousho --help` lists the implemented flags again: `--no-schedules`/`--traces` on `dev` and `chat`, `eval`'s record/replay/drift/`--config` flags, `init`'s `--sdk-path`, and `build`'s positional form.
 - A cassette failure keeps its type through `agent.send()`: a replay mismatch (or a missing cassette raised by the provider-interception seam that `lousho eval` installs) was compacted into a generic `CompactedLLMProviderError`, losing the cassette path, the call number and the re-record hint. `CassetteMismatchError` is now an `SDKError` with code `LOUSHO_CASSETTE_INVALID` (docs/errors.md already claimed cassette errors carry it), and the run loop rethrows cassette errors untouched instead of compacting them, so `send()` rejects with the `CassetteMismatchError` itself (`.cassette`, `.callNumber`). `setProviderInterceptor()` and the `ProviderInterceptor` type are now exported from `@lousho/build-ai-agent/testing`, the public entry for the model-boundary seam docs/evals.md describes.
 - A tool call approved with `agent.approvals.resolve()` (or `resumeAfterApproval()`) now has its `execute_tool` span. It ran before the continued run started, outside any span, so OpenTelemetry and `fileTraceExporter()` showed the continued run's `invoke_agent` and `chat` spans but not the approved tool. The continued run's `invoke_agent` span now opens first and the approved call runs inside it: its `execute_tool` span is a child of it (a `run_code` call's inner calls and a sub-agent the tool starts are children of the tool span), with the same `captureContent` / `redactContent` rules as any tool span, and no span is made for a rejected call. A pause that happens again (sign-in) leaves the `invoke_agent` span with the tool span and no `chat`.
 - A tool that returns `undefined` (or an async generator that yields nothing) no longer writes a `tool` message with `content: undefined` into the transcript. Its result is now `null` everywhere: the transcript and the next model request carry `"null"`, and `tool.done`, approval resumes, `run_code` and flows see `null`. Providers, session stores and checkpoints get a valid string.
@@ -665,7 +779,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 ### Added
 - Remote sub-agent approvals go through the lead run: a `remoteAgent()` task whose remote run pauses for a tool approval now pauses the lead run the way a local sub-agent does (it used to fail with `LOUSHO_SESSION_AWAITING_APPROVAL`): the lead's pending approval (`agent.approvals.list()`, channel buttons, the dev chat, ACP permission requests) has the remote tool's name and input and `subagentPath: [<remote agent>]`, and a remote `ask_question` arrives as a question. Deciding it on the lead (`resolve`, `streamResolve`, `answer`) posts the decision to the remote `POST <url>/chat/:sessionId/approvals/:id` and the continuation's final answer is the `task` result; a further pause pauses the lead again. The lead's approval snapshot stores the remote session id, the remote approval id, the `taskId` and the agent name (never the token), so a fresh lead process on the same store can decide it. Failures while deciding (401, other non-2xx including the remote's 404 for an approval no longer pending, network) are the `task` call's structured tool error with `LOUSHO_REMOTE_UNAUTHORIZED` / `LOUSHO_REMOTE_REQUEST_FAILED`. A remote agent with an `output` schema now returns its object as JSON with the footer (the V4.2 shape), read from `run.done`'s `object`. `RemoteSubagent.run()` takes `pausable` and `decision` (type `RemoteRunOptions`); the internal session client gains `resolveRemoteApproval()` and `SessionTurnSummary.object`. Only a lead run without an approval store keeps the old `LOUSHO_SESSION_AWAITING_APPROVAL` error. See docs/sub-agents.md#remote-approvals.
 - Structured output for sessions and sub-agents, typed for either zod major: `createAgent({ output })` and `ExecuteOptions.output` accept a zod 3 schema, a zod 4 schema (`zod/v4` on zod 3.25, or zod 4) or a Standard Schema that can produce JSON Schema, and `result.object` is inferred from each without a cast (`InferSchemaOutput`, as `defineTool`). `AgentSession` is generic (`AgentSession<TObject = unknown>`): `agent.session().send()` and `.stream()` results carry the typed `object`. A sub-agent with its own `output` returns its validated object as JSON (then the `taskId` footer) as the `task` and `agent_await` result; its `output-invalid` finish is a structured tool error. Sub-agents do not inherit the lead's `output`; `remoteAgent()` returns text only. The exported spec schemas (`agentSpecSchema`, ...) are typed as `SpecSchema<T>` / `SpecObjectSchema<T>`, so the published `schema-*.d.ts` no longer depends on zod 3 generics (`skipLibCheck: false` projects on zod 4). The Ollama missing-peer note now says `ollama-ai-provider-v2` needs zod 4 (`npm install zod@^4.0.0`). See docs/structured-output.md.
-- Publish readiness: `npm run pack-smoke` (scripts/pack-smoke.ts, a CI job) packs the SDK and `create-lousho-agent`, checks the tarball (no `.env`, tests or secret-looking strings; entry count and size caps), runs `npm publish --dry-run` for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every `exports` entry, a mock-model agent turn, the `lousho` bin (`--help`, `doctor`) and `tsc` with `moduleResolution` bundler and node16.
+- Publish readiness: `npm run pack-smoke` (scripts/pack-smoke.ts, a CI job) packs the SDK and `create-lousho-agent`, checks the tarball (no `.env`, tests or secret-looking strings; entry count and size caps), runs `npm publish --dry-run` for both (nothing is published), installs the tarballs plus peers from the registry into a fresh project and verifies ESM and CJS loads of every `exports` entry, a mock-model agent turn, the `@linuxdevil/lousho` bin (`--help`, `doctor`) and `tsc` with `moduleResolution` bundler and node16.
 - One event system: `AgentEvent` listeners for callers who do not iterate a run. `createAgent({ onEvent: (event: AgentEvent) => void })` and the new `ExecuteOptions.onAgentEvent` (also taken by `AgentExecutor.stream()` and `resumeAfterApproval()`) are called synchronously with every `AgentEvent` of the run, on `send()` / `execute()` as on `stream()`, sub-agents' events included: the same events in the same order as the stream yields (a non-streamed run generates each model step whole, so its text is one `text.delta` per step). A run with a listener also reports hook events, permission decisions, budgets and guardrails to it when it is not streamed. A non-streamed `resumeAfterApproval()` with a listener now reports the decided call (`run.start`, `tool.start`, `tool.done`) like a streamed one. See docs/streaming.md#listening-without-iterating.
 - Reasoning: new `reasoning` option on `createAgent()`, `send()` / `stream()` (per call, overriding the agent's), `ExecuteOptions` and `GenerateOptions`: `'none' | 'minimal' | 'low' | 'medium' | 'high'` or `{ effort?, budgetTokens?, summary?: 'auto' | 'none', force? }` (types `ReasoningOption`, `ReasoningEffort`, `ReasoningSettings`). The built-in providers send it through `providerOptions` on `ai` 4.3 and 6/7: OpenAI `reasoningEffort` (+ `reasoningSummary`), Anthropic `thinking: { type: 'enabled', budgetTokens }` (effort table 1024 / 2048 / 8192 / 24576 tokens), Ollama `think` (`ollama-ai-provider-v2` only; ignored with one warning on `ai` 4), and OpenRouter's unified `reasoning` body field (`effort` or `max_tokens`). It is only sent to model families known to accept it (`force: true` overrides); `'none'` sends nothing. New events `reasoning.start`, `reasoning.delta` (`text`) and `reasoning.done` (`text`, `tokens?`) in the `AgentEvent` union, emitted inside the step before its first text or tool call, from `ai` v4 `reasoning` parts and v6/v7 `reasoning-start/delta/end`; `ExecutionResult.reasoning` holds the run's reasoning text and `GenerateResult.reasoning` a call's blocks (new type `ReasoningBlock`); new stream chunk types `reasoning-delta` / `reasoning-end` (`StreamChunk.reasoning`). Reasoning is not written to the transcript as text; an assistant tool-call turn keeps Anthropic's signed or redacted thinking blocks in the new `Message.reasoning`, which the Anthropic provider sends back unmodified (it survives checkpoints and resumes). The UI reducer keeps `UIMessage.reasoning`, `toUIMessageStream()` emits `reasoning-start` / `reasoning-delta` / `reasoning-end`, `lousho acp` sends `agent_thought_chunk`, `lousho chat` prints reasoning dimmed, and `chat` spans carry `lousho.usage.reasoning_tokens`. Cassettes record the reasoning chunks. See docs/reasoning.md.
 - Tools know their session: `ToolExecutionContext.sessionId` is now set whenever the run has one: `AgentExecutor.execute({ sessionId })`, `send({ sessionId })`, every `agent.session()` turn (the session id; a checkpointed turn's own `<id>.turn-<n>`, as hooks see it), approval resumes (the paused run's), and sub-agents (`<parent session>/<task tool call id>`). A session turn's run now carries the session id even without a checkpoint store (no checkpoint is written), so hooks and the `invoke_agent` span's conversation id see it too.
@@ -696,7 +810,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 - Svelte store: new `@lousho/build-ai-agent/svelte` subpath with `loushoAgent(source, options?)`. It returns a Svelte store (`subscribe(run) => unsubscribe`, so `$agent` works in Svelte 4 and 5) whose value is the same state as the React hook and the Vue composable (`messages`, `status`, `pendingApproval`, `error`, `usage`, `lastEvent`), plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and `reset()`. The run in flight is aborted by `stop()` and when the last subscriber unsubscribes. The store contract is implemented by hand: the entry imports nothing from `svelte`, so there is no new peer dependency. See docs/svelte.md.
 - Per-run dynamic config: `createAgent()`'s `model`, `instructions` / `prompt` and `tools` each also take a function of the run, `(ctx) => value | Promise<value>` (new types `PerRun<T>` and `RunConfigContext` = `{ sessionId?, input, metadata? }`), resolved once at the start of each run and of each session turn, before the first model call. `fallbackModels`, `retry`, `projectInstructions`, memory, MCP tools, sub-agents, permissions, approvals and guardrails apply to the resolved values; a dynamic agent used as a sub-agent resolves with the task prompt as `input`. `session.send()` / `session.stream()` gain the `metadata` option (`send()` / `stream()` already had it, and now pass it to these functions too). A function that throws fails the run with the new `LOUSHO_CONFIG_RESOLVER_FAILED` (`field` names the option, `cause` is the error); a session keeps its transcript. A run paused for approval stores its `ctx` and resolved model in the approval snapshot (`agent.metadata.loushoRunConfig`): resuming it uses that model and re-resolves the tools with the same `ctx`; a crash resume from a checkpoint resolves with `input: []`. Static options behave and type as before. `SessionRunner` / `SessionStreamRunner` take an optional fourth `call` argument (new type `SessionTurnCall`). See docs/api-overview.md#dynamic-config.
 - Vue composable: new `@lousho/build-ai-agent/vue` subpath with `useLoushoAgent(source, options?)` for Vue 3. It takes the same sources and options as the React hook (either may be a `ref`, read when a turn starts) and returns `messages`, `status`, `pendingApproval`, `error`, `usage` and `lastEvent` as read-only refs, plus `send()`, `stop()`, `approve()`, `reject()`, `answer()` and a new `reset()` (aborts, forgets the in-process session, clears the chat). The run in flight is aborted by `stop()` and when the owning scope is disposed (`onScopeDispose`: component unmount, `effectScope().stop()`). `vue` (`^3`) is an optional peer dependency, loaded by no other entry. To share the logic, the reducer and the stream parser moved from `src/react/` to a framework-neutral `src/ui/`, together with the run logic extracted from the React hook (`createAgentRunner()`); the `./react` exports are unchanged, and the reducer gains an additive `ui.reset` action. See docs/vue.md.
-- One flag parser for the `lousho` CLI: every command (`dev`, `chat`, `eval`, `build`, `mcp`, `doctor`, `studio`; `init` already did) parses its flags with `node:util` `parseArgs` in strict mode through `src/cli/args.ts`. `--flag value` and `--flag=value` work everywhere, `--` ends the flags, `-h` / `--help` prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with `LOUSHO_CONFIG_INVALID` and the command's usage as the hint. **Behaviour change (migration):** `dev`, `studio`, `mcp`, `build` and `doctor` used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (`--portx 1` read as `--port`); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with `-` must be written `--flag=-x` (a bare `--flag -x` is a missing value); `--port` must be an integer from 0 to 65535 for `dev`, `studio` and `mcp`; `dev`, `mcp` and `doctor` reject a second path; `studio --prod --dev` is rejected instead of preferring `--prod`. `lousho dev` and `lousho studio` parsing moved from `bin/lousho.js` into `src/cli/dev.ts` / `src/cli/studio.ts` (`parseDevArgs`, `runDev`, `parseStudioArgs`, `runStudio`). See docs/cli.md.
+- One flag parser for the `@linuxdevil/lousho` CLI: every command (`dev`, `chat`, `eval`, `build`, `mcp`, `doctor`, `studio`; `init` already did) parses its flags with `node:util` `parseArgs` in strict mode through `src/cli/args.ts`. `--flag value` and `--flag=value` work everywhere, `--` ends the flags, `-h` / `--help` prints the usage and exits 0, and an unknown flag, a flag without its value or an extra argument fails with `LOUSHO_CONFIG_INVALID` and the command's usage as the hint. **Behaviour change (migration):** `dev`, `studio`, `mcp`, `build` and `doctor` used to ignore unknown flags, and a flag missing its value could take the next flag or a prefix match (`--portx 1` read as `--port`); they now fail with exit 1 and the usage line, so remove typos from scripts. A value that starts with `-` must be written `--flag=-x` (a bare `--flag -x` is a missing value); `--port` must be an integer from 0 to 65535 for `dev`, `studio` and `mcp`; `dev`, `mcp` and `doctor` reject a second path; `studio --prod --dev` is rejected instead of preferring `--prod`. `lousho dev` and `lousho studio` parsing moved from `bin/lousho.js` into `src/cli/dev.ts` / `src/cli/studio.ts` (`parseDevArgs`, `runDev`, `parseStudioArgs`, `runStudio`). See docs/cli.md.
 - `sqliteMemory(store, { maxItems? })` (exported from `@lousho/build-ai-agent/sqlite`) keeps `defineMemory` slots in the agent's `SqliteStore` file: a new `memory_items` table (migration 3, one JSON array per scope key, with the same serialization, `maxItems` and query rules as `fileMemory`). An existing database gains the table on open and keeps its sessions and checkpoints. The memory provider contract tests now run against the in-memory, file and SQLite providers. See docs/memory.md#sqlite.
 - Slack channel: `slackChannel({ signingSecret, botToken, name?, fetch? })` (new export, with types `SlackChannelOptions`, `SlackChannelEvent`, `SlackThread`) serves a Slack app's Events API and interactivity requests through `mountChannels()`. It verifies the `v0` request signature with Web Crypto (no `node:*` import; the timestamp and header checks are shared with `verifySlackSignature()`), answers the `url_verification` challenge, and acknowledges every request before the turn runs. Each Slack thread is one session (team + channel + thread root `ts`): a mention starts or continues it, and later messages in a thread the bot was mentioned in continue it. Retries (`X-Slack-Retry-Num`) and bot messages are skipped. Replies go to the thread with `chat.postMessage` over `fetch`; a tool approval is posted as Approve / Deny buttons whose click resumes the session, and an `ask_question` as text answered by the next thread message. The channel contract gains two additive hooks for this: `parse(req, respond)` may call `respond` to answer the request before the turn runs, and may return `{ decision }` (new type `ChannelDecision`; `ChannelApprovalDecision` now lives in `defineChannel.ts`, same public export) to resolve a pause instead of starting a turn. See docs/channels.md#slack.
 - Remote sub-agents: `remoteAgent({ url, auth?, name?, description?, headers?, fetch? })` (new export, with types `RemoteAgentOptions` and `RemoteSubagent`) makes a deployed agent usable wherever a local sub-agent is: in `createAgent({ subagents })` records and `SubagentCatalog.resolve()`, delegated to by the `task` tool and by `background: true` tasks. Each task opens a fresh session on the remote agent over `POST <url>/chat` (bearer `auth`: a string or a function, called per task), reads the SSE stream to the end and returns the remote agent's final text; the lead run's abort signal aborts the request. Failures (network, 401 or other non-2xx, malformed stream, remote run error) are structured tool errors with the new code `LOUSHO_REMOTE_AGENT_FAILED`, and the token never appears in errors or events; a remote run that pauses for approval fails with `LOUSHO_SESSION_AWAITING_APPROVAL` naming the remote session (proxying approvals is a follow-up). Worker-safe (`fetch` only). See docs/sub-agents.md#remote-sub-agents.
@@ -783,7 +897,7 @@ See the 1.0.0-alpha.19 section, which covers everything from 1.0.0-alpha.15 thro
 - README revamped into a short front page; the details it dropped moved to `docs/` (new pages: tools, approvals, providers, cli, flows, guardrails, utilities).
 
 ### Renamed
-- The project is now **lousho** (it was `loushy`), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package `@lousho/build-ai-agent` (was `@loushy/build-ai-agent`), the `lousho` CLI (was `loushy`), `create-lousho-agent` (was `create-loushy-agent`), the exports `useLoushoAgent`, `loushoAgent`, `LoushoAgentSource`, `LoushoUIMessageChunk` and the other `Lousho*` types, every `LOUSHO_*` error code and environment variable (`LOUSHO_MODEL`, `LOUSHO_API_TOKEN`, `LOUSHO_STORE`, ...), the `.lousho/` directory, the `lousho.*` span attributes and the `data-lousho-approval` stream part. Migration for a checkout that used the old name: replace `loushy` with `lousho` (keeping the case) in imports, scripts, environment variables and config, and rename an existing `.loushy/` directory to `.lousho/`.
+- The project is now **lousho** (it was `loushy`), before the first npm release, so nothing was ever published under the old name. Everything that carried the name changed with it, and this changelog uses the new names throughout, including in older entries: the package `@lousho/build-ai-agent` (was `@loushy/build-ai-agent`), the `@linuxdevil/lousho` CLI (was `loushy`), `create-lousho-agent` (was `create-loushy-agent`), the exports `useLoushoAgent`, `loushoAgent`, `LoushoAgentSource`, `LoushoUIMessageChunk` and the other `Lousho*` types, every `LOUSHO_*` error code and environment variable (`LOUSHO_MODEL`, `LOUSHO_API_TOKEN`, `LOUSHO_STORE`, ...), the `.lousho/` directory, the `lousho.*` span attributes and the `data-lousho-approval` stream part. Migration for a checkout that used the old name: replace `loushy` with `@linuxdevil/lousho` (keeping the case) in imports, scripts, environment variables and config, and rename an existing `.loushy/` directory to `.lousho/`.
 
 ### Published
 - `@lousho/build-ai-agent` and `create-lousho-agent` are on npm. The README and the installation, quick start, CLI and Agent Forge docs no longer say the package is unpublished; "Installing before the first release" is now "Installing from a local build" (docs/installation.md#installing-from-a-local-build) and covers trying an unreleased commit. The hint printed after a failed `lousho init` install no longer mentions a 404; it points to `--sdk-path`. The docs site moved to https://lousho.com.
diff --git a/channels.mdx b/channels.mdx
index fa3a26e..f69d67b 100644
--- a/channels.mdx
+++ b/channels.mdx
@@ -46,7 +46,7 @@ const channels = mountFetchChannels(agent, [slack], { waitUntil: (turn) => void
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, createMockProvider, httpChannel, mountChannels } from 'lousho';
+import { createAgent, createMockProvider, httpChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const channels = mountChannels(agent, [
@@ -121,7 +121,7 @@ Discord, Telegram, Teams, GitHub) keeps its own answer and tells the user the
 request failed in the conversation.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer text messages.', provider });
 
@@ -205,7 +205,7 @@ dropped silently once the surface was acknowledged. `resolveApproval()`
 throws `LOUSHO_APPROVAL_CONFLICT` for an approval another request is deciding.
 
 ```ts
-import { createAgent, defineChannel, mountChannels } from 'lousho';
+import { createAgent, defineChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider, askQuestion: true });
 
@@ -250,7 +250,7 @@ the verified request (the alerting system that sent the hook, an integration
 user); `body` is the parsed JSON body, `undefined` when it is not JSON.
 
 ```ts
-import { createAgent, httpChannel, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, httpChannel, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider });
 
@@ -343,7 +343,7 @@ Set up the app at [api.slack.com/apps](https://api.slack.com/apps):
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, slackChannel } from 'lousho';
+import { createAgent, mountChannels, slackChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Slack bot.', provider });
 
@@ -418,7 +418,7 @@ curl -X POST "https://discord.com/api/v10/applications/$APP_ID/guilds/$GUILD_ID/
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, discordChannel, mountChannels } from 'lousho';
+import { createAgent, discordChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Discord bot.', provider });
 
@@ -502,7 +502,7 @@ curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" -H "Co
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, telegramChannel } from 'lousho';
+import { createAgent, mountChannels, telegramChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are a helpful Telegram bot.', provider });
 
@@ -554,7 +554,7 @@ so it also runs on Workers.
   them somewhere shared and durable, e.g. Redis `SET NX EX`:
 
   ```ts
-  import { githubChannel, type DeliveryStore } from 'lousho';
+  import { githubChannel, type DeliveryStore } from '@linuxdevil/lousho';
 
   const seenIds = new Set<string>(); // stands in for Redis or a database table
   const deliveries: DeliveryStore = { seen: (id) => seenIds.has(id) || (seenIds.add(id), false) };
@@ -655,7 +655,7 @@ agent from answering its own comments.
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, githubChannel, mountChannels } from 'lousho';
+import { createAgent, githubChannel, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You answer questions about this repository.', provider });
 
@@ -751,7 +751,7 @@ Set up the bot:
 
 ```ts
 import * as http from 'node:http';
-import { createAgent, mountChannels, teamsChannel } from 'lousho';
+import { createAgent, mountChannels, teamsChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You help the team with questions.', provider });
 
diff --git a/claude-projects.mdx b/claude-projects.mdx
index a2eaad5..57cdc98 100644
--- a/claude-projects.mdx
+++ b/claude-projects.mdx
@@ -10,8 +10,8 @@ into `createAgent()`, so the same directory drives both harnesses. Nothing is
 copied or renamed; Lousho reads the files where they already are.
 
 ```ts
-import { createAgent, claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
@@ -68,8 +68,8 @@ task-shaped notes, hooks can pause on `scratchpad` writes like any tool.
 ## Options
 
 ```ts
-import { claudeProject } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { claudeProject } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
diff --git a/cli.mdx b/cli.mdx
index d46bba0..39a5944 100644
--- a/cli.mdx
+++ b/cli.mdx
@@ -1,12 +1,12 @@
 ---
 title: "CLI"
 ---
-{/* Generated from docs/cli.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/cli.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
-Installing the package also installs the `lousho` command. It scaffolds
+Installing the package also installs the `@linuxdevil/lousho` command. It scaffolds
 projects, checks your setup, runs an agent locally, serves it over MCP, runs
-evals, shows saved traces, builds a deployable artifact and launches the Agent Forge dashboard.
-Run it with `npx lousho <command>` inside a project that has the SDK installed.
+evals, shows saved traces, builds a deployable artifact and opens Lousho Studio.
+Run it with `npx @linuxdevil/lousho <command>` inside a project that has the SDK installed.
 
 | Command | What it does | Details |
 | ------- | ------------ | ------- |
@@ -20,8 +20,11 @@ Run it with `npx lousho <command>` inside a project that has the SDK installed.
 | `lousho eval [globs...]` | Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports. | [Evals](/evals#lousho-eval) |
 | `lousho traces [id]` | List the recent runs saved by `fileTraceExporter()` (duration, model and tool calls, tokens, cost), or print one run as a span tree. | [Observability](/observability#local-traces) |
 | `lousho build --target=<t> --agent=<spec>` | Build a deployable Node server, Docker image or Cloudflare Worker. | [Deployment](/deployment) |
-| `lousho studio` | Launch Agent Forge, the visual dashboard, on one local port. | [Agent Forge](/agent-forge) |
-| `lousho improve <path> --check <module>` | Experimental. Propose edits to an agent's instructions and skills from failed runs in your local observe database. Prints a review card and applies nothing. | [Below](#lousho-improve) |
+| `lousho studio` | Open Lousho Studio (the separate `@linuxdevil/studio` package) on this project. | [Lousho Studio](/agent-forge) |
+| `lousho bridge` | Speak Studio's bridge protocol on stdio; started by Studio, not run by hand. | [Below](#lousho-bridge) |
+| `lousho workspace <init\|ls\|show\|validate\|run>` | Create, inspect, validate and run a workspace from a folder or a running service. | [Workspaces](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/workspaces.md) |
+| `lousho observe <sub>` | Run the local collector every agent reports to when `LOUSHO_OBSERVE` is set: `start`, `status`, `stop`, `rebuild-rollups`, `prune`, `export`, `failures`, `score`, `token`. | [Below](#lousho-observe) |
+| `lousho improve <path> --check <module>` | Experimental. Run one self-healing cycle on an agent directory: propose edits to its instructions and skills from failed runs in your local observe database, gate them, replay them on fresh runs, and apply (auto mode, the default) or queue (manual mode) one that passes. `--watch` keeps it running; `pause`, `status`, `rollback`, `approve` and the other subcommands manage it. `--dry-run` prints the review card and applies nothing. | [Below](#lousho-improve) |
 
 Every command that takes a `<spec>` reads an agent spec file (`.yaml`,
 `.yml` or `.json`, see [Configuration](/configuration#agent-spec-files-agentspec)).
@@ -35,14 +38,17 @@ lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [-
 lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
 lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--allow <list>] [--overwrite] [--dry-run]    (or --list)
 lousho build <agent-dir|spec|agent.ts> --target=<node-server|cloudflare-worker|docker> [--out=<dir>]    (or --agent=<path>)
-lousho studio [--port N] [--host H] [--prod|--dev]
+lousho studio [--port N] [--host H]
+lousho bridge
+lousho workspace <init|ls|show|validate|run> [args] [--source <dir> | --service <url>]
 lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
 lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
 lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
 lousho observe <start|status|stop|rebuild-rollups|prune|export|failures|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--session-idle-minutes N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
 lousho prompt <push <file|->|list|get <name[@version|@label]>|label <name> <label> <version>> [--url U] [--port N] [--token T] [--json] [--name N] [--labels a,b] [--variables x,y]
-lousho improve <agent-dir|agent.ts> --check <module> [--model provider/model] [--editor provider/model] [--db path] [--since <N>d|<N>h|<N>m] [--agent X] [--protect traceId]... [--read-only tool]... [--out file]
+lousho improve <agent-dir|agent.ts> --check <module> [--model provider/model] [--editor provider/model] [--db path] [--since <N>d|<N>h|<N>m] [--agent X] [--protect traceId]... [--read-only tool]... [--max-tokens n] [--out file] [--with-recoveries] [--approval auto|manual] [--proposers 1-4] [--mode agg|seq] [--select] [--no-parallel-editors] [--dry-run] [--watch [--interval 15m]]
+lousho improve <revisions|rollback|audit|pending|approve|reject|pause|resume|status> <agent-dir> ...
 lousho --version
 ```
 
@@ -78,18 +84,18 @@ not the shared `LOUSHO_CONFIG_INVALID` path. The only short flags besides
 instead of the generated one; globs then narrow that config's files as vitest
 filters.
 
-`npm create lousho my-agent` runs `lousho init` with the same arguments.
+`npm create @linuxdevil/lousho my-agent` runs `lousho init` with the same arguments.
 To scaffold against an unreleased build of the SDK, pass `--sdk-path` (see
 [Installing from a local build](/installation#installing-from-a-local-build)).
 
 ## `lousho dev`
 
 ```bash
-npx lousho dev agent.yaml                  # a spec file
-npx lousho dev ./my-agent                  # an agent directory
-npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
-npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
-npx lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
+npx @linuxdevil/lousho dev agent.yaml                  # a spec file
+npx @linuxdevil/lousho dev ./my-agent                  # an agent directory
+npx @linuxdevil/lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
+npx @linuxdevil/lousho dev agent.yaml --port 4000 --host 0.0.0.0
+npx @linuxdevil/lousho dev ./my-agent --no-schedules   # do not fire cron schedules or a spec's cron triggers
 ```
 
 For an agent directory, `channels/` are mounted under `/channels` and
@@ -128,7 +134,7 @@ plus a free-text field. The same endpoints work from `curl` or your own page:
 
 `--traces` (or `--traces=<dir>`) writes every run to local trace files with
 `fileTraceExporter()`, in `.lousho/traces` unless you name a directory, so
-`npx lousho traces` shows what the agent did. It is off by default because the
+`npx @linuxdevil/lousho traces` shows what the agent did. It is off by default because the
 files hold prompt, tool argument and tool result content, and the flag prints
 the directory it writes to. It applies to spec files, agent directories and
 modules alike (a module's own `exporter` is replaced while the flag is set).
@@ -191,9 +197,9 @@ Directories and modules are your code and run with your permissions; only run
 ## `lousho chat`
 
 ```bash
-npx lousho chat agent.yaml                          # a spec file
-npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
-npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
+npx @linuxdevil/lousho chat agent.yaml                          # a spec file
+npx @linuxdevil/lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
+npx @linuxdevil/lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support
 ```
 
 A terminal REPL: each line you type is one turn of a session. `<path>` is
@@ -252,9 +258,9 @@ scripted lines and a `mockModel` agent and no terminal.
 ## `lousho build`
 
 ```bash
-npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
-npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
-npx lousho build src/agent.ts --target=node-server              # an agent module (node-server, docker)
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)
+npx @linuxdevil/lousho build src/agent.ts --target=node-server              # an agent module (node-server, docker)
 ```
 
 Writes the artifact to `--out` (default `.lousho/build/<target>`) and prints
@@ -265,30 +271,45 @@ Workers limits are in [Deployment](/deployment).
 ## `lousho studio`
 
 ```bash
-npx lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
-npx lousho studio --port 5000
+npx @linuxdevil/lousho studio            # prints http://127.0.0.1:4750/?token=<per-launch token>
+npx @linuxdevil/lousho studio --port 5000
 ```
 
-Starts one local server for the Agent Forge API and UI. Agents and run state
-are stored under `.lousho/` in the current directory. The app has a left
-navigation: Agents (the builder) and Playground, then Traces, Threads and
-Monitoring, Evaluations (Scores, Datasets, Evaluators, Annotation queues),
-Prompts, Context Hub and Settings; everything past the Playground reads the
-`lousho observe` daemon. See [Agent Forge](/agent-forge) for the screens
+Opens Lousho Studio on this project. Studio is a separate package
+(`@linuxdevil/studio`): install it with `npm i -g @linuxdevil/studio` (or run
+`npx @linuxdevil/studio`); this command finds it and opens the current folder
+as a workspace. When no Studio is installed it prints
+`Studio is a separate install: npx @linuxdevil/studio` and exits.
+
+Options: `--port N` and `--host H` pass through to Studio (defaults 4750 and
+`127.0.0.1`). `--prod` and `--dev` only apply inside the SDK's own repository
+checkout. See [Lousho Studio](/agent-forge) for workspaces, the screens
 and the walkthrough.
 
+## `lousho bridge`
+
+```bash
+lousho bridge
+```
+
+Speaks Studio's bridge protocol (NDJSON) on stdin/stdout so Studio can build
+and run agents with this project's own SDK. Studio starts it for each
+workspace that has `@linuxdevil/lousho` installed; you do not run it
+yourself.
+
 ## `lousho observe`
 
 ```bash
-npx lousho observe start                        # collector on http://127.0.0.1:7777
-npx lousho observe status                       # health + fleet counts
-npx lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
-npx lousho observe rebuild-rollups              # recompute insight aggregates
-npx lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
-npx lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
-npx lousho observe failures --since 7d          # recurring tool and model failures, by agent
-npx lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
-npx lousho observe token create --project myapp # bearer key for non-loopback auth
+npx @linuxdevil/lousho observe start                        # collector on http://127.0.0.1:7777
+npx @linuxdevil/lousho observe status                       # health + fleet counts
+npx @linuxdevil/lousho observe stop                         # <db>.pid + SIGTERM (checks the daemon serves --db)
+npx @linuxdevil/lousho observe rebuild-rollups              # recompute insight aggregates
+npx @linuxdevil/lousho observe prune --older-than 30d       # delete finished runs older than 30 days, then VACUUM
+npx @linuxdevil/lousho observe export --since 7d --out runs.jsonl # traces as JSONL, one per line
+npx @linuxdevil/lousho observe failures --since 7d          # recurring tool and model failures, by agent
+npx @linuxdevil/lousho observe failures --traces .lousho/traces --json # the same from trace files, no database
+npx @linuxdevil/lousho observe score --agent support        # continuous score, pass rate and trajectory gate state
+npx @linuxdevil/lousho observe token create --project myapp # bearer key for non-loopback auth
 ```
 
 Runs the local collector every agent reports to when `LOUSHO_OBSERVE` is
@@ -339,11 +360,11 @@ no daemon needs to be running. See [Export](/observability#export).
 ## `lousho prompt`
 
 ```bash
-npx lousho prompt push prompt.md --name mira    # publishes a new version
-npx lousho prompt list
-npx lousho prompt get mira@latest
-npx lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
-npx lousho prompt get mira@prod
+npx @linuxdevil/lousho prompt push prompt.md --name mira    # publishes a new version
+npx @linuxdevil/lousho prompt list
+npx @linuxdevil/lousho prompt get mira@latest
+npx @linuxdevil/lousho prompt label mira prod 3             # mira@prod -> 3 (was 2)
+npx @linuxdevil/lousho prompt get mira@prod
 ```
 
 Publishes and reads prompt versions in the observe daemon's registry. Agents
@@ -364,10 +385,10 @@ resolve them with `createAgent({ prompt: 'mira@latest' })` (or a label,
 
 ## `lousho improve`
 
-Experimental, like the [`improveAgent()`](/improve) it runs.
+Experimental, like the [`improveAgent()`](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md) it runs.
 
 ```bash
-npx lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --since 7d --out proposal.md
 ```
 
 ```js
@@ -377,15 +398,26 @@ export default (input, answer) => !answer.includes('I cannot help');
 It takes the failed runs in your local observe database (default
 `~/.lousho/observe.db`, or `--db`), replays each recorded input through the
 agent, scores each answer with your check, and prints the review card from
-`formatImproveResult()`. It never changes the agent: no file in the agent
-directory is written, and there is no flag to apply a proposal. Review the card
-and apply what you accept by hand.
+`formatImproveResult()`. On an agent directory it then runs one self-healing
+cycle with `healOnce()`: only failed runs of the current harness revision count,
+a proposal that passes the gate is replayed on fresh runs (the canary), and in
+auto mode (the default) it is written to `instructions.md` and
+`skills/<name>/SKILL.md`, after which the corpus guard replays the protected
+cases and rolls back on a regression. In manual mode it is queued for
+`lousho improve approve`. Every step is audited, and `improve.json`'s daily caps,
+the cooldown after a rollback and the `.lousho/improve.stop` kill switch apply.
+`--dry-run` keeps the old behaviour: every failed run counts, the card is
+printed, and nothing is written. An agent module, or an agent whose instructions
+don't live in `instructions.md`, always runs dry.
 
 - `<path>` is an agent directory or a `.ts`/`.js` agent module whose
   instructions are plain text. Editors may change only the instructions and
   skills.
 - `--check <module>` is required. Its default export is a `CaseCheck`,
-  `(input, answer) => boolean | null`; `null` means the answer can't be scored.
+  `(input, answer) => boolean | null | { passed, failure? }`; `null` means the
+  answer can't be scored. Return `{ passed: false, failure }` to name the check
+  a failed answer missed: the editors read it in that run's record, and without
+  it a failed run whose answer looks right gives them nothing to fix.
   `input` is the user's message for a one-message run, else the recorded
   messages as JSON text.
 - `--since` and `--agent` pick which failed runs become cases, as for
@@ -402,8 +434,186 @@ and apply what you accept by hand.
   model (default `--model`, else the agent's own).
 - `--out file` also writes the card, or the JSON result for a `.json` path. It
   must be a new file, outside the agent's files.
+- `--max-tokens <n>` passes `maxTokens` to `improveAgent()`: it stops once `n`
+  tokens are spent on agent runs and editor calls. The total is checked after
+  each run or editor call, so the last one can go over. The card and the JSON
+  then report `budget-exceeded` with the reason, nothing is proposed, and
+  stderr suggests raising it. `n` must be a positive integer; anything else is
+  a usage error (exit 2). It is unset by default, so there is no cap. The runs
+  that admit `--protect` traces happen before and don't count toward it.
+- `--with-recoveries` also shows the editors, for each failed run, the
+  `<id>.heal` fork from `agent.recover()` that finished and whose answer passes
+  `--check`, if there is one. It's evidence only: it never counts as a run and
+  never protects a case, and a fork you `--protect` is left out. See
+  [Recovery forks as evidence](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#recovery-forks-as-evidence).
+- `--approval auto|manual` sets the approval mode, over the
+  `LOUSHO_IMPROVE_APPROVAL` variable, which wins over `"approval"` in
+  `improve.json` beside the agent. The default is `auto`. In `manual` mode an
+  edit that quotes a failed check word for word is kept and flagged on the card
+  for the person who approves it; in `auto` mode it is sent back to the editor
+  once and then dropped. An `improve.json` that doesn't validate stops the
+  run. See [Approval modes](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#approval-modes).
+- `--proposers <1-4>`, `--mode agg|seq`, `--select` and
+  `--no-parallel-editors` set the cycle's
+  [Harness² options](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#harness-options), over the `editors` block in
+  `improve.json`. `--select` can only turn the selector on and
+  `--no-parallel-editors` can only turn parallel off. `--proposers k` runs k invariant and k domain editors (or k
+  rounds with `--mode seq`), and costs about k times the editor sessions and
+  proposal runs. `--select` gates every candidate and lets the advisory selector
+  choose among those that pass. `--no-parallel-editors` runs the editors and
+  their probes one at a time, for a rate-limited model. They apply to dry runs
+  and `--watch` too.
+- `--dry-run` writes nothing: no apply, no queue, no audit entry. It reads
+  every failed run whatever its revision, and ignores the kill switch and the
+  daily caps.
+- `--watch` keeps running cycles on a timer; `--interval` (default `15m`, as
+  `<N>s`, `<N>m` or `<N>h`) sets the spacing. It needs an agent directory, takes
+  its budget from `improve.json`, and can't be combined with `--dry-run`,
+  `--max-tokens` or `--out`. See below.
+
+Before it starts, a cycle prints its approval mode and whether it applies or
+queues; a dry run prints how many runs it will make at least, and the token
+budget if any. Every run and every editor call is billed to your models.
+`--max-tokens` caps one cycle within `improve.json`'s daily caps.
+It exits 1 on an `outage`: no run could be scored, or the editors' provider
+failed. A `budget-exceeded` run exits 0, since you set the cap. Each run's error goes to
+stderr. It reads nothing but your own database. See [Improving an agent](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#from-the-command-line).
+
+### Revisions, rollback and the audit log
+
+Every change to an agent directory's `instructions.md` and
+`skills/<name>/SKILL.md` made through `applyProposal()` is saved as a revision
+under `.lousho/revisions/` and recorded in the hash-chained
+`.lousho/audit.jsonl`. Three subcommands read and undo that history:
+
+```bash
+npx @linuxdevil/lousho improve revisions ./my-agent
+npx @linuxdevil/lousho improve rollback ./my-agent --by ali --reason "answers got worse"
+npx @linuxdevil/lousho improve audit ./my-agent --verify
+```
+
+- `revisions <dir> [--json]` lists the saved revisions, newest first, with their
+  source (`baseline`, `apply` or `rollback`), who made them and when. `*` marks
+  the one the directory holds now.
+- `rollback <dir> --by <name> [--to <revision>] [--reason text]` restores a
+  saved revision through the same writer as an apply: it changes only
+  instructions and skills, makes a new revision and writes one `rollback` audit
+  entry. It never rewrites history. Without `--to` it goes to the parent of the
+  current revision. It refuses instead when the current revision came from a
+  rollback, or when the directory holds hand edits that match no revision; pass
+  `--to` then. A hand edit that a rollback replaces is saved as a revision
+  first. `--to` takes an id or a unique prefix of at least 4 characters. `--by`
+  is required. If an apply lands between your command and the write, the
+  rollback is refused as stale.
+- `audit <dir> [--verify] [--json]` prints the audit log, oldest first.
+  `--verify` checks the hash chain and exits 1 at the first edited, removed or
+  truncated line.
+
+A directory literally named `revisions`, `rollback`, `audit`, `pending`,
+`approve`, `reject`, `pause`, `resume` or `status` must be passed as
+`./revisions` and so on.
+
+### Pending proposals (manual mode)
+
+In manual mode a proposal that passed the gate waits in
+`.lousho/proposals/<id>.json` until a person decides:
+
+```bash
+npx @linuxdevil/lousho improve pending ./my-agent
+npx @linuxdevil/lousho improve approve ./my-agent 3f9c0a1b2d4e --by ali --check ./check.mjs
+npx @linuxdevil/lousho improve reject ./my-agent 3f9c0a1b2d4e --by ali --reason "too broad"
+```
+
+- `pending <dir> [--show <id>] [--json]` lists the queue, newest first, marking
+  stale and refused entries. The id is the first 12 characters of the proposed
+  harness's hash, and a file whose content doesn't match its id is left out.
+  `--show <id>` prints that proposal's review card.
+- `approve <dir> <id> --by <name> [--check <module>] [--model provider/model]
+  [--read-only tool]... [--no-guard] [--db path]` applies the proposal through
+  `applyProposal()` as that person's approval and removes it from the queue.
+  With `canary.traffic` set, it starts the
+  [traffic canary](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#live-traffic-canary-opt-in) instead and writes
+  nothing yet, reading the observe database at `--db` (default
+  `~/.lousho/observe.db`); the proposal is applied as that approval when the
+  canary passes, and the watcher guards it then. A
+  proposal whose agent directory changed since it was made is refused and
+  marked stale; run improve again. Any other refusal is recorded on the entry
+  and shown by `pending`. Right after the write it runs the corpus guard, as an
+  automatic apply does: `guard.runs` fresh runs of every corpus case, scored by
+  `--check`, with tools simulated unless `--read-only` names them. If a case
+  regressed or the guard can't judge (a run that errors counts as unscored, and
+  its error goes to stderr), the edit is rolled back to the approved
+  revision's parent and `approve` exits 1. If the directory changed between the
+  write and the guard, the guard doesn't run and `approve` exits 1 too. The guard's tokens count toward
+  today's budget. With cases in the corpus, `--check` is required, and the
+  agent and the check are loaded before anything is written. `--no-guard`
+  skips the guard and leaves it to a watcher's next scheduled guard. An empty
+  corpus needs neither.
+- `reject <dir> <id> --by <name> [--reason text]` records a `reject` audit entry
+  and moves the file to `.lousho/proposals/rejected/`. A rejected proposal is
+  never queued again.
+
+### Watching, pausing and status
+
+`--watch` keeps the loop running on an agent directory:
+
+```bash
+npx @linuxdevil/lousho improve ./my-agent --check ./check.mjs --watch --interval 15m
+npx @linuxdevil/lousho improve pause ./my-agent --reason "release freeze" --by ali
+npx @linuxdevil/lousho improve resume ./my-agent --by ali
+```
+
+Each tick checks the kill switch (`.lousho/improve.stop`, `LOUSHO_IMPROVE=off`
+or `"enabled": false`, audited once as `pause`), takes a lease so only one
+watcher runs per directory, runs the post-apply monitor, replays the corpus
+every `guard.everyHours`, and then runs one cycle within the daily caps. A tick
+with the same failures as the last one and no new failed run is skipped.
+Three outages in a row write the stop file. Editor calls are limited to
+`rateLimit.rpm` a minute. Ctrl-C stops after the current step. `pause` writes
+the stop file and `resume` removes it; both are audited. `resume` doesn't
+undo `LOUSHO_IMPROVE=off` or `"enabled": false`. While the loop is paused, the
+monitor doesn't run either, so nothing is rolled back automatically. Only a
+watcher runs the monitor: a single `lousho improve` cycle doesn't. See
+[Running it continuously](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#running-it-continuously).
+
+`lousho improve status <dir> [--json]` prints the mode and active revision, the
+last 5 audit entries, pending proposals, the monitor's verdict (with a warning
+while it waits for runs or kept an edit unverified), what is left of today's
+budget, the cooldown, the kill switch, the canary and the editor options a
+cycle uses (from `improve.json` and the defaults). The watcher's events go
+to the `alerts.json` webhooks beside the observe db (see
+[Observability](/observability)).
+
+### `improve.json`
+
+Self-healing settings live in `improve.json` beside the agent. Every key is
+optional, and an unknown key or a bad value is an error
+(`LOUSHO_CONFIG_INVALID`):
+
+```json
+{
+  "approval": "auto",
+  "budget": { "maxTokensPerDay": 2000000, "maxCyclesPerDay": 4, "maxAppliesPerDay": 1 },
+  "trigger": { "minNewFailures": 3, "requireRecurring": true },
+  "canary": { "replayRuns": 6 },
+  "monitor": { "minRuns": 20, "window": 20, "maxDrop": 0.05, "autoRollback": true, "giveUpDays": 7 },
+  "guard": { "runs": 3, "everyHours": 24, "maxCases": 30 },
+  "cooldownHours": 24,
+  "rateLimit": { "rpm": 20 },
+  "library": { "enabled": true },
+  "editors": { "proposers": 1, "mode": "agg", "select": false, "parallel": true }
+}
+```
 
-Before the first run it prints how many runs it will make at least. Every run
-and every editor call is billed to your models. It exits 1 on an `outage`: no
-run could be scored, or the editors' provider failed. Each run's error goes to
-stderr. It reads nothing but your own database. See [Improving an agent](/improve#from-the-command-line).
+These are the defaults. Counts are whole numbers of 1 or more, and `maxDrop` is
+between 0 and 1, and `editors.proposers` is 1 to 4. `requireRecurring`
+defaults to `false` in manual mode.
+`"enabled": false` stops the loop for this agent. `budget.maxTokensPerCycle`,
+`canary.traffic` (`share` up to 0.25, `sessions` up to 50) and `library.domain`
+are unset unless you set them. With `canary.traffic` set, a proposal that
+passes the replay canary (in auto mode), or that a person approves (in manual
+mode), starts the
+[live traffic canary](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#live-traffic-canary-opt-in), which serves it
+to real sessions, instead of being written.
+`loadImproveSettings()` reads the file. See
+[Settings](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#settings) for what each key does.
diff --git a/cloudflare-workers.mdx b/cloudflare-workers.mdx
index 00827d0..e26619a 100644
--- a/cloudflare-workers.mdx
+++ b/cloudflare-workers.mdx
@@ -3,7 +3,7 @@ title: "Cloudflare Workers"
 ---
 {/* Generated from docs/cloudflare-workers.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
-`npx lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](/configuration) or an [agent directory](/agent-directories) (`npx lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](/deployment#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
+`npx @linuxdevil/lousho build --target=cloudflare-worker --agent=agent.yaml` generates a module Worker (`worker.ts`), a `wrangler.toml` and a bundle, `dist/worker.js`, that the build checks for `node:` imports. It needs `tsup` and `wrangler` installed, and it takes an [agent spec file](/configuration) or an [agent directory](/agent-directories) (`npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker`). The Worker serves the same [HTTP API](/deployment#http-api) as the other targets. This target has the tightest limits of the three, so they come first.
 
 ## What works and what does not
 
@@ -14,7 +14,7 @@ title: "Cloudflare Workers"
 | [Agent directories](/agent-directories) | yes: config, `instructions.md`, `tools/`, `skills/`, `subagents/`, `schedules/` (Worker cron rules), `channels/` (mounted under `/channels`), `memory/` (`kvMemory()`, or `inMemoryMemory()` per isolate) and `projectInstructions` (embedded at build time) | yes, all of it |
 | Providers | `mock`, `openai`, `anthropic`, `openrouter` | `mock`, `openai`, `anthropic`, `ollama`, `openrouter` |
 | Built-in tools | `current-date`, `day-name`, `http` (listed host names only, from the `LOUSHO_HTTP_ALLOW` binding) | all, including `http` and `web-fetch` |
-| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
+| Tools written in TypeScript | yes, in an agent directory: no Node builtins, and from `@linuxdevil/lousho` only the names listed under [Agent directories on a Worker](#build-and-deploy) | yes, in an agent directory |
 | Sandboxed tool execution | no (the build swaps the sandbox for a shim that fails when used) | yes |
 | MCP servers over stdio | no (the child process cannot start; the shim fails when used) | yes |
 | [Code mode](/code-mode) (`codeMode`) | no (the build swaps QuickJS for a shim that fails the run at its start) | yes |
@@ -107,7 +107,7 @@ Worker builds the agent with the same rules as `resolveAgentDir()` (config
 keys, tool exports, duplicate tool names):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 cd .lousho/build/cloudflare-worker && npx wrangler deploy
 ```
 
@@ -213,8 +213,8 @@ binding typed as `KVBinding` (the `get`/`put`/`delete` part of Cloudflare's
 from the `/worker` subpath - see [Writing your own Worker](#writing-your-own-worker):
 
 ```ts
-import { createAgent } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_KV: KVBinding;
@@ -277,7 +277,7 @@ new call, which gets a new approval id, so a tool that must act once per
 invoice also needs a key from its own arguments (the invoice number here):
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 // `payments` stands in for your payment client.
@@ -319,7 +319,7 @@ day-of-week (`LOUSHO_SCHEDULE_INVALID`).
 
 In a Worker you write yourself, wire an agent defined in code with
 `handleScheduled(agent, schedules, controller, ctx)` (exported from
-`lousho/worker` — the `lousho/deploy-runtime-worker`
+`@linuxdevil/lousho/worker` — the `@linuxdevil/lousho/deploy-runtime-worker`
 specifier in the generated code is a virtual one that only `lousho build`'s
 bundler resolves; do not import it yourself). It runs the schedules whose
 `cron` equals `controller.cron` inside `ctx.waitUntil()` and never throws; list
@@ -328,9 +328,9 @@ the same expressions under `[triggers] crons` yourself. Give the agent a store
 isolate's memory and is gone when it is recycled:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, handleScheduled } from 'lousho/worker';
-import type { ScheduledContext, ScheduledController } from 'lousho/worker';
-import { KVStore, type KVBinding } from 'lousho/kv';
+import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@linuxdevil/lousho/worker';
+import type { ScheduledContext, ScheduledController } from '@linuxdevil/lousho/worker';
+import { KVStore, type KVBinding } from '@linuxdevil/lousho/kv';
 
 interface Env {
   AGENT_CHECKPOINTS: KVBinding;
@@ -352,7 +352,7 @@ export default {
 
 ## Writing your own Worker
 
-Import from `lousho/worker`, not the package root. The root entry
+Import from `@linuxdevil/lousho/worker`, not the package root. The root entry
 also exports file stores, the agent-directory loader, MCP over stdio, sandboxes
 and other Node-only modules, so bundling it for `platform: 'browser'` fails with
 `Could not resolve "async_hooks"` and friends. `/worker` is `createAgent` plus the
@@ -364,8 +364,8 @@ import {
   createAgent, createMockProvider, defineSchedule, defineTool, handleScheduled,
   memoryStore, serveFetch, OpenAIProvider, AnthropicProvider, OpenRouterProvider,
   LLMProviderRegistry, SDKError, /* ... */
-} from 'lousho/worker';
-import { KVStore } from 'lousho/kv'; // also re-exported from /worker
+} from '@linuxdevil/lousho/worker';
+import { KVStore } from '@linuxdevil/lousho/kv'; // also re-exported from /worker
 ```
 
 The exports: `createAgent` (and its config types), `memoryStore`, the KV stores
@@ -438,8 +438,8 @@ read-modify-write is not atomic.
 ## Bundle size and Node builtins
 
 The KV-backed stores (`KVStore`, `KVCheckpointStore` and `CHECKPOINT_KV_BINDING`,
-exported from `lousho/kv`) have no `node:*` references anywhere
-in their dependency graph, and neither does the `lousho/worker`
+exported from `@linuxdevil/lousho/kv`) have no `node:*` references anywhere
+in their dependency graph, and neither does the `@linuxdevil/lousho/worker`
 entry a hand-written Worker bundles (its build is checked the same way; see
 [Writing your own Worker](#writing-your-own-worker)). The Worker runs the spec as a `createAgent()` agent, whose
 Node-only imports (project instructions, the file session store, guardrail
diff --git a/code-mode.mdx b/code-mode.mdx
index 6ac85bc..80c780e 100644
--- a/code-mode.mdx
+++ b/code-mode.mdx
@@ -38,7 +38,7 @@ npm install quickjs-emscripten@^0.32.0
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const prices: Record<string, number> = { apple: 1.2, pear: 0.8, plum: 2 };
diff --git a/compaction.mdx b/compaction.mdx
index 9c18fb5..e22020a 100644
--- a/compaction.mdx
+++ b/compaction.mdx
@@ -21,7 +21,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const simple = createAgent({ model: 'openai/gpt-4o', compaction: true });
 
@@ -87,7 +87,7 @@ listeners (`createAgent({ onEvent })`, `onAgentEvent`) or is streamed.
 a cheap summarizer model:
 
 ```ts
-import { createAgent, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { createAgent, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -160,7 +160,7 @@ model's loaded context length (`loaded_context_length` from
 prints the model's default).
 
 ```ts
-import { createAgent, registerModel } from 'lousho';
+import { createAgent, registerModel } from '@linuxdevil/lousho';
 
 // Either on the agent...
 const agent = createAgent({
@@ -186,8 +186,8 @@ Registering the hook in a `HookRegistry` is for code that calls the executor
 directly (see [the executor API](/executor-api)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { HookRegistry, createCompactionHook, twoPhaseStrategy } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { HookRegistry, createCompactionHook, twoPhaseStrategy } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register(
@@ -273,7 +273,7 @@ message; a pinned tool result keeps its whole assistant turn. Pin what the
 agent must always see in full, such as the task statement or a key document:
 
 ```ts
-import { pinMessage, isPinned, type Message } from 'lousho';
+import { pinMessage, isPinned, type Message } from '@linuxdevil/lousho';
 
 const messages: Message[] = [
   { role: 'system', content: 'You are a research assistant.' },
@@ -291,7 +291,7 @@ of the conversation, and resolves to a new array (its input is not modified).
 Use it to shrink a stored transcript before you continue it:
 
 ```ts
-import { compactMessages, summarizeStrategy, type Message } from 'lousho';
+import { compactMessages, summarizeStrategy, type Message } from '@linuxdevil/lousho';
 
 declare const history: Message[];
 
@@ -325,8 +325,8 @@ durable turn is unfinished. Listeners added with `session.on()` get
 checkpoint and checkpoint history, and emits `context.cleared`.
 
 ```ts
-import { createAgent, twoPhaseStrategy } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, twoPhaseStrategy } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['ok']) });
 const session = agent.session({ compaction: { strategy: twoPhaseStrategy({ model: 'openai/gpt-4o-mini' }) } });
@@ -351,7 +351,7 @@ unchanged when there is nothing to do: the hook then leaves the run alone and
 does not call `onCompaction`.
 
 ```ts
-import { createCompactionHook, isPinned, type CompactionStrategy } from 'lousho';
+import { createCompactionHook, isPinned, type CompactionStrategy } from '@linuxdevil/lousho';
 
 // Keep the system prompt, pinned messages and the last 20 messages.
 const keepRecent: CompactionStrategy = {
diff --git a/comparison.mdx b/comparison.mdx
index 5c23ede..b1af692 100644
--- a/comparison.mdx
+++ b/comparison.mdx
@@ -1,8 +1,9 @@
 ---
 title: "How Lousho compares"
+sidebarTitle: "Comparison"
 description: "This page compares Lousho with four other TypeScript agent libraries: the Vercel AI SDK (ToolLoopAgent), the OpenAI Agents SDK for JavaScript, Mastra and LangGraph.js. Each competitor cell comes from that project's official docs."
 ---
-{/* Generated from docs/comparison.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/comparison.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 Last checked: 9 Nov 2026. These projects move fast, so a cell may be out of
 date. Corrections welcome: [open an issue](https://github.com/LinuxDevil/lousho/issues).
@@ -67,7 +68,7 @@ Each Lousho ✅ links to the Lousho page that documents it.
   frameworks.
 - **OpenTelemetry**: spans you can send to any OpenTelemetry backend.
 - **Local studio/debugger**: a UI on your machine to inspect and run agents.
-- **Provider-agnostic**: works with models from more than one vendor.
+- **Provider-agnostic**: works with models from more than one vendor. Lousho resolves `vendor/model` strings for its own providers and for every official `@ai-sdk/*` package ([any AI SDK vendor](/providers#any-ai-sdk-vendor-by-name)).
 
 ## When not to use Lousho
 
diff --git a/configuration.mdx b/configuration.mdx
index 2e84194..1ed24d1 100644
--- a/configuration.mdx
+++ b/configuration.mdx
@@ -1,11 +1,11 @@
 ---
 title: "Configuration"
 ---
-{/* Generated from docs/configuration.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/configuration.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 ## Agent spec files (`AgentSpec`)
 
-> This page describes spec version 1. New specs use [Agent spec v2](/agent-spec); `upgradeSpec()` converts a v1 spec.
+> This page describes spec version 1. New specs use [Agent spec v2](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-spec.md); `upgradeSpec()` converts a v1 spec.
 
 A declarative agent is a YAML (`.yaml`/`.yml`) or JSON (`.json`) file,
 validated with zod by `loadSpec()` (`src/spec/schema.ts`). It is the format
@@ -145,7 +145,7 @@ mcpServers:
 ```
 
 ```ts
-import { agentSpecSchema, specToAgent, type McpServerSpec } from 'lousho';
+import { agentSpecSchema, specToAgent, type McpServerSpec } from '@linuxdevil/lousho';
 
 const filesystem: McpServerSpec = { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem'] };
 const spec = agentSpecSchema.parse({
@@ -188,7 +188,7 @@ other models. The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -230,7 +230,7 @@ To build the same thing by hand, or for providers you construct yourself,
 anywhere a provider is accepted:
 
 ```ts
-import { createAgent, resolveProvider, withFallback, withRetry } from 'lousho';
+import { createAgent, resolveProvider, withFallback, withRetry } from '@linuxdevil/lousho';
 
 const provider = withFallback(
   [
@@ -301,7 +301,7 @@ flow waves and eval suites cannot burst unbounded model calls. Every limit is
 optional:
 
 ```ts
-import { withRateLimit, resolveProvider } from 'lousho';
+import { withRateLimit, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = withRateLimit(resolveProvider('openai/gpt-4o-mini'), {
   requestsPerMinute: 60, // calls started per rolling minute
@@ -331,7 +331,7 @@ its own provider is queued too). Give several agents the same
 `createRateLimiter()` to share it across them.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher }, rateLimit: { maxConcurrent: 2 } });
@@ -410,7 +410,7 @@ A `send()` or `stream()` call can pass its own, which win key by key over the
 agent's:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -445,7 +445,7 @@ Besides `modelSettings`, a `send()` or `stream()` call can set its own
 instructions for that run:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You triage support tickets.' });
 await agent.send('Summarize the ticket.', { maxSteps: 2, instructions: 'Answer in French.' });
@@ -463,7 +463,7 @@ keeps `model` / `provider` and `instructions` / `prompt` mutually exclusive,
 so TypeScript rejects spreading it next to a literal that sets one of them.
 
 ```ts
-import { createAgent, type CreateAgentBase } from 'lousho';
+import { createAgent, type CreateAgentBase } from '@linuxdevil/lousho';
 
 const shared: CreateAgentBase = { maxSteps: 8, modelSettings: { temperature: 0 } };
 
@@ -522,7 +522,7 @@ with a checkpoint store it is checkpointed as finished, like `'max-steps'`.
 (`LOUSHO_BUDGET_EXCEEDED`, with the same `budget`) instead.
 
 ```ts
-import { BudgetExceededError, createAgent } from 'lousho';
+import { BudgetExceededError, createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -551,7 +551,7 @@ continued from its store keeps its budget. Both apply together; the first limit
 reached stops the turn. A turn that was aborted is not counted.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore(), limits: { maxTokens: 20_000 } });
 const session = agent.session({ id: 'user-42', limits: { maxCostUsd: 1 } });
@@ -565,7 +565,7 @@ Many repositories keep guidance for coding agents in an `AGENTS.md` (or
 `CLAUDE.md`) file. `createAgent` can append it to the agent's instructions:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You review pull requests.',
diff --git a/connectors.mdx b/connectors.mdx
index 4e9aa3d..5ef10e2 100644
--- a/connectors.mdx
+++ b/connectors.mdx
@@ -9,7 +9,7 @@ connector is an **MCP server**: add it to `mcpServers` and its tools join the
 agent's registry namespaced as `<server>__<tool>`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -50,8 +50,8 @@ into the SDK's approval gate: a `slack.post_message` pauses the run until
 approved, `docs.get_document` does not. Tune it per server:
 
 ```ts
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'ok' }]);
 
diff --git a/decisions.mdx b/decisions.mdx
index bebc6cc..0e3f126 100644
--- a/decisions.mdx
+++ b/decisions.mdx
@@ -8,7 +8,7 @@ title: "Decisions"
 Public beta: `gpt-6-luna` is the only model the endpoint serves, and the surface may still change. The endpoint is not part of chat completions, so it does not go through `createAgent()` providers or OpenRouter — it needs `OPENAI_API_KEY` (or `apiKey`/`baseURL` for a compatible endpoint).
 
 ```ts
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const { answers } = await decide({
   input: 'I was charged twice for my order.',
@@ -35,7 +35,7 @@ if (route.type === 'choice' && route.confidence >= 0.7) {
 ## Question types
 
 ```ts
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   // predicate: probability 0-1 that a condition holds
@@ -72,7 +72,7 @@ const questions: DecisionQuestion[] = [
 Independent questions share one `input` and one request:
 
 ```ts
-import { decide, type DecisionQuestion } from 'lousho';
+import { decide, type DecisionQuestion } from '@linuxdevil/lousho';
 
 const questions: DecisionQuestion[] = [
   { type: 'predicate', name: 'is_spam', instructions: 'Is this spam?' },
@@ -94,7 +94,7 @@ const byName = Object.fromEntries(answers.map((a) => [a.name, a]));
 ## Options
 
 ```ts
-import { decide } from 'lousho';
+import { decide } from '@linuxdevil/lousho';
 
 const result = await decide({
   input: '...',
diff --git a/deployment.mdx b/deployment.mdx
index 99c6b67..cc28ba6 100644
--- a/deployment.mdx
+++ b/deployment.mdx
@@ -7,7 +7,7 @@ title: "Deployment"
 into a deployable artifact for one target platform:
 
 ```bash
-npx lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
+npx @linuxdevil/lousho build --target=<target> --agent=agent.yaml [--out=<dir>]
 ```
 
 It runs the target's adapter through three steps - **scaffold** (write the
@@ -33,7 +33,7 @@ All three targets also take an [agent directory](/agent-directories)
 in place of a spec file (the path may be positional or `--agent`):
 
 ```bash
-npx lousho build ./my-agent --target=node-server
+npx @linuxdevil/lousho build ./my-agent --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -44,7 +44,7 @@ directory's [schedules](/schedules) when it listens, mounts its
 routes keep the bearer token), and logs `schedules: ...; channels: ...`.
 The directory's code files are pre-bundled with the build's tsup step into
 `dist/agent/**.js` (one ESM build sharing one copy of the SDK, so a `from
-'lousho'` import in a tool is the SDK the server runs), and
+'@linuxdevil/lousho'` import in a tool is the SDK the server runs), and
 only the files the server reads as data are copied: `instructions.md`,
 `instructions/`, `skills/`, a JSON/YAML config, and the same in each
 `subagents/<name>/`. Nothing else in the directory reaches `dist/`: not `.env`
@@ -65,7 +65,7 @@ only a Worker-safe part of `lousho`
 ([Cloudflare Workers](/cloudflare-workers#build-and-deploy) has the details):
 
 ```bash
-npx lousho build ./my-agent --target=cloudflare-worker
+npx @linuxdevil/lousho build ./my-agent --target=cloudflare-worker
 ```
 
 ## Agent modules
@@ -76,7 +76,7 @@ same file `lousho dev src/agent.ts` serves, and what the minimal and tools
 scaffolds have (their `npm run build` runs this):
 
 ```bash
-npx lousho build src/agent.ts --target=node-server
+npx @linuxdevil/lousho build src/agent.ts --target=node-server
 node .lousho/build/node-server/dist/server.js
 ```
 
@@ -294,7 +294,7 @@ signal handler: stop accepting, let the requests in flight finish, then call
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent, mountChannels } from 'lousho';
+import { createAgent, mountChannels } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const handler = mountChannels(agent, []);
diff --git a/docs.json b/docs.json
index 762e05e..d22e400 100644
--- a/docs.json
+++ b/docs.json
@@ -171,6 +171,9 @@
                   "cloudflare-workers",
                   "registry",
                   "agent-forge",
+                  "forge-builder",
+                  "forge-author",
+                  "forge-lifecycle",
                   {
                     "group": "Deployment guides",
                     "pages": [
diff --git a/durable-execution.mdx b/durable-execution.mdx
index 6eaa83d..2e44e4e 100644
--- a/durable-execution.mdx
+++ b/durable-execution.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Durable execution"
 ---
-{/* Generated from docs/durable-execution.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/durable-execution.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 Give `createAgent()` a `store` and pass a `sessionId` to `send()`, and the
 run survives a crash, a restart, an abort or a human approval that takes
@@ -13,8 +13,8 @@ and any `ApprovalStore` work the same way.
 See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutorial.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/jobs.db') });
 
@@ -107,7 +107,7 @@ session (the session already has its system prompt). To end a session and
 start over under the same id, call `store.checkpoints.delete(sessionId)`.
 
 ```ts
-import { createAgent, memoryStore, SessionAwaitingApprovalError } from 'lousho';
+import { createAgent, memoryStore, SessionAwaitingApprovalError } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -139,7 +139,7 @@ underneath):
 3. calls the model once every call of the turn has exactly one result.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: memoryStore() });
 
@@ -163,7 +163,7 @@ finishes it. `agent.pending()` lists those runs across every session and
 `send(msg, { sessionId })` id, so a restarted process can find them:
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 
@@ -228,8 +228,8 @@ without durable writes) is listed as `'in-progress'` with `lastError.code`
 to the code that serves traffic:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
@@ -311,7 +311,7 @@ without a checkpoint store. With a custom store that has no leases
 (`acquireLease`), nothing stops it from resuming a run another process is
 still running: run it in one process only.
 
-For an overview of recovery alongside the progress guard and `improveAgent()`, see [Self-healing and self-improvement](/self-healing).
+For an overview of recovery alongside the progress guard and `improveAgent()`, see [Self-healing and self-improvement](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/self-healing.md).
 
 ## Run leases
 
@@ -439,7 +439,7 @@ model calls). To run a job once, derive the `sessionId` from the delivery id
 and look at the checkpoint before sending:
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ provider, store });
@@ -477,7 +477,7 @@ same call is re-run on resume) is passed to `execute`, so it works as an
 idempotency key against a re-run of one call:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const payments: { charge(amount: number, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -513,7 +513,7 @@ one invoice) needs an idempotency key from your own data, such as the claim id
 in the arguments, checked or passed on to the system you write to:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 declare const claims: { file(claim: { claimId: string }, opts: { idempotencyKey: string }): Promise<{ id: string }> };
@@ -543,14 +543,14 @@ Which stores keep one:
 | `SqliteStore` | yes (`checkpoint_history` table) | `new SqliteStore(path, { historyLimit })` |
 | `LocalStorageCheckpointStore` | yes | `new LocalStorageCheckpointStore(storage, { historyLimit })` |
 | `fileStore(dir)` (JSON files) | yes (`checkpoint-history/<id>.json`) | `fileStore(dir, { historyLimit })` |
-| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
+| `KVCheckpointStore` / `KVStore` (Cloudflare Workers KV, from `@linuxdevil/lousho/kv`) | yes (see below) | `new KVStore(kv, { historyLimit })` |
 | Agent Forge's `FileCheckpointStore` | yes | `new FileCheckpointStore(dir, { historyLimit })` |
 | a custom `CheckpointStore` | only if it implements `history()` | - |
 
 For example, with the in-memory store:
 
 ```ts
-import { getCheckpointHistory, memoryStore } from 'lousho';
+import { getCheckpointHistory, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore({ historyLimit: 20 }); // default 50, 0 keeps none
 // new SqliteStore(path, { historyLimit }), new LocalStorageCheckpointStore(storage, { historyLimit })
@@ -605,7 +605,7 @@ saves the result as the `'in-progress'` checkpoint of the new session over
 fork like any unfinished run with `agent.resume(fork.sessionId)`:
 
 ```ts
-import { createAgent, compareTrajectories, memoryStore } from 'lousho';
+import { createAgent, compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const assistant = createAgent({ provider, store });
@@ -686,8 +686,8 @@ it and it has no result yet, or the human approved it) always rejects with
 whatever the option.
 
 ```ts
-import { createAgent, memoryStore } from 'lousho';
-import type { LLMProvider } from 'lousho';
+import { createAgent, memoryStore } from '@linuxdevil/lousho';
+import type { LLMProvider } from '@linuxdevil/lousho';
 
 declare const provider: LLMProvider;
 
@@ -728,8 +728,8 @@ call it corresponds to.
 `agent.send(message, { sessionId })`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { LocalStorageCheckpointStore } from 'lousho/utils';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { LocalStorageCheckpointStore } from '@linuxdevil/lousho/utils';
 
 const checkpoints = new LocalStorageCheckpointStore(storage);
 
@@ -743,8 +743,8 @@ await AgentExecutor.execute({ agent, input: 'Make it 3 people', provider, sessio
 It throws `SessionAwaitingApprovalError` on a paused session, as `send()` does:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SessionAwaitingApprovalError, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SessionAwaitingApprovalError, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 
@@ -761,7 +761,7 @@ The exported `resumeAfterApproval()` function is what
 `agent.approvals.resolve()` calls:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, resumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({
   agent, input, provider, toolRegistry, approvalStore, sessionId: 'chat-42', checkpointStore,
@@ -785,8 +785,8 @@ if (paused.finishReason === 'awaiting-approval') {
 fork's `sessionId` is `agent.resume(fork.sessionId)`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { compareTrajectories, memoryStore } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { compareTrajectories, memoryStore } from '@linuxdevil/lousho';
 
 const { checkpoints } = memoryStore();
 await AgentExecutor.execute({ agent, provider, toolRegistry, input: 'Plan my trip', sessionId: 'trip', checkpointStore: checkpoints });
diff --git a/errors.mdx b/errors.mdx
index 21c3eb0..4c60e74 100644
--- a/errors.mdx
+++ b/errors.mdx
@@ -1,12 +1,8 @@
 ---
 title: "Errors"
-description: "Every deliberate SDK error is an SDKError with a stable LOUSHO_* code, a hint and a link to its section here; this page lists each code with its cause and fix."
+description: "Nearly every error the SDK throws on purpose is an SDKError (or a subclass such as ConfigurationError, ValidationError or MissingPeerDependencyError) with:"
 ---
-{/* Generated from docs/errors.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
-
-Nearly every error the SDK throws on purpose is an `SDKError` (or a subclass
-such as `ConfigurationError`, `ValidationError` or `MissingPeerDependencyError`)
-with:
+{/* Generated from docs/errors.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 - `code`: a stable string, `LOUSHO_<AREA>_<NAME>`. Branch on it, not on the
   message text, which may get clearer over time.
@@ -31,7 +27,7 @@ serialising the error is unchanged). It is absent when the run failed before
 it started.
 
 ```ts
-import { createAgent, type RunUsage } from 'lousho';
+import { createAgent, type RunUsage } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider }).send('Go');
@@ -52,7 +48,7 @@ on purpose: `PropagatingToolError` and its subclasses (a tool throws one to
 stop the run), `WorkspaceError` (a workspace operation refused or failed -
 the model sees it as a tool error), `McpToolError` (a loaded MCP tool whose
 server reports `isError`; also a tool error), `AuthError` (an
-`lousho/auth` entry rejects the request with its 401 or 403),
+`@linuxdevil/lousho/auth` entry rejects the request with its 401 or 403),
 `CronExpressionError` (`parseCronExpression()`, which
 `defineSchedule()` wraps as `LOUSHO_SCHEDULE_INVALID`) and
 `DecryptionError` (`EncryptionUtils`, `DTOEncryptionFilter`).
@@ -63,7 +59,7 @@ server reports `isError`; also a tool error), `AuthError` (an
 and `.cassette` / `.callNumber` fields.
 
 ```ts
-import { createAgent, SDKError } from 'lousho';
+import { createAgent, SDKError } from '@linuxdevil/lousho';
 
 try {
   await createAgent({ provider, instructions: 'Be brief.' }).send('hi');
@@ -92,17 +88,18 @@ Find a code by area:
 | [Providers and peers](#providers-and-peers) | [`LOUSHO_PROVIDER_SPEC_INVALID`](#lousho_provider_spec_invalid), [`LOUSHO_PROVIDER_UNKNOWN`](#lousho_provider_unknown), [`LOUSHO_PROVIDER_MISSING_API_KEY`](#lousho_provider_missing_api_key), [`LOUSHO_PROVIDER_REQUEST_FAILED`](#lousho_provider_request_failed), [`LOUSHO_PROVIDER_RATE_LIMITED`](#lousho_provider_rate_limited), [`LOUSHO_PEER_MISSING`](#lousho_peer_missing), [`LOUSHO_HOSTED_TOOL_UNSUPPORTED`](#lousho_hosted_tool_unsupported), [`LOUSHO_UNSUPPORTED_CONTENT`](#lousho_unsupported_content) | Resolving a model string, a missing API key or peer package, a failed or rate-limited model request, a hosted tool the provider cannot run, a file the provider cannot send. |
 | [Agent spec files](#agent-spec-files) | [`LOUSHO_SPEC_NOT_FOUND`](#lousho_spec_not_found), [`LOUSHO_SPEC_INVALID`](#lousho_spec_invalid), [`LOUSHO_SPEC_UNKNOWN_FIELD`](#lousho_spec_unknown_field), [`LOUSHO_SPEC_UNSUPPORTED_FORMAT`](#lousho_spec_unsupported_format), [`LOUSHO_SPEC_UNSUPPORTED`](#lousho_spec_unsupported), [`LOUSHO_SPEC_SECRET_MISSING`](#lousho_spec_secret_missing) | Loading an `AgentSpec` file with `loadSpec()` or `specToAgent()`. |
 | [Tools](#tools) | [`LOUSHO_TOOL_NOT_FOUND`](#lousho_tool_not_found), [`LOUSHO_TOOL_NEEDS_CREDENTIALS`](#lousho_tool_needs_credentials), [`LOUSHO_TOOL_EXECUTION_FAILED`](#lousho_tool_execution_failed), [`LOUSHO_TOOL_ARGS_INVALID`](#lousho_tool_args_invalid), [`LOUSHO_MCP_START_FAILED`](#lousho_mcp_start_failed), [`LOUSHO_MCP_CALL_FAILED`](#lousho_mcp_call_failed) | A tool the model called is unknown, needs credentials, threw, or got invalid arguments; a stdio MCP server did not start or a call to one failed. |
-| [Approvals and sessions](#approvals-and-sessions) | [`LOUSHO_APPROVAL_STORE_MISSING`](#lousho_approval_store_missing), [`LOUSHO_APPROVAL_NOT_FOUND`](#lousho_approval_not_found), [`LOUSHO_APPROVAL_ORPHANED`](#lousho_approval_orphaned), [`LOUSHO_APPROVAL_CONFLICT`](#lousho_approval_conflict), [`LOUSHO_APPROVAL_FORBIDDEN`](#lousho_approval_forbidden), [`LOUSHO_APPROVAL_DECISION_INVALID`](#lousho_approval_decision_invalid), [`LOUSHO_APPROVAL_KIND_MISMATCH`](#lousho_approval_kind_mismatch), [`LOUSHO_SESSION_FORBIDDEN`](#lousho_session_forbidden), [`LOUSHO_SESSION_AWAITING_APPROVAL`](#lousho_session_awaiting_approval), [`LOUSHO_SESSION_ID_INVALID`](#lousho_session_id_invalid), [`LOUSHO_SESSION_FILE_CORRUPT`](#lousho_session_file_corrupt), [`LOUSHO_SESSION_BUSY`](#lousho_session_busy), [`LOUSHO_SESSION_TURN_PENDING`](#lousho_session_turn_pending), [`LOUSHO_SESSION_TURN_FAILED`](#lousho_session_turn_failed), [`LOUSHO_SESSION_STREAM_UNSUPPORTED`](#lousho_session_stream_unsupported), [`LOUSHO_SESSION_STEP_NOT_FOUND`](#lousho_session_step_not_found), [`LOUSHO_SESSION_EXISTS`](#lousho_session_exists), [`LOUSHO_SESSION_FORK_UNSUPPORTED`](#lousho_session_fork_unsupported), [`LOUSHO_REMOTE_UNAUTHORIZED`](#lousho_remote_unauthorized), [`LOUSHO_REMOTE_REQUEST_FAILED`](#lousho_remote_request_failed), [`LOUSHO_SUBAGENT_TASK_NOT_FOUND`](#lousho_subagent_task_not_found), [`LOUSHO_SUBAGENT_TASK_BUSY`](#lousho_subagent_task_busy), [`LOUSHO_CHECKPOINT_NOT_FOUND`](#lousho_checkpoint_not_found), [`LOUSHO_CHECKPOINT_CORRUPT`](#lousho_checkpoint_corrupt), [`LOUSHO_AGENT_DRIFT`](#lousho_agent_drift), [`LOUSHO_RESUME_TOOL_MISSING`](#lousho_resume_tool_missing), [`LOUSHO_RUN_ALREADY_ITERATED`](#lousho_run_already_iterated), [`LOUSHO_RUN_NO_PROGRESS`](#lousho_run_no_progress) | Approvals, sessions, checkpoints and resume, remote agents and sub-agent tasks. |
+| [Approvals and sessions](#approvals-and-sessions) | [`LOUSHO_APPROVAL_STORE_MISSING`](#lousho_approval_store_missing), [`LOUSHO_APPROVAL_NOT_FOUND`](#lousho_approval_not_found), [`LOUSHO_APPROVAL_ORPHANED`](#lousho_approval_orphaned), [`LOUSHO_APPROVAL_CONFLICT`](#lousho_approval_conflict), [`LOUSHO_APPROVAL_FORBIDDEN`](#lousho_approval_forbidden), [`LOUSHO_APPROVAL_DECISION_INVALID`](#lousho_approval_decision_invalid), [`LOUSHO_APPROVAL_KIND_MISMATCH`](#lousho_approval_kind_mismatch), [`LOUSHO_AUTO_APPROVAL_INVALID`](#lousho_auto_approval_invalid), [`LOUSHO_SESSION_FORBIDDEN`](#lousho_session_forbidden), [`LOUSHO_SESSION_AWAITING_APPROVAL`](#lousho_session_awaiting_approval), [`LOUSHO_SESSION_ID_INVALID`](#lousho_session_id_invalid), [`LOUSHO_SESSION_FILE_CORRUPT`](#lousho_session_file_corrupt), [`LOUSHO_SESSION_BUSY`](#lousho_session_busy), [`LOUSHO_SESSION_TURN_PENDING`](#lousho_session_turn_pending), [`LOUSHO_SESSION_TURN_FAILED`](#lousho_session_turn_failed), [`LOUSHO_SESSION_STREAM_UNSUPPORTED`](#lousho_session_stream_unsupported), [`LOUSHO_SESSION_STEP_NOT_FOUND`](#lousho_session_step_not_found), [`LOUSHO_SESSION_EXISTS`](#lousho_session_exists), [`LOUSHO_SESSION_FORK_UNSUPPORTED`](#lousho_session_fork_unsupported), [`LOUSHO_REMOTE_UNAUTHORIZED`](#lousho_remote_unauthorized), [`LOUSHO_REMOTE_REQUEST_FAILED`](#lousho_remote_request_failed), [`LOUSHO_SUBAGENT_TASK_NOT_FOUND`](#lousho_subagent_task_not_found), [`LOUSHO_SUBAGENT_TASK_BUSY`](#lousho_subagent_task_busy), [`LOUSHO_CHECKPOINT_NOT_FOUND`](#lousho_checkpoint_not_found), [`LOUSHO_CHECKPOINT_CORRUPT`](#lousho_checkpoint_corrupt), [`LOUSHO_AGENT_DRIFT`](#lousho_agent_drift), [`LOUSHO_RESUME_TOOL_MISSING`](#lousho_resume_tool_missing), [`LOUSHO_RUN_ALREADY_ITERATED`](#lousho_run_already_iterated), [`LOUSHO_RUN_NO_PROGRESS`](#lousho_run_no_progress) | Approvals, sessions, checkpoints and resume, remote agents and sub-agent tasks. |
 | [Schedules](#schedules) | [`LOUSHO_SCHEDULE_INVALID`](#lousho_schedule_invalid), [`LOUSHO_SCHEDULE_RUN_INCOMPLETE`](#lousho_schedule_run_incomplete) | Defining or loading a schedule, or a scheduled turn that did not finish. |
 | [Channels](#channels) | [`LOUSHO_CHANNEL_INVALID`](#lousho_channel_invalid), [`LOUSHO_MEMORY_INVALID`](#lousho_memory_invalid) | Defining a channel or a memory slot. |
 | [Registry](#registry) | [`LOUSHO_REGISTRY_UNREACHABLE`](#lousho_registry_unreachable), [`LOUSHO_REGISTRY_ITEM_NOT_FOUND`](#lousho_registry_item_not_found), [`LOUSHO_REGISTRY_INVALID`](#lousho_registry_invalid), [`LOUSHO_REGISTRY_UNSAFE_PATH`](#lousho_registry_unsafe_path), [`LOUSHO_REGISTRY_FILE_EXISTS`](#lousho_registry_file_exists), [`LOUSHO_REGISTRY_MANIFEST_MISMATCH`](#lousho_registry_manifest_mismatch) | `lousho add` fetching or copying from a registry. |
 | [Sandbox](#sandbox) | [`LOUSHO_SANDBOX_EGRESS_UNSUPPORTED`](#lousho_sandbox_egress_unsupported), [`LOUSHO_SANDBOX_PATH_DENIED`](#lousho_sandbox_path_denied), [`LOUSHO_SANDBOX_FAILED`](#lousho_sandbox_failed) | Asking a sandbox for something it cannot do on the current platform, writing outside its root, or a code-sandbox boundary (timeout / OOM / driver) failing a run. |
 | [Agent directories, skills and flows](#agent-directories-skills-and-flows) | [`LOUSHO_AGENT_DIR_INVALID`](#lousho_agent_dir_invalid), [`LOUSHO_SKILL_INVALID`](#lousho_skill_invalid), [`LOUSHO_FLOW_INVALID`](#lousho_flow_invalid), [`LOUSHO_FLOW_TOOL_DENIED`](#lousho_flow_tool_denied), [`LOUSHO_FLOW_CHANGED`](#lousho_flow_changed) | Loading an agent directory, a skill, or a flow definition, and gating a flow's tool calls. |
-| [Storage, deployment and integrations](#storage-deployment-and-integrations) | [`LOUSHO_STORAGE_FAILED`](#lousho_storage_failed), [`LOUSHO_STORAGE_BUSY`](#lousho_storage_busy), [`LOUSHO_TRIGGER_INVALID`](#lousho_trigger_invalid), [`LOUSHO_CHANNEL_REQUEST_FAILED`](#lousho_channel_request_failed), [`LOUSHO_DEPLOY_FAILED`](#lousho_deploy_failed), [`LOUSHO_SERVER_UNPROTECTED`](#lousho_server_unprotected) | A storage backend, a trigger, a channel request, `lousho build` or the built server's start-up. |
+| [Storage, deployment and integrations](#storage-deployment-and-integrations) | [`LOUSHO_STORAGE_FAILED`](#lousho_storage_failed), [`LOUSHO_STORAGE_BUSY`](#lousho_storage_busy), [`LOUSHO_ARTIFACT_FORBIDDEN`](#lousho_artifact_forbidden), [`LOUSHO_ARTIFACT_TOO_LARGE`](#lousho_artifact_too_large), [`LOUSHO_ARTIFACT_EXISTS`](#lousho_artifact_exists), [`LOUSHO_ARTIFACT_UNSAFE_PATH`](#lousho_artifact_unsafe_path), [`LOUSHO_TRIGGER_INVALID`](#lousho_trigger_invalid), [`LOUSHO_CHANNEL_REQUEST_FAILED`](#lousho_channel_request_failed), [`LOUSHO_DEPLOY_FAILED`](#lousho_deploy_failed), [`LOUSHO_SERVER_UNPROTECTED`](#lousho_server_unprotected) | A storage backend, a workspace artifact store, a trigger, a channel request, `lousho build` or the built server's start-up. |
 | [Tests and evals](#tests-and-evals) | [`LOUSHO_EVALS_INVALID`](#lousho_evals_invalid), [`LOUSHO_DATASET_UNAVAILABLE`](#lousho_dataset_unavailable), [`LOUSHO_TEST_FAILED`](#lousho_test_failed), [`LOUSHO_CASSETTE_INVALID`](#lousho_cassette_invalid) | `defineEval()`, `mockModel` and cassettes. |
 | [General](#general) | [`LOUSHO_GENERIC_ERROR`](#lousho_generic_error), [`LOUSHO_AGENT_EXECUTION_FAILED`](#lousho_agent_execution_failed), [`LOUSHO_FLOW_EXECUTION_FAILED`](#lousho_flow_execution_failed), [`LOUSHO_VALIDATION_FAILED`](#lousho_validation_failed), [`LOUSHO_OPERATION_TIMEOUT`](#lousho_operation_timeout), [`LOUSHO_OUTPUT_INVALID`](#lousho_output_invalid), [`LOUSHO_BUDGET_EXCEEDED`](#lousho_budget_exceeded), [`LOUSHO_GUARDRAIL_TRIPPED`](#lousho_guardrail_tripped) | Run-level failures: a timeout, a budget or guardrail stop, invalid output, and the catch-all codes. |
 | [Auth](#auth) | [`LOUSHO_AUTH_CONFIG_INVALID`](#lousho_auth_config_invalid) | A route auth helper (`jwt()`, `oidc()`, `basic()`, `apiToken()`) got options it cannot verify with. |
 | [OAuth](#oauth) | [`LOUSHO_TOKEN_KEY_MISSING`](#lousho_token_key_missing), [`LOUSHO_TOKEN_DECRYPT_FAILED`](#lousho_token_decrypt_failed), [`LOUSHO_OAUTH_PRINCIPAL_REQUIRED`](#lousho_oauth_principal_required), [`LOUSHO_OAUTH_APP_SIGNIN_REQUIRED`](#lousho_oauth_app_signin_required), [`LOUSHO_OAUTH_STORE_MISSING`](#lousho_oauth_store_missing), [`LOUSHO_OAUTH_STATE_INVALID`](#lousho_oauth_state_invalid), [`LOUSHO_SIGNIN_PENDING`](#lousho_signin_pending), [`LOUSHO_OAUTH_TOKEN_EXCHANGE_FAILED`](#lousho_oauth_token_exchange_failed), [`LOUSHO_MCP_AUTH_REQUIRED`](#lousho_mcp_auth_required) | Storing or reading OAuth tokens in a file, SQLite or KV store, sign-in and token exchange for OAuth tools and MCP servers. |
+| [Workspaces](#workspaces) | [`LOUSHO_WORKSPACE_STALE_REVISION`](#lousho_workspace_stale_revision), [`LOUSHO_WORKSPACE_NO_CHANGE`](#lousho_workspace_no_change), [`LOUSHO_WORKSPACE_PATH_INVALID`](#lousho_workspace_path_invalid), [`LOUSHO_WORKSPACE_REVISION_UNKNOWN`](#lousho_workspace_revision_unknown), [`LOUSHO_WORKSPACE_SOURCE_LIMIT`](#lousho_workspace_source_limit), [`LOUSHO_WORKSPACE_SOURCE_CORRUPT`](#lousho_workspace_source_corrupt), [`LOUSHO_WORKSPACE_CONTENT_UNSUPPORTED`](#lousho_workspace_content_unsupported), [`LOUSHO_WORKSPACE_INVALID`](#lousho_workspace_invalid), [`LOUSHO_WORKSPACE_AGENT_UNRESOLVED`](#lousho_workspace_agent_unresolved), [`LOUSHO_WORKSPACE_MAIN_HARNESS_TEXT_MISSING`](#lousho_workspace_main_harness_text_missing), [`LOUSHO_WORKSPACE_CAPABILITY_MISSING`](#lousho_workspace_capability_missing), [`LOUSHO_WORKSPACE_ENGINE_UNKNOWN`](#lousho_workspace_engine_unknown), [`LOUSHO_WORKSPACE_PAGE_UNKNOWN`](#lousho_workspace_page_unknown), [`LOUSHO_WORKSPACE_NO_MAIN_AGENT`](#lousho_workspace_no_main_agent), [`LOUSHO_WORKSPACE_HOST_INVALID`](#lousho_workspace_host_invalid), [`LOUSHO_WORKSPACE_RUNTIME_CLOSED`](#lousho_workspace_runtime_closed), [`LOUSHO_WORKSPACE_RUN_ACTIVE`](#lousho_workspace_run_active) | Reading or writing a workspace through a `WorkspaceSource` (`folderSource()`, `memorySource()`, `sqliteWorkspaceSource()`, `postgresWorkspaceSource()`), loading it with `loadWorkspace()`, resolving page agents with `resolveAttachments()`, assembling prompts with `assembleMainInstructions()`, applying the policy at page start with `pagePolicy()`, running a page with `runPage()`, and running a workspace session with `openWorkspaceSession()`, and running a workspace through `createWorkspaceRuntime()`. |
 
 ## Configuration
 
@@ -399,7 +396,7 @@ where the agent is being built.
 agent spec has no field for.
 
 **Fix:** build the agent with `createAgent()` and pass the configured tool, e.g.
-`createGitHubTools(config)` from `lousho/integrations`.
+`createGitHubTools(config)` from `@linuxdevil/lousho/integrations`.
 
 **Example:** `tools: [github]` in a spec.
 
@@ -565,6 +562,19 @@ pending pause's `approvalKind`.
 **Example:** posting `{ "approved": true }` to a pause that waits for the
 model's `ask_question` answer.
 
+### LOUSHO_AUTO_APPROVAL_INVALID
+
+**Means:** `modelAutoApprover` (the model-scored approver behind
+`createAutoApprove`) could not read a verdict from the model's reply: no JSON
+object, a `safety` that is not a number in [0, 1], or no `reason` string.
+
+**Fix:** check the auto approver's model and prompt — its reply must be a
+JSON object `{ "safety": <0..1>, "reason": "<text>" }`; prose around it is
+fine. See [Approvals](/approvals#model-decided-approvals).
+
+**Example:** `createAutoApprove({ autoApprover: modelAutoApprover({ provider }), isAuto })`
+with a model that answers `"safe"` instead of the JSON verdict.
+
 ### LOUSHO_SESSION_FORBIDDEN
 
 **Means:** a `403` from a session route: the route's `authorizeSession`
@@ -1115,6 +1125,47 @@ file-based store), and create a new store after closing one.
 
 **Example:** two processes saving to the same `agent.db` while one runs a multi-second transaction.
 
+### LOUSHO_ARTIFACT_FORBIDDEN
+
+**Means:** a workspace artifact store's `get(uri, scope)` was asked for an artifact
+outside the caller's scope: another workspace, or another run whose uri did not come
+back to this run as a ref. A page cannot read another page's artifacts.
+
+**Fix:** read only the run's own artifacts, or pass the artifact's uri to this run in
+`scope.refs` (through the main agent).
+
+**Example:** the run `run-b` asking for `artifact://marketing/run-a/post.md`.
+
+### LOUSHO_ARTIFACT_TOO_LARGE
+
+**Means:** an artifact was larger than the store's `maxArtifactBytes` (200 MiB by
+default). Nothing was stored.
+
+**Fix:** write a smaller artifact, or raise `maxArtifactBytes` on the store.
+
+**Example:** `fileArtifactStore(root, { maxArtifactBytes: 1024 })` given a 2 KB file.
+
+### LOUSHO_ARTIFACT_EXISTS
+
+**Means:** an artifact name was stored again in the same run with other content or
+another media type. A stored artifact never changes; the same content again is
+accepted and returns the stored ref.
+
+**Fix:** store the new content under a new name.
+
+**Example:** `put(scope, 'post.md', 'v2', 'text/markdown')` after `'v1'` was stored as `post.md`.
+
+### LOUSHO_ARTIFACT_UNSAFE_PATH
+
+**Means:** `fileArtifactStore` found a symlink, or something other than a plain folder
+or file, where it reads or writes under its root (a workspace, `runs`, run,
+`artifacts` or `artifact-meta` folder, or an artifact file). Nothing was read or written
+through it.
+
+**Fix:** remove the entry the message names from the store's folder.
+
+**Example:** `<root>/marketing/runs` replaced by a symlink to another folder.
+
 ### LOUSHO_TRIGGER_INVALID
 
 **Means:** a trigger adapter got invalid options: a cron adapter without exactly
@@ -1202,7 +1253,7 @@ dataset and add examples to it (`POST /api/v1/datasets`, `POST
 **Means:** a record/replay cassette is missing, is not valid JSON or does not
 match the recorded request. The message names the file. A mismatch inside a
 run reaches `send()` as the `CassetteMismatchError` itself (from
-`lousho/testing`, with `.cassette` and `.callNumber`) - it is
+`@linuxdevil/lousho/testing`, with `.cassette` and `.callNumber`) - it is
 a test-fixture failure, so it is never compacted into a
 `CompactedLLMProviderError`.
 
@@ -1289,11 +1340,223 @@ See [Budgets](/configuration#budgets).
 
 **Example:** `createAgent({ provider, guardrails: { input: [maxLengthGuardrail({ maxChars: 10 })], onTripped: 'throw' } })` sent a longer message.
 
+## Workspaces
+
+### LOUSHO_WORKSPACE_STALE_REVISION
+
+**Means:** a write to a workspace source named an `expectedRevision` that is no
+longer the current revision: someone else wrote first, or the folder was edited
+by hand. Nothing was written. The error is a `StaleRevisionError` with
+`expectedRevision` and `currentRevision`.
+
+**Fix:** read the workspace again at the current revision, apply your change to
+it, and write with that revision as `expectedRevision`.
+
+**Example:** two editors open revision `a1…` and both save; the second save is
+refused.
+
+### LOUSHO_WORKSPACE_NO_CHANGE
+
+**Means:** a write to a workspace source would leave every file as it is, so
+the tree would keep its current revision id. No revision is recorded. The error
+is a `NoChangeError` with the current `revision`.
+
+**Fix:** drop the write, or change at least one file. A rollback that restores
+older content is a real change and is written as a new revision.
+
+**Example:** saving a page's harness prose without editing it.
+
+### LOUSHO_WORKSPACE_PATH_INVALID
+
+**Means:** a workspace source was given a path that is not a plain relative
+path inside the workspace (an absolute path, a backslash, an empty, `.` or `..`
+segment, or a path under `.lousho/`, `.git/` or `node_modules/`), or the folder
+source found a symlink that resolves outside the folder or to a folder, or the
+folder itself does not exist.
+
+**Fix:** use forward-slash paths relative to the workspace root, and replace
+symlinks that leave the workspace with the files themselves.
+
+**Example:** `source.read('../secrets.env')`, or `pages/x` symlinked to
+`/etc`.
+
+### LOUSHO_WORKSPACE_REVISION_UNKNOWN
+
+**Means:** a read or list named a revision the source has never recorded, or an
+old revision whose snapshot the folder source has pruned (it keeps the last
+`keep` revisions, 50 by default).
+
+**Fix:** pick a revision from `source.history()`, or raise `keep` on
+`folderSource()` to keep older snapshots readable.
+
+**Example:** `source.read('workspace.json', { revision: 'f…f' })`.
+
+### LOUSHO_WORKSPACE_SOURCE_CORRUPT
+
+**Means:** the folder source found `.lousho/revisions/index.json` or the
+write journal `pending.json` in a shape it did not write, or it could not
+finish an interrupted write. A journal it could not finish is renamed to
+`pending.failed-<time>.json`, the files it named are put back as they were
+before that write where the snapshot allows, and only the call that found it
+fails; later calls work.
+
+**Fix:** look at the file the message names. Check the workspace, then delete
+the set-aside journal. A damaged index is not set aside: fix or delete
+`<workspace folder>/.lousho/revisions/index.json` by hand (deleting it empties
+`history()`; the files and snapshots stay as they are).
+
+**Example:** a journal cut short by a full disk.
+
+### LOUSHO_WORKSPACE_SOURCE_LIMIT
+
+**Means:** the folder source refused to read a file larger than
+`maxFileBytes` (1 MiB by default), a folder with more than `maxFiles` files
+(5000), or a tree or snapshot larger than `maxTreeBytes` (32 MiB).
+
+**Fix:** move large or generated files out of the workspace folder, or raise
+the limit the message names on `folderSource()`.
+
+**Example:** a 20 MB video left in `pages/launch/`.
+
+### LOUSHO_WORKSPACE_CONTENT_UNSUPPORTED
+
+**Means:** a database workspace source (`sqliteWorkspaceSource()`,
+`postgresWorkspaceSource()`) refused a write or seed file whose content has a
+NUL character (`\u0000`). SQLite would cut the text at it and Postgres rejects
+it, so the stored tree would not match its revision id. Nothing is written.
+
+**Fix:** remove the NUL characters from the file the message names; a
+database workspace source stores text only.
+
+**Example:** `source.write({ 'notes.md': 'a\u0000b' }, …)`.
+
+### LOUSHO_WORKSPACE_INVALID
+
+**Means:** `loadWorkspace()` read a workspace from its source and
+`validateWorkspace` found at least one error. The error is a
+`WorkspaceValidationError`; `problems` lists every error with its `PRDnnn`
+code, file and field path. Nothing is returned, so a broken workspace never
+runs.
+
+**Fix:** fix the files the problems name, then load again. Warnings and notes
+do not throw; they come back in `problems` of the loaded workspace.
+
+**Example:** `workspace.json` lists a page whose `pages/<id>/` folder is
+missing.
+
+### LOUSHO_WORKSPACE_AGENT_UNRESOLVED
+
+**Means:** `resolveAttachments()` could not find an agent a page attaches. A
+`workspace:` or `local:` ref names a folder the loaded workspace does not
+have, a `global:` ref was given no `globalRegistry`, or the registry has no
+version in the ref's range. The page id may also be missing from
+`workspace.json`.
+
+**Fix:** check the ref in the page's `agents.json`. Add the agent folder, or
+pass a `globalRegistry` (`projectAgentRegistry(root)` or
+`sourceAgentRegistry(source)`) that holds a version in range.
+
+**Example:** `global:fact-checker@^2` when the registry only has `1.0.0`.
+
+### LOUSHO_WORKSPACE_MAIN_HARNESS_TEXT_MISSING
+
+**Means:** `assembleMainInstructions()` was given a `main-harness.json` that
+lists an instruction file, but the `texts` map has no entry for it, under
+either `main-agent/harness/<file>` or the bare file name. The prompt would
+silently lose that section, so the call throws.
+
+**Fix:** pass the text of every listed file, or remove the name from
+`instructions` in `main-harness.json`.
+
+**Example:** `instructions: ['routing.md']` with `texts: {}`.
+
+### LOUSHO_WORKSPACE_CAPABILITY_MISSING
+
+**Means:** `pagePolicy()` stopped a page at start (`capability-missing`): the
+harness's `capabilities.require` names a capability that no tool in the page's
+effective toolsets provides. A tool counts only when an attached agent has it,
+the host registry supplies it, the workspace policy and host ceiling allow
+it, and no ceiling or workspace rule denies it outright. A capability never
+grants a tool.
+
+**Fix:** give an attached agent a host tool that declares the capability and
+that the policy allows, or remove the capability from `capabilities.require`.
+
+**Example:** the harness requires `image.generate`, and the only tool that
+provides it is not in `shared/policies/policy.json` `tools.allow`.
+
+### LOUSHO_WORKSPACE_ENGINE_UNKNOWN
+
+**Means:** `runPage()` or `engineFor()` found no engine for the page's
+`execution.type` (`engine-unknown`). The runtime ships the `single` engine;
+each other execution type runs once its engine is in the registry.
+
+**Fix:** set `execution.type` in `page.json` to a type the runtime has an
+engine for, or pass an `engines` registry that has one.
+
+**Example:** a page with `execution.type: 'workflow'` on a runtime whose
+registry has only `single`.
+
+### LOUSHO_WORKSPACE_PAGE_UNKNOWN
+
+**Means:** `runPage()` was given a `pageId` that the loaded workspace does
+not list in `workspace.json` `pages`, or that has no `pages/<id>/page.json`
+(`page-unknown`).
+
+**Fix:** pass one of the workspace's page ids; the message lists them.
+
+**Example:** `runPage(workspace, { pageId: 'nope', task: '' }, ctx)` on a
+workspace whose pages are `fix` and `review`.
+
+### LOUSHO_WORKSPACE_NO_MAIN_AGENT
+
+**Means:** `WorkspaceSession.run()` got a message without a `pageId` on a
+workspace whose `workspace.json` sets `mainAgent` to `null` (`no-main-agent`).
+Without a main agent there is no router, so nothing can pick the page. The
+session returns a `WorkspaceRunError` with this code instead of throwing.
+
+**Fix:** pass `{ pageId }` to `run()`, or call `runPage()` directly; or give the
+workspace a main agent in `main-agent/`.
+
+**Example:** `session.run('Summarise today')` on the `ops-desk` workspace.
+
+### LOUSHO_WORKSPACE_HOST_INVALID
+
+**Means:** `createWorkspaceRuntime(source, host)` got a host that misses a
+dependency (the message names the field, such as `host.stores.threads`), or a
+`limits.maxConcurrentRuns` that is not a positive integer. At run time it also
+means a tool's scope grants secrets, limits it to network hosts or requires a
+sandbox, and the host gave no `bindTool` to enforce that.
+
+**Fix:** pass the named field; pass `bindTool` whenever the policy grants a
+tool secrets or hosts, or sets `sandbox.required`.
+
+**Example:** a host built without `stores.threads`.
+
+### LOUSHO_WORKSPACE_RUNTIME_CLOSED
+
+**Means:** `run()`, `runPage()` or `explain()` was called on a workspace
+runtime after its `close()`.
+
+**Fix:** create a new runtime with `createWorkspaceRuntime()`.
+
+**Example:** a request handled while the service shuts down.
+
+### LOUSHO_WORKSPACE_RUN_ACTIVE
+
+**Means:** `run()` or `runPage()` got a `runId` that a run of the same
+runtime is still using. The runtime refuses it, so `cancel()` and `close()`
+keep reaching the run that holds the id.
+
+**Fix:** pass a new run id, or leave `runId` out so the runtime makes one.
+
+**Example:** two requests that both pass `runId: 'job-1'` while the first runs.
+
 ## Auth
 
 ### LOUSHO_AUTH_CONFIG_INVALID
 
-**Means:** a route auth helper from `lousho/auth` (`jwt()`,
+**Means:** a route auth helper from `@linuxdevil/lousho/auth` (`jwt()`,
 `oidc()`, `basic()`, `apiToken()`) got options it cannot verify with, and
 refused them when it was created, not at the first request. The message names
 the option: no key source or two of them, an HMAC `secret` shorter than 32
diff --git a/evals.mdx b/evals.mdx
index 97d55b9..2e1d33e 100644
--- a/evals.mdx
+++ b/evals.mdx
@@ -17,7 +17,7 @@ prints a summary and writes JUnit and JSON reports.
 
 ```bash
 npm install --save-dev vitest
-npx lousho eval
+npx @linuxdevil/lousho eval
 ```
 
 ## Writing a trajectory eval
@@ -31,8 +31,8 @@ for the [judge evals](#judge-evals) below.
 ```ts
 // refund.eval.ts
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool, includes } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool, includes } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -114,7 +114,7 @@ it. Pass `{ subagent: 'researcher' }` to look at one sub-agent (and the
 sub-agents under it) only:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You research.', description: 'Finds sources' });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', subagents: { researcher } });
@@ -144,7 +144,7 @@ case `n` times; the case passes when all `n` runs pass, or when at least
 `passAt: k` of them do:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You handle refunds.' });
 
@@ -170,8 +170,8 @@ any object; its `label` (or `name`, or its `input`) names it.
 
 ```ts
 import { z } from 'zod';
-import { createAgent, defineEval, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const lookupOrder = defineTool({
   name: 'lookup_order',
@@ -223,7 +223,7 @@ curl -X POST "$LOUSHO_OBSERVE/api/v1/datasets/refunds/examples" -H 'content-type
 ```
 
 ```ts
-import { createAgent, defineEval, includes } from 'lousho';
+import { createAgent, defineEval, includes } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'refunds',
@@ -261,8 +261,8 @@ it.
 
 ```ts
 // tone.judge.eval.ts: run with `lousho eval --judge`
-import { createAgent, defineEval, atLeast } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineEval, atLeast } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 defineEval({
   name: 'tone',
@@ -341,7 +341,7 @@ model. `--timeout ms` sets the limit for every case (`0` turns it off). With
 One eval can set its own limit, which wins over both:
 
 ```ts
-import { createAgent, defineEval } from 'lousho';
+import { createAgent, defineEval } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'research report',
@@ -382,7 +382,7 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - run: npm ci
-      - run: npx lousho eval --junit reports/evals.xml --json reports/evals.json
+      - run: npx @linuxdevil/lousho eval --junit reports/evals.xml --json reports/evals.json
       - uses: actions/upload-artifact@v4
         if: always()
         with:
@@ -423,9 +423,9 @@ between: it records each case once against the real provider through
 Your eval files do not change.
 
 ```bash
-npx lousho eval --record        # real provider: writes the cassettes, commit them
-npx lousho eval --replay        # every case from its cassette, no network, no key
-npx lousho eval --drift         # re-record and diff each case's trajectory
+npx @linuxdevil/lousho eval --record        # real provider: writes the cassettes, commit them
+npx @linuxdevil/lousho eval --replay        # every case from its cassette, no network, no key
+npx @linuxdevil/lousho eval --drift         # re-record and diff each case's trajectory
 ```
 
 - **`--record`** runs every case with its agent's real provider and writes one
@@ -478,7 +478,7 @@ a real judge only in `*.judge.eval.ts` files.
 How it works: the run loop sends every model call (`generate` or `stream`, from
 a plain run, a streamed run, a sub-agent or an approval resume) through one
 provider-interception seam, `setProviderInterceptor()` (exported from
-`lousho/testing`; `src/providers/interception.ts` in the
+`@linuxdevil/lousho/testing`; `src/providers/interception.ts` in the
 source). Nothing is installed by default, so the seam is
 free. While a case runs under one of these modes, `lousho eval` answers it with
 the provider wrapped by `recordReplay()` for that case's cassette. You can use
@@ -496,7 +496,7 @@ The same eval file that gates CI in-process can smoke-test a deployed agent (the
 URL and every case runs against the deployment instead of the in-process agent:
 
 ```bash
-npx lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
+npx @linuxdevil/lousho eval --url https://agent.example.com --token "$DEPLOY_TOKEN"   # or LOUSHO_EVAL_TOKEN
 ```
 
 Each case gets its own remote session (`POST /chat { sessionId, input }`, one
@@ -522,7 +522,7 @@ and tools the behaviour you want to check.
 In code, pass a `target` (this overrides `agent`; `--url` overrides both):
 
 ```ts
-import { defineEval, remoteTarget } from 'lousho';
+import { defineEval, remoteTarget } from '@linuxdevil/lousho';
 
 defineEval({
   name: 'deployed refund flow',
diff --git a/executor-api.mdx b/executor-api.mdx
index a4c3ebe..5ed748f 100644
--- a/executor-api.mdx
+++ b/executor-api.mdx
@@ -19,8 +19,8 @@ take: `temperature` and `maxTokens` (`exporter`, `captureContent` and
 import {
   AgentBuilder,
   AgentExecutor,
-} from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+} from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create()
   .setName('Customer Support Agent')
diff --git a/flows.mdx b/flows.mdx
index 064ee5c..1fcfd7b 100644
--- a/flows.mdx
+++ b/flows.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Flows"
 ---
-{/* Generated from docs/flows.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/flows.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 A flow is a fixed, multi-step workflow run by one agent: the steps and their
 order are written down up front instead of being left to the model's judgment.
@@ -9,8 +9,8 @@ Describe the graph with `FlowBuilder` and run it with the static
 `FlowExecutor.execute(flow, context, onEvent?)`.
 
 ```ts
-import { FlowBuilder, FlowExecutor, type EditorStep } from 'lousho/flows';
-import { resolveProvider, type AgentConfig } from 'lousho';
+import { FlowBuilder, FlowExecutor, type EditorStep } from '@linuxdevil/lousho/flows';
+import { resolveProvider, type AgentConfig } from '@linuxdevil/lousho';
 
 // A flow calls an LLMProvider directly (reads OPENAI_API_KEY).
 const provider = resolveProvider('openai/gpt-4o-mini');
@@ -112,7 +112,7 @@ its tool runs:
   never run unapproved.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -137,7 +137,7 @@ set stays as before: `'{{missing}}'` is `''`, and `'$USD'` (no variable
 named `USD`) is the literal string `'$USD'`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 // With variables { count: 5, tags: ['a', 'b'] }, the tool gets { count: 5, tags: ['a', 'b'], note: 'count: 5' }.
 const step: EditorStep = {
@@ -159,7 +159,7 @@ once it is aborted, no further step starts and the flow fails with the signal's
 to the model request, and a `toolCall` hands it to the tool as `ctx.abortSignal`.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -217,7 +217,7 @@ Invalid values (`maxAttempts` < 1 or not an integer, a negative `backoffMs`,
 a `timeoutMs` &lt;= 0) fail the step with `LOUSHO_FLOW_INVALID`.
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const fetchInvoice: EditorStep = {
   type: 'toolCall',
@@ -251,8 +251,8 @@ from the saved variables. `result.usage` and `result.steps` include the
 earlier attempts.
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -321,8 +321,8 @@ are cancelled. Steps they completed are kept, and the rest run again on resume.
 To continue, pass the decision to `resume()`:
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { memoryStore } from 'lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { memoryStore } from '@linuxdevil/lousho';
 
 declare const flow: AgentFlow;
 const checkpointStore = memoryStore().checkpoints;
@@ -369,7 +369,7 @@ asked, and the context's `approve` callback decides, exactly as for a
 node's `id`, or its place in the flow).
 
 ```ts
-import type { EditorStep } from 'lousho/flows';
+import type { EditorStep } from '@linuxdevil/lousho/flows';
 
 const steps: EditorStep = {
   type: 'sequence',
@@ -390,7 +390,7 @@ const steps: EditorStep = {
   the decision:
 
 ```ts
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 declare const flow: AgentFlow;
 
@@ -414,8 +414,8 @@ An `agent` step calls a `createAgent()` agent registered in the context's
 guardrails and approvals — and the step stores its reply text:
 
 ```ts
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
 
 const writer = createAgent({ name: 'writer', model: 'openai/gpt-4o-mini', instructions: 'Draft a reply.' });
 
@@ -460,9 +460,9 @@ typed value rather than text:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { FlowExecutor, type AgentFlow } from 'lousho/flows';
-import { ToolRegistry } from 'lousho/tools';
+import { createAgent } from '@linuxdevil/lousho';
+import { FlowExecutor, type AgentFlow } from '@linuxdevil/lousho/flows';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
 
 const researcher = createAgent({ name: 'researcher', model: 'openai/gpt-4o-mini', instructions: 'Answer with three facts.' });
 
diff --git a/forge-author.mdx b/forge-author.mdx
new file mode 100644
index 0000000..7d24cde
--- /dev/null
+++ b/forge-author.mdx
@@ -0,0 +1,161 @@
+---
+title: "The Agent Author"
+---
+{/* Generated from docs/forge-author.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+
+The Agent Author is a chat panel in [Agent Forge](/agent-forge) that
+drafts agents and changes to them. Describe what you want in plain words;
+it reads your workspace's agents, specs and catalogs, and answers with
+**proposals** — cards that show exactly what would change. Nothing is
+written until you apply a card, and even then a new agent is saved switched
+off until you enable it.
+
+This page covers opening the Author, how proposals and the save gate
+work, the tools it can call, secrets, the draft review, its settings, and
+the eval that measures it.
+
+## Open the Author
+
+- **Ctrl/Cmd+J** toggles the panel, from anywhere — even while typing in a
+  field. The nav rail's **Agent Author** button and the command palette's
+  **Open Agent Author** do the same.
+- **Describe with AI** on the agents list, **Describe it to the Agent
+  Author** on an agent's empty canvas, and **Change with AI** on an
+  agent's header all open it with the right focus already set.
+- A **focus chip** above the composer shows what the Author is working on:
+  **New agent**, or **Editing: \&lt;agent id\>** for the agent you are
+  viewing. Its clear button ("Start a new agent instead") drops the edit
+  focus.
+- A new chat starts on "What should we build?" with a few suggestion
+  buttons; **New chat** and **Chat history** sit in the panel header.
+
+The Author runs on a model, so it needs a provider key like any other
+feature: with none configured the panel shows "Add an API key to use the
+Agent Author" with a link to Settings (see [Settings](#settings)).
+
+## Proposals, not writes
+
+Every change the Author wants to make comes back as a proposal card in
+the chat — the model's own tools cannot write an agent directly.
+
+- A **new agent** card is headed "New agent" with the proposed name and
+  its enabled state; an **update** card is headed "Change" and lists
+  "What changes · n fields" — a field-by-field diff of the spec (added,
+  removed and edited fields, with the instructions as a line diff).
+  **Show full configuration** expands the whole proposed spec.
+- **Nothing is written until you apply.** The card's **Save agent** (new)
+  or **Apply changes** (update) button is the only way a proposal becomes
+  an agent; **Saving…** shows while the write is in flight. The Author
+  can also save in a later turn once you have confirmed — the same gate
+  applies.
+- While an update proposal is open, the canvas shows the proposed graph
+  read-only: proposed additions, changes and removals draw as dashed
+  nodes, a banner counts them ("Showing a proposed change: a added, e
+  changed, r removed."), and a toolbar pill ("Proposed change · review in
+  the Author") jumps back to the card, and the banner's **Hide** button
+  dismisses the overlay so you can edit the real graph again.
+- A card can fold in your earlier unsaved proposals for the same agent;
+  it says so ("Your earlier change was never saved, so it is included
+  here…") and applying saves everything shown.
+- Cards list **requirements** — missing provider keys, secrets, MCP
+  servers or tools — each with a fix button (**Add secret**, **Open
+  Settings**, **Check**). They never block a save; a new agent just stays
+  off until they are met.
+
+If a save is refused, the card says why in plain words — for example
+"A newer proposal replaced this one, and only the newest proposal can be
+saved." or "This agent changed after the proposal was made." The full set
+of refusals is enforced in code: an unknown, stale, discarded, already
+saved or wrong-agent proposal, a proposal from the current unanswered
+turn, or one that no longer passes the spec schema.
+
+After a save the canvas reloads with the new version ("Canvas updated
+with the Author's change."); if you have unsaved edits of your own it
+warns first and offers **Reload**.
+
+## What it can do
+
+The Author's tools fall into three groups: reads of your workspace and
+catalogs, proposals and gated writes, and a few client-side actions. It
+cannot run or edit anything else.
+
+| Tool | What it does |
+| --- | --- |
+| `getCurrentSpec` | Read an agent's saved spec, enabled state and latest version. |
+| `listAgents` | List the workspace's agents with name, description and enabled state. |
+| `listModels` | The model catalog with capabilities and which providers have a key. |
+| `listTools` | The built-in tools an agent can call. |
+| `listGuardrails` | The guardrail types and their option schemas. |
+| `listTriggerTypes` | The trigger types and the fields each takes. |
+| `listSkills` | The skills available to attach. |
+| `listKits` | The kits (bundled agent parts) available. |
+| `listTemplates` | The agent templates that can seed a new agent. |
+| `listMcpServers` | MCP servers configured in any agent plus registry entries — secret fields reduced to key names. |
+| `probeMcpServer` | Connect to an MCP server spec and list the tools it exposes. |
+| `searchDocs` | Search the bundled SDK docs and return matching excerpts. |
+| `getTrace` | Read a run's trace as condensed steps with cost. |
+| `runDraft` | Run the agent's saved working copy once (60-second cap) and report the result — it cannot run an unsaved proposal. |
+| `openPage` | Navigate the Studio to one of its screens. |
+| `proposeAgent` | Return a proposal card for a new agent. Writes nothing. |
+| `proposeAgentUpdate` | Return a proposal card patching an existing agent. Writes nothing. |
+| `saveAgent` / `saveAgentUpdate` | Save the newest confirmed proposal — gated: refused unless you have seen and confirmed the card. |
+| `discardPendingChanges` | Drop unsaved proposal cards; never touches saved agents. |
+| `setAgentEnabled` | Switch an agent on or off — only when you explicitly asked for it in the same message. |
+| `requestSecret` | Ask you for a secret value in a card (see [Secrets](#secrets)). |
+
+## Secrets
+
+When a draft needs a key — an MCP server's token, a provider key — the
+Author calls `requestSecret`, and a card appears in the chat: "Enter
+\&lt;name\>", a password field, **Save secret** and **Skip**. The value goes
+straight to Studio's secrets store on this machine; it never lands in the
+chat transcript, the stream or browser storage, and the Author itself
+never sees it — the tool only learns that the name is set. Provider key
+names that belong in Settings (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and
+the like) are refused here and pointed at Settings instead. Skipping is
+fine: the proposal still saves, and the requirement row stays until the
+secret exists.
+
+## Review before you see a card
+
+Before a proposal card reaches you, a second, smaller model gives the
+draft a once-over — five yes/no questions:
+
+1. **runs** — can this agent run as configured (catalog ids valid, MCP
+   servers reachable, no literal secrets)?
+2. **fulfillsIntent** — does the draft do what you asked?
+3. **toolsComplete** — does every step in the instructions have a way to
+   happen?
+4. **guardrailsFit** — do the guardrails and approvals fit the risk?
+5. **triggersFit** — do the triggers match when you want the agent to run?
+
+A "no" sends the draft back to the Author to fix, for at most three
+rounds; after that the card is shown anyway. The check fails open — an
+unavailable review model, a timeout or a missing verdict all pass — and
+you never see it: it is not mentioned in the chat.
+
+## Settings
+
+`#/settings` has an **Agent Author** card: the **Author model** (default
+`anthropic/claude-sonnet-5-5`) that writes proposals, the **Review model**
+(default `anthropic/claude-haiku-5-5`) that checks each draft, and a
+**Review drafts** switch to turn the check off. The card's pill shows
+**Ready** or **Needs a key** (with **Add key** jumping to Provider keys);
+models without a configured key are listed but disabled.
+
+## Evaluating the Author
+
+The Author ships with a scenario eval in the SDK repo:
+`npm run eval:author -w apps/agent-forge` runs the scripted scenarios in
+`apps/agent-forge/evals/author/scenarios/` through the real server path —
+hard checks (including safety checks such as ignoring pasted
+credentials) plus a rubric judged by the review model. Useful flags:
+`--mock` for a scripted pass with no rubric, `--only <names>` for a
+subset, `--no-review` to skip the draft review, and `--update-baseline`
+to record the run's pass rate as the new baseline.
+
+Results land in `evals/author/results/<date>.json` (not committed). A run
+fails when its pass rate drops more than 5 points below
+`evals/author/baseline.json`, when any scenario errors, or when a safety
+check fails; a missing baseline passes until you write one with
+`--update-baseline`.
diff --git a/forge-builder.mdx b/forge-builder.mdx
new file mode 100644
index 0000000..febd626
--- /dev/null
+++ b/forge-builder.mdx
@@ -0,0 +1,170 @@
+---
+title: "The visual builder"
+---
+{/* Generated from docs/forge-builder.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+
+The builder is the canvas at the heart of
+[Agent Forge](/agent-forge): you assemble an agent's graph by dragging
+nodes onto a canvas, edit their fields in the Inspector or the Configure
+tab, and run the agent in place to watch what it does. Everything it edits
+is the same [Agent spec v2](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/agent-spec.md) document the rest of the SDK
+reads, stored as YAML under `.lousho/agents/`.
+
+This page covers what the builder edits, the canvas and its node kinds,
+the Inspector and Configure tab, testing a run without leaving the screen,
+the Code tab, and the keyboard shortcuts. For launching Studio and the
+other screens see [Agent Forge](/agent-forge).
+
+## What the builder edits
+
+An agent's spec lives in `.lousho/agents/<id>.yaml`. Three surfaces edit
+that one document and nothing else:
+
+- **The canvas** — nodes and edges are a view of the spec's sections
+  (tools, triggers, guardrails, flow steps and so on).
+- **The Configure tab** (`#/agents/<id>/configure`) — the same spec as a
+  stack of schema-driven forms.
+- **The Code tab's YAML view** (`#/agents/<id>/code`) — the spec itself,
+  read-only.
+
+Canvas-only state — node positions, which groups are collapsed, sticky
+notes and the last viewport — lives in a separate
+`.lousho/agents/<id>/layout.json`, so rearranging the canvas never changes
+what the agent does. Edits autosave to the working copy; **Save** (or
+Ctrl/Cmd+S) additionally writes an entry in the agent's version history —
+the **Versions** tab lists them.
+
+## The canvas
+
+The graph is agent-centred: an agent node sits at the centre and the
+things it uses — tools, skills, memory, guardrails — attach to it. When
+the spec has a `flow`, its steps form a separate chain. An agent with
+subagents shows each one as a collapsible group containing that
+subagent's own capability nodes.
+
+The left rail's **Nodes** tab is the palette, grouped **Start**, **Agents**,
+**Capabilities**, **Safety**, **Output**, **Flow** and **Canvas**. Drag an
+entry onto the canvas, or click it (or press Enter on it) to add it at the
+centre of the view; `/` jumps to the palette's search. Edges are derived
+from the spec — they show what uses what and are not stored separately.
+
+| Node kind | What it sets in the spec |
+| --- | --- |
+| Trigger | One `triggers[]` entry — chat, a cron schedule, a webhook, a channel (Slack, Telegram, GitHub and more) or another agent finishing. |
+| Agent | The agent itself: name, description, model, instructions and the root fields. An inline subagent appears as an agent node inside its group's canvas. |
+| Subagent | One `subagents` entry that delegates to another agent in the workspace or to a remote URL. |
+| Handoff | One `handoffs[]` entry — passes the conversation to another agent, optionally filtered. |
+| Tool | One `tools[]` entry — a built-in, registry, file, integration, OpenAPI or hosted tool. |
+| MCP server | One `mcpServers` entry — a stdio or HTTP MCP server whose tools the agent can call. |
+| Skill | One `skills[]` entry — instructions loaded on demand from a directory, the registry or inline. |
+| Memory | One `memory[]` entry — what the agent remembers across turns, and its scope. |
+| Guardrail | One `guardrails[]` entry — checks input or output and can block, warn or rewrite. |
+| Permission rule | One `permissions[]` entry — allows, denies, asks or auto-approves tool calls matching a pattern. |
+| Hook | One `hooks[]` entry — sandboxed code run before or after a tool call or a model call. |
+| Output schema | The agent's `output` — a JSON Schema for a structured result. |
+| Abort listener | One `abortListeners[]` entry — cancels runs when a trigger fires. |
+| Flow step | One step of `flow` — sequence, router, loop, evaluate, model call, agent step, approval, tool call, set variable or end. |
+| Note | Nothing — a sticky comment stored in `layout.json`, never in the spec. |
+
+The toolbar has **Undo**/**Redo**, **Duplicate**, **Auto layout** (an
+elkjs pass that repositions the whole graph) and **Fit view**; the
+React Flow controls at the bottom-left zoom and fit, and the minimap at
+the bottom-right shows the whole graph. `Backspace`/`Delete` removes the
+selected nodes; Ctrl/Cmd+D duplicates them.
+
+## Inspector and Configure tab
+
+Click a node and the Inspector on the right opens with its kind, a
+**Settings** section of schema-driven fields (the same fields the node's
+kind defines — a tool node's picker and options, a trigger's type and
+schema fields, and so on), and a **Debug** section for breakpoints while
+debug mode is on. A **Problems (n)** section lists everything
+`validateGraph` flags for that node; clicking a problem scrolls to and
+focuses the offending field. The **View spans** button (enabled once the
+node has run) opens the node's spans sheet — see
+[Testing in place](#testing-in-place).
+
+Node cards carry small badges: a problem count when validation flags the
+node, a pin badge on a tool node whose result is pinned for replay, and an
+"edited" chip while an [Author proposal](/forge-author) is overlaid on
+the canvas.
+
+The **Configure** tab is the spec as a form: eight stacked cards —
+Identity, Model, Instructions, Tools, Knowledge, Safety, Triggers, and
+Output and limits — generated from the spec's JSON schema, with a sticky
+index that marks changed sections and counts issues. A dirty bar at the
+bottom shows how many sections changed with **Discard** and **Save**;
+**Save** is disabled while the spec has errors. The
+`version`, `flow` and `evals` sections are not editable here — flow lives
+on the canvas, versions and evals on their own tabs.
+
+The drawer's **Problems** tab lists every graph problem in one table —
+severity, node, message and field — errors first; opening a row selects
+the node on the canvas.
+
+## Testing in place
+
+The bottom drawer's **Test** tab runs the agent without leaving the
+builder. Its run bar shows the run status pill, the provider and model,
+a ticking elapsed time, an **Open trace** link once the run reports to
+the observe daemon, and a rating control when the run finishes.
+
+While a run is going:
+
+- **Node status overlay** — each card shows its state in the current run:
+  a running ring, "awaiting approval" while the run waits on a person,
+  done, or failed. Edges leaving a running node animate. Clicking a
+  node's status pill opens its spans sheet.
+- **Steering** — the box above the composer ("Message the running agent")
+  queues a message onto the live run; each message shows whether it was
+  **Queued**, **Delivered** or **Undelivered** when the run ended first.
+- **Stop** — aborts the run (the button reads "Stopping…" in flight).
+- **Inline approvals and questions** — a tool call that needs approval
+  shows an approval card ("Approve &lt;tool>?" with its arguments) with a
+  "Decide within &lt;time>" deadline; a question from the agent shows its
+  options or a free-text answer with an "Answer within &lt;time>" deadline.
+  The first answer wins; an expired question resolves as unanswered.
+
+The **spans sheet** (from a node's status pill or its Inspector) lists the
+node's spans from the last run — model calls, tool calls, errors, cost —
+with an **Open trace** link. On a `tool` node it also offers replay
+controls: **Pin this result** records the tool's result so the next run
+replays it instead of calling the tool, **Run from here** re-runs the
+agent from its newest user message with the pinned results, and each
+recorded tool call has **Fork from here**, which opens the replay editor
+(forking needs a checkpointed run — see
+[Time travel](/agent-forge#time-travel)).
+
+## Code tab
+
+`#/agents/<id>/code` shows the spec three ways, generated on demand:
+
+- **TypeScript** — a readable `.ts` rendering of the agent
+  (`<id>.agent.ts` on download).
+- **YAML** — the spec document itself (`<id>.yaml` on download).
+- **Agent directory** — a file-tree preview of the agent's on-disk
+  directory.
+
+Every view has **Copy** and **Download** (Download is disabled on the
+directory view — copy files one at a time from the tree). The tab is
+read-only by design: "Generated from the spec. Read-only — edit on the
+canvas or in Configure."
+
+## Keyboard shortcuts
+
+| Keys | Does | Where |
+| --- | --- | --- |
+| `Ctrl/Cmd+K` | Open the command palette | Everywhere |
+| `Ctrl/Cmd+J` | Open or close the Agent Author | Everywhere, even while typing |
+| `?` | Show the keyboard shortcuts | Everywhere (not while typing) |
+| `Ctrl/Cmd+S` | Save a version of the agent | The builder |
+| `Ctrl/Cmd+Z` | Undo the last canvas edit | The canvas |
+| `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y` | Redo the last undone edit | The canvas |
+| `Ctrl/Cmd+D` | Duplicate the selected node(s) | The canvas |
+| `Backspace` / `Delete` | Delete the selected node(s) | The canvas |
+| `/` | Focus the palette's search | The canvas |
+| `j` / `k` / `Enter` | Next / previous / open the selected row | Tables and lists |
+| `Esc` | Close the palette, the shortcut sheet, a dialog or the narrow nav drawer | Everywhere |
+
+The `?` sheet lists most of these; Ctrl/Cmd+D, Ctrl/Cmd+Y,
+Backspace/Delete and `/` work on the canvas but are not on the sheet.
diff --git a/forge-lifecycle.mdx b/forge-lifecycle.mdx
new file mode 100644
index 0000000..784860b
--- /dev/null
+++ b/forge-lifecycle.mdx
@@ -0,0 +1,437 @@
+---
+title: "Versions, triggers and publishing"
+---
+{/* Generated from docs/forge-lifecycle.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+
+Agent Forge keeps an agent's spec as a working copy on disk and grows an
+append-only version history beside it. This page covers that lifecycle:
+when a version is written, drafts and suggestions, export and import,
+templates, the on/off switch and labels, the trigger kinds Studio runs,
+the inbox, model-decided approvals, ratings, the publish eval gate,
+serving and deploying a published version, and where everything is
+stored.
+
+The canvas, Inspector and Author have their own pages —
+[the visual builder](/forge-builder) and
+[the Agent Author](/forge-author). For the screens around the agent
+detail page see [Agent Forge](/agent-forge).
+
+## Working copy, versions and publish
+
+The working copy is `.lousho/agents/<id>.yaml` — the Agent spec v2
+document every Studio surface edits. Versions are snapshots of it (plus
+the agent's labels) under `.lousho/agents/<id>/versions/`, listed on the
+detail page's **Versions** tab.
+
+A version is written when:
+
+- You press **Save** (or Ctrl/Cmd+S). Edits autosave to the working copy
+  continuously, but autosave alone never writes a version.
+- The Agent Author applies a proposal, a pending draft is approved, or a
+  prompt suggestion is applied.
+- You restore an old version, import an agent, or create one from a
+  template or by copying.
+- You publish — publishing first captures the working copy as a
+  `publish` version when needed (see
+  [Publish and the eval gate](#publish-and-the-eval-gate)).
+- The working copy sits unchanged for 60 seconds after the last edit —
+  a background "idle" capture makes sure long editing sessions still
+  land in history.
+
+Two rules keep history honest:
+
+- **No-op saves write nothing.** A capture whose spec and labels match
+  the latest version is skipped, so pressing Save twice does not grow
+  the list. The Versions tab calls this out rather than showing a
+  duplicate.
+- **External edits become `baseline` versions.** If the YAML file changes
+  outside Studio (an editor, a script, git), the next Studio read notices
+  the file's hash no longer matches what Studio last wrote and captures
+  the file's content as a `baseline` version attributed to
+  `external_file_edit` — Studio adopts what is on disk instead of
+  silently overwriting it.
+
+Every version carries a one-line summary when the background summary pass
+has run (it is skipped for restores and baselines). Restoring a version
+writes a new `restore` version pointing at the old content — history is
+never rewritten — and **never changes the agent's On/Off state**: a
+restore of a version saved while the agent was on does not re-enable an
+agent you turned off.
+
+## Drafts and suggestions
+
+Studio never lets a background change touch the spec silently. Proposals
+from the Agent Author, imports and other sources land as **drafts**: one
+pending draft per agent, shown as a "Pending change" card with its
+origin, reason, a field-by-field change list, and **Approve**/**Reject**
+buttons. Approving writes the spec and a version; rejecting records the
+draft in history.
+
+Every draft gets an automatic review pass covering three things:
+
+- **Safety** — a verdict on whether the change looks risky.
+- **Routine vs gated fields** — edits to routine fields (instructions,
+  description, labels, skills) are skimmable; edits to gated fields
+  (model, tools' permissions, triggers, hooks, subagents and anything
+  unclassified) are always flagged "Needs your approval". The
+  classification fails closed: a spec field nobody classified is gated.
+- **Trigger reach** — whether the change alters who or what can start
+  the agent.
+
+The verdict is advisory: approving always takes your click, and a
+missing model key or a failed review leaves the draft pending and
+approvable rather than blocking it. If the agent's spec moves on while a
+draft waits, a drift banner appears — "The agent changed since this
+draft was made (v3 → v5)" — and approving still applies the draft on top
+of the current version.
+
+**Prompt suggestions** are the trace-driven half of the same idea: rate a
+run poorly or pick **Suggest a fix**, and a background pass reads the
+run's trace and proposes one anchored edit to the agent's instructions.
+The proposal is deliberately small — at most 15 changed lines, replacing
+an `oldText` segment that must occur exactly once in the instructions.
+Applying it is guarded twice: the instructions must still hash to the
+`expectedPromptHash` the suggestion was computed against, and the anchor
+must still be unique. If either check fails the suggestion is marked
+`conflict` instead of corrupting the prompt. Open suggestions appear in
+the Inbox and on the agent's **Suggestions** tab.
+
+## Export, import and portability
+
+`GET /agents/<id>/export` offers two formats:
+
+- **`yaml`** — the working-copy spec verbatim, under a Studio-export
+  header comment. This is the file to hand to `lousho build`, commit to a
+  repo, or diff.
+- **`bundle`** — a `lousho.agent-bundle` JSON document: the spec, the
+  agent's labels, its registered prompts, and the examples of any eval
+  datasets its gates reference, pulled from the observe daemon. Bundle
+  prompts the daemon cannot serve degrade to a warning, not a failure.
+
+**Secrets are never exported.** Specs carry secret *references* (a named
+secret or an env var), never values; the bundle and the YAML both keep
+them as references, so an export is safe to share — but the recipient
+must supply the referenced secrets themselves.
+
+`POST /agents/import` (with a preview step first) accepts pasted YAML, a
+JSON spec or a bundle — v1 specs are upgraded to v2 on the way in — and
+commits in one of three modes:
+
+- **`new`** and **`copy`** create a fresh agent, start it disabled, and
+  record a `create` version.
+- **`replace`** overwrites an existing agent's spec, keeps its On/Off and
+  publish state, and records an `update` version (skipped as a no-op when
+  nothing changed).
+
+Before sharing, the **portability check** pass scans the instructions for
+machine-specific details — repository names, email addresses, channels,
+paths, hosts, pasted secrets — and rewrites them with `[YOUR REPO]`,
+`[YOUR EMAIL]`, `[YOUR PATH]`-style placeholders you fill in per
+deployment. It needs a model key; without one you can still export, the
+check just does not run.
+
+## Templates
+
+The Templates screen (`#/templates`) starts a new agent from a shipped
+spec. Six templates ship with Studio:
+
+| Template | What it is for |
+| --- | --- |
+| `support-triage` | Routes incoming support requests to the right handler. |
+| `pr-reviewer` | Reviews pull requests against a checklist. |
+| `research-assistant` | Gathers and summarises sources on a topic. |
+| `inbox-triage` | Sorts and prioritises an inbox of items. |
+| `incident-responder` | Works an incident from alert to mitigation notes. |
+| `docs-qa` | Answers questions about a documentation set. |
+
+Creating from a template writes the spec, a `create` version attributed
+to `template`, and any tags the template carries become the agent's
+labels (subject to the label rules below).
+
+## On, off and labels
+
+Every agent has an **Enabled** switch on its detail header — the UI calls
+it On/Off ("On. Triggers can start it." / "Turned off. Triggers won't
+start it."). Only *Studio-run* triggers respect it: webhook, cron,
+channel and agent-chain dispatch all skip or refuse a disabled agent,
+while chat, the test pane and manual runs are unaffected — you can always
+talk to an agent that is off.
+
+Turning an agent off also drops its queued trigger runs; a run already in
+flight finishes. Turning it back on resumes normal dispatch.
+
+A safety net backs the switch: **five consecutive failed triggered runs
+auto-disable the agent** (`disabledReason: 'auto_failure_streak'`), raise
+an `auto_disabled` inbox alert, and show an "Auto-off" note explaining
+what happened. A triggered run that finishes `done` resets the streak; a
+cancelled or manually-run failure does not count.
+
+**Labels** are the Agents list's filter facets. Rules, enforced on every
+write (PATCH meta, draft approve, template create): at most **20 labels**,
+each at most **32 characters**, trimmed, lowercased, inner whitespace
+collapsed and deduplicated. A label that breaks the rules is a 400, not a
+silent drop.
+
+## Triggers in Studio
+
+A spec's `triggers[]` list can hold chat (at most one per agent), cron,
+webhook, channel and agent entries. Studio mounts and runs all of them
+while it is up; the canvas dims non-chat trigger nodes when the agent is
+off.
+
+**Webhook** triggers answer `POST /hooks/<agentId>/<path>` where `path`
+is the trigger's configured path. With no `secret` configured the route
+only accepts loopback calls; with a secret it requires an HMAC signature
+— header `x-signature-256: sha256=<hex>` over the raw request body,
+checked with a constant-time compare. A bad signature is a 401, an
+unknown path a 404, and a successful dispatch answers 202.
+
+**Channel** triggers mount the SDK's channel handlers at
+`POST /hooks/<agentId>/channel/<kind>` (plus
+`…/channel/<kind>/approvals/<id>` for approval callbacks). Each platform
+verifies its own way — Slack's `x-slack-signature`, Telegram's
+`x-telegram-bot-api-secret-token`, GitHub's `x-hub-signature-256`, a
+Teams JWT, Discord's Ed25519 pair — and every failure answers a uniform
+401. An agent can mount at most one trigger per channel kind; a second is
+a mount error surfaced on the Overview card. Channel bodies are capped at
+1 MB.
+
+**Cron** triggers fire on a schedule with a fixed prompt; per-trigger
+fire cursors live in the agent's `triggers/state.json` so a restart does
+not re-fire a missed window.
+
+**Agent** triggers chain agents: `{ after, on, promptTemplate }` starts
+the target agent when the named agent finishes — `on` is `done`, `error`
+or `any`. Chains are capped at **3 agents deep** and cannot cycle: saving
+a spec that would loop (A → B → A) or exceed the depth fails with
+`LOUSHO_CHAIN_INVALID` (400), and the runtime skips any chain that would
+loop anyway. The prompt template can interpolate
+`{{run.status}}`, `{{run.resultText}}` (capped at 8000 characters) and
+`{{run.traceId}}`.
+
+**Abort listeners** are the inverse: `abortListeners[]` entries watch
+webhook and channel triggers only (at most 20) and cancel queued or
+running runs when an event matches. Each entry has `triggerId` (which
+trigger's runs are candidates), `when` and `match` (safe expressions over
+the event — and for `match`, the candidate run — that must evaluate to
+strictly `true`), and `scope` (`queued`, `running` or `both`). Every
+inbound webhook or channel event evaluates all of the agent's listeners
+*before* that event's own filter and dispatch, so a listener can cancel
+the very run the event would have started — but never itself, since the
+delivering run does not exist yet. Chat and cron events do not evaluate
+listeners.
+
+## Inbox
+
+The **Inbox** screen (`#/inbox`) collects everything waiting on you across
+agents, and the nav badge counts open items. Rows come in five kinds:
+
+- **approvals** and **questions** — a run paused for a tool-call decision
+  or an `ask_question`; they expire, and the row carries the countdown.
+- **drafts** — pending change drafts (see above), with gated-field flags.
+- **suggestions** — open prompt-edit suggestions.
+- **alerts** — `auto_disabled` (the failure streak), `publish_failed`
+  (the eval gate refused a publish), and `low_rating` (a run rated 2 or
+  lower).
+
+Alert rows act inline: a `low_rating` alert offers **Add to dataset
+`<agentId>-regressions`** (copies the trace into the agent's regression
+dataset), **Suggest a fix** (starts the prompt-suggestion pass on that
+trace) and **Dismiss**; the other alerts offer **Dismiss**. Approval and
+question rows answer in place.
+
+## Approvals decided by a model
+
+A permission rule's `action` can be `allow`, `deny`, `ask` or `auto`.
+`auto` compiles to `ask` and is then decided by a cheap model scoring the
+*exact* tool call about to run: it sees the call and its arguments, not
+the agent's general behaviour.
+
+The rule is deliberately one-directional:
+
+- A safety score **≥ 0.8** returned **within 8 seconds** approves the
+  call.
+- A lower score, a timeout, an error or a truncated reply does not deny —
+  it **escalates to you**, and the run pauses for a normal approval.
+- The model can never deny on its own, and the approval binds to that
+  exact call: a different call asks again.
+
+## Ratings
+
+Runs, traces and test runs carry a 1–5 rating (Poor, Fair, Good, Great,
+Excellent). `POST /agents/<id>/rating` records it as a `rating` score on
+the run's trace in the observe daemon — the same place eval datasets and
+traces live — and a rating of **2 or lower** also raises a `low_rating`
+inbox alert (see above). From the alert you can copy the trace into the
+agent's `<agentId>-regressions` dataset or start a prompt suggestion on
+it, which is how a bad run becomes a regression test or a prompt fix.
+
+## Publish and the eval gate
+
+The publish pill on the builder pins a version as the agent's *live*
+spec — the version triggers, Serve and Deploy run. `POST
+/agents/<id>/publish` accepts an optional `{ "version": n }`; without it
+the working copy is captured as a `publish` version first (skipped when
+nothing changed, so an unchanged agent just re-pins the latest).
+
+When the target version's spec declares `evals`, the **eval gate** runs
+each dataset's examples through the candidate version before the pin
+lands:
+
+```yaml
+evals:
+  - dataset: support-triage-gold
+    minPassRate: 0.8
+    gates:
+      - calledTool: lookup_order
+      - notCalledTool: delete_account
+      - maxCostUsd: 0.05
+      - maxSteps: 12
+      - judge:
+          model: anthropic/claude-haiku-4-5
+          rubric: The answer cites the order status and offers a next step.
+          minScore: 0.7
+```
+
+Each entry names an observe `dataset` (up to 50 examples are fetched,
+each run capped at 60 seconds), 1–20 `gates` every example must pass, and
+a `minPassRate` (0–1) of examples that must pass for the set to count. A
+spec may carry up to 20 eval entries. Gate kinds:
+
+- `calledTool` / `notCalledTool` — the run's tool calls must (not) include
+  the named tool.
+- `maxCostUsd` / `maxSteps` — bounds on the run's cost and step count.
+- `judge` — a model grades the answer against a `rubric` and must reach
+  `minScore` (0–1).
+
+A passing gate pins the version and reports the publish. A failing one
+answers **409 `LOUSHO_EVAL_GATE_FAILED`** with the full per-set result —
+pass rates, failing examples (first 10 shown, then "+n more") with their
+failure sentences and `Open trace` links — and Studio shows the "Eval
+gate failed" dialog ("v3 was not published. Fix the failures or change
+the gate, then publish again."). There is no "publish anyway". The
+captured `publish` version stays in history, simply unpinned, and a
+`publish_failed` inbox alert is raised. A second publish while a gate is
+running answers 409 `LOUSHO_EVAL_GATE_BUSY`.
+
+## Serve while Studio runs
+
+With a version published, the **Serve** card on the Code tab exposes the
+agent over HTTP while Studio runs: `POST <origin><baseUrl>/chat`, an SSE
+stream of the run's events. Enable it with the "Serve the published
+version" switch — it stays disabled until something is published.
+
+Callers authenticate with a **bearer token**: 32 base64url characters,
+shown masked (first four and last four) in the card. Reveal shows it for
+30 seconds; copy puts it straight on the clipboard; rotate invalidates the
+old one everywhere, including a running MCP server (which restarts on a
+new port). Treat the token like a password — anyone holding it can run
+the agent, spend its budget and see its sessions. Keep it server-side;
+never commit it or put it in client-side code.
+
+**Allowed origins** is the CORS list for browser callers, one origin per
+line (e.g. `http://localhost:3000`). Empty means server-side callers
+only. Requests from an unlisted `Origin` get no CORS headers — and the
+chat widget refuses them outright.
+
+```bash
+curl -N http://127.0.0.1:41234/serve/my-agent/chat \
+  -H "Authorization: Bearer $LOUSHO_SERVE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"sessionId":"demo","input":"Hello"}'
+```
+
+Serve routes enforce a loopback `Host` check: they answer only requests
+addressed to Studio's own host. The snippets assume Studio on
+`127.0.0.1` — if you started it with `--host`, substitute the real host
+in the endpoint, the MCP URL and the widget snippet.
+
+**MCP**: the card can also start the published agent as an MCP server on
+an ephemeral loopback port. Add it to Claude Code with:
+
+```bash
+claude mcp add --transport http my-agent http://127.0.0.1:41234/mcp \
+  --header "Authorization: Bearer $LOUSHO_SERVE_TOKEN"
+```
+
+(The card prints the exact command with the live URL.) For a server that
+outlives Studio, the stdio form runs the published snapshot directly —
+`lousho mcp .lousho/agents/<id>/published.yaml` — which exists once the
+agent has been published (a deploy also writes it).
+
+**Embeddable chat**: the widget bundle is served at
+`<baseUrl>/widget.js` and mounts a `<forge-chat>` element. It uses a
+separate **widget key** (`fwk_…`) that is narrower than the serve token —
+it can only call chat, and only from an origin on the allowed-origins
+list (a page elsewhere gets 403 `LOUSHO_WIDGET_ORIGIN`). Embed it with:
+
+```html
+<script src="http://127.0.0.1:41234/serve/my-agent/widget.js" defer></script>
+<forge-chat endpoint="http://127.0.0.1:41234/serve/my-agent/chat" token="fwk_YOUR_KEY" title="my-agent"></forge-chat>
+```
+
+The widget derives its endpoint from `location.origin`, so the snippet's
+host must be the Studio host the visitor's browser can reach — the
+loopback default works for local demos, not for a public site.
+
+## Deploy
+
+**Deploy** (Settings → Deploy, or the deploy section) builds the
+*published* version into a runnable artifact — never the working copy.
+Publishing writes `.lousho/agents/<id>/published.yaml`, the snapshot
+deploy consumes, and deploy runs the real CLI:
+
+```
+node bin/lousho.js build --target=<adapter> --agent=<published.yaml> --out=<baseDir>/.lousho/build/<adapter>/<id>
+```
+
+Three adapters ship: `node-server`, `cloudflare-worker` and `docker`.
+Deploying an agent with nothing published answers 409
+`LOUSHO_NOT_PUBLISHED` — "Publish a version before deploying".
+
+One caveat worth knowing: `published.yaml` holds the spec's **v1
+projection**, not the raw v2 document, because `lousho build` and
+`lousho mcp` still load spec files through the v1 loader. A v2-only
+field that does not project into v1 will not reach the deployed artifact.
+
+## Where things are stored
+
+Studio state lives under the workspace's `.lousho/` directory. Per agent,
+`.lousho/agents/<id>/` is a sidecar folder next to the spec:
+
+```
+.lousho/
+  agents/
+    <id>.yaml                     # the spec v2 working copy
+    <id>/
+      meta.json                   # enabled, disabledReason, failureStreak, labels, publish pointer, createdFrom
+      layout.json                 # canvas positions, collapsed groups, notes, viewport
+      working.json                # Studio-write marker (spec hash) for external-edit detection
+      published.yaml              # v1 projection of the published version (deploy/mcp/serve)
+      versions/
+        index.jsonl               # one line per version, newest facts first
+        000001.json …             # full snapshots (spec + labels)
+      drafts/
+        current.json              # the one pending draft
+        history/<draftId>.json    # resolved drafts
+      suggestions/<id>.json       # prompt-edit and portability records
+      triggers/state.json         # cron fire cursors
+      checkpoints/<sessionId>.json        # resumable run state
+      checkpoint-history/<sessionId>.json # finished checkpoints
+      approvals/<approvalId>.json        # paused tool-call decisions
+  passes/spend.jsonl              # append-only pass model spend log
+  inbox/alerts.json               # auto_disabled / publish_failed / low_rating records
+  serve.json                      # per-agent serve switches, tokens refs, allowed origins
+  secrets.json                    # encrypted provider keys and named secrets
+  secrets.key                     # the encryption key for secrets.json
+  workspaces.json                 # the workspace registry
+  settings.json                   # settings profiles
+  assistant/sessions/             # Agent Author session files
+```
+
+`versions/` is append-only: the full record is written before its
+`index.jsonl` line, so a crash mid-capture cannot leave a dangling index
+entry. Pass records — version summaries, draft reviews, portability
+checks, prompt suggestions, eval judges, auto-approvals — write their
+results back onto the draft, suggestion or version they belong to, and
+their model spend lands in `passes/spend.jsonl`.
diff --git a/guardrails.mdx b/guardrails.mdx
index 5e9d876..3ed3358 100644
--- a/guardrails.mdx
+++ b/guardrails.mdx
@@ -50,7 +50,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, moderationGuardrail, piiGuardrail } from 'lousho';
+import { createAgent, moderationGuardrail, piiGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -90,7 +90,7 @@ import {
   maxLengthGuardrail,
   regexGuardrail,
   type IoGuardrail,
-} from 'lousho';
+} from '@linuxdevil/lousho';
 
 const noProdWrites: IoGuardrail = {
   name: 'no-prod-writes',
@@ -136,7 +136,7 @@ try {
 The last four are a starter set for checks most production agents need:
 
 ```ts
-import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from 'lousho';
+import { createAgent, piiGuardrail, promptInjectionGuardrail, secretsGuardrail } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
@@ -184,7 +184,7 @@ proposed patch and rolls the results up into one verdict. The
 agent's patch before a pull request is opened:
 
 ```ts
-import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from 'lousho';
+import { runPatchChecks, secretScanCheck, createDiffSizeCheck, createCommandCheck } from '@linuxdevil/lousho';
 
 const verdict = await runPatchChecks(
   { diff: patch },
@@ -224,8 +224,8 @@ function. The executor then calls `sandboxExecute` with the run's
 #### Advanced: the executor API
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { SubprocessSandbox } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { SubprocessSandbox } from '@linuxdevil/lousho';
 
 // Route a flagged tool (requiresSandbox + sandboxExecute) through a real,
 // Docker-backed sandbox instead of the in-process NoopSandbox default
diff --git a/handoffs.mdx b/handoffs.mdx
index ade11f3..4af8c43 100644
--- a/handoffs.mdx
+++ b/handoffs.mdx
@@ -19,7 +19,7 @@ description to decide when to hand off), then pass them to the triage agent as
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupCharges = defineTool({
@@ -70,7 +70,7 @@ name with one of the agent's tools.
 Wrap a target in `handoff()` to configure it:
 
 ```ts
-import { createAgent, handoff, handoffFilters } from 'lousho';
+import { createAgent, handoff, handoffFilters } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const refunds = createAgent({ name: 'refunds', description: 'Issues refunds', model: 'openai/gpt-4o-mini' });
@@ -122,7 +122,7 @@ the middle of a conversation. Two filters are built in:
 - `handoffFilters.lastUserMessage`: keeps only the last user message.
 
 ```ts
-import { handoffFilters, type HandoffInputData } from 'lousho';
+import { handoffFilters, type HandoffInputData } from '@linuxdevil/lousho';
 
 // The last four messages, without tool traffic.
 const recent = (data: HandoffInputData) => handoffFilters.removeToolCalls(data).slice(-4);
@@ -169,7 +169,7 @@ In a session the active agent is the one the transcript last handed off to
 `session.send()` / `session.stream()` runs that agent:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
@@ -187,7 +187,7 @@ its targets, give the target an array and add the lead to it afterwards (the
 array is read at every run):
 
 ```ts
-import { createAgent, handoff, type Handoff } from 'lousho';
+import { createAgent, handoff, type Handoff } from '@linuxdevil/lousho';
 
 const billingHandoffs: Handoff[] = [];
 const billing = createAgent({
@@ -237,7 +237,7 @@ A handoff is reported between the handoff call's `tool.start` / `tool.done`
 and the target's first `step.start`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ name: 'billing', description: 'Handles charges and refunds', model: 'openai/gpt-4o-mini' });
 const triage = createAgent({ name: 'triage', model: 'openai/gpt-4o-mini', handoffs: [billing] });
diff --git a/hooks.mdx b/hooks.mdx
index 1e06679..280fff4 100644
--- a/hooks.mdx
+++ b/hooks.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Hooks"
 ---
-{/* Generated from docs/hooks.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
+{/* Generated from docs/hooks.md in LinuxDevil/agent-sdk by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 A hook is an object `{ name, preToolCall?, postToolCall?, preGenerate?, postGenerate? }` that runs inside the agent loop, around every tool call and every model call. Use one to write an audit log, deny a tool, redact or truncate a result, inject context before the model call, or change the request (a header, `temperature`) it sends.
 
@@ -12,8 +12,8 @@ Hooks are code you write, not policy and not a human decision: for rules that al
 Pass hooks to `createAgent({ hooks })`. This one logs every tool call and what it returned:
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const auditHook: AgentHook = {
@@ -84,8 +84,8 @@ that throws still rejects the run, as before. Sub-agents inherit the lead
 agent's hooks and their outcomes.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel(['Done.']);
 
@@ -127,8 +127,8 @@ getting anywhere. It's off unless you add it:
   `LOUSHO_RUN_NO_PROGRESS`, which `agent.recover()` won't retry.
 
 ```ts
-import { createAgent, createProgressGuard, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createProgressGuard, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const lookup = defineTool({
@@ -166,8 +166,8 @@ sees it as `outputCheckFailed` on the result and can fix the output. The check
 is your code, so make it independent of what the model wrote.
 
 ```ts
-import { createAgent, createOutputCheck, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createOutputCheck, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const files = new Map<string, string>();
@@ -197,8 +197,8 @@ await agent.send('Write the report');
 ### Deny a tool by name
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -230,8 +230,8 @@ console.log(result.text);
 Return `{ input }` to run the tool with different arguments. They are validated against the tool's schema again.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const search = defineTool({
@@ -264,8 +264,8 @@ await agent.send('Search for hooks');
 `postToolCall` receives the settled result and may return `{ result }` to replace what the model sees. The tool itself ran unchanged.
 
 ```ts
-import { createAgent, defineTool, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const readLog = defineTool({
@@ -299,8 +299,8 @@ console.log(toolMessage?.role); // 'tool': its content is the redacted text
 `preGenerate` sees the live `ctx.messages` and `ctx.request`. Push a message to add context, or change a request field.
 
 ```ts
-import { createAgent, type AgentHook } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, type AgentHook } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const addDate: AgentHook = {
   name: 'add-date',
@@ -338,7 +338,7 @@ refused with a tool error instead of running. See [Approvals](/approvals) for th
 `createAgent({ hooks })` takes a plain array. Code that uses the executor API ([The executor API](/executor-api)) passes a `HookRegistry`: an ordered collection with `register`, `registerMany`, `get`, `has`, `list`, `unregister`, `clear` and `size()` — `size` is a method (`hooks.size()`), not a `Map`-style property. Registering a second hook with the same `name` replaces the first and logs a warning.
 
 ```ts
-import { HookRegistry, type AgentHook } from 'lousho/hooks';
+import { HookRegistry, type AgentHook } from '@linuxdevil/lousho/hooks';
 
 const redactPii: AgentHook = {
   name: 'redact-pii',
@@ -352,4 +352,4 @@ hooks.register(redactPii);
 console.log(hooks.list().map((hook) => hook.name)); // [ 'redact-pii' ]
 ```
 
-`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](/agent-forge#hooks).
+`HookRegistry`, `AgentHook` and the context types are available from the package root and from the `@linuxdevil/lousho/hooks` subpath. Hooks authored in the Agent Forge canvas editor are compiled into a `HookRegistry` and run sandboxed rather than in the host process: see [Agent Forge](/agent-forge#hooks).
diff --git a/hosted-tools.mdx b/hosted-tools.mdx
index dfdd8f1..4007ad4 100644
--- a/hosted-tools.mdx
+++ b/hosted-tools.mdx
@@ -9,7 +9,7 @@ web search, code interpreter and file search are the common ones. Put them in
 each call in its events, keeps it on the transcript and counts it in usage.
 
 ```ts
-import { createAgent, webSearch, defineTool } from 'lousho';
+import { createAgent, webSearch, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const saveNote = defineTool({
@@ -112,7 +112,7 @@ providers and with any AI SDK model wrapped by
 [`fromAiSdk()`](/providers#any-ai-sdk-model-fromaisdk):
 
 ```ts
-import { createAgent, fromAiSdk, hostedTool } from 'lousho';
+import { createAgent, fromAiSdk, hostedTool } from '@linuxdevil/lousho';
 import { openai } from '@ai-sdk/openai';
 
 const agent = createAgent({
@@ -129,7 +129,7 @@ A hosted call is reported like a tool call, with `executedBy: 'provider'` on
 `tool.start`, `tool.done` and `tool.error`:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', tools: [webSearch()] });
 
@@ -183,7 +183,7 @@ without a human, leave the tool out of `tools`, or choose tools per run with a
 function:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -220,8 +220,8 @@ hosted tools; a resuming agent with a different set reports
 request, so an agent with hosted tools runs offline:
 
 ```ts
-import { createAgent, webSearch } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, webSearch } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([
   {
diff --git a/installation.mdx b/installation.mdx
index 43b9872..b33acce 100644
--- a/installation.mdx
+++ b/installation.mdx
@@ -12,11 +12,11 @@ title: "Installation"
 ## Install the package
 
 ```bash
-npm install lousho ai zod
+npm install @linuxdevil/lousho ai zod
 # or
-pnpm add lousho ai zod
+pnpm add @linuxdevil/lousho ai zod
 # or
-yarn add lousho ai zod
+yarn add @linuxdevil/lousho ai zod
 ```
 
 `ai` (the Vercel AI SDK: `^4.3.19`, `^6.0.0` or `^7.0.0`) and `zod`
@@ -45,7 +45,7 @@ that pairs with your `ai` major. Install the pair from one row:
 For example, on the current `ai` major:
 
 ```bash
-npm install lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
+npm install @linuxdevil/lousho ai@^7.0.0 zod @ai-sdk/openai@^4.0.0
 ```
 
 **Ollama on `ai` 6/7 needs zod 4.** `ollama-ai-provider-v2` (the Ollama package
@@ -63,7 +63,7 @@ with zod 4, and `ai` 7 with zod 3 and with zod 4. The two zod 4 entries on
 `ai` 6 and 7 also install `ollama-ai-provider-v2` (3.x and 4.x) and run the
 Ollama provider against it, so Ollama on `ai` 6/7 is tested, not assumed.
 
-Peers are loaded on demand: importing `lousho` (or any of
+Peers are loaded on demand: importing `@linuxdevil/lousho` (or any of
 its sub-entries) never loads a provider package, so you only need to install
 the ones you use. Each provider package is loaded the first time that
 provider makes a call; if it is missing, that call fails with a
@@ -77,7 +77,7 @@ npm install @ai-sdk/openai@^0.0.42
 ```
 
 ```ts
-import { MissingPeerDependencyError, resolveProvider } from 'lousho';
+import { MissingPeerDependencyError, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = resolveProvider('openai/gpt-4o-mini'); // needs OPENAI_API_KEY; does not load the peer
 try {
@@ -99,9 +99,9 @@ the `lousho init` questions or code mode installs none of them:
 | --------------------------- | --------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------ |
 | `dockerode`                 | `^5.0.1`  | Docker sandboxing: `SubprocessSandbox` (and `lousho doctor`'s Docker ping)                    | `npm install dockerode@^5.0.1`                   |
 | `@modelcontextprotocol/sdk` | `^1.31.0` | MCP: `createAgent({ mcpServers })` / `connectMcp()`, `serveMcp()` and `lousho mcp`            | `npm install @modelcontextprotocol/sdk@^1.31.0`  |
-| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
-| `react`                     | `^18`, `^19` | The React bindings (`lousho/react`)                                      | `npm install react`                              |
-| `vue`                       | `^3`      | The Vue bindings (`lousho/vue`)                                               | `npm install vue@^3`                             |
+| `@opentelemetry/api`        | `^1.9.1`  | OpenTelemetry tracing: `createOtelTraceExporter()` from `@linuxdevil/lousho/otel`         | `npm install @opentelemetry/api@^1.9.1`          |
+| `react`                     | `^18`, `^19` | The React bindings (`@linuxdevil/lousho/react`)                                      | `npm install react`                              |
+| `vue`                       | `^3`      | The Vue bindings (`@linuxdevil/lousho/vue`)                                               | `npm install vue@^3`                             |
 | `tsup`                      | `^8.0.0`  | `lousho build`, which bundles the agent for each target                                       | `npm install --save-dev tsup@^8.0.0`             |
 | `prompts`                   | `^2.4.2`  | The interactive questions of `lousho init` (`lousho init --yes` and flags need nothing)       | `npm install prompts@^2.4.2`                     |
 | `quickjs-emscripten`        | `^0.32.0` | [Code mode](/code-mode): `createAgent({ codeMode })` runs `run_code` scripts in its QuickJS isolate | `npm install quickjs-emscripten@^0.32.0` |
@@ -114,7 +114,7 @@ that names the feature and the exact command, for example:
 The optional package 'dockerode' is not installed, but Docker sandboxing (SubprocessSandbox) needs it. Run: npm install dockerode@^5.0.1
 ```
 
-`npm create lousho` installs `prompts` itself, so scaffolding with it
+`npm create @linuxdevil/lousho` installs `prompts` itself, so scaffolding with it
 needs nothing extra. `lousho doctor` lists every optional peer, what it
 enables and whether it is installed (a missing `dockerode` is an error only
 when the agent spec uses a sandboxed tool).
@@ -132,8 +132,7 @@ The tarball is about 4 MB packed (15 MB unpacked). That is a stated trade-off,
 not an accident: `src/` ships because `lousho build` bundles
 `src/deploy/runtime.worker.ts` and `src/index.ts` from the installed package
 and the `dist/` source maps point at it (the maps carry no embedded source;
-embedding it instead and dropping `src/` measured larger, 5.2 MB packed), and
-`apps/agent-forge/` is the prebuilt dashboard that `lousho studio` serves. The
+embedding it instead and dropping `src/` measured larger, 5.2 MB packed). The
 1 MB `llms-full.txt` is in the repo, not the package.
 
 ## Entry points share code (ESM and CJS)
@@ -154,25 +153,25 @@ The entries `exports` declares, and what each one holds:
 
 | Import specifier | What it holds |
 | ---------------- | ------------- |
-| `lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
-| `lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
-| `lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
-| `lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
-| `lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
-| `lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
-| `lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
-| `lousho/types` | The public types without the runtime |
-| `lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
-| `lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
-| `lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
-| `lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
-| `lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
-| `lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
-| `lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
-| `lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
-| `lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
-| `lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
-| `lousho/svelte` | `loushoAgent()` as a Svelte store |
+| `@linuxdevil/lousho` | The root: `createAgent()`, `defineTool()`, `defineChannel()`, agents' public types, events, stores (`memoryStore()`, `fileStore()`), hooks, guardrails, sessions, skills, memory, sub-agents, evals, spec files, deployment types |
+| `@linuxdevil/lousho/executor` | The executor API (advanced - prefer `createAgent()`): `AgentExecutor`, `AgentBuilder`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()`, `ToolRegistry`, `globalToolRegistry` |
+| `@linuxdevil/lousho/tools` | The tools surface: `defineTool()`, `ToolRegistry`, the built-in tools, MCP/OpenAPI helpers |
+| `@linuxdevil/lousho/flows` | `FlowBuilder`, `FlowExecutor`, `validateFlow()` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) |
+| `@linuxdevil/lousho/integrations` | The credentialed third-party tools: `createJiraTools()`, `createGitHubTools()`, `createSlackTool()` / `slackTool`, `postSlackAlert()`, `createEmailTool()` and their types |
+| `@linuxdevil/lousho/utils` | `EncryptionUtils`, `sha256()`, `generatePassword()`, `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` and the validators (`validateWithSchema`, `isValidEmail`, ...) |
+| `@linuxdevil/lousho/mcp` | MCP client and server helpers: `connectMcp()`, `loadMcpTools()`, `serveMcp()` |
+| `@linuxdevil/lousho/types` | The public types without the runtime |
+| `@linuxdevil/lousho/testing` | `mockModel()`, `recordReplay()` and the offline-test helpers |
+| `@linuxdevil/lousho/otel` | `createOtelTraceExporter()` (needs the optional `@opentelemetry/api` peer) |
+| `@linuxdevil/lousho/hooks` | The hooks surface: `HookRegistry`, hook types |
+| `@linuxdevil/lousho/sqlite` | `SqliteStore` (sessions, checkpoints, approvals and tokens in one SQLite file; needs Node's `node:sqlite`) |
+| `@linuxdevil/lousho/auth` | Route auth: `routeAuth()`, `jwt()`, `oidc()`, `basic()`, `apiToken()`, `anonymous()` |
+| `@linuxdevil/lousho/kv` | `KVStore`, `KVCheckpointStore` for a hand-written Cloudflare Worker |
+| `@linuxdevil/lousho/traces` | `fileTraceExporter()`, `listTraces()`, `readTrace()` (what `lousho traces` reads) |
+| `@linuxdevil/lousho/triggers` | `TriggerAdapter`, `TriggerRegistry`, `verifySlackSignature`, `parseCronExpression` |
+| `@linuxdevil/lousho/react` | `useLoushoAgent()` and the React helpers (needs `react`) |
+| `@linuxdevil/lousho/vue` | `useLoushoAgent()` as a Vue composable (needs `vue`) |
+| `@linuxdevil/lousho/svelte` | `loushoAgent()` as a Svelte store |
 
 ### TypeScript settings
 
@@ -242,8 +241,8 @@ one-line `CLAUDE.md` importing it) telling coding agents the project's files,
 scripts and conventions. It then installs the dependencies and runs `git init`.
 
 ```bash
-npm create lousho my-agent   # or: npx lousho init my-agent
-npx lousho init my-agent --yes --provider anthropic --template tools --no-install
+npm create @linuxdevil/lousho my-agent   # or: npx @linuxdevil/lousho init my-agent
+npx @linuxdevil/lousho init my-agent --yes --provider anthropic --template tools --no-install
 ```
 
 | Flag | Meaning |
@@ -259,16 +258,26 @@ npx lousho init my-agent --yes --provider anthropic --template tools --no-instal
 `create-lousho` (`packages/create-lousho`) is a thin wrapper that
 runs `lousho init` with the same arguments.
 
-## The `lousho` CLI
+## The `@linuxdevil/lousho` CLI
 
-Installing the package also installs the `lousho` command: `init`, `doctor`,
-`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build` and `studio`. See
+Installing the package also installs the `@linuxdevil/lousho` command: `init`, `doctor`,
+`dev`, `chat`, `acp`, `add`, `mcp`, `eval`, `traces`, `build`, `studio`,
+`observe`, `bridge` and more. See
 [CLI](/cli) for what each one does and its flags. Building needs `tsup`,
 an optional peer (see the table above): `npm install --save-dev tsup`.
 
+### Studio (optional)
+
+The visual dashboard, Lousho Studio, is a separate package,
+`@linuxdevil/studio` - it is not part of this tarball. Install it with
+`npm i -g @linuxdevil/studio` (or run `npx @linuxdevil/studio`), or just run
+`lousho studio` inside a project that has the SDK: the launcher finds an
+installed Studio and opens the folder as a workspace. See
+[Lousho Studio](/agent-forge).
+
 ## Troubleshooting: lousho doctor
 
-Run `npx lousho doctor` right after installing. It prints one line per check
+Run `npx @linuxdevil/lousho doctor` right after installing. It prints one line per check
 with a status (`ok`, `warn`, `FAIL`), what it found, and, for anything that is
 not ok, the command to run or the setting to change:
 
diff --git a/mcp-integration.mdx b/mcp-integration.mdx
index 32a40e6..beabc2a 100644
--- a/mcp-integration.mdx
+++ b/mcp-integration.mdx
@@ -6,7 +6,7 @@ sidebarTitle: "MCP"
 
 MCP works in two directions. Your agent can call the tools of MCP servers, or
 your agent can be an MCP server that Claude Code, Cursor and other MCP clients
-call. Both live in the `lousho/mcp` subpath, and
+call. Both live in the `@linuxdevil/lousho/mcp` subpath, and
 `@modelcontextprotocol/sdk` is an optional peer: install it to use either
 direction.
 
@@ -15,7 +15,7 @@ npm install @modelcontextprotocol/sdk
 ```
 
 `connectMcp`, `loadMcpTools` and `serveMcp` are exported from
-`lousho/mcp`; the package root and `lousho/tools`
+`@linuxdevil/lousho/mcp`; the package root and `@linuxdevil/lousho/tools`
 export them too. `createAgent({ mcpServers })` needs no import from the subpath.
 
 ## Use MCP servers in an agent
@@ -30,7 +30,7 @@ or `ready()`, reconnects. Without `mcpServers`, `ready()` and `close()` do nothi
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -126,8 +126,8 @@ own tools and MCP tools can sit in one list. (Spreading into one record,
 `tools: { ...mcp.tools, my_tool: myTool }`, works too.)
 
 ```ts
-import { createAgent } from 'lousho';
-import { connectMcp } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { connectMcp } from '@linuxdevil/lousho/mcp';
 
 const mcp = await connectMcp(
   { files: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] } },
@@ -204,7 +204,7 @@ in `loadMcpTools(client, name, { approval })`:
 `allow`, `deny` or `ask`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -228,15 +228,15 @@ its tools with `loadMcpTools()`, then pass the result to `createAgent()` (or
 register it on a `ToolRegistry`):
 
 ```ts
-import { createAgent } from 'lousho';
-import { loadMcpTools } from 'lousho/mcp';
+import { createAgent } from '@linuxdevil/lousho';
+import { loadMcpTools } from '@linuxdevil/lousho/mcp';
 
 const tools = await loadMcpTools(mcpClient, 'my-server');
 const agent = createAgent({ instructions: '...', provider, tools });
 ```
 
 `loadMcpTools` is also available from the package root and from
-`lousho/tools`.
+`@linuxdevil/lousho/tools`.
 
 ## Serve an agent over MCP
 
@@ -245,8 +245,8 @@ optionally, some of its tools) as an MCP server, so Claude Code, Cursor and
 other MCP clients can call it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { serveMcp } from 'lousho/mcp';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { serveMcp } from '@linuxdevil/lousho/mcp';
 import { z } from 'zod';
 
 const searchDocs = defineTool({
@@ -311,7 +311,7 @@ needs approval is never advertised read-only. The built-in `read_file`, `list_di
 `glob`, `grep`, `todo_read`, `current_date` and `day_name` tools are read-only.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -328,8 +328,8 @@ const lookupOrder = defineTool({
 `lousho mcp` serves an agent spec file (stdio by default):
 
 ```sh
-npx lousho mcp agent.yaml
-npx lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
+npx @linuxdevil/lousho mcp agent.yaml
+npx @linuxdevil/lousho mcp agent.yaml --http --port 3920 --host 127.0.0.1
 ```
 
 To use it from an MCP client, add it to the client's MCP config (for example
diff --git a/memory.mdx b/memory.mdx
index 3979d9e..234c137 100644
--- a/memory.mdx
+++ b/memory.mdx
@@ -39,7 +39,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineMemory, fileMemory } from 'lousho';
+import { createAgent, defineMemory, fileMemory } from '@linuxdevil/lousho';
 
 const preferences = defineMemory({
   name: 'preferences',
@@ -87,8 +87,8 @@ A scope function sees the run's `sessionId` and the `metadata` passed to
 sessions:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const userFacts = defineMemory({
   name: 'user_facts',
@@ -131,7 +131,7 @@ every start: `add()` dedupes on text, so nothing is copied twice. Each copy
 keeps `text` and `metadata` and gets a new `id` and `createdAt`.
 
 ```ts
-import { defineMemory, fileMemory, migrateMemoryKeys } from 'lousho';
+import { defineMemory, fileMemory, migrateMemoryKeys } from '@linuxdevil/lousho';
 
 const provider = fileMemory({ dir: './.lousho/memory' });
 const notes = defineMemory({ name: 'notes', scope: 'global', provider });
@@ -169,7 +169,7 @@ the count.
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const relationship = defineMemory({
   name: 'relationship',
@@ -200,7 +200,7 @@ adding a second version. The item keeps its id, becomes the newest, and
 
 ```ts
 import { z } from 'zod';
-import { defineMemory, inMemoryMemory } from 'lousho';
+import { defineMemory, inMemoryMemory } from '@linuxdevil/lousho';
 
 const settings = defineMemory({
   name: 'settings',
@@ -286,8 +286,8 @@ by meaning instead of by keyword, use `sqliteVectorMemory()`: see
 [Semantic recall](#semantic-recall).
 
 ```ts
-import { createAgent, defineMemory } from 'lousho';
-import { SqliteStore, sqliteMemory } from 'lousho/sqlite';
+import { createAgent, defineMemory } from '@linuxdevil/lousho';
+import { SqliteStore, sqliteMemory } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: sqliteMemory(store) });
@@ -297,7 +297,7 @@ const agent = createAgent({ model: 'openai/gpt-4o-mini', store, memory: [notes]
 For a hosted store or your own ranking, implement `MemoryProvider`:
 
 ```ts
-import type { MemoryItem, MemoryProvider } from 'lousho';
+import type { MemoryItem, MemoryProvider } from '@linuxdevil/lousho';
 
 const items = new Map<string, MemoryItem[]>();
 const myProvider: MemoryProvider = {
@@ -326,8 +326,8 @@ With [`mockModel`](/testing), assert on the system prompt of the first
 request and drive the tools with scripted tool calls:
 
 ```ts
-import { createAgent, defineMemory, inMemoryMemory, memoryKey } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineMemory, inMemoryMemory, memoryKey } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const store = inMemoryMemory();
 const notes = defineMemory({ name: 'notes', scope: 'global', provider: store });
@@ -369,7 +369,7 @@ package that pairs with your `ai` major, as for language models). It adds no
 dependency: `ai` is already a peer, and the provider package is yours.
 
 ```ts
-import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from 'lousho';
+import { createAgent, defineMemory, aiSdkEmbedder, inMemoryVectorMemory } from '@linuxdevil/lousho';
 import { createOpenAI } from '@ai-sdk/openai';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
@@ -391,7 +391,7 @@ Two providers rank by meaning, with the same options:
 - `inMemoryVectorMemory({ embedder, maxItems?, minScore? })` keeps items in this
   process.
 - `sqliteVectorMemory(store, { embedder, maxItems?, minScore? })` (from
-  `lousho/sqlite`) keeps them in the agent's SQLite file, in a
+  `@linuxdevil/lousho/sqlite`) keeps them in the agent's SQLite file, in a
   `memory_vectors` table that an existing file gains when it is opened. Vectors
   survive restarts.
 
@@ -415,14 +415,14 @@ re-embeds them in batches and returns how many it changed.
 `reindex(providerKey)` does one key only — for a slot's key, pass
 `memoryKey(slot, ctx)`.
 
-`hashEmbedder()` from `lousho/testing` is a deterministic
+`hashEmbedder()` from `@linuxdevil/lousho/testing` is a deterministic
 offline embedder for tests: a hashed bag of word stems, so texts that share
 words are close. It is not a semantic model and does not know that "vegetarian"
 and "eat" are related.
 
 ```ts
-import { inMemoryVectorMemory } from 'lousho';
-import { hashEmbedder } from 'lousho/testing';
+import { inMemoryVectorMemory } from '@linuxdevil/lousho';
+import { hashEmbedder } from '@linuxdevil/lousho/testing';
 
 const memory = inMemoryVectorMemory({ embedder: hashEmbedder() });
 await memory.add('global', { text: 'Sam is vegetarian' });
diff --git a/migrating-from-ai-sdk.mdx b/migrating-from-ai-sdk.mdx
index a1e32c5..63c3e33 100644
--- a/migrating-from-ai-sdk.mdx
+++ b/migrating-from-ai-sdk.mdx
@@ -45,7 +45,7 @@ you already configured (keys, base URL, provider options) works as it is:
 
 ```ts
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({ provider: fromAiSdk(openai.chat('gpt-4o-mini')), instructions: 'You are helpful.' });
@@ -63,7 +63,7 @@ See [Providers](/providers#any-ai-sdk-model-fromaisdk) for the options and which
 ```ts
 import { tool } from 'ai';
 import { z } from 'zod';
-import { createAgent, fromAiSdk, fromAiSdkTools } from 'lousho';
+import { createAgent, fromAiSdk, fromAiSdkTools } from '@linuxdevil/lousho';
 
 const weather = tool({
   description: 'Get the weather in a city',
@@ -89,8 +89,8 @@ and a plain object works too. This one runs offline:
 
 ```ts
 import { z } from 'zod';
-import { createAgent, fromAiSdkTools } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, fromAiSdkTools } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const tools = fromAiSdkTools({
   weather: {
@@ -132,7 +132,7 @@ A `useChat` front end keeps working: the route returns the agent's run as a UI m
 stream.
 
 ```ts
-import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from 'lousho';
+import { createAgent, fromUIMessages, memoryStore, toUIMessageStreamResponse, type UIMessageLike } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You are helpful.', store: memoryStore() });
 
diff --git a/migrating-to-create-agent.mdx b/migrating-to-create-agent.mdx
index 984d868..f932591 100644
--- a/migrating-to-create-agent.mdx
+++ b/migrating-to-create-agent.mdx
@@ -6,7 +6,7 @@ sidebarTitle: "Migrating to createAgent()"
 
 This page is for code that uses `AgentBuilder`, `AgentExecutor`, `ToolRegistry` and
 `resumeAfterApproval()`: the lower-level API the SDK started with. Those exports now
-live at `lousho/executor` and are not going away; if you stay on
+live at `@linuxdevil/lousho/executor` and are not going away; if you stay on
 them, see [The executor API](/executor-api). The reason to move is that one
 `createAgent()` call wires tools, stores, approvals, sessions, retries and
 compaction, where the executor makes you assemble each of them and pass them to every
@@ -28,9 +28,9 @@ import {
   AgentExecutor,
   ToolRegistry,
   resumeAfterApproval,
-} from 'lousho/executor';
-import { InMemoryApprovalStore, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+} from '@linuxdevil/lousho/executor';
+import { InMemoryApprovalStore, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -72,8 +72,8 @@ console.log(result.text); // 'Sent the report to Sam.'
 ```
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
diff --git a/models-and-cost.mdx b/models-and-cost.mdx
index 30e2b8f..d4640d5 100644
--- a/models-and-cost.mdx
+++ b/models-and-cost.mdx
@@ -10,7 +10,7 @@ sidebarTitle: "Models and cost"
 Dependency-free helpers for budgeting and context decisions.
 
 ```ts
-import { estimateTokens, estimateCost, getModelInfo, registerModel } from 'lousho';
+import { estimateTokens, estimateCost, getModelInfo, registerModel } from '@linuxdevil/lousho';
 
 // A custom or self-hosted model: add it (or override a built-in) before use.
 registerModel({
@@ -40,7 +40,7 @@ The built-in context windows and prices are a dated snapshot (see the retrieval
 Every `ExecutionResult` (and `agent.send()` result) carries `usage`, the running total of the whole run:
 
 ```ts
-import { createAgent, formatUsage } from 'lousho';
+import { createAgent, formatUsage } from '@linuxdevil/lousho';
 
 const result = await createAgent({ provider, instructions: 'You compare cities.' }).send('Compare 3 cities');
 
@@ -65,7 +65,7 @@ console.log(formatUsage(result.usage)); // 1,234 in / 567 out tokens · $0.0042
 Prices come from the model registry above, so to get a cost for a custom or fine-tuned model, register it under the id you pass as the model:
 
 ```ts
-import { registerModel } from 'lousho';
+import { registerModel } from '@linuxdevil/lousho';
 
 registerModel({
   id: 'ft:gpt-4o-mini:acme',
@@ -86,7 +86,7 @@ Anthropic caches a request prefix only up to a `cache_control` breakpoint that t
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const longPolicy = readFileSync('./policy.md', 'utf8'); // a long, stable system prompt
 const agent = createAgent({ model: 'openrouter/anthropic/claude-haiku-4.5', instructions: longPolicy }); // promptCaching: 'auto'
diff --git a/nextjs.mdx b/nextjs.mdx
index a45ef0e..5d7d0f4 100644
--- a/nextjs.mdx
+++ b/nextjs.mdx
@@ -17,7 +17,7 @@ prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 
 ```ts
 // app/api/agent/[[...path]]/route.ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
 
 // `store` is what lets a session survive across requests: without one every
 // `agent.session({ id })` the handler opens gets a fresh in-memory transcript,
@@ -40,7 +40,7 @@ and spend your model budget. Pass a bearer token, or a function that checks your
 own session or cookie:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 declare function isSignedIn(request: Request): Promise<boolean>;
 
@@ -93,8 +93,8 @@ customer's session (`GET /chat/:id`, to show what they are approving) and to
 decide in it; by default the session belongs to the customer alone:
 
 ```ts
-import { createAgent, createRouteHandler, memoryStore } from 'lousho';
-import { jwt } from 'lousho/auth';
+import { createAgent, createRouteHandler, memoryStore } from '@linuxdevil/lousho';
+import { jwt } from '@linuxdevil/lousho/auth';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', store: memoryStore() });
 const isSupervisor = (principal?: { claims?: Readonly<Record<string, unknown>> }) => principal?.claims?.role === 'supervisor';
@@ -135,7 +135,7 @@ see [Route auth and principals](/auth).
 
 ```tsx
 'use client';
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent', headers: { Authorization: `Bearer ${token}` } }, { approvalsUrl: '/api/agent/approvals' });
@@ -162,7 +162,7 @@ const { messages, sendMessage } = useChat({ transport: new DefaultChatTransport(
 The same handler, mounted where the framework wants it:
 
 ```ts
-import { createAgent, createRouteHandler } from 'lousho';
+import { createAgent, createRouteHandler } from '@linuxdevil/lousho';
 
 const { handler } = createRouteHandler(createAgent({ model: 'openai/gpt-4o-mini' }), { basePath: '/agent', auth: 'secret' });
 
diff --git a/oauth.mdx b/oauth.mdx
index 9fae594..2ffe22e 100644
--- a/oauth.mdx
+++ b/oauth.mdx
@@ -41,7 +41,7 @@ token, an operator who knows which authenticator the old tokens belong to moves
 them once:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho', { tokenKey: process.env.LOUSHO_TOKEN_KEY });
 const legacy = { owner: 'user', principalId: 'U04ABCDEF' } as const;
@@ -63,7 +63,7 @@ key unambiguous: a principal id containing `|` cannot collide with another
 owner.
 
 ```ts
-import { tokenStoreKey } from 'lousho';
+import { tokenStoreKey } from '@linuxdevil/lousho';
 
 tokenStoreKey('github', { owner: 'app' }); // 'github|app'
 tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id.example.com' });
@@ -75,7 +75,7 @@ tokenStoreKey('github', { owner: 'user', principalId: 'a|b', issuer: 'https://id
 `AgentStore.tokens` is an `OAuthTokenStore`:
 
 ```ts
-import { memoryStore } from 'lousho';
+import { memoryStore } from '@linuxdevil/lousho';
 
 const { tokens } = memoryStore();
 const alice = { owner: 'user', principalId: 'alice', issuer: 'https://id.example.com' } as const;
@@ -118,7 +118,7 @@ node -e "console.log(Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toS
 ```
 
 ```ts
-import { createAgent, fileStore, generateTokenKey } from 'lousho';
+import { createAgent, fileStore, generateTokenKey } from '@linuxdevil/lousho';
 
 console.log(generateTokenKey()); // store it as a secret, e.g. LOUSHO_TOKEN_KEY
 
@@ -174,7 +174,7 @@ Define the provider once, at module level next to the tools that use it, with
 `defineOAuthProvider()`. A tool asks for a token with `ctx.getToken(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, defineTool, memoryStore } from 'lousho';
+import { createAgent, defineOAuthProvider, defineTool, memoryStore } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const github = defineOAuthProvider({
@@ -239,7 +239,7 @@ the agent's credential for every user: without the token the call fails with
 The operator signs the app in once with `agent.oauth.signInUrl(provider)`:
 
 ```ts
-import { createAgent, defineOAuthProvider, fileStore } from 'lousho';
+import { createAgent, defineOAuthProvider, fileStore } from '@linuxdevil/lousho';
 
 const slackBot = defineOAuthProvider({
   name: 'slack_bot',
@@ -322,7 +322,7 @@ link continues the run by approving the pause. Serving your own route, do the
 same:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 
@@ -396,8 +396,8 @@ token store (encrypted by the persistent stores) under the provider name
 one.
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({
   provider,
diff --git a/observability.mdx b/observability.mdx
index 5d41bc4..719ed0c 100644
--- a/observability.mdx
+++ b/observability.mdx
@@ -23,14 +23,14 @@ mapping.
 Pass an `exporter` to `createAgent()`; every run of the agent (`send()`,
 `stream()`, session turns, `resume()` and runs continued by
 `agent.approvals.resolve()`) is traced, sub-agents included. To keep traces
-on disk and browse them with `npx lousho traces`, use `fileTraceExporter()`
+on disk and browse them with `npx @linuxdevil/lousho traces`, use `fileTraceExporter()`
 (see [Local traces](#local-traces)). The `vendor/` model prefix chooses the
 provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -48,8 +48,8 @@ reported once per exporter with `console.warn` and otherwise ignored.
 With the executor, pass the exporter to `AgentExecutor.execute()`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 const exporter: TraceExporter = {
   onSpanStart: (span) => console.log('[start]', span.kind, span.name),
@@ -60,7 +60,7 @@ await AgentExecutor.execute({ agent, input, provider, toolRegistry, exporter });
 ```
 
 For real OpenTelemetry spans, import `createOtelTraceExporter()` from
-`lousho/otel` (needs the optional peer dependency
+`@linuxdevil/lousho/otel` (needs the optional peer dependency
 `@opentelemetry/api` and a registered `TracerProvider`). It carries span kind
 and error status over to OpenTelemetry. See `examples/tracing`
 (`npm run example:tracing:console`, `npm run example:tracing:otel`, which also prints metrics).
@@ -88,7 +88,7 @@ To put several runs in one trace, pass a span id of yours as `parentSpanId`;
 the run's `invoke_agent` span becomes its child, and its cost rolls up into it:
 
 ```ts
-import { withSpan, type SimpleAgent, type TraceExporter } from 'lousho';
+import { withSpan, type SimpleAgent, type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 declare const planner: SimpleAgent;
@@ -139,6 +139,18 @@ Constants for every name live in `src/execution/semconv.ts` (exported as
 | `lousho.subagent.name` | On a sub-agent's run: the name the lead knows it by (the `task` tool's `agent`) |
 | `lousho.subagent.depth` | On a sub-agent's run: `1` for a sub-agent of the top-level run, `2` for its sub-agent, and so on |
 | `lousho.task.id` | On a sub-agent's run started by `task`: the task's `taskId` |
+| `lousho.harness.revision` | The harness revision: a sha256 of the instructions and skills, the same id `harnessHash` gives and `lousho improve` records. Two agents with the same instructions and skills share it. Absent when the instructions are a function or come from the prompt registry. It covers `instructions` and `skills` only: `projectInstructions` (AGENTS.md), a per-send `instructions` addition and the tools are not part of it, and an `instructions/<family>.md` tail is, so such a run matches no saved revision. `lousho traces` shows its first 12 characters |
+| `lousho.workspace` | On a workspace page run: the workspace id |
+| `lousho.page` | On a workspace page run: the flat page id |
+| `lousho.attachment` | On a workspace page run: the attachment alias from `agents.json` that ran the step |
+| `lousho.execution_type` | On a workspace page run: the page's execution type (`single`, `multi-agent`, `workflow` or `goal-oriented`) |
+| `lousho.step.kind` | On a workspace page run: `single`, `workflow-step`, `delegate` or `goal-iteration`, the same on every engine |
+| `lousho.step.index` | On a workspace page run: the step's position in one sequence across the run, from 0 |
+| `lousho.harness.hash` | On a workspace page run: the composed harness hash, so two pages sharing an agent differ here |
+| `lousho.harness.part_hash` | On a workspace page run: the hash of the harness part of the assembled prompt |
+| `lousho.agent.ref.version` | On the run of an agent from a `global:` ref: the resolved version |
+| `lousho.agent.ref.sha256` | On the run of an agent from a `global:` ref: the sha256 of the resolved agent |
+| `lousho.workspace.revision` | Reserved for the workspace revision of a run; not set yet |
 
 #### Summing token usage over spans
 
@@ -243,7 +255,7 @@ duration metric, only the model and tool calls inside them.
 ```ts
 import { metrics } from '@opentelemetry/api';
 import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
-import { createOtelTraceExporter } from 'lousho/otel';
+import { createOtelTraceExporter } from '@linuxdevil/lousho/otel';
 
 // Swap ConsoleMetricExporter for an OTLP exporter to reach any backend.
 metrics.setGlobalMeterProvider(
@@ -313,7 +325,7 @@ piece of plain text (before JSON encoding) and returns what to record; if it
 throws, that text is recorded as `[redacted]` and the run carries on:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 createAgent({
   model: 'openai/gpt-4o-mini',
@@ -329,8 +341,8 @@ createAgent({
 With the executor, opt in per run:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { type TraceExporter } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { type TraceExporter } from '@linuxdevil/lousho';
 
 declare const exporter: TraceExporter;
 
@@ -386,13 +398,13 @@ governs only the `gen_ai.*` content attributes.
 
 ## Local traces
 
-`fileTraceExporter()` from `lousho/traces` writes each run to a
+`fileTraceExporter()` from `@linuxdevil/lousho/traces` writes each run to a
 file, and `lousho traces` shows the files in the terminal. No OpenTelemetry
 backend, no extra package.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { fileTraceExporter } from 'lousho/traces';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { fileTraceExporter } from '@linuxdevil/lousho/traces';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -412,10 +424,10 @@ const agent = createAgent({
 Then, from the project directory:
 
 ```bash
-npx lousho traces                 # the 20 most recent runs, newest first
-npx lousho traces --limit 50 --json
-npx lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
-npx lousho traces 3f2a --content  # also the captured messages and tool arguments
+npx @linuxdevil/lousho traces                 # the 20 most recent runs, newest first
+npx @linuxdevil/lousho traces --limit 50 --json
+npx @linuxdevil/lousho traces 3f2a            # one run as a tree; a unique id prefix is enough
+npx @linuxdevil/lousho traces 3f2a --content  # also the captured messages and tool arguments
 ```
 
 ```
@@ -479,6 +491,15 @@ is printed per process and reporting stays off. `LOUSHO_OBSERVE_PROJECT` labels
 the rows; `LOUSHO_OBSERVE_TOKEN` sends a bearer token for daemons bound
 beyond loopback (`--require-token` plus `lousho observe token create`).
 
+`LOUSHO_OBSERVE_PROJECT` also decides where an agent lands in
+[Lousho Studio](/agent-forge): set it to a workspace id (shown in Studio's
+**Settings → Workspaces**) and the agent's observed card appears under that
+workspace; unset, the project name is the package name and the agent appears
+under **Elsewhere**. Studio reads the same collector - it attaches to a
+running daemon or starts one itself on loopback (see
+[The collector](/agent-forge#the-collector)) - so a deployed agent that
+reports to Studio's collector shows up with no Studio-specific code.
+
 **Security.** Because the loopback daemon takes no token, it refuses requests
 a web page in your browser could forge. On every `/api/*` route:
 
@@ -498,15 +519,40 @@ check comes first.
 
 One SQLite file (default `~/.lousho/observe.db`, WAL mode) holds the fleet's
 observations, sessions, eval scores, prompt versions and shared context.
-`npx lousho studio` renders it (see [Agent Forge](/agent-forge#screens)):
+`npx @linuxdevil/studio` renders it (see [Lousho Studio](/agent-forge#screens)):
 Traces and Trace (trace trees with latency waterfalls), Threads, Monitoring
 (a live fleet monitor with heartbeat-derived status — a crashed agent's open
 sessions flip to `interrupted` — over per-agent charts of runs, p95 latency,
 error rate, cost and tokens), Scores, Datasets, Evaluators, Annotation
 queues, Prompts and Context Hub. The Studio's nav shows whether it can reach
-the daemon. Alerts on `down` transitions or
-error-rate thresholds POST to `--webhook` URLs or an `alerts.json` next to
-the db.
+the daemon. Alerts on `down` transitions,
+error-rate thresholds and score regressions (see
+[Continuous score](#continuous-score)) POST to `--webhook` URLs or an
+`alerts.json` next to the db.
+
+`lousho improve --watch` posts to the same `alerts.json` webhooks:
+`improve.pending`, `improve.applied`, `improve.rolled_back`,
+`improve.guard_failed`, `improve.paused` and `improve.canary`. `details` holds
+`{ agent, dir, from, to, reason, cycle }`, plus `card`, the local path of a
+pending proposal. A regression the monitor or a scheduled guard saw but did
+not roll back (automatic rollback off, or refused) is `improve.guard_failed`,
+posted once per revision. The reason is plain text: links, images and markup are
+stripped. Each event is also one stderr line, and a webhook that fails never
+fails the cycle.
+
+The sweep also records each `agent.score_regression` in the db's
+`score_regressions` table, with or without webhooks. A running
+`lousho improve --watch` polls it every tick and starts a cycle with
+`trigger: 'score'` for a regression of the agent's current revision, instead
+of waiting for new failed runs; every budget, the cooldown and the kill switch
+still apply. The daemon never writes to an agent directory. A watcher lists
+itself in `watchers.json` beside the db while it runs (informational: the sweep
+records every regression, once per agent and revision, across daemon restarts).
+A score cycle learns from the revision's failed and low-scored runs; a
+regression with neither ends `idle`. The `score_regressions` table is a schema
+migration, so once this daemon has opened a db, a process on an older `lousho`
+refuses it with `LOUSHO_STORAGE_FAILED`; upgrade every process that shares the
+db. See [Running it continuously](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/improve.md#running-it-continuously).
 
 Insights averages runs/day over the days an agent was active in the window
 (from the later of the window start and the agent's first sighting), so an
@@ -867,6 +913,90 @@ count goes to stderr) unless `--out` names a file, which is overwritten. It
 reads the db directly and works without a running daemon. Captured content is
 exported as stored, so treat the file like the db.
 
+### Continuous score
+
+Each finished run of an agent becomes one point in a series, oldest first:
+
+- the mean of the run's finished online evaluator scores, when it has any;
+- otherwise 0 when the run is in the failure report (a failed call, no
+  answer, an interrupted process or a low score), and 1 when it is not.
+
+A point of 0.5 or more counts as a pass. Scores still without a value, and
+runs still in flight, are left out. Each point carries the run's
+`lousho.harness.revision`, so a series can be cut to one revision.
+
+The trajectory gate from the Self-Healing Harness paper judges the shape of
+the series rather than one number. It works on the rolling mean of 10
+points:
+
+- The first full window (10 points) sets a running peak.
+- A later window mean at least 0.02 above the peak is a gain, which raises
+  the peak.
+
+The gate judges the newest window:
+
+| State | When |
+| --- | --- |
+| `regression` | The newest window's mean is more than 0.15 below the peak, **and** the newest window sits significantly below the points before it (one-sided 95%, on the pass rate or on the mean value) |
+| `stall` | 10 windows have passed since the last gain while the peak is below 0.5, so a stall needs at least 20 points |
+| `ok` | Neither. This covers a low start that keeps improving, a plateau above 0.5, and a dip that has recovered |
+
+The significance check is the paper's corroboration step. A drop of 0.15 is
+only one or two failures in a window of pass/fail runs, so the shape alone
+would fire on most healthy agents. The test depends on the values:
+
+- for pass/fail values it compares pass rates (Newcombe's interval from
+  Wilson bounds);
+- otherwise it compares means (Welch's t).
+
+One judgement of a stable series reads `regression` about 5% of the time.
+Before the first full window the gate reports `ok` with `ready: false`.
+
+The daemon does not judge on every run, because repeating the test would add
+up to false alarms. It waits until an agent has 20 finished runs. After
+that, each time 10 new runs have arrived, it runs the gate over the last 200
+points at a stricter z of 1.96. The long lookback keeps the old baseline in
+view when a lasting drop fills recent runs. It raises an
+`agent.score_regression` alert only after three judgements in a row read
+`regression`.
+
+These are simulated figures for pass/fail agents (1,000 seeded streams each).
+
+A stable agent with a pass rate between 0.6 and 0.95 raised a false alert in
+under 1% of 1,000-run stretches.
+
+When 200 runs at the old rate were followed by 100 at the new one, the fall
+was caught within those 100 runs this often:
+
+| Fall | Caught |
+| --- | --- |
+| 0.9 → 0.1 | always |
+| 0.9 → 0.5 | about 80% |
+| 0.9 → 0.6 | about half |
+| 0.7 → 0.4 | about 1 in 5 |
+
+The alert fires at most once per agent per revision. The revision is that of
+the newest run, and `null` when that run has no stamp.
+The alert's `details` carry:
+
+- `revision`, `peak`, `mean` and `drop`;
+- `since_gain` and the number of `runs`;
+- `recent`: a summary of the newest 10 runs.
+
+The daemon keeps this memory only while it delivers alerts, and starts it
+afresh on restart. A failure in this pass is logged and never costs the
+sweep its other alerts.
+
+`lousho observe score [--agent X] [--revision R] [--limit N] [--json]` prints
+the same view for each agent from the db:
+
+- runs, mean, and the pass rate with its one-sided 95% Wilson lower bound;
+- pass^3, the chance that three independent runs all pass;
+- the gate state.
+
+Without `--revision`, the line covers every revision in the window and names
+the latest one. It reads the db directly and works without a running daemon.
+
 ### Trace list API
 
 `GET /api/v1/traces` returns `{ traces, total, limit, offset }`, one row per
diff --git a/openapi-tools.mdx b/openapi-tools.mdx
index 032aa2a..854e9cf 100644
--- a/openapi-tools.mdx
+++ b/openapi-tools.mdx
@@ -9,15 +9,15 @@ the API without a hand-written `defineTool()` per endpoint and without the raw
 [`http` tool](/tools#built-in-tools). Operations that change data ask for
 [approval](/approvals) by default.
 
-`openApiTools` is exported from `lousho` and
-`lousho/tools`. It needs no extra package. The `vendor/` model
+`openApiTools` is exported from `@linuxdevil/lousho` and
+`@linuxdevil/lousho/tools`. It needs no extra package. The `vendor/` model
 prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>`
 (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ## Quick start
 
 ```ts
-import { createAgent, openApiTools } from 'lousho';
+import { createAgent, openApiTools } from '@linuxdevil/lousho';
 
 const tools = await openApiTools('https://api.example.com/openapi.json', {
   include: ['getOrder', 'refundOrder'],
@@ -78,7 +78,7 @@ destructiveHint: false` on GET, HEAD and OPTIONS; `readOnlyHint: false` on the
 rest, with `destructiveHint: true` for DELETE. Anything that reads annotations treats these tools the way it treats MCP tools.
 
 ```ts
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
@@ -96,7 +96,7 @@ never sees it) and added to the request. The value can be a function, called per
 request with the operation and the tool call id.
 
 ```ts
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 declare const currentTenant: () => string;
@@ -167,7 +167,7 @@ An API with hundreds of operations is hundreds of tools. Give the agent the ones
 it needs with `include` or `exclude`, or with a predicate on `op.tags`:
 
 ```ts
-import { openApiTools } from 'lousho';
+import { openApiTools } from '@linuxdevil/lousho';
 
 declare const spec: object;
 
diff --git a/pause-and-resume.mdx b/pause-and-resume.mdx
index 3a74da3..b838bec 100644
--- a/pause-and-resume.mdx
+++ b/pause-and-resume.mdx
@@ -13,7 +13,7 @@ section links to the page that has the full detail.
 Set `needsApproval` on the tool. The run pauses before the tool executes:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 export const refund = defineTool({
@@ -41,9 +41,9 @@ shared by several processes on one host) or `fileStore(dir)` (plain JSON files).
 `finishReason: 'awaiting-approval'` and the id to decide:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -78,9 +78,9 @@ run left in the store. `agent.approvals.resolve()` runs the call (or rejects it)
 continues the run, and resolves with the result:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const refund = defineTool({
@@ -135,8 +135,8 @@ This snippet stands in for the crash with a tool that throws
 step), then recovers:
 
 ```ts
-import { createAgent, defineTool, memoryStore, PropagatingToolError } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool, memoryStore, PropagatingToolError } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let charges = 0;
diff --git a/permission-modes.mdx b/permission-modes.mdx
index c04e061..0861132 100644
--- a/permission-modes.mdx
+++ b/permission-modes.mdx
@@ -9,8 +9,8 @@ pause (`dontAsk`). Switch it in the middle of a session, the way you would work
 with a coding agent: plan first, then let it edit.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const agent = createAgent({
@@ -76,7 +76,7 @@ says nothing is treated as one with side effects and is refused.
 Declare a custom read-only tool like this:
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookUpOrder = defineTool({
@@ -98,7 +98,7 @@ The hint is a promise you make about your tool: plan mode trusts it.
 alone, so a tool of your own named `write_file` is not approved silently.
 
 ```ts
-import { defineTool } from 'lousho';
+import { defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const appendLine = defineTool({
@@ -143,7 +143,7 @@ Switching is always an explicit call to `setPermissionMode()`. Each switch is
 reported to `onPermissionModeChange` with `{ sessionId, from, to, at }`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider,
diff --git a/prompting-techniques.mdx b/prompting-techniques.mdx
index 9f454de..d20adb1 100644
--- a/prompting-techniques.mdx
+++ b/prompting-techniques.mdx
@@ -62,8 +62,8 @@ The four operations, and where each lives in the SDK:
 | **Isolate** | Run work in a clean context so detail doesn't flood the lead | Sub-agents (`task` calls see only their prompt), code mode (`run_code` returns one value), the `inputFilter` boundary |
 
 ```ts
-import { createAgent, loadSkills } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const provider = mockModel([{ text: 'done' }]);
 const researchAgent = createAgent({ provider, instructions: 'You research one slice.' });
diff --git a/providers.mdx b/providers.mdx
index e070c85..b05ba95 100644
--- a/providers.mdx
+++ b/providers.mdx
@@ -12,7 +12,7 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { resolveProvider, LLMProviderRegistry } from 'lousho';
+import { resolveProvider, LLMProviderRegistry } from '@linuxdevil/lousho';
 
 // The convenient way — reads the credential from the environment
 const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
@@ -34,6 +34,32 @@ The `google/` prefix needs the optional `@ai-sdk/google` package (`^1.2.0` with
 `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with `ai` 7) and reads
 `GOOGLE_GENERATIVE_AI_API_KEY`, the variable `@ai-sdk/google` itself uses.
 
+### Any AI SDK vendor by name
+
+Every official `@ai-sdk/*` provider resolves from a model string too. Install
+the vendor's package (`^1.0.0` with `ai` 4, `^3.0.0` with `ai` 6, `^4.0.0` with
+`ai` 7); it is loaded on the first call and reads its own credentials
+(`MISTRAL_API_KEY`, `GROQ_API_KEY`, the AWS chain for Bedrock, and so on).
+
+```ts
+import { createAgent } from '@linuxdevil/lousho';
+
+createAgent({ model: 'mistral/mistral-large-latest' });   // @ai-sdk/mistral
+createAgent({ model: 'bedrock/anthropic.claude-sonnet' }); // @ai-sdk/amazon-bedrock
+createAgent({ model: 'vertex/gemini-2.5-pro' });           // @ai-sdk/google-vertex
+createAgent({ model: 'ai-sdk/cohere/command-r' });         // any @ai-sdk/<vendor>
+```
+
+The named prefixes are `azure`, `bedrock` (or `amazon-bedrock`), `vertex` (or
+`google-vertex`), `mistral`, `groq`, `xai`, `deepseek`, `cerebras`, `together`
+(or `togetherai`), `fireworks`, `deepinfra`, `cohere`, `perplexity`, `baseten`,
+`huggingface` and `vercel`. `ai-sdk/<vendor>/<model>` loads `@ai-sdk/<vendor>`
+for any other vendor, including ones newer than your Lousho version. A missing
+package fails on the first call with
+[`LOUSHO_PEER_MISSING`](/errors#lousho_peer_missing) and the install
+command. A provider you add with `LLMProviderRegistry.register()` under the
+same name wins over the AI SDK package.
+
 ### Vendors without a prefix
 
 A prefix the SDK does not know fails with
@@ -66,7 +92,7 @@ it anyway:
    present. With none set it throws an error listing the fixes.
 
 ```ts
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const fromString = createAgent({ model: 'anthropic/claude-sonnet-5-5' });
 const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
@@ -84,7 +110,7 @@ error, 5xx) twice by default, and with `fallbackModels` moves on to the next
 model when the call still fails:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -127,7 +153,7 @@ Parts sent through `createAgent()`:
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 
@@ -143,7 +169,7 @@ console.log(answer.text);
 A `Message[]` is passed through as it is; `textOf()` returns the text parts of a message:
 
 ```ts
-import { createAgent, textOf, type Message } from 'lousho';
+import { createAgent, textOf, type Message } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'Describe images briefly.', model: 'openai/gpt-4o-mini' });
 const messages: Message[] = [
@@ -202,8 +228,8 @@ console.log(textOf(messages[0]), '->', result.text);
 `AgentExecutor.execute()` takes the same messages as its `input` (see [the executor API](/executor-api)):
 
 ```ts
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { resolveProvider, type Message } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { resolveProvider, type Message } from '@linuxdevil/lousho';
 
 const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
 const input: Message[] = [
@@ -265,7 +291,7 @@ text is not retried, so it fails after one `timeout`. To fail sooner, lower
 `timeout` or `retry.maxRetries`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, timeout: 60_000 });
 ```
@@ -279,7 +305,7 @@ Pass `store: true` to have OpenAI store them (for its dashboard logs or
 evals). `store` is ignored with `api: 'chat'`.
 
 ```ts
-import { OpenAIProvider } from 'lousho';
+import { OpenAIProvider } from '@linuxdevil/lousho';
 
 const provider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, store: true });
 ```
@@ -296,7 +322,7 @@ instead. Install `undici` and pass its `Agent` as the dispatcher:
 
 ```ts
 import { Agent } from 'undici';
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 // Wait up to 15 minutes for the response headers and between body chunks.
 const dispatcher = new Agent({ headersTimeout: 15 * 60_000, bodyTimeout: 15 * 60_000 });
@@ -324,7 +350,7 @@ your function, so a failure you return from it is classified as it would be
 from the real network:
 
 ```ts
-import { OpenRouterProvider } from 'lousho';
+import { OpenRouterProvider } from '@linuxdevil/lousho';
 
 let failures = 1;
 const provider = new OpenRouterProvider({
@@ -342,7 +368,7 @@ into an `LLMProvider`, so you do not write an adapter:
 
 ```ts
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const agent = createAgent({
@@ -393,7 +419,7 @@ npm install @earendil-works/pi-ai@^1.0.3
 ```
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 // OpenRouter's `openai/gpt-4o-mini`, through pi's openrouter adapter:
 const agent = createAgent({ model: 'pi/openrouter/openai/gpt-4o-mini' });
@@ -439,7 +465,7 @@ wire format. Point `OpenAIProvider` at the server's `/v1` URL and pick the API
 it implements with `api`:
 
 ```ts
-import { createAgent, OpenAIProvider } from 'lousho';
+import { createAgent, OpenAIProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   provider: new OpenAIProvider({
@@ -492,14 +518,14 @@ Ollama's `/v1` need).
 
 ```ts
 import { createOpenAI } from '@ai-sdk/openai';
-import { createAgent, fromAiSdk } from 'lousho';
+import { createAgent, fromAiSdk } from '@linuxdevil/lousho';
 
 const local = createOpenAI({ baseURL: 'http://localhost:8080/v1', apiKey: 'any' });
 const agent = createAgent({ provider: fromAiSdk(local.chat('qwen3-8b')), instructions: 'You are a helpful assistant.' });
 ```
 
-`npx lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
-`npx lousho doctor --ping` calls `GET <base>/models` on each configured
+`npx @linuxdevil/lousho doctor` shows `OPENAI_BASE_URL` when it is set, and
+`npx @linuxdevil/lousho doctor --ping` calls `GET <base>/models` on each configured
 provider to check that the server answers.
 
 ## Vercel AI SDK versions
diff --git a/queue-and-steer.mdx b/queue-and-steer.mdx
index a96a453..8597d6e 100644
--- a/queue-and-steer.mdx
+++ b/queue-and-steer.mdx
@@ -19,7 +19,7 @@ reply gets one more step, so the model answers it in the same run. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
@@ -66,8 +66,8 @@ Without a stream, pass an `InputQueue` to `AgentExecutor.execute()` (see
 [the executor API](/executor-api)):
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
-import { InputQueue } from 'lousho';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
+import { InputQueue } from '@linuxdevil/lousho';
 
 const inputQueue = new InputQueue();
 const pending = AgentExecutor.execute({ agent, provider, input: 'Plan my trip.', inputQueue });
@@ -94,7 +94,7 @@ the user changes their mind while the agent is still thinking:
 - `applied` is `false` once the run has finished: send the input as a new turn.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Plan a weekend in Rome.');
diff --git a/quickstart.mdx b/quickstart.mdx
index 59eb3a4..d5bf697 100644
--- a/quickstart.mdx
+++ b/quickstart.mdx
@@ -21,19 +21,19 @@ npm test                 # offline tests: no API key needed
 
 To try a locally packed `create-lousho` (`npm pack`), pass the tarball's absolute path with `--package`: `npx --package=/abs/path/create-lousho-x.y.z.tgz create-lousho my-agent`. A bare `npx ../x.tgz` fails on Windows.
 
-`npx lousho init my-agent` is equivalent (pass `--provider`
+`npx @linuxdevil/lousho init my-agent` is equivalent (pass `--provider`
 and `--template`, since it runs without the interactive prompts). Inside a
-project that already has the SDK installed, `npx lousho init` works too: the
-`lousho` command comes from the SDK package, so a bare `npx lousho` outside such
+project that already has the SDK installed, `npx @linuxdevil/lousho init` works too: the
+`lousho` command comes from the SDK package, so a bare `npx @linuxdevil/lousho` outside such
 a project finds nothing to run. Without arguments, `init` asks for the
-directory, provider and template; `npx lousho init --help`
+directory, provider and template; `npx @linuxdevil/lousho init --help`
 lists every flag.
 
 Prefer to add the SDK to an existing project? Install it by hand (see
 [Installation](/installation)):
 
 ```bash
-npm install lousho ai@^7.0.0 zod
+npm install @linuxdevil/lousho ai@^7.0.0 zod
 npm install @ai-sdk/openai@^4.0.0 @ai-sdk/anthropic@^4.0.0
 ```
 
@@ -50,7 +50,7 @@ providers). The `vendor/` model prefix chooses the provider; with OpenRouter
 use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4.1-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4.1-mini', instructions: 'You are a helpful assistant.' });
 const { text } = await agent.send('Hello!');
@@ -73,7 +73,7 @@ whenever the user message mentions a tool's name, so this snippet exercises a
 real tool round trip without an LLM.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const currentDate = defineTool({
@@ -106,7 +106,7 @@ it for typed events (model text as it arrives, tool calls, step boundaries),
 and `await run.result` for the same result `send()` returns.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -132,7 +132,7 @@ sending the events to a browser.
 keeps the transcript and passes it to the model on each `send()`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a helpful assistant.',
@@ -154,12 +154,12 @@ Pass a store to keep sessions across restarts; see [Sessions](/sessions).
 Flag a tool `needsApproval` and the run pauses before calling it. `send()`
 resolves with `finishReason: 'awaiting-approval'` and an `approvalId`; your code
 (or a human) then approves or rejects the call and the run continues. Here
-`mockModel` from `lousho/testing` scripts the model's turns
+`mockModel` from `@linuxdevil/lousho/testing` scripts the model's turns
 exactly, so the tool call is certain.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const sendEmail = defineTool({
@@ -197,8 +197,8 @@ request the agent made, so you can assert on what the model was sent as well as
 on the result. No network, no key.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 let sent: string | undefined;
@@ -245,7 +245,7 @@ the mock provider otherwise - the same pattern the runnable
 [examples](https://github.com/LinuxDevil/lousho/blob/main/examples/README.md) use.
 
 ```ts
-import { createAgent, createMockProvider, resolveProvider } from 'lousho';
+import { createAgent, createMockProvider, resolveProvider } from '@linuxdevil/lousho';
 
 const provider = process.env.OPENAI_API_KEY
   ? resolveProvider('openai/gpt-4.1-mini')
@@ -268,7 +268,7 @@ into a live agent with `specToAgent()`. The same shape can be written as a
 YAML or JSON file and loaded with `loadSpec()`.
 
 ```ts
-import { specToAgent, agentSpecSchema } from 'lousho';
+import { specToAgent, agentSpecSchema } from '@linuxdevil/lousho';
 
 const spec = agentSpecSchema.parse({
   name: 'support-bot',
@@ -298,8 +298,8 @@ the same spec runs in the local dev server (chat UI at `/`, `POST /chat`,
 hot reload on save) and builds into a deployable server:
 
 ```bash
-npx lousho dev agent.yaml
-npx lousho build --target=node-server --agent=agent.yaml
+npx @linuxdevil/lousho dev agent.yaml
+npx @linuxdevil/lousho build --target=node-server --agent=agent.yaml
 ```
 
 ## Advanced: the executor API
diff --git a/react.mdx b/react.mdx
index ef7e434..f43534c 100644
--- a/react.mdx
+++ b/react.mdx
@@ -8,11 +8,11 @@ title: "React"
 render-ready state: messages with their text and tool calls, a `status` for
 the composer, and the tool call waiting for approval, if any.
 
-It lives in the `lousho/react` subpath. `react` (18 or 19) is
+It lives in the `@linuxdevil/lousho/react` subpath. `react` (18 or 19) is
 an optional peer dependency: install it in the app that uses the hook.
 
 ```tsx
-import { useLoushoAgent } from 'lousho/react';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 export function Chat() {
   const agent = useLoushoAgent({ url: '/api/agent' });
@@ -123,8 +123,8 @@ model prefix chooses the provider; with OpenRouter use
 
 ```ts
 import { createServer, type IncomingMessage } from 'node:http';
-import { createAgent } from 'lousho';
-import type { ApprovalOutcome } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import type { ApprovalOutcome } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -173,8 +173,8 @@ gets a fresh in-memory transcript and the next turn forgets the first (see
 The hook takes the agent itself, too. Called from a custom hook:
 
 ```ts
-import { createAgent } from 'lousho';
-import { useLoushoAgent } from 'lousho/react';
+import { createAgent } from '@linuxdevil/lousho';
+import { useLoushoAgent } from '@linuxdevil/lousho/react';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -194,7 +194,7 @@ event)`, a pure reducer over `AgentEvent`s and a few local actions
 exported from the same subpath, for a custom binding or a non-React client:
 
 ```ts
-import { initialAgentUIState, parseEventStream, reduceAgentEvents } from 'lousho/react';
+import { initialAgentUIState, parseEventStream, reduceAgentEvents } from '@linuxdevil/lousho/react';
 
 let state = reduceAgentEvents(initialAgentUIState, { type: 'ui.send', input: 'Weather in Paris?' });
 const response = await fetch('http://localhost:3000/api/agent', {
@@ -222,7 +222,7 @@ chat and the plan. The list carries across turns and is cleared by nothing but a
 new hook (it is not restored when the page reconnects to an existing session).
 
 ```tsx
-import { useLoushoAgent, useTodos } from 'lousho/react';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/react';
 
 export function Plan() {
   const agent = useLoushoAgent({ url: '/api/agent' });
diff --git a/reasoning.mdx b/reasoning.mdx
index 8ecc50b..d62b9f9 100644
--- a/reasoning.mdx
+++ b/reasoning.mdx
@@ -10,7 +10,7 @@ as `reasoning.*` events in `agent.stream()`, and as `result.reasoning`. The
 `openrouter/<vendor>/<model>` (e.g. `openrouter/anthropic/claude-sonnet-4.5`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'anthropic/claude-sonnet-4-5',
diff --git a/registry.mdx b/registry.mdx
index 78ab1f4..885591a 100644
--- a/registry.mdx
+++ b/registry.mdx
@@ -91,7 +91,7 @@ Each item document is:
   "files": [
     {
       "path": "tools/web-search.ts",
-      "content": "import { defineTool } from 'lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
+      "content": "import { defineTool } from '@linuxdevil/lousho';\nimport { z } from 'zod';\n\nexport default defineTool({\n  name: 'web-search',\n  description: 'Search the web',\n  input: z.object({ query: z.string() }),\n  needsApproval: true,\n  execute: async ({ query }) => {\n    const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {\n      headers: { authorization: `Bearer ${process.env.SEARCH_KEY}` },\n    });\n    return response.json();\n  },\n});\n"
     }
   ],
   "permissions": {
diff --git a/runs.mdx b/runs.mdx
index e8c733b..ddf68a7 100644
--- a/runs.mdx
+++ b/runs.mdx
@@ -28,7 +28,7 @@ same reason is on `run.done` in [streaming](/streaming) (and on `finish`,
 the deprecated `onEvent` counterpart).
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider(), maxSteps: 3 });
 const result = await agent.send('Research this thoroughly');
 if (result.finishReason === 'max-steps') console.warn(`Gave up after ${result.steps} steps`);
@@ -41,7 +41,7 @@ Pass an `AbortSignal` to stop a run: `agent.send(input, { signal })`,
 `resumeAfterApproval(..., { signal })`.
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const controller = new AbortController();
 setTimeout(() => controller.abort(), 5_000); // e.g. from a Stop button
@@ -52,7 +52,7 @@ console.log(result.finishReason); // 'aborted' if it was cancelled, else 'stop'
 For a time limit, use `AbortSignal.timeout(ms)`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 const result = await agent.send('Summarize this', { signal: AbortSignal.timeout(30_000) });
 ```
@@ -104,7 +104,7 @@ for strictly sequential execution, e.g. when your tools share state that is
 not safe to touch concurrently.
 
 ```ts
-import { createAgent, createMockProvider, defineTool } from 'lousho';
+import { createAgent, createMockProvider, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
diff --git a/schedules.mdx b/schedules.mdx
index 34bf839..996a9c3 100644
--- a/schedules.mdx
+++ b/schedules.mdx
@@ -15,7 +15,7 @@ Give a cron expression and exactly one of `prompt` (text sent to the agent as a
 new turn) or `run` (your own function).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 
@@ -61,7 +61,7 @@ server or a test exits normally. A script that does nothing but run schedules
 would therefore exit straight away; pass `keepAlive: true` for that:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, startSchedules } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, startSchedules } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const running = startSchedules(agent, [defineSchedule({ cron: '@hourly', prompt: 'Check the queue.' })], { keepAlive: true });
@@ -87,7 +87,7 @@ claim is best effort across edge locations (see
 [Durable execution](/durable-execution#run-leases)).
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
 const report = defineSchedule({ name: 'report', cron: '0 9 * * *', prompt: 'Run the daily report.' });
@@ -108,7 +108,7 @@ they show an empty transcript for a schedule id. Read a fire's report from the
 checkpoint store instead, or continue it with `agent.fork(id)`:
 
 ```ts
-import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from 'lousho';
+import { createAgent, createMockProvider, defineSchedule, fireSchedule, memoryStore } from '@linuxdevil/lousho';
 
 const store = memoryStore();
 const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider(), store });
@@ -134,7 +134,7 @@ my-agent/
 `schedules/` loads exactly as before.
 
 ```ts
-import { createAgent, resolveAgentDir, startSchedules } from 'lousho';
+import { createAgent, resolveAgentDir, startSchedules } from '@linuxdevil/lousho';
 
 const { config, schedules } = await resolveAgentDir('./my-agent');
 const agent = createAgent(config);
diff --git a/scripts/sync-sdk-docs.mjs b/scripts/sync-sdk-docs.mjs
index ccc9860..1f812d7 100644
--- a/scripts/sync-sdk-docs.mjs
+++ b/scripts/sync-sdk-docs.mjs
@@ -64,6 +64,9 @@ const PAGES = {
   'docs/auth.md': 'auth',
   'docs/registry.md': 'registry',
   'docs/agent-forge.md': 'agent-forge',
+  'docs/forge-builder.md': 'forge-builder',
+  'docs/forge-author.md': 'forge-author',
+  'docs/forge-lifecycle.md': 'forge-lifecycle',
   'docs/api-overview.md': 'api-overview',
   'docs/configuration.md': 'configuration',
   'docs/errors.md': 'errors',
diff --git a/sessions.mdx b/sessions.mdx
index 8bb38a8..07015a6 100644
--- a/sessions.mdx
+++ b/sessions.mdx
@@ -12,7 +12,7 @@ See also: [Pause, restart, resume](/pause-and-resume), a short end-to-end tutori
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 
@@ -74,7 +74,7 @@ The `vendor/` model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42', turnPolicy: 'queue' });
@@ -126,7 +126,7 @@ returns the same `AgentRun` (typed events plus a `result` promise, see
 it.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const chat = createAgent({ instructions: 'Be brief.', provider });
 const session = chat.session();
@@ -195,8 +195,8 @@ crash, a failed checkpoint write or a `PropagatingToolError` can then be
 finished later, in another process:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const agent = createAgent({ provider, store: new SqliteStore('./.lousho/agent.db') });
 
@@ -289,7 +289,7 @@ console.log(finished?.text, await agent.session({ id: 'user-42' }).pending()); /
 A `SessionStore` keeps transcripts between calls:
 
 ```ts
-import type { Message } from 'lousho';
+import type { Message } from '@linuxdevil/lousho';
 
 interface SessionStore {
   load(id: string): Promise<Message[] | undefined>;
@@ -320,7 +320,7 @@ writer in another process can still slip between, losing one turn.
   files on Windows and macOS too.
 
 ```ts
-import { createAgent, FileSessionStore } from 'lousho';
+import { createAgent, FileSessionStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider });
 const store = new FileSessionStore('./.lousho/sessions');
@@ -353,7 +353,7 @@ implementation by where the process runs:
 | In memory (`memoryStore()`) | `MemorySessionStore` | in memory | `InMemoryApprovalStore` | Tests, scripts, one process that never restarts |
 | Files (`fileStore(dir)`) | `<dir>/sessions/<id>.json` | `<dir>/checkpoints/`, `<dir>/checkpoint-history/` | `<dir>/approvals/<id>.json` | One machine, you want plain inspectable files |
 | SQLite | `store.sessions` | `store.checkpoints` | `store.approvals` | A Node server: one durable, transactional file, shared by several processes on one host (see [Sharing a SQLite file](#sharing-a-sqlite-file)) |
-| Cloudflare KV (`KVStore` from `lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](/deployment)) |
+| Cloudflare KV (`KVStore` from `@linuxdevil/lousho/kv`) | `store.sessions` | `store.checkpoints` | `store.approvals` | Workers deployments (see [Deployment](/deployment)) |
 
 Each one is an `AgentStore` part: pass them together as
 `createAgent({ store: { sessions, checkpoints, approvals } })`. `memoryStore()`,
@@ -367,7 +367,7 @@ another writer or reader has open fails for a moment with `EPERM`, `EACCES` or
 file still end with one of them (the last rename wins):
 
 ```ts
-import { createAgent, fileStore } from 'lousho';
+import { createAgent, fileStore } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider, store: fileStore('./.lousho') });
 // ./.lousho/sessions/user-42.json, ./.lousho/checkpoints/..., ./.lousho/approvals/...
@@ -404,7 +404,7 @@ session's transcript), and so are pending approvals and OAuth tokens. It
 resolves with the counts, `{ sessions, checkpoints, checkpointHistory, oauthPending }`:
 
 ```ts
-import { fileStore } from 'lousho';
+import { fileStore } from '@linuxdevil/lousho';
 
 const store = fileStore('./.lousho');
 await store.prune({ olderThanMs: 30 * 24 * 60 * 60 * 1000 }); // a month
@@ -419,8 +419,8 @@ generated Worker uses `KVCheckpointStore`, see [Deployment](/deployment)).
 re-exported from the root entry, so importing the SDK never loads it):
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db'); // or ':memory:'
 const agent = createAgent({ provider, store }); // transcripts, per-step checkpoints and approvals
@@ -485,8 +485,8 @@ starts a new session from any of them, so you can try another direction
 without losing the original conversation:
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 import { z } from 'zod';
 
 const searchFlights = defineTool({
diff --git a/skills.mdx b/skills.mdx
index 101dad3..aefb343 100644
--- a/skills.mdx
+++ b/skills.mdx
@@ -25,7 +25,7 @@ can correct itself.
 ## Skills in code
 
 ```ts
-import { createAgent, defineSkill } from 'lousho';
+import { createAgent, defineSkill } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
@@ -94,7 +94,7 @@ Use the imperative mood and link the PR.
   (both paths are listed).
 
 ```ts
-import { createAgent, loadSkills } from 'lousho';
+import { createAgent, loadSkills } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You are a release engineer.',
diff --git a/stream-events.mdx b/stream-events.mdx
index d7ad672..d41ac25 100644
--- a/stream-events.mdx
+++ b/stream-events.mdx
@@ -127,7 +127,7 @@ payload. Each event type is exported too (`TextDeltaEvent`, `ToolDoneEvent`,
 `RunDoneEvent`, ...), and `AgentEventOf<'tool.done'>` picks one by name.
 
 ```ts
-import { isAgentEvent, isToolEvent, type AgentEvent } from 'lousho';
+import { isAgentEvent, isToolEvent, type AgentEvent } from '@linuxdevil/lousho';
 
 function render(event: AgentEvent): string {
   switch (event.type) {
diff --git a/streaming.mdx b/streaming.mdx
index 43d185e..6f2fe20 100644
--- a/streaming.mdx
+++ b/streaming.mdx
@@ -14,7 +14,7 @@ provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`); `agent` is a `createAgent()` result; `input` is the user's text, a `string`; `approvalStore` is an `ApprovalStore`; `toolRegistry` is a `ToolRegistry`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -75,7 +75,7 @@ interface AgentRun extends AsyncIterable<AgentEvent> {
   throw synchronously from `stream()`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -102,7 +102,7 @@ Output guardrails still check only the final reply of a `send()`, as without
 a listener. Sub-agents' events arrive tagged with `subagent`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -153,7 +153,7 @@ save, so the transcript is complete when the loop ends. An aborted or failed
 run, or one you stop reading early, is not saved.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const session = agent.session({ id: 'user-42' });
@@ -181,7 +181,7 @@ process, since everything is read from the approval store. A model chosen per
 run (`model` as a function) is the one the paused run used.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ provider /* , a tool with needsApproval */ });
 const paused = await agent.send('Delete the old reports.');
@@ -200,7 +200,7 @@ of `resumeAfterApproval()` (see [the executor API](/executor-api)) and
 returns the same `AgentRun`.
 
 ```ts
-import { AgentExecutor, streamResumeAfterApproval } from 'lousho/executor';
+import { AgentExecutor, streamResumeAfterApproval } from '@linuxdevil/lousho/executor';
 
 const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry, approvalStore });
 const run = streamResumeAfterApproval({ id: paused.approvalId!, approved: true }, approvalStore, toolRegistry, provider);
@@ -234,7 +234,7 @@ for approval is reported once, by the top-level `approval.requested` (which
 carries the sub-agent's call).
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate.', subagents: { researcher } });
@@ -275,7 +275,7 @@ step was running) and `run.done` (`'aborted'`), and `result` resolves with
 `finishReason: 'aborted'`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 const run = agent.stream('Write a long story');
@@ -293,7 +293,7 @@ To add input to a run that is still going, or to redirect it, see [Queued input
 ## Example: terminal
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const getWeather = defineTool({
@@ -332,7 +332,7 @@ saved even when the client leaves (see [Next.js](/nextjs#routes)).
 
 ```ts
 import { createServer } from 'node:http';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini' });
 
@@ -375,7 +375,7 @@ with `{ sessionId, input }` streams `agent.session({ id }).stream(input)` as
 needs approval ends the stream with `approval.requested`:
 
 ```ts
-import { AgentExecutor } from 'lousho/executor';
+import { AgentExecutor } from '@linuxdevil/lousho/executor';
 
 const run = AgentExecutor.stream({ agent, input, provider, toolRegistry, approvalStore });
 for await (const event of run) {
diff --git a/structured-output.mdx b/structured-output.mdx
index df2e743..e49f937 100644
--- a/structured-output.mdx
+++ b/structured-output.mdx
@@ -11,7 +11,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -39,7 +39,7 @@ itself) or any other Standard Schema that can produce JSON Schema:
 
 ```ts
 import { z } from 'zod/v4';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string() }) });
 const { object } = await agent.send('Where is the Eiffel Tower?');
@@ -57,7 +57,7 @@ the tool take the data and keep `output` for a summary or status.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function postComment(comment: { file: string; body: string }): Promise<void>;
 
@@ -80,7 +80,7 @@ from the data (a claim id), because a rerun of the whole flow extracts again:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 declare function askReviewer(claim: { claimId: string; amountCents: number }): Promise<boolean>;
 declare const claims: { file(claim: { claimId: string; amountCents: number }, opts: { idempotencyKey: string }): Promise<void> };
@@ -109,7 +109,7 @@ turn. There is no per-call `output` override: the schema is the agent's.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ city: z.string(), tempC: z.number() }) });
 const session = agent.session();
@@ -139,7 +139,7 @@ read from the `object` of the remote stream's `run.done` event.
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const reporter = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -164,7 +164,7 @@ and `result.object` has no key for it. A field that accepts `null` itself
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openrouter/openai/gpt-4o-mini',
@@ -244,7 +244,7 @@ here; set `'final'` to keep it off those calls):
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o',
@@ -281,7 +281,7 @@ where a failure is yours to report:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const Invoice = z.object({ subtotal: z.number(), tax: z.number(), total: z.number() });
 const agent = createAgent({ model: 'openai/gpt-4o-mini', output: Invoice });
@@ -333,7 +333,7 @@ progress, and `result.object` for the answer. The UI bindings keep it as
 `partialObject`.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const planner = createAgent({ model: 'openai/gpt-4o-mini', output: z.object({ days: z.array(z.string()) }) });
@@ -350,8 +350,8 @@ schema, or use `createAgent()` for the inferred type.
 
 ```ts
 import { z } from 'zod';
-import { AgentBuilder, AgentExecutor } from 'lousho/executor';
-import { createMockProvider } from 'lousho';
+import { AgentBuilder, AgentExecutor } from '@linuxdevil/lousho/executor';
+import { createMockProvider } from '@linuxdevil/lousho';
 
 const Ticket = z.object({ title: z.string(), priority: z.enum(['low', 'high']) });
 const agent = AgentBuilder.create().setName('triage').setPrompt('You triage bug reports.').build();
@@ -365,8 +365,8 @@ With `mockModel`, script the JSON text the model would write:
 
 ```ts
 import { z } from 'zod';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const agent = createAgent({ provider: mockModel(['{"city":"Paris","tempC":21}']), output: z.object({ city: z.string(), tempC: z.number() }) });
 const { object } = await agent.send('Weather in Paris?');
diff --git a/sub-agents.mdx b/sub-agents.mdx
index 4373f33..c395d90 100644
--- a/sub-agents.mdx
+++ b/sub-agents.mdx
@@ -24,7 +24,7 @@ Give each sub-agent a `description` (the lead model reads it to choose), then
 pass them to the lead as `subagents`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({
   provider,
@@ -112,8 +112,8 @@ needs no code. A lead that keeps its work across turns or restarts needs a
 store and a session:
 
 ```ts
-import { createAgent } from 'lousho';
-import { SqliteStore } from 'lousho/sqlite';
+import { createAgent } from '@linuxdevil/lousho';
+import { SqliteStore } from '@linuxdevil/lousho/sqlite';
 
 const store = new SqliteStore('./.lousho/agent.db');
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
@@ -161,7 +161,7 @@ sometimes pass one sub-agent's `taskId` to another and waste a turn on the
 error; this removes the option.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const analyst = createAgent({ provider, instructions: 'You analyze.', description: 'Analyzes data' });
 const lead = createAgent({ provider, subagents: { analyst }, subagentOptions: { continuation: false } });
@@ -197,7 +197,7 @@ At most `maxConcurrent` background sub-agents of one lead run run at once
 as slots free. Set it with `subagentOptions` on `createAgent()`:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 
@@ -238,7 +238,7 @@ events arrive before the lead's `run.done`.
 The result lists every background task of the run with its final status:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const researcher = createAgent({ provider, instructions: 'You research.', description: 'Finds and summarizes sources' });
 const lead = createAgent({ provider, instructions: 'You coordinate research.', subagents: { researcher } });
@@ -290,7 +290,7 @@ Limits:
   cannot be resumed: the model chose not to wait for it.
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const shell = defineTool({
@@ -321,7 +321,7 @@ the set can change between runs; `resolve()` is called when the lead picks a
 name (return `undefined` for an unknown one).
 
 ```ts
-import { createAgent, type SubagentCatalog } from 'lousho';
+import { createAgent, type SubagentCatalog } from '@linuxdevil/lousho';
 
 const experts = new Map([
   ['researcher', createAgent({ provider, instructions: 'You research.' })],
@@ -343,7 +343,7 @@ next to local ones, and the lead delegates to it with the same `task` tool,
 including `background: true`.
 
 ```ts
-import { createAgent, remoteAgent } from 'lousho';
+import { createAgent, remoteAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -407,7 +407,7 @@ final answer becomes the `task` result; a continuation that pauses again pauses
 the lead again.
 
 ```ts
-import type { SimpleAgent } from 'lousho';
+import type { SimpleAgent } from '@linuxdevil/lousho';
 declare const lead: SimpleAgent; // the lead agent above
 
 const paused = await lead.send('Deploy the docs site');
@@ -441,7 +441,7 @@ use the ready-made Pi adapter.
 Pi's tools (`read`, `bash`, `edit`, `write`, ...) work on a local directory.
 
 ```ts
-import { createAgent, piAgent, ask, allow } from 'lousho';
+import { createAgent, piAgent, ask, allow } from '@linuxdevil/lousho';
 import { ModelRuntime } from '@earendil-works/pi-coding-agent';
 
 const runtime = await ModelRuntime.create(); // reads ~/.pi/agent auth, env keys
@@ -532,7 +532,7 @@ the enclosing sub-agent as `parent` when nested deeper. A hook that should only
 see the top-level run returns early:
 
 ```ts
-import { HookRegistry } from 'lousho';
+import { HookRegistry } from '@linuxdevil/lousho';
 
 const hooks = new HookRegistry();
 hooks.register({
@@ -568,7 +568,7 @@ sub-agents it runs inside (e.g. `['researcher']`). Approve or reject it with
 is needed):
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const lead = createAgent({
   provider,
@@ -625,8 +625,8 @@ Resume with `resumeAfterApproval()`, passing the same `subagents` option as the
 paused run:
 
 ```ts
-import { AgentExecutor, resumeAfterApproval, ToolRegistry } from 'lousho/executor';
-import { createAgent } from 'lousho';
+import { AgentExecutor, resumeAfterApproval, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { createAgent } from '@linuxdevil/lousho';
 
 const subagents = { researcher: createAgent({ provider, instructions: 'You research.', description: 'Researches' }) };
 
diff --git a/svelte.mdx b/svelte.mdx
index 595fbd0..8942d3f 100644
--- a/svelte.mdx
+++ b/svelte.mdx
@@ -9,13 +9,13 @@ sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/svelte` subpath. The store implements
+It lives in the `@linuxdevil/lousho/svelte` subpath. The store implements
 Svelte's store contract (`subscribe(run) => unsubscribe`) by hand, so it works
 with `$agent` in Svelte 4 and 5 and needs no `svelte` import: there is no peer
 dependency to install.
 
 ```ts
-import { loushoAgent } from 'lousho/svelte';
+import { loushoAgent } from '@linuxdevil/lousho/svelte';
 
 // In a component's <script lang="ts">, or a module that several components share:
 export const agent = loushoAgent({ url: '/api/agent' }, { approvalsUrl: '/api/approvals' });
@@ -74,7 +74,7 @@ snippets here):
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -86,7 +86,7 @@ the same stream as the chat, and notifies only when the list changes (see
 [React](/react#todos)).
 
 ```ts
-import { loushoAgent, loushoTodos } from 'lousho/svelte';
+import { loushoAgent, loushoTodos } from '@linuxdevil/lousho/svelte';
 
 export const agent = loushoAgent({ url: '/api/agent' });
 export const plan = loushoTodos(agent);
diff --git a/testing.mdx b/testing.mdx
index 87599ac..fd24cb4 100644
--- a/testing.mdx
+++ b/testing.mdx
@@ -3,7 +3,7 @@ title: "Testing agents"
 ---
 {/* Generated from docs/testing.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
-`lousho/testing` ships `mockModel`: a scripted, deterministic
+`@linuxdevil/lousho/testing` ships `mockModel`: a scripted, deterministic
 `LLMProvider` for unit tests. You write down what the model should say on each
 turn, run your agent, and then assert on exactly what the agent sent to the
 model. No network, no API keys, no flakiness.
@@ -17,8 +17,8 @@ npm install --save-dev vitest
 A bare string is shorthand for `{ text }`.
 
 ```ts
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel(['Hello! How can I help?']);
 const agent = createAgent({ instructions: 'You are friendly.', provider: model });
@@ -40,8 +40,8 @@ ids are generated deterministically (`call_1`, `call_2`, ...) unless you pass
 ```ts
 import { describe, it, expect, vi } from 'vitest';
 import { z } from 'zod';
-import { createAgent, defineTool } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 describe('weather agent', () => {
   it('calls get_weather and reports the result', async () => {
@@ -80,8 +80,8 @@ when the provider fails.
 
 ```ts
 import { it, expect } from 'vitest';
-import { createAgent } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 it('surfaces a provider failure', async () => {
   const model = mockModel([{ error: new Error('upstream 503') }]);
@@ -112,7 +112,7 @@ Pass a function to compute a turn from the request. It may be async and may
 return a string or any turn object.
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const model = mockModel([(req) => `You said: ${req.messages.at(-1)?.content}`]);
 const result = await model.generate({ messages: [{ role: 'user', content: 'ping' }] });
@@ -139,7 +139,7 @@ request and tells you to add a turn. To replay the final turn forever (handy for
 loop and step-limit tests), pass `{ onExhausted: 'repeat-last' }`:
 
 ```ts
-import { mockModel } from 'lousho/testing';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const looping = mockModel([{ toolCalls: [{ name: 'again' }] }], { onExhausted: 'repeat-last' });
 ```
@@ -164,8 +164,8 @@ OpenRouter use `openrouter/<vendor>/<model>` (e.g.
 `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, resolveProvider } from 'lousho';
-import { recordReplay } from 'lousho/testing';
+import { createAgent, resolveProvider } from '@linuxdevil/lousho';
+import { recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(() => resolveProvider('openai/gpt-4o-mini'), {
   cassette: './__cassettes__/refund-flow.json',
@@ -213,7 +213,7 @@ If the change is intentional, re-record the cassette (run with LOUSHO_RECORD=1,
 
 That hint assumes you wired `mode` to `LOUSHO_RECORD` as above. If you record
 some other way, pass `rerecordHint` with the command your project uses; under
-`lousho eval` the hint names `npx lousho eval --record` instead.
+`lousho eval` the hint names `npx @linuxdevil/lousho eval --record` instead.
 
 For parallel or unordered calls pass `match: 'request'`: each call finds the
 first unused entry with an identical request, in any order. Running out of
@@ -230,7 +230,7 @@ changing the schema itself still fails the match. For anything else, pass
 `normalize`:
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/users.json',
@@ -280,7 +280,7 @@ the file. Pass `redact` to scrub them (it runs on every recorded string, in both
 requests and responses, and replay applies it when matching):
 
 ```ts
-import { mockModel, recordReplay } from 'lousho/testing';
+import { mockModel, recordReplay } from '@linuxdevil/lousho/testing';
 
 const provider = recordReplay(mockModel(['ok']), {
   cassette: './__cassettes__/support.json',
diff --git a/tool-search.mdx b/tool-search.mdx
index dfad7bf..e26ba90 100644
--- a/tool-search.mdx
+++ b/tool-search.mdx
@@ -29,7 +29,7 @@ model prefix chooses the provider; with OpenRouter use
 `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const convertCurrency = defineTool({
@@ -59,7 +59,7 @@ const agent = createAgent({
 Or mark a whole MCP server: every tool it lists is deferred.
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
@@ -129,7 +129,7 @@ the search. Deferral itself is turned on by marking tools or servers
 | `search(query, tools)` | keyword ranking | Your own ranking (for example embeddings): return tool names, best first. Unknown names and duplicates are dropped. If it throws, the call is a tool error and loads nothing. |
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   model: 'openai/gpt-4o-mini',
diff --git a/tools.mdx b/tools.mdx
index 91d95ae..e0f2185 100644
--- a/tools.mdx
+++ b/tools.mdx
@@ -12,7 +12,7 @@ accepted (`createAgent({ tools: [...] })`, `ToolRegistry.register(tool)`,
 > Snippets on this page leave some names to you: `provider` is any `LLMProvider` (offline: `createMockProvider()`).
 
 ```ts
-import { defineTool, createAgent, type ToolInput, type ToolOutput } from 'lousho';
+import { defineTool, createAgent, type ToolInput, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const weather = defineTool({
@@ -161,7 +161,7 @@ The transcript message carries `isError: true`; `tool-result` events, `onToolRes
 `toolErrorMessage` to `createAgent` to replace the text of `execution` errors:
 
 ```ts
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const agent = createAgent({
   instructions: 'You answer questions about orders.',
@@ -221,7 +221,7 @@ its next model call with `finishReason: 'budget-exceeded'` and
 under `onExceeded: 'throw'`, see [Budgets](/configuration#budgets)).
 
 ```ts
-import { createAgent, defineTool } from 'lousho';
+import { createAgent, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const stats = defineTool({ name: 'stats', description: 'Weekly stats', input: z.object({}), execute: async () => (await fetch('https://stats.example.com/week')).json() });
@@ -241,7 +241,7 @@ if (result.toolErrors) console.warn(`${result.toolErrors} tool call(s) failed; t
 | `createTodoTools()` | `todo_write` / `todo_read` so an agent can plan multi-step work; see [Todo tools](#todo-tools). |
 | `askQuestionTool()`, `createAgent({ askQuestion: true })` | `ask_question`: the agent asks the user something and the run pauses until `agent.approvals.answer()`; see [Asking the user a question](/approvals#asking-the-user-a-question). |
 | `createFsTools()`, `createShellTool()` | File system and shell tools for coding agents; see [Workspace tools](/workspace-tools). |
-| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
+| `createEmailTool()`, `createSlackTool()`, `createGitHubTools()`, `createJiraTools()` (from `@linuxdevil/lousho/integrations`) | Integrations that need credentials, so they are built with options. `createSlackTool()` reads the webhook URL from `SLACK_WEBHOOK_URL` unless you pass `webhookUrl`; `createJiraTools()` takes `baseUrl`, `email` and `apiToken` explicitly (conventionally from `JIRA_BASE_URL`, `JIRA_EMAIL` and `JIRA_API_TOKEN`). |
 | `createAgent({ mcpServers })`, `connectMcp(servers)` | Every tool of MCP servers given as config (stdio `command` or HTTP `url`), named `<server>__<tool>`; see [Use MCP servers in an agent](/mcp-integration#use-mcp-servers-in-an-agent). |
 | `openApiTools(document, options)` | One tool per operation of an OpenAPI 3.0 / 3.1 document; mutating operations ask for approval. See [OpenAPI tools](/openapi-tools). |
 | `loadMcpTools(client, name)` | Every tool of a connected MCP server; see [MCP tools](/mcp-integration#tools-from-a-client-you-connected-yourself). |
@@ -279,7 +279,7 @@ the provider; with OpenRouter use `openrouter/<vendor>/<model>`, e.g.
 `openrouter/openai/gpt-4o-mini`):
 
 ```ts
-import { createAgent, createWebFetchTool } from 'lousho';
+import { createAgent, createWebFetchTool } from '@linuxdevil/lousho';
 
 const webFetch = createWebFetchTool({
   timeoutMs: 30_000, // whole request: redirects and body included
@@ -318,7 +318,7 @@ emits a `todo.updated` stream event with the new list and its counts (see
 `useTodos()` / `loushoTodos()`, so a UI shows the plan live without `onChange`.
 
 ```ts
-import { createAgent, createTodoTools, type TodoStore } from 'lousho';
+import { createAgent, createTodoTools, type TodoStore } from '@linuxdevil/lousho';
 
 const todos = createTodoTools({ onChange: (list) => console.log(list.length, 'todos') });
 const planner = createAgent({ instructions: 'Plan multi-step work, then do it.', provider, tools: todos.tools });
@@ -341,8 +341,8 @@ raw `ToolDescriptor` (a built-in tool, an MCP tool, or an existing `tool()` from
 the `ai` SDK), and `registerMany()` for a record of descriptors or an array of defined tools.
 
 ```ts
-import { ToolRegistry } from 'lousho/tools';
-import { currentDateTool, defineTool } from 'lousho';
+import { ToolRegistry } from '@linuxdevil/lousho/tools';
+import { currentDateTool, defineTool } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const lookupOrder = defineTool({
@@ -374,7 +374,7 @@ the result `null`, as does any tool that returns `undefined`: the transcript, th
 model and `tool.done` all see `null`.
 
 ```ts
-import { createAgent, defineTool, type ToolOutput } from 'lousho';
+import { createAgent, defineTool, type ToolOutput } from '@linuxdevil/lousho';
 import { z } from 'zod';
 
 const buildReport = defineTool({
diff --git a/triggers.mdx b/triggers.mdx
index 0956392..242b409 100644
--- a/triggers.mdx
+++ b/triggers.mdx
@@ -3,7 +3,7 @@ title: "Triggers"
 ---
 {/* Generated from docs/triggers.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
-A trigger adapter turns one wake-up mechanism into an agent run. The `lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](/upgrading#migrating-from-triggers).
+A trigger adapter turns one wake-up mechanism into an agent run. The `@linuxdevil/lousho/triggers` subpath is the extension point for your own mechanism (`TriggerAdapter`, `TriggerRegistry`) plus a few helpers shared with channels and schedules: the `WebhookAuth` shapes, `verifySlackSignature()` and `parseCronExpression()`. The built-in webhook, Slack and cron adapters were removed; see [Migrating from triggers](/upgrading#migrating-from-triggers).
 
 ## Choosing between triggers, channels and schedules
 
@@ -33,8 +33,8 @@ Reply semantics differ per adapter. An adapter whose reply is the open request (
 Write your own adapter by returning a handle from `listen`:
 
 ```ts
-import { createAgent, createMockProvider } from 'lousho';
-import type { TriggerAdapter } from 'lousho/triggers';
+import { createAgent, createMockProvider } from '@linuxdevil/lousho';
+import type { TriggerAdapter } from '@linuxdevil/lousho/triggers';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -57,7 +57,7 @@ handle.stop();
 The `WebhookAuth` shapes are the reference for `webhookChannel({ auth })` (see [Channels](/channels)). `checkWebhookAuth()` and `assertValidWebhookAuth()` are exported for your own handler.
 
 ```ts
-import { createAgent, createMockProvider, mountChannels, webhookChannel } from 'lousho';
+import { createAgent, createMockProvider, mountChannels, webhookChannel } from '@linuxdevil/lousho';
 
 const agent = createAgent({ instructions: 'You are helpful.', provider: createMockProvider() });
 
@@ -102,7 +102,7 @@ sent in clear text.
 `slackChannel()` verifies every request for you (see [Slack in Channels](/channels#slack)). For your own handler (slash commands, interactivity), verify the RAW body with `verifySlackSignature()`: HMAC-SHA256 over `v0:{X-Slack-Request-Timestamp}:{raw body}`, compared in constant time with `X-Slack-Signature` (`v0=<hex>`). Requests more than five minutes old, or more than a minute ahead of local time, are rejected (the timestamp is in seconds, as Slack sends it). See [Slack's documentation](https://docs.slack.dev/authentication/verifying-requests-from-slack).
 
 ```ts
-import { verifySlackSignature } from 'lousho/triggers';
+import { verifySlackSignature } from '@linuxdevil/lousho/triggers';
 
 const authentic = verifySlackSignature({
   signingSecret: process.env.SLACK_SIGNING_SECRET ?? '',
@@ -128,3 +128,33 @@ Around daylight-saving changes, a fixed-hour job whose time does not exist
 (spring forward, e.g. `30 2 * * *`) runs once at the first instant after the
 gap (03:00) instead of being skipped for the day, and a time that happens twice (fall back) fires once;
 an every-hour schedule keeps firing hourly.
+
+## Abort listeners
+
+`spec.abortListeners` cancels queued or running runs when a watched trigger's
+event matches. Each entry names a `webhook` or `channel` trigger, a `when`
+expression over the incoming event, a `match` expression pairing the trigger
+event with a run's own event, and a `scope` of `queued`, `running` or `both`:
+
+```yaml
+triggers:
+  - id: deploy-hook
+    type: webhook
+    path: /deploy
+    promptTemplate: Deploy {{body.ref}}.
+abortListeners:
+  - id: cancel-deploy
+    triggerId: deploy-hook
+    when: event.action == 'rollback'
+    match: run.event.pr == event.pr
+    scope: both
+```
+
+`when` and `match` use the same safe expression grammar as flow conditions
+(see [Flows](/flows#flow-expressions)); variable references are checked
+when the spec parses and unknown names resolve to `undefined` at runtime.
+At most 20 listeners are allowed per spec. Studio's trigger host evaluates
+them on every inbound webhook and channel event, before the event's own
+filter and dispatch, so the delivering run can never cancel itself; a
+cancelled run logs `Run cancelled by abort listener <id>` and its webhook
+response lists the cancelled run keys under `cancelled`.
diff --git a/troubleshooting.mdx b/troubleshooting.mdx
index 7157e2f..19a8616 100644
--- a/troubleshooting.mdx
+++ b/troubleshooting.mdx
@@ -4,7 +4,7 @@ title: "Troubleshooting"
 {/* Generated from docs/troubleshooting.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 This page starts from what you see and points to the cause, the fix and the page
-that explains it. First run `npx lousho doctor` ([what it checks](/installation#troubleshooting-lousho-doctor)),
+that explains it. First run `npx @linuxdevil/lousho doctor` ([what it checks](/installation#troubleshooting-lousho-doctor)),
 then, if you have an error code (`LOUSHO_...`), look it up in [Errors](/errors).
 
 ## Setup
@@ -19,7 +19,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### "The API key is not set"
 
 - **Cause:** the provider's key variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`) is not in the environment of the process that runs the agent (`LOUSHO_PROVIDER_MISSING_API_KEY`).
-- **Fix:** set it, or pass a configured provider instance. `npx lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
+- **Fix:** set it, or pass a configured provider instance. `npx @linuxdevil/lousho doctor` prints `set` or `not set` for each key, never the value. The `vendor/` model prefix chooses the provider; with OpenRouter use `openrouter/<vendor>/<model>` (e.g. `openrouter/openai/gpt-4o-mini`) — `model: 'openai/gpt-4o-mini'` needs `OPENAI_API_KEY` even when only `OPENROUTER_API_KEY` is set.
 - **More:** [the error](/errors#lousho_provider_missing_api_key).
 
 ### "Cannot find package `@ai-sdk/openai`" or "install the optional peer"
@@ -43,7 +43,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 ### The Node version is too old
 
 - **Cause:** the SDK needs Node.js 22.19 or newer (`engines.node`).
-- **Fix:** upgrade Node. `npx lousho doctor` compares your version with the requirement.
+- **Fix:** upgrade Node. `npx @linuxdevil/lousho doctor` compares your version with the requirement.
 - **More:** [Requirements](/installation#requirements).
 
 ### Ollama and zod versions disagree
@@ -142,7 +142,7 @@ environment (`LOUSHO_CONFIG_MISSING_PROVIDER`).
 
 Open an issue at [https://github.com/LinuxDevil/lousho/issues](https://github.com/LinuxDevil/lousho/issues). Include:
 
-- the output of `npx lousho doctor --json`,
+- the output of `npx @linuxdevil/lousho doctor --json`,
 - the error code (`LOUSHO_...`) and the full message,
 - the SDK version (`npm ls lousho`) and your `ai` version.
 
diff --git a/upgrading.mdx b/upgrading.mdx
index b40ef1a..992847e 100644
--- a/upgrading.mdx
+++ b/upgrading.mdx
@@ -20,7 +20,7 @@ Already on `1.0.0-alpha.19`? Skip to
 since.
 
 ```bash
-npm install lousho@^1.0.0-alpha.19
+npm install @linuxdevil/lousho@^1.0.0-alpha.19
 ```
 
 ## Import paths that moved
@@ -31,23 +31,23 @@ are unchanged apart from where they live.
 
 | Name(s) | Old import | New import |
 | ------- | ---------- | ---------- |
-| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `lousho/core` | `lousho/executor` |
-| `ToolRegistry`, `globalToolRegistry` | `lousho` or `lousho/core` | `lousho/executor` (also still in `lousho/tools`) |
-| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `lousho/core` | `lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
-| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `lousho/types` | `lousho/flows` |
-| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `lousho/tools` | `lousho/integrations` |
-| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `lousho/utils` |
-| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
-| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `lousho/utils` |
-
-The `lousho/core` subpath no longer exists; everything it
+| `AgentExecutor`, `AgentBuilder`, `ExecuteOptions`, `ResumeExecuteOptions`, `ResumeRequest`, `resumeAfterApproval()`, `streamResumeAfterApproval()`, `resumeRequest()` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` |
+| `ToolRegistry`, `globalToolRegistry` | `lousho` or `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (also still in `@linuxdevil/lousho/tools`) |
+| `ExecutionResult`, `ExecutionFinishReason` (the executor's types) | `@linuxdevil/lousho/core` | `@linuxdevil/lousho/executor` (`ExecutionResult` is also still in the root, where `createAgent()`'s result type lives) |
+| `FlowBuilder`, `FlowExecutor`, `validateFlow` and every flow type (`AgentFlow`, `EditorStep`, `FlowExecutionEvent`, ...) | `lousho` or `@linuxdevil/lousho/types` | `@linuxdevil/lousho/flows` |
+| `createJiraTools`, `createGitHubTools`, `createSlackTool`, `slackTool`, `postSlackAlert`, `createEmailTool` and their types | `lousho` or `@linuxdevil/lousho/tools` | `@linuxdevil/lousho/integrations` |
+| `EncryptionUtils`, `DTOEncryptionFilter`, `DecryptionError`, `sha256`, `generatePassword` | `lousho` | `@linuxdevil/lousho/utils` |
+| `StorageService`, `StorageServiceApprovalStore`, `LocalStorageCheckpointStore` | `lousho` | `@linuxdevil/lousho/utils` (with `createAgent()` stores, prefer `fileStore(dir)` from the root) |
+| `validateWithSchema`, `safeValidate`, `isValidEmail` and the other validators | `lousho` | `@linuxdevil/lousho/utils` |
+
+The `@linuxdevil/lousho/core` subpath no longer exists; everything it
 exported is under `/executor`.
 
 ```ts
-import { AgentExecutor, AgentBuilder, ToolRegistry } from 'lousho/executor';
-import { FlowBuilder, validateFlow } from 'lousho/flows';
-import { createSlackTool } from 'lousho/integrations';
-import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
+import { AgentExecutor, AgentBuilder, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { FlowBuilder, validateFlow } from '@linuxdevil/lousho/flows';
+import { createSlackTool } from '@linuxdevil/lousho/integrations';
+import { EncryptionUtils, validateWithSchema } from '@linuxdevil/lousho/utils';
 ```
 
 ## Removed APIs and their replacements
@@ -79,13 +79,13 @@ import { EncryptionUtils, validateWithSchema } from 'lousho/utils';
 
 ```ts
 // Before (alpha):
-import { createDelegateTool } from 'lousho';
+import { createDelegateTool } from '@linuxdevil/lousho';
 const delegate = createDelegateTool({ agent: billing, name: 'billing' });
 ```
 
 ```ts
 // After (1.0): the lead gets a `task` tool per sub-agent.
-import { createAgent } from 'lousho';
+import { createAgent } from '@linuxdevil/lousho';
 
 const billing = createAgent({ model: 'openai/gpt-4o-mini', instructions: 'You answer billing questions.' });
 const lead = createAgent({
@@ -118,7 +118,7 @@ results and behavior are unchanged; `SECRET_PATTERNS` keeps its name. See
 
 ## Migrating from triggers
 
-`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](/triggers).
+`WebhookTriggerAdapter`, `SlackTriggerAdapter`, `CronTriggerAdapter` and their option/handle types were removed from `@linuxdevil/lousho/triggers`. `TriggerAdapter`, `TriggerRegistry`, the `WebhookAuth` helpers, `verifySlackSignature()` and `parseCronExpression()` stay. See [Triggers](/triggers).
 
 | Removed | Replacement |
 | ------- | ----------- |
@@ -290,7 +290,7 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | `agent.stream()` rethrows the run's error after the `error` and `run.done` events. See [Streaming](/streaming). | `stream(input, { throwOnError: false })` |
 | `send([])` throws `LOUSHO_CONFIG_INVALID`. | no opt-out |
 
-### CLI, evals and Agent Forge
+### CLI, evals and Studio
 
 | Change | Opt-out |
 | ------ | ------- |
@@ -305,7 +305,30 @@ there is one. A change marked "no opt-out" closed a security or data-loss bug.
 | The observe daemon prunes old data by default: on its first sweep and then once a day it deletes every trace whose observations all finished more than 30 days ago, with that trace's scores and prompt-use links, and sessions that are no longer `active`, ended before the window and no longer referenced. A trace with a run still open, active sessions, the Insights rollups, prompts, hub entries, the agent registry, tokens, datasets, evaluator rules and annotation queues are never pruned. See [Retention](/observability#retention). | `lousho observe start --retention-days 0` keeps everything (or `N` for another window) |
 | `lousho mcp --port N` or `--host H` without `--http` is a usage error (exit 2); stdio has no port. | drop the flags, or add `--http` |
 | The `package.json` of a node-server or docker build no longer lists `lousho` (the bundle contains it). | add it yourself if other code next to the build imports the SDK |
-| The npm package no longer ships `dist/cli/*.js` (the CommonJS CLI build) or `dist/cli/*.d.ts`; `bin/lousho.js` never loaded them. | run the CLI through `bin/lousho.js` (`npx lousho`) |
+| The npm package no longer ships `dist/cli/*.js` (the CommonJS CLI build) or `dist/cli/*.d.ts`; `bin/lousho.js` never loaded them. | run the CLI through `bin/lousho.js` (`npx @linuxdevil/lousho`) |
+| The npm package no longer ships Studio (`apps/agent-forge`); `lousho studio` is now a launcher that finds an installed `@linuxdevil/studio`. | `npm i -g @linuxdevil/studio` (or `npx @linuxdevil/studio`); see below |
+
+### Studio moved to its own package
+
+Lousho Studio is published separately as `@linuxdevil/studio` and is no longer
+part of the `@linuxdevil/lousho` tarball. What to do:
+
+- Install it once: `npm i -g @linuxdevil/studio`, then run `lousho-studio`.
+  Or run `npx @linuxdevil/studio`. `lousho studio` inside a project keeps
+  working - it finds the installed Studio and opens that folder as a
+  workspace; with none installed it prints
+  `Studio is a separate install: npx @linuxdevil/studio`.
+- Studio-wide settings and secrets moved from a project's `.lousho/` to
+  `~/.lousho/studio/`. On first launch Studio offers **Import settings and
+  keys from &lt;workspace>** once and copies them; the originals stay put.
+- `lousho studio --prod`/`--dev` now only apply inside the SDK's own
+  repository checkout; an installed Studio is always the production build.
+- A workspace's agents run on the project's own `@linuxdevil/lousho` through
+  `lousho bridge` when the installed SDK is new enough; older SDKs make the
+  workspace read-only until updated (the banner names the minimum). Studio
+  and the SDK update independently.
+
+See [Lousho Studio](/agent-forge) for the full picture.
 
 ## What 1.0 promises
 
diff --git a/utilities.mdx b/utilities.mdx
index 57f5a00..43e5d5f 100644
--- a/utilities.mdx
+++ b/utilities.mdx
@@ -1,13 +1,13 @@
 ---
 title: "Utilities"
-description: "Supporting helpers exported from the lousho/utils subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one."
+description: "Supporting helpers exported from the @linuxdevil/lousho/utils subpath: encryption and hashing, and file storage for attachments. None of them is needed to build an agent; they are here for the apps around one."
 ---
 {/* Generated from docs/utilities.md in LinuxDevil/lousho by scripts/sync-sdk-docs.mjs. Do not edit here. */}
 
 ## Encryption and hashing
 
 ```ts
-import { EncryptionUtils, sha256 } from 'lousho/utils';
+import { EncryptionUtils, sha256 } from '@linuxdevil/lousho/utils';
 
 const encryption = new EncryptionUtils('your-secret-key');
 const encrypted = await encryption.encrypt('sensitive data'); // fresh random salt every call
@@ -28,7 +28,7 @@ as-is. It is also what `StorageServiceApprovalStore` and
 `LocalStorageCheckpointStore` write through.
 
 ```ts
-import { StorageService } from 'lousho/utils';
+import { StorageService } from '@linuxdevil/lousho/utils';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
diff --git a/vue.mdx b/vue.mdx
index b4ed23e..f129208 100644
--- a/vue.mdx
+++ b/vue.mdx
@@ -9,11 +9,11 @@ the same sources, the same state and the same actions, over the same
 field means, the two kinds of source, how approvals work and the server side;
 this page covers what differs.
 
-It lives in the `lousho/vue` subpath. `vue` (3.x) is an
+It lives in the `@linuxdevil/lousho/vue` subpath. `vue` (3.x) is an
 optional peer dependency: install it in the app that uses the composable.
 
 ```ts
-import { useLoushoAgent } from 'lousho/vue';
+import { useLoushoAgent } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const { messages, status, pendingApproval, send, stop, approve, reject, reset } = useLoushoAgent(
@@ -62,7 +62,7 @@ and in the template:
 
 The reducer and the stream parser are exported from this subpath too
 (`reduceAgentEvents`, `initialAgentUIState`, `parseEventStream`), the same
-ones as in `lousho/react`.
+ones as in `@linuxdevil/lousho/react`.
 
 ## Todos
 
@@ -73,7 +73,7 @@ shows the plan of an agent with the [todo tools](/tools#todo-tools) live, from
 the same stream as the chat (see [React](/react#todos)).
 
 ```ts
-import { useLoushoAgent, useTodos } from 'lousho/vue';
+import { useLoushoAgent, useTodos } from '@linuxdevil/lousho/vue';
 
 // In <script setup>:
 const agent = useLoushoAgent({ url: '/api/agent' });
diff --git a/workspace-tools.mdx b/workspace-tools.mdx
index 862e48a..d29f559 100644
--- a/workspace-tools.mdx
+++ b/workspace-tools.mdx
@@ -12,7 +12,7 @@ sandbox such as E2B, Daytona or Cloudflare.
 For a walkthrough, see [Build a coding agent](/build-a-coding-agent).
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' }); // every path is confined to this directory
 const agent = createAgent({
@@ -36,7 +36,7 @@ if (paused.finishReason === 'awaiting-approval') {
 predicate that returns `false` for the commands you trust.
 
 ```ts
-import { createAgent, NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const agent = createAgent({
@@ -64,8 +64,8 @@ the same, and `resumeAfterApproval(...)` is what `agent.approvals.resolve()`
 calls once a human approves:
 
 ```ts
-import { AgentExecutor, ToolRegistry } from 'lousho/executor';
-import { NodeWorkspace, createFsTools, createShellTool } from 'lousho';
+import { AgentExecutor, ToolRegistry } from '@linuxdevil/lousho/executor';
+import { NodeWorkspace, createFsTools, createShellTool } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' }); // every path is confined to this directory
 const registry = new ToolRegistry();
@@ -119,7 +119,7 @@ has `timedOut: true` or `aborted: true` and a `note` saying why.
 | `name`             | `'shell'` | Tool name. |
 
 ```ts
-import { createShellTool, NodeWorkspace } from 'lousho';
+import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
 const shell = createShellTool(new NodeWorkspace({ root: '.' }), {
   needsApproval: (command) => !/^(ls|cat|git (status|diff|log))\b/.test(command), // read-only commands run without asking
@@ -146,8 +146,8 @@ agent created is deleted, one it edited or overwrote gets its content back.
 With `dryRun: true` it changes nothing and returns the same report.
 
 ```ts
-import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, MemoryWorkspace, WorkspaceCheckpoints } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({ files: { 'notes.md': '# Notes\n' } });
 const checkpoints = new WorkspaceCheckpoints(workspace); // backups in memory; FileWorkspaceCheckpointStore keeps them on disk
@@ -284,7 +284,7 @@ A `deny` you pass **replaces** the defaults, it does not extend them: list
 'secrets']` (entry names, not paths), or pass `deny: []` to turn the check off.
 
 ```ts
-import { createFsTools, NodeWorkspace } from 'lousho';
+import { createFsTools, NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: '.' });
 const tools = createFsTools(workspace, { readOnly: true, deny: ['.git', '.env', '.env.*'] });
@@ -332,7 +332,7 @@ Node's process launcher also adds the session variables every process needs
 them is a secret.
 
 ```ts
-import { NodeWorkspace } from 'lousho';
+import { NodeWorkspace } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({
   root: './project',
@@ -371,7 +371,7 @@ refused command is never offered for approval:
   returns `true` for the rest of the line (`''` when there is none):
 
   ```ts
-  import { createShellTool, NodeWorkspace } from 'lousho';
+  import { createShellTool, NodeWorkspace } from '@linuxdevil/lousho';
 
   const workspace = new NodeWorkspace({ root: '.' });
   createShellTool(workspace, {
@@ -434,7 +434,7 @@ you pass, nothing from the host. File tools can keep using `NodeWorkspace`
 on the same directory:
 
 ```ts
-import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const workspace = new NodeWorkspace({ root: './project' });
 const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: workspace.root });
@@ -490,7 +490,7 @@ list is only enforced when a proxy is the container's only way out.
    before; the network stays for the sandbox's next run until `close()`.
 
 ```ts
-import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; it never enters the container
 const broker = await createCredentialBroker({ rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } } });
@@ -546,7 +546,7 @@ the SDK's tests exercise the wiring against a fake Docker client, not a live
 daemon.
 
 ```ts
-import { createShellTool, SandboxShell, SubprocessSandbox } from 'lousho';
+import { createShellTool, SandboxShell, SubprocessSandbox } from '@linuxdevil/lousho';
 
 const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: 'none' });
 const shell = new SandboxShell(sandbox, {
@@ -577,7 +577,7 @@ local HTTP proxy that adds the auth headers to requests for the hosts you
 name, so the command only ever sees the proxy's address.
 
 ```ts
-import { createCredentialBroker, NodeWorkspace } from 'lousho';
+import { createCredentialBroker, NodeWorkspace } from '@linuxdevil/lousho';
 
 const token = 'ghp_example'; // read from your secret store; never passed to the command
 const broker = await createCredentialBroker({
@@ -638,7 +638,7 @@ custom tool could call it directly. Throw `WorkspaceError` with a readable
 message on failure.
 
 ```ts
-import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from 'lousho';
+import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from '@linuxdevil/lousho';
 
 // A stand-in for your remote sandbox SDK (E2B, Daytona, Cloudflare, ...).
 declare const remote: {
@@ -694,8 +694,8 @@ way. Its `exec` is a stub you program, and every command it receives is
 recorded. Combine it with `mockModel` for deterministic tests:
 
 ```ts
-import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from 'lousho';
-import { mockModel } from 'lousho/testing';
+import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@linuxdevil/lousho';
+import { mockModel } from '@linuxdevil/lousho/testing';
 
 const workspace = new MemoryWorkspace({
   files: { 'src/math.ts': 'export const add = (a: number, b: number) => a - b;\n' },