@xingular/harness 0.1.6 → 1.0.0

package/README.md

@@ -1,22 +1,62 @@
 # Xingular Harness
 
-A Pi agent harness, as one TypeScript package (`@xingular/harness`). It is everything a model
-needs to work for someone over time, and nothing about any particular application:
-
-| Part | Folder | What it does |
+A Pi agent harness built on **recursive harnessing** ([Harness²](https://arxiv.org/abs/2610.14224),
+Apache-2.0, Google LLC), as one TypeScript package (`@xingular/harness`). It lets a running host
+improve the harness itself, with model weights fixed. To say that precisely, the harness has two
+halves:
+
+- **The foundation is fixed.** Pi sessions, the prompt compiler, the run recorder, the tool gate,
+  accounts, plugin-code trust, the refinement method and the extension points. Only a release
+  changes it.
+- **A Harness Variant (HV) mutates.** It is what a model is told and can load: eight components
+  (c1–c8) for one scope. Each scope has versioned, validated HVs; a run pins one version, and
+  refinement proposes a better HV that a person adopts.
+
+*The foundation runs a variant, records how it went, and lets refinement propose a better
+variant; only a person adopts one.* Refinement edits a copy of a variant and never the
+foundation. See [Foundation and variants](docs/architecture/00-overview.md#foundation-and-variants).
+
+Recursive refinement proposes HV improvements from run evidence. A person adopts candidates;
+model weights and the foundation stay fixed. See the [Google Harness² feature guide](docs/features/google-harness2/README.md)
+for the method and HV components.
+
+| Area | Main features | Guide |
 |---|---|---|
-| Accounts | `src/accounts/` | Several isolated Pi accounts and pools, sign-in, model lists, health and limits. A session keeps the account it started with. |
-| Sessions | `src/sessions/` | Pi SDK turns, run records and `events.jsonl`, interrupt, approvals, questions, recovery after a crash. |
-| Prompt | `src/prompt/` | The system prompt compiled from sections with budgets and profiles; a stable prefix, and changing state delivered as updates in native history. |
-| Memory | `src/memory/` | The Wiki: pages, facts, memory blocks, revisions, proposals with an evidence gate, undo, an Inbox, recall over past runs, and sleep-time consolidation. |
-| Skills | `src/skills/` | Skills, prompts, and rules: a person's own in the data root, and built-in ones shipped with the harness or the application. |
-| Plugins | `src/plugins/` | What a Pi session loads, chosen by the harness and never by Pi's own discovery; trust for a working folder's code; the list of every plugin and what reaches one caller. |
-| Tools | `src/tools/` | Tool definitions, the memory tools, `ask_user`; a gate that asks the application's policy, then standing approvals, then the person. |
-| Connected apps | `src/mcp/` | MCP connections, OAuth, per-session grants, redaction, a trace of what each call returned. |
-| Terminal | `src/terminal/` | Interactive Pi sessions with isolated accounts, compiled instructions, a telemetry and tool extension, and the session socket with the `xagent-wiki` and `xagent-mcp` commands. |
-| Server | `src/server/` | The same API over newline-delimited JSON, for a host that is not a Node program. |
-
-It was split out of Xingular Agent, which is now an application built on it.
+| Core runtime | Accounts, sessions and runs, prompt compilation, tool governance | [Cores](docs/features/cores/README.md) |
+| Harness² | HVs, recursive refinement, answer-free selection, experience library | [Google Harness²](docs/features/google-harness2/README.md) |
+| Automations | Subagents, recovery, optional run reflections, plugin hooks | [Automations](docs/features/automations/README.md) |
+| Memory | Wiki notes, run recall, trajectory search and reads | [Memory](docs/features/memory/README.md) |
+| Integrations | Application extension points, plugins, connected apps and Hub | [Integrations](docs/features/integrations/README.md) |
+| Interfaces | Node embedding, standalone terminal and JSON-lines server | [Interfaces](docs/features/interfaces/README.md) |
+
+The binding design of every part is the [architecture specification](docs/architecture/README.md).
+
+Try refinement with no model and no credentials: `npm run build && node dist/cli.js refine demo --k 2`.
+The [feature guide](docs/features/README.md) groups capabilities by area; the [documentation
+index](docs/README.md) links the architecture and other project records.
+
+### Session options for applications
+
+- Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
+- `harness.subagents.spawn({ parentRunId, brief, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. It returns `{ runId, nativeSessionId }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
+- The model's `spawn_subagent` returns immediately by default; `wait: true` returns an inline result. `wait_subagents` joins selected children. The SDK and standalone terminal share this execution service. Terminal calls use its private control channel, including when connected apps are disabled.
+- Parents receive results at native turn boundaries and join outstanding children before completing. Typed native-history receipts prevent duplicate automatic delivery; explicit waits can reread results. Ownership is recorded before startup so an explicit resume can recover even a lost spawn return. Startup reservations without a run become interrupted outcomes. A restarted Harness never restarts model work automatically. Recovery requires the same recorded account, caller, working folder, and selected history branch. Session IDs are opaque; consumers follow `parentRunId` and `relation`.
+- `providers: false` runs a session with the harness's own tools only.
+- `variant: { scope }` runs the session on that scope's head variant (or `{ scope, version }`, or `{ dir }` for a variant on disk). The version is pinned for the run and recorded on it.
+- On the caller, `recallExcludeAgents` hides those agents' conversations from history and trajectory tools.
+- `harnessTools: false` runs a session without the History, Wiki and skill tools (and without `ask_user` and `checklist_write`).
+- Every session with harness tools gets `checklist_write`: the model sends its whole checklist (`pending`, `in_progress`, `completed`, at most 50 steps) and the run records it as a `checklist.updated` event. `checklistOf(events)` or the `runs.checklist` method reads the latest one. Plan mode allows it.
+- `continueFrom: <run id>` continues a run that stopped before it finished (interrupted or failed) as a new run. `harness.recovery.interruptedRunIds` lists the runs `open` marked interrupted, and `continuationOf(root, runId, sessionDir)` (`runs.continuation`) says whether one can be continued and what it left: checklist, unanswered approvals and questions, the last tool and whether it finished, unfinished subagents. The new run reopens the same native history, records `resumedFromRunId`, keeps the account, variant version and capability set (`continuation_mismatch` otherwise), and the model is told where the earlier run stopped. The harness never continues a run by itself; which runs to continue, and when, is the application's choice.
+- The first-party `lessons` plugin (off by default) reflects on a completed top-level run with enough tool calls and may keep one general lesson in the Wiki under `library/lessons/`, in refinement's cue/lesson shape. It uses the run's own account and model, read-only file tools, and is capped (`minToolCalls`, `maxLessons`, `maxChars`). See PROP-0008.
+
+Every session also gets `trajectory_search` and `trajectory_read` from the built-in History plugin.
+Search lists runs in the current data root, including active runs, with filters and a continuation
+cursor. Read returns pages of the canonical execution events, including captured prompt/context,
+tool, decision, retry, compaction, and usage evidence. Active runs show the latest events saved so
+far; settled reads stop at the first outcome. Payloads are bounded and marked when truncated, and
+the tools omit account identifiers, credential fields, attachment bytes, native adapter payloads,
+and provider reasoning text or summaries.
+They report recorded evidence without scoring runs, and do not backfill older records.
 
 ## Using it from Node
 
@@ -24,16 +64,19 @@ It was split out of Xingular Agent, which is now an application built on it.
 import { createHarness } from '@xingular/harness'
 
 const harness = createHarness({
-  dataRoot: '/path/to/data',        // knowledge and history: wiki/, registry/, runs/, index.sqlite
+  dataRoot: '/path/to/data',        // variants/, library/, refine/, wiki/, registry/, runs/, index.sqlite
   stateDir: '/path/to/state',       // device-local: accounts, approvals, connections, sockets
   productName: 'My App',            // how the harness names itself to a model (default 'Xingular Harness')
   secrets,                          // SecretStore; defaults to an owner-only file in stateDir
   policy,                           // ToolPolicy: what a run may do, and what needs a person
   directory,                        // names for the ids the application uses
   builtins: ['/path/to/builtin'],   // folders of built-in skills, prompts, and rules
-  plugins: [myPlugin]               // the application's own parts, described as plugins
+  plugins: [myPlugin],              // the application's own parts, described as plugins
+  refineHost                        // where refinement executions work, as whom, with which tools
 })
 
+harness.refine.start({ task: { id, scope: 'agent-1', prompt }, k: 1, mode: 'parallel' })
+
 harness.sessions.provide((session) => myTools(session))   // the application's own tools
 harness.runs.listen((event, run) => show(event))            // every run event, after it is saved
 
@@ -41,6 +84,7 @@ await harness.sessions.run({
   run: { id, sessionId },
   cwd, sessionDir, text,
   caller: { agentId, agentName, actor: 'Chat' },
+  variant: { scope: 'agent-1' },
   launch: { sections: [{ id: 'identity', title: 'Identity', body, budget: 2000, order: 10 }] },
   tools: { allow: ['read', 'bash', 'my_tool'], gated: ['bash'] }
 })
@@ -48,14 +92,14 @@ await harness.sessions.run({
 
 ## How an application extends it
 
-The harness knows a caller (an opaque id that owns memory), never an agent, a group, or a task.
-An application adds what it knows through six points:
+The harness knows a caller and a harness scope (opaque ids), never an agent, a group, or a task.
+An application adds what it knows through seven points:
 
 1. **Prompt sections** (`Launch.sections`, `Launch.toolGroups`, `Launch.references`). Each
-   section has an `order` and may be `dynamic`. The harness adds its own (`blocks` 30, `rules` 40,
-   `references` 50, `skills` 60, `knowledge` 80, `tools` 90), applies budgets and the caller's
-   context profile, keeps stable sections in the system prompt, and sends dynamic ones as
-   updates.
+   section has an `order` and may be `dynamic`. The harness adds its own (`system` 25,
+   `guardrails` 40, `memory` 45, `references` 50, `subagents` 64, `scripts` 66, `wiki` 80,
+   `tools` 90), applies budgets, keeps stable sections in the system prompt, and sends dynamic
+   ones as updates.
 2. **Tool providers** (`harness.sessions.provide`). A provider returns `ToolSpec`s for a session;
    only the names in the session's `allow` list are registered, in that order.
    A tool may return `attachments` as `{ id, name, mimeType }` references. The harness records
@@ -65,8 +109,10 @@ An application adds what it knows through six points:
    key read from the secret store) and `web_fetch` (checked reads of public pages). An application
    passes it to `harness.sessions.provide` and switches the names on for each agent.
 3. **`ToolPolicy`**. `scope` says whether a call is inside what the run may do (or needs one
-   approval); `authorize` says whether the tool is still switched on; `approval` adds facts for
-   standing approvals; `connections` narrows the connected apps a session reaches.
+   approval). A decision with `humanOnly` is for a person alone: the always-approve switch and
+   remembered answers do not apply to it. `authorize` says whether the tool is still switched on;
+   `approval` adds facts for standing approvals; `connections` narrows the connected apps a session
+   reaches.
 4. **`SecretStore`**. Where credentials live (a keychain, a vault). Keys are
    `<account id>/<name>`.
 5. **`Directory`**. Names for the application's ids, shown in what the harness writes.
@@ -74,6 +120,11 @@ An application adds what it knows through six points:
    the application and says which tools, prompt sections and tool groups it provides. It is data:
    it changes what `plugins.list` and `plugins.inventory` report, never what runs. `WEB_PLUGIN`
    describes the web tools. A host that is not a Node program sends them with `plugins.describe`.
+7. **`RefineHost`** (`HarnessOptions.refineHost`). Where a refinement execution works
+   (`prepareWorkspace`: an isolated folder, such as a git worktree), as whom and with which tools
+   (`session`), and what it produced (`deliverable`). Executions run as unattended runs with
+   trigger `probe`, so a `ToolPolicy` can refuse anything with effects outside that folder;
+   improver sessions run with trigger `improver`, file tools only, on a copy of the evidence.
 
 `apps.expose(...)` additionally offers the application's tools through the connected-apps
 broker (`mcp_list_tools`, `mcp_call_tool`), which is how a terminal session reaches them.
@@ -82,7 +133,7 @@ broker (`mcp_list_tools`, `mcp_call_tool`), which is how a terminal session reac
 
 A plugin is a bundle with a title, a description and contributions: instructions, skills,
 commands, tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it
-is; so are the harness's own parts (Memory, Wiki, History, Ask the user, Connected apps, Pi), the
+is; so are the harness's own parts (Harness, Wiki, History, Subagents, Ask the user, Connected apps, Pi), the
 application's, a person's registry ("Yours"), the folder every account shares, and what a
 working folder brings.
 
@@ -111,14 +162,15 @@ working folder brings.
   does nothing. A tool an extension registered is offered to the model and asks before every
   call. A command it registered runs when a message starts with it.
 - **The gate runs last.** In an SDK session it is an inline extension, loaded after those on
-  disk; in a terminal the harness's extension is the last `--extension`. A plugin that changes a
-  tool call's input does so before the gate sees it.
+  disk. A terminal retains its final prepared `--extension` bridge argument; the owned frontend
+  loads that bridge as the final trusted inline factory. A plugin that changes a tool call's
+  input does so before the gate sees it. Every resource reload revalidates the parent's original
+  trusted selection; changed or revoked code requires review and a fresh terminal.
 - **A required part can be extended.** A package names the part it adds to and, optionally, a
-  hooks file: `"harness": { "extends": ["memory"], "hooks": "./hooks.mjs" }`. The harness runs
-  hooks itself (`src/plugins/hooks.ts`), in its own process, because most memory is written while
-  no session is open. `export default function (harness) { harness.on('memory.saved', async
-  (event, ctx) => …) }`; the events are `memory.saved`, `memory.block.changed`,
-  `wiki.page.saved` and `history.run.ended`. A hook is told after the write and cannot stop it,
+  hooks file: `"harness": { "extends": ["wiki"], "hooks": "./hooks.mjs" }`. The harness runs
+  hooks itself (`src/plugins/hooks.ts`), in its own process, because notes are often written while
+  no session is open. `export default function (harness) { harness.on('wiki.page.saved', async
+  (event, ctx) => …) }`; the events are `wiki.page.saved` and `history.run.ended`. A hook is told after the write and cannot stop it,
   has 30 seconds, and what it throws is kept in `plugin-hooks.json` and shown on its plugin. It
   runs only while its plugin is switched on for everyone and trusted; what is loaded is checked
   against that before each delivery. `ctx.call(connection, tool, args)` reaches a connected app
@@ -138,14 +190,15 @@ working folder brings.
 - **A person can do the same from a terminal.** In a terminal session, `/plugins` lists what the
   session loads and switches a plugin, or one thing it brings, for the session's project or for
   everyone, and trusts code after showing its files. The session's shell can read the session
-  token from its environment, so a change is taken only with a second key that the harness's
-  extension claims once as it loads (`control.claim`) and keeps in its own memory; the socket's
+  token from its environment, so a change is taken only with a second key that the trusted
+  terminal process claims once (`control.claim`) and shares with its bridge in memory; the socket's
   `plugins.list` is open to the session, and `plugins.attach`, `plugins.detach`, `plugins.trust`
   and `plugins.untrust` refuse without that key. A change applies when the session restarts.
-  Outside a session, `xingular-harness plugins list | show | install | remove | update | attach |
+  Outside a session, `xharness plugins list | show | install | remove | update | attach |
   detach | trust | untrust` acts directly, as the person who typed it; `trust` shows the files
   and wants a typed yes or `--yes`. It does not open the data root, so it settles no run.
-- **Unattended runs and memory maintenance load no extension**, as before.
+- **Unattended runs load no extension found on disk.** A variant's own trusted plugins still
+  load, so a refinement probe runs the plugin it is testing.
 - **A person switches things on and off for a scope.** `plugins.attach` and `plugins.detach`
   take a plugin's or a contribution's `id` and a `scope` (`{}` for everywhere, `{ agentId }`, or
   `{ projectId }`). The narrowest scope that says something wins: an agent, then a project, then
@@ -162,9 +215,10 @@ working folder brings.
   one caller, each item attributed to a plugin, with `unattributed` naming any prompt section,
   tool group or tool no plugin accounts for.
 
-A terminal session's `pi` command has four extensions of its own (`builtin:mcp`, `codemode`,
-`tool-search`, `llama.cpp`). They are passed by name unless Pi's settings switch them off. An SDK
-session does not have them.
+A terminal session can load Pi's four existing builtins (`builtin:mcp`, `codemode`,
+`tool-search`, `llama.cpp`). The Harness resource selection passes enabled builtins by name,
+and the pinned compatibility adapter supplies their implementations to the persistent SDK
+runtime. The separate per-turn SDK execution path does not load these terminal builtins.
 
 ## Using it from another language
 
@@ -188,7 +242,8 @@ table. With the `--host-*` flags the harness calls the host for `secrets.get|set
 `policy.scope|authorize|approval|connections`, and `tools.call`; the host registers its tools
 with `tools.register` and its names with `directory.set`.
 
-`skills.import` accepts complete user-owned skill folders:
+`variants.importComponents` adds complete skill folders, or single-file rules and prompts, to the
+component library:
 
 ```ts
 { skills: [{ name, files: [{ path, content, encoding }] }] }
@@ -199,60 +254,127 @@ It validates bounded relative paths and file encodings, requires a root
 has no knowledge of the application feature that may call it.
 
 `npm run prove` starts that server on a throwaway data root, with no application present, and
-exercises accounts, memory, skills, the prompt, connected apps, and a recorded session.
+exercises accounts, variants, the Wiki, the prompt, connected apps, a recorded session, a
+plugin hook, and the refinement demo end to end.
 
-## Run it as a standalone Pi terminal
+## Run it as a standalone Harness terminal
 
 After the CLI package is published to npm or your company's npm registry, install and launch it:
 
 ```sh
 npm install --global @xingular/harness
-xingular-harness
+xharness
 ```
 
-The machine needs Node 22.19 or newer. On macOS and Linux, the `pi` command must be on `PATH`;
-on Windows, Harness runs the pinned Pi CLI package through the active Node runtime. On first
-launch, the harness creates a `Default` Pi account; Pi handles provider sign-in.
+The machine needs Node 22.19 or newer and Bun 1.3.14 or newer. Harness runs its own OpenTUI
+terminal frontend with Bun, using its pinned Pi SDK; no separate global `pi` installation is
+required. On first launch, it creates a `Default` isolated account. Use `/accounts` to sign in.
+
+Provider sign-in progress lives in the running Harness process. An embedding application can call
+`accounts.loginStatus` after reconnecting to recover the current device code or prompt by account;
+the status carries a revision so it can be safely merged with streamed login events. Progress is
+never written to account files, and a completed or cancelled attempt no longer exposes its code.
 
-To build and run from a source checkout instead:
+To build and run from a source checkout, use the development command:
 
 ```sh
 npm install
-npm run build
-node dist/cli.js
+npm run dev
 ```
 
-This opens Pi's interactive terminal in the current working directory. The harness adds its
-compiled context, isolated account, approval gate, Wiki commands, and terminal extension while
-Pi provides the interface.
-
-The default data and device state directories are `~/.xingular-harness/data` and
-`~/.xingular-harness/state`. Override them with `--data <dir>` and `--state <dir>`. Session
-history is stored per working directory and can be reopened with Pi's `/resume` command. The
-explicit `terminal` command is an alias for the default launch. Use `--help` to see the commands;
-`serve` remains the host-facing RPC service for integrations such as Xingular Agent/App.
+`npm run dev` rebuilds the CLI and opens the Harness terminal in the current working directory.
+It uses separate development directories by default: `~/.xingular-harness-dev/data` and
+`~/.xingular-harness-dev/state`. This keeps development harness data and device settings—including
+accounts, Pi settings, approvals, and connections—separate from the installed command. Press
+`/quit`, Ctrl+C or Ctrl+D to close it. Override either directory with `--data <dir>` or
+`--state <dir>`; for example: `npm run dev -- --data <dir> --state <dir>`. An omitted option keeps
+its development specific default.
+
+The OpenTUI/Solid frontend is the only terminal. Install Bun 1.3.14 or newer and run
+`npm run build:tui` (or `npm run build`); without Bun the build fails rather than producing a
+terminal that cannot start. The harness runs `dist/terminal-opentui.js`, which uses the same
+session runtime, accounts, command pages, approvals, questions, plugins and run records as the
+embedded SDK. See [the terminal guide](docs/terminal-tui.md).
+
+Building a checkout does not update an existing global `xharness` installation.
+To replace that command with this checkout, run `npm pack`, then install the exact tarball
+filename it prints with `npm install --global ./<tarball-filename>`. This is a local install;
+it does not publish a release. Close an already-running terminal session and launch the command
+again to load the new frontend. A package version alone cannot distinguish an unreleased local
+build from an older installed build with the same version.
+
+This opens the Harness-owned OpenTUI terminal in the current working directory. Its presentation
+uses the Harness titanium palette and an OpenCode-inspired layout: the transcript above a
+borderless composer with the working status above it and the model, context and token line below.
+Harness owns screen composition, editing/input dispatch, scrolling, command routing and plugin UI;
+Pi supplies the persistent execution runtime, native history and rich content components. The
+existing isolated account, compiled context, approval gate, telemetry and Wiki/socket commands
+remain behind the terminal. No Pi `InteractiveMode` is constructed.
+
+`/resume` stays inside the prepared account history and working folder. Cancel an active response
+before changing or reloading a session. Full OMP visual parity is not established by the current
+verification. `/accounts`, `/permissions`, `/plugins`, `/hub`, `/components`, `/settings`, `/trajectory`
+and `/log` each open their own centered page dialog with local tabs. `/permissions` reviews device-local Pi
+terminal grants and the Full Permission switch; tool grants apply across terminal sessions sharing this
+Harness state, and Full Permission requires confirmation. `/components` browses reusable skills,
+prompts and rules; a confirmed skill or rule addition creates a variant version for future sessions while
+the current terminal stays pinned. `/trajectory` opens recorded runs for the current native conversation,
+with event navigation and a detail inspector. `/log` shows a static, redacted snapshot of Harness
+diagnostics and run events for the current conversation; press Escape to close. See
+[terminal architecture and evidence](docs/terminal-tui.md),
+[the ownership decision](docs/decisions/ADR-0001-owned-terminal.md),
+[the OpenTUI-only decision](docs/decisions/ADR-0006-opentui-only-terminal.md), and
+[third-party notices](NOTICE.md).
+
+### `/accounts` in the terminal
+
+`/accounts` manages the Pi accounts the same way the app's Accounts screen does: add, rename,
+check, make default, sign in (browser or API key), sign out, remove a provider or an account,
+manage pools, and read the activity log. Each change is made by the person at the terminal; a
+command the model runs in the shell cannot make it.
+
+A running session stays on the account it started with. To use another account for this
+session, choose **Use for this session**: the terminal child restarts and the same conversation
+resumes on that account. Removing an account that a running terminal is using is refused. Only
+terminals in this process are counted, so an account used by another running `xharness` window can
+still be removed; that session then asks for another account the next time it starts.
+
+The installed standalone command defaults to `~/.xingular-harness/data` and
+`~/.xingular-harness/state`; `npm run dev` instead defaults to the separate
+`~/.xingular-harness-dev/data` and `~/.xingular-harness-dev/state`. Override either with
+`--data <dir>` and `--state <dir>`. Session history is stored per working directory and can be
+reopened with the terminal's `/resume` command. The explicit `terminal` command is an alias for
+the default launch. Use `--help` to see the commands; `serve` remains the host-facing RPC service
+for integrations such as Xingular Agent/App.
 
 ## Storage
 
 ```
 <data root>/
-  wiki/             home.md, library/, projects/<slug>/, facts/, blocks/, revisions, inbox, log
-  registry/         skills/, prompts/, rules/   (a person's own; never copied)
+  variants/<scope>/  versions/<fingerprint>/variant/, head.json, lineage.jsonl   (the eight components)
+  refine/<id>/      summary.json, task.json, variants/<label>/, rollouts/, context/, selection/, reflection/, improver/
+  library/<scope>/<area>/  INDEX.md, variants/<task>/{variant/, EXPERIENCE.md}   (the experience library)
+  wiki/             home.md, library/, projects/<slug>/   (project notes)
+  wiki-history/     earlier versions of notes
+  legacy/           what an earlier Wiki kept (memory blocks, facts, revisions, Inbox), moved once
+  registry/         skills/, prompts/, rules/   (the component library; the Hub installs here)
   plugins/<name>/   packages kept with a person's data; each is found as an installed plugin
-  runs/<id>/        run.json, events.jsonl, context.json, caller.json
-  config/           context profiles, what is switched on for whom (plugin-attachments.json),
+  runs/<id>/        run.json, events.jsonl, context.json, caller.json, subagents.json (reserved child IDs)
+  config/           what is switched on for whom (plugin-attachments.json),
                     settings the harness reads
-  index.sqlite      a rebuildable index of Wiki entries and runs (FTS5)
+  index.sqlite      a rebuildable index of runs for recall (FTS5)
   projects.json     read only: the application owns it
 
 <state dir>/
   accounts/         registry, per-account Pi agent folders, audit log
   approvals.json    standing approvals
   plugin-trust.json       the code a person trusted, by hash, and whether earlier packages were taken over
+  variant-plugin-trust.json  harness-variant plugin code a person trusted, and scopes whose probes may run improver code
   plugin-registered.json  what each extension registered the last time a session loaded it
   plugin-hooks.json       what each hooks file listens for and how its last run went
   connections.json  connected apps (secrets are in the SecretStore)
   run/              the session socket and the terminal commands
+  harness.log       diagnostics from the standalone terminal, kept off its screen
 ```
 
 The files are the source of truth; `index.sqlite` can be deleted and rebuilt
@@ -261,14 +383,86 @@ The files are the source of truth; `index.sqlite` can be deleted and rebuilt
 ## Commands
 
 ```sh
-npm run typecheck
-npm test          # unit tests and the golden prompt/memory fixtures in tests/golden
-npm run build     # dist/cli.js (the xingular-harness command) and dist/terminal-pi.js
-npm run prove     # the standalone proof above
+npm run ci        # typecheck, unit/golden tests, and standalone proof; matches GitHub CI
+npm run build     # dist/cli.js, dist/terminal-pi.js, and the OpenTUI frontend
+npm run build:tui # only the OpenTUI frontend
 ```
 
-Node 22.13 or newer (for `node:sqlite`).
+Node 22.19 or newer and Bun 1.3.14 or newer.
 
 ## Images
 
-`SessionRunInput.requiresImageInput` optionally requires a vision-capable resolved Pi model before a prompt is delivered. The check includes direct `images` input, and the generic tool wrapper rejects image results on text-only models. Direct prompt images use Pi's `{ type: 'image', data, mimeType }` content shape. Applications own file formats, attachment selection, extraction and image preparation; the Harness only transports typed image content and validates model capability.
+`SessionRunInput.requiresImageInput` optionally requires a vision-capable resolved Pi model before a prompt is delivered. The check includes direct `images` input, and the generic tool wrapper rejects image results on text-only models. Direct prompt images use Pi's `{ type: 'image', data, mimeType }` content shape. Applications own attachment selection, extraction and image preparation; the Harness transports typed image content and validates model capability. In the standalone terminal, pasting Finder-copied HEIC/HEIF files on macOS converts them to temporary PNGs so Pi can read their pixels. See [the terminal guide](docs/terminal-tui.md#clipboard-image-paste).
+
+`SessionRunInput.initialBashCommand` is an opt-in for one new interactive user turn. It must match
+the leading `!` command in `text`; Harness checks it through the same per-call gate as model-issued
+Bash, executes it once in Pi's native session, records its bounded result, and asks the model to
+inspect that result before replying. Automatic, plan, resumed, relation, probe, and improver runs
+cannot carry it. See the [terminal guide](docs/terminal-tui.md#bash-command-mode).
+
+## Curated Hub
+
+`xharness hub list [--refresh]`, `xharness hub show publisher/name@version`, and
+`hub install publisher/name@version` browse and install exact catalog versions. `/hub` offers the
+same review in the interactive terminal, using its private control key for installation. Both the
+terminal and embedding applications use `hub.list`, `hub.get`, `hub.preview`, `hub.install`,
+`hub.uninstall`, and `hub.readDocument`. `hub.get { id, version, preview: true }` verifies data
+payload bytes without installing them. `hub.preview { id, version, offset }` returns bounded,
+UTF-8-safe pages of up to 16 KiB from a verified payload.
+
+Registry bundles import complete skills or single Markdown prompts/rules, disabled. Pi packages
+reuse the existing installer and require an exact npm version or full GitHub commit. Documents
+are saved as inert JSON for a compatible host to interpret; the harness does not apply them.
+Installation grants no attachment, trust, credentials, or permission. Writes are serialized and
+existing registry files are never overwritten. Receipts report whether their resources are intact;
+uninstall removes only the exact receipt's resources, including local edits within those paths, and
+revokes its attachment choices.
+
+Installed documents and provenance live under `<data root>/hub/`; the catalog cache is
+`<state dir>/hub/catalog.json`. An offline snapshot ships with the package. Explicit refresh keeps
+the last valid catalog when the network or schema fails. The prepared public distribution repository
+is `../Hub`; publication remains separate from local installation and testing. Run its build with
+`--sync-harness` to regenerate this package's offline snapshot after reviewing catalog changes.
+
+Standalone defaults stay separate from a host application's folders. Use explicit `--data` and
+`--state` to target the same library. CLI hub commands construct the harness without opening the
+data root, so they do not migrate the Wiki or settle another process's runs.
+
+
+## External curation
+
+An embedding application may set `externalMaintenance: true`, supply trusted `CallerContext`
+`vaultAccess` (`self` or `curator`), and register `maintenanceTools`/`MAINTENANCE_PLUGIN`.
+Self callers directly edit only their own writable persona/notes; shared knowledge and text-resource
+writes become persistent proposals. Curator tools read original evidence, compare captured target
+revisions, read all host-assigned requests together, and apply reconciled Wiki proposals as one
+undoable change set. Resource proposals keep their own receipts; executable proposals remain inert
+until the user reviews/trusts them. Later user edits are never overwritten.
+`maintenance.list`, `maintenance.review` and `maintenance.retry` let the host dispatch its own
+recorded sessions. Curator runs do not recursively queue maintenance. Optional assigned IDs freeze
+which requests a batch may claim. These fields are trusted host context, never model arguments.
+`maintenance_read_batch` reads those assigned requests together; `maintenance_apply_batch` records
+one decision for each and applies the evidence-checked Wiki set atomically. Standalone callers that
+omit this option retain the existing lifecycle and direct-write contract.
+
+## Readiness diagnostics
+
+Use `/doctor` in the terminal for local readiness checks and explicitly selected live probes. The same
+structured jobs are available through `harness.doctor` and `doctor.*` server methods. See
+[Doctor](docs/doctor.md) for coverage, consent, isolation, and provider callbacks.
+
+## Public 1.0.0 release candidate
+
+The public package is ESM: import from `@xingular/harness` or supported subpaths such as
+`@xingular/harness/variant/seed`. JavaScript and declarations are shipped in `dist/sdk`; a
+TypeScript loader is not required. Node 22.19 or later is required. The interactive terminal
+also requires Bun (release builds use 1.4.2); the CLI reports its version with `xharness --version`.
+Original project code is Apache-2.0. See LICENSE, NOTICE.md and THIRD_PARTY_LICENSES.md.
+
+A host providing its own browser tools sets `browser: false` on `createHarness` to disable the
+generic backend and prevent tool-name collisions. The desktop App uses this for shared tabs.
+The default standalone Harness keeps its isolated browser backend enabled.
+
+This candidate intentionally resets development numbering to 1.0.0 while preserving old versions.
+See [release notes](docs/releases/1.0.0.md) and [release procedure](docs/releases/README.md).
+Publication requires registry verification, green CI and approval of the candidate/tag push.