@relay-harness/coding-agent 0.0.0-stage → 1.0.3

package/docs/extensions.md

@@ -0,0 +1,274 @@
+# Extensions
+
+Extensions are TypeScript modules that add executable behavior to Relay. Use one when a workflow needs tools, commands, event handlers, model providers, session state, or terminal UI rather than instructions alone.
+
+An extension runs inside the Relay process with the same operating-system permissions. It can inspect prompts, tool calls, files, credentials, and session history, so load extensions only from sources you trust.
+
+Typical extensions add an agent tool, protect paths, confirm dangerous commands, react to session events, modify context, expose a command, or display persistent status.
+
+<a id="quick-start"></a>
+<a id="writing-an-extension"></a>
+<a id="create-an-extension"></a>
+
+## Create and load an extension
+
+An extension exports a default factory that receives `ExtensionAPI`. The factory registers capabilities for the current extension runtime.
+
+Create `~/.relay/agent/extensions/hello.ts`:
+
+```typescript
+import type { ExtensionAPI } from "@relay-harness/coding-agent";
+
+export default function (relay: ExtensionAPI) {
+  relay.registerCommand("hello", {
+    description: "Show a greeting",
+    handler: async (name, ctx) => {
+      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
+    },
+  });
+}
+```
+
+Start Relay and run `/hello`. During development, load a file directly:
+
+```bash
+relay --extension ./hello.ts
+```
+
+Relay uses `jiti`, so local TypeScript extensions do not need a separate compilation step. Use [Relay packages](packages.md) for distributed extensions and dependencies.
+
+<a id="extension-locations"></a>
+<a id="available-imports"></a>
+<a id="choose-where-it-loads"></a>
+
+## Add it to Relay
+
+Place the extension in your user or project extensions directory. Relay loads direct TypeScript or JavaScript files and subdirectories containing an `index.ts` or `index.js` entry point.
+
+Use a single file for a small extension and a directory for a multi-file implementation. Put npm dependencies in a nearby `package.json`. See [Configuration](configuration.md) for conventional locations and [Settings](settings.md#resources) for additional paths.
+
+Reload replaces the extension runtime, so code after `await ctx.reload()` must not reuse state from the old runtime. Only personal and explicit command-line extensions can participate in the `project_trust` event that runs before project extensions load.
+
+<a id="understand-the-lifecycle"></a>
+
+## Respect the runtime lifecycle
+
+The factory can be synchronous or asynchronous. Relay waits for an asynchronous factory before startup continues, allowing it to fetch configuration or register providers needed during startup.
+
+Do not start processes, sockets, watchers, or timers in the factory because some invocations load extensions without starting a session.
+Start long-lived resources from `session_start` or from the command or tool that needs them.
+Close session-scoped resources from an idempotent `session_shutdown` handler.
+
+A run proceeds from input and `before_agent_start`, through model, message, and tool events, to `agent_end`.
+Automatic retries, recovery, compaction, or queued work can continue afterward.
+<a id="agent_start--agent_end--agent_before_settle--agent_settled"></a>
+
+`agent_before_settle` is the final actionable boundary: it can append entries and request one continuation.
+`agent_settled` is final and notification-only; use it when an integration needs to know Relay will not continue automatically.
+
+<a id="extensionapi-methods"></a>
+
+## Choose an integration point
+
+| Capability | Main API |
+|---|---|
+| Observe or modify lifecycle behavior | `relay.on()` |
+| Add a model-callable operation | `relay.registerTool()` |
+| Add a `/` command | `relay.registerCommand()` |
+| Add a shortcut or CLI flag | `relay.registerShortcut()` or `relay.registerFlag()` |
+| Send user or custom messages | `relay.sendUserMessage()` or `relay.sendMessage()` |
+| Persist non-context session data | `relay.appendEntry()` |
+| Change active tools, model, or thinking level | Session control methods on `relay` |
+| Add a model provider | `relay.registerProvider()` |
+| Add an MCP server | `relay.registerMcpServer()` |
+| Route each request to a model | [`relay.registerVirtualModel()`](virtual-models.md) |
+| Add terminal rendering | Renderer registration and `ctx.ui` |
+| Communicate with another extension | `relay.events` |
+
+Use the exported declarations in [`extensions/types.ts`](https://github.com/eltonssouza/relay-harness/blob/main/packages/coding-agent/src/core/extensions/types.ts) for exact event, context, tool, and result types.
+
+## Follow the extension contracts
+
+<a id="events"></a>
+<a id="work-with-events"></a>
+
+### Events and concurrency
+
+Handlers run in extension load and registration order. `relay.on()` returns a function that unsubscribes that registration; changes do not affect a dispatch already in progress.
+Some events notify; others transform data, replace results, or cancel an operation.
+Use each event’s declared result type rather than assuming every return value has an effect.
+
+Events cover resource discovery, sessions, agent and message lifecycle, providers, tools, and raw input.
+
+`before_agent_start` exposes both the current prompt and its structured `systemPromptOptions`. Prefer changing prompt sections, selected tools, or guidelines so Relay can append a transcript delta. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for that run while the transcript continues recording the structured sections. Providers receive the forced text as their leading system prompt.
+
+`message_end` can replace a finalized message while preserving its role. `tool_call` can mutate input or block execution. `tool_result` handlers compose, with each handler seeing prior changes.
+
+<a id="provider_stream_event"></a>
+
+`provider_stream_event` fires for each parsed provider stream event before Relay normalizes it. The event identifies the provider, API, and model; `event.data` is the earliest structured value available to Relay, not necessarily the original HTTP bytes or SSE frame. Treat it as read-only because mutation can affect normalization. The event is notification-only and is not persisted.
+
+Handlers are awaited in stream order, so slow handlers delay stream consumption. Handler errors are reported without changing the provider response. See [`debug-provider.ts`](../examples/extensions/debug-provider.ts) for an opt-in viewer that groups raw events by assistant message.
+
+<a id="context_with_system"></a>
+
+`context` transforms conversation messages without prompt and tool system messages; Relay restores that state afterward. Use `context_with_system` only when a request-local transformation must own the complete transcript, and keep a system message at index zero.
+
+`turn_end` and `agent_before_settle` are actionable boundaries. Their handlers can chain proposed `custom`, `custom_message`, `context_edit`, or `compaction` entries and return `continue: true` for one next model request. Guard continuation conditions because an unconditional continuation can loop. Use the exported event declarations for the complete validation and ordering contract.
+
+<a id="cache_warming_decision"></a>
+
+`cache_warming_decision` can override an idle prompt-cache refresh with `{ action: "warm" }` or `{ action: "stop" }`. The last handler that returns an action wins.
+
+Tool calls from one assistant message can run in parallel.
+Do not assume a sibling call or result exists when another tool event runs.
+Use `ctx.signal` for nested work owned by an active turn; commands and idle session events often have no operation signal.
+
+A `user_bash` handler that returns `undefined` passes the command to the next handler and then to local execution if no handler handles it. Returning `operations` or `result` stops propagation. A handler failure blocks the command rather than falling through to local execution.
+
+<a id="custom-tools"></a>
+<a id="register-tools"></a>
+
+### Tools
+
+A custom tool defines a name, model-facing description, TypeBox parameter schema, and `execute()` function.
+Its result requires model-facing `content` and a `details` field for rendering or state reconstruction.
+Use `details: undefined` when there are no structured details. If the tool makes nested model calls, include their `usage` in the result so session totals remain accurate.
+
+Throw from `execute()` to produce a failed tool result.
+Returning an object does not mark it as an error.
+Return `terminate: true` only when the agent should skip its automatic follow-up after every completed tool in that batch agrees to terminate.
+
+Use sequential execution when tools share mutable in-memory state.
+File-mutating tools should wrap the complete read-modify-write operation with `withFileMutationQueue()`.
+Truncate large model-facing results and tell the model where to read the complete output.
+
+Declare `outputSchema` and return a matching `structuredContent` when the result is data. The model still receives `content`; programmatic callers such as codemode scripts receive `structuredContent` instead of the text. Tools without `outputSchema` are passed to scripts as their text content. To report a failure that still carries data, return the result with `isError: true` instead of throwing: the model sees an error, and scripts still receive `structuredContent`.
+
+A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate })`. Nested calls go through argument validation and the `tool_call` and `tool_result` handlers like model-issued calls, and emit `tool_execution_start`, `tool_execution_update`, and `tool_execution_end`; all of these events carry `parentToolCallId`, and their `toolCallId` is assigned by relay as `<parent id>/<n>`. These ids do not appear as tool calls or tool results in the transcript. Nested calls do not add transcript entries: their results only reach the calling tool, which reports them itself, for example through `onUpdate` and `details`. The session keeps a bounded record of them (name, arguments, status, duration, error; never results) as `nestedCalls` on the calling tool's result message. It is used for compaction file lists and shown in HTML exports. Arguments over 8 KiB per call or 32 KiB per tool result are omitted, at most 256 calls are kept, and `complete: false` marks a record that lost anything. The `usage` of nested results, at every depth, is added to the calling tool's result `usage`, so a tool reports only its own usage, not that of the tools it called. `ctx.tools` lists the tools `ctx.executeTool()` can call. `tool_result` handlers that redact `content` should also replace `structuredContent`; replacing only `content` drops it.
+
+See [`hello.ts`](../examples/extensions/hello.ts), [`todo.ts`](../examples/extensions/todo.ts), [`dynamic-tools.ts`](../examples/extensions/dynamic-tools.ts), and [`truncated-tool.ts`](../examples/extensions/truncated-tool.ts).
+
+### Tool exposure
+
+`exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
+
+- `direct` (default): declared to the model while active, and callable while active.
+- `model-only`: declared to the model while active, never callable. Use it for tools that orchestrate other tools or ask the user.
+- `codemode`: callable whenever registered, and listed by the `codemode` tool. Not declared to the model unless activated explicitly.
+- `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
+- `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
+
+`namespace: { name, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`.
+
+Registering a `direct` or `model-only` tool activates it; the other exposures are not activated on registration. The active set (`relay.getActiveTools()`, `relay.setActiveTools()`) is the set of tools declared to the model. `relay.getAllTools()` reports each tool's `exposure`, `namespace`, and `annotations`.
+
+`annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
+
+```typescript
+relay.on("tool_call", async (event, ctx) => {
+  const hints = relay.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
+  const needsApproval =
+    hints?.destructiveHint === true ||
+    (!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
+  if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
+    return { block: true, reason: `${event.toolName} was not approved` };
+  }
+});
+```
+
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure and namespace. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. `codemode` uses only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+### Activate tools dynamically
+
+Register every tool first, keep optional tools inactive, and use `relay.setActiveTools()` from a loader tool to select the desired active tools. Names must already be registered; unknown names are ignored.
+
+Relay records the initial prompt and tool set in the transcript's first system message, then appends tool and prompt changes before the next model request. Providers that cannot represent the transition receive a complete transcript checkpoint, which can invalidate the cached prefix.
+
+### Tool rendering
+
+A tool's `renderCall` and `renderResult` draw its calls in the interactive transcript and in HTML exports. `relay.registerToolRenderer((toolName, next) => renderers)` chooses renderers for calls to any tool, including tools that are not registered yet, such as MCP tools in a resumed session before their server connected. `next()` returns what the remaining resolvers (in extension load order), then the registered tool, would use, so `next() ?? mine` only fills in.
+
+### MCP servers
+
+`relay.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.
+
+```typescript
+relay.registerMcpServer("jira", { url: "https://mcp.example.com/jira", exposure: "codemode" });
+relay.unregisterMcpServer("jira");
+```
+
+Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `relay.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
+
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `relay.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+
+<a id="extensioncontext"></a>
+<a id="extensioncommandcontext"></a>
+<a id="use-extension-context"></a>
+
+### Context and session changes
+
+`ExtensionContext` provides the working directory, mode, UI, session manager, model runtime, abort signal, context usage, and controls for compaction and shutdown.
+Use `ctx.modelRegistry.streamSimple()` for provider-neutral nested model calls.
+
+Command handlers receive `ExtensionCommandContext`, which adds operations for waiting until idle, reloading, tree navigation, and session replacement.
+These operations are command-only because calling them from lifecycle handlers can deadlock the runtime.
+
+Session replacement invalidates the old context. Capture only plain data before switching, then use the fresh context supplied to `withSession` for session-bound work.
+
+<a id="state-management"></a>
+<a id="persist-state"></a>
+
+### State
+
+Choose storage based on how state participates in the conversation:
+
+| State | Storage |
+|---|---|
+| Tool state that follows the active branch | Tool-result `details` |
+| Durable data excluded from model context | `relay.appendEntry()` |
+| Custom content stored and sent to the model | `relay.sendMessage()` |
+| Data outside one session | External storage |
+
+Reconstruct branch-sensitive state from `ctx.sessionManager.getBranch()` during `session_start`.
+Do not rebuild it from every file entry because abandoned branches represent alternative histories.
+Register an entry or message renderer when custom stored content should appear in the transcript.
+
+<a id="custom-ui"></a>
+<a id="mode-behavior"></a>
+<a id="interact-with-the-user"></a>
+<a id="account-for-each-mode"></a>
+
+### UI and modes
+
+`ctx.ui` provides dialogs, notifications, status text, widgets, titles, editor access, and custom components.
+Use `ctx.ui.custom()` only when the interaction needs its own rendering and input.
+See [Terminal UI](tui.md) for component, focus, overlay, theme, and performance guidance.
+
+Extensions load in interactive, RPC, JSON, and print modes.
+Interactive mode provides the complete terminal UI.
+RPC can forward supported dialogs and notifications through the [RPC Extension UI protocol](rpc-extension-ui.md), but not custom terminal components; JSON and print modes have no UI.
+Guard terminal-only behavior with `ctx.mode === "tui"` and use `ctx.hasUI` for interactions supported by interactive and RPC clients.
+
+Keep tool and event behavior independent from rendering so non-interactive modes remain functional.
+
+<a id="error-handling"></a>
+<a id="handle-errors-and-shutdown"></a>
+
+### Errors and cleanup
+
+Relay reports handler errors and continues where possible. A `tool_call` handler failure blocks the tool as a fail-safe; a tool execution failure becomes an error result for the model.
+
+Release resources in `session_shutdown` even when normal operation attempted cleanup.
+Keep cleanup idempotent because cancellation, reload, session replacement, and process exit can converge on the same path.
+Use `ctx.shutdown()` to request an orderly process shutdown.
+
+<a id="examples-reference"></a>
+<a id="use-examples-as-the-implementation-reference"></a>
+
+## Examples and reference
+
+The checked [extension examples](../examples/extensions/) cover tools, lifecycle events, commands, flags, shortcuts, state, rendering, providers, OAuth, remote execution, and terminal components.
+Start with the smallest example matching your integration point.
+
+Use [Custom Providers](custom-provider.md) for model-service integrations, [Terminal UI](tui.md) for custom components, and [Relay Packages](packages.md) to install or distribute extensions with other resources.

package/docs/harness-core.md

@@ -0,0 +1,99 @@
+# Harness Core
+
+The harness core is four rules that apply to every model Relay runs: Claude, GPT, Gemini, Grok, or a local model. They act on the agent loop's hooks and events, not on a provider API, and need no extra model call. Each one addresses a measured failure of coding agents.
+
+| Pillar | Failure it addresses | What the harness does |
+|---|---|---|
+| Alignment | Agents violate explicit developer constraints (38% of misalignment), treat questions as permission to edit, and run destructive commands. | Keeps constraints as state and restates them on every request. Asks before destructive or external commands. Stops the first edit in a turn where you only asked a question. Works as a pair: records your corrections and offers constraints and corrections as candidates for AGENTS.md. |
+| Evidence | Agents report "done" when the work failed. LLM judges miss most of these cases. | Records what tool calls actually changed and checked. A completion claim without a passing check after the last change gets one verification request. Counts only checks whose exit code is not masked, optionally only the project's declared commands, and flags oversized changes and files. |
+| Context | Old tool results describe states that no longer exist and grow the context. | Sends recent tool results verbatim, replaces old large ones with one-line stubs, and restates a compact progress digest. |
+| Skills | A skill's organization changes how the agent uses it, and nobody measures it. | Tells the model to treat `SKILL.md` as a router, measures which skill resources lead to actions, and audits skill structure. |
+
+All four are enabled by default. Inspect them with `/harness`; configure them with [`harnessCore` settings](settings.md#harness-core).
+
+## Alignment
+
+**Constraints.** Sentences in your messages that state a standing rule ("Never use `any`", "Não altere os testes", "Use pnpm instead of npm") are recorded as constraints. Each request restates them next to your latest message, where the model weighs them most. Constraints are saved in the session file, so they survive compaction and resume. Code blocks and expanded skills or files are ignored.
+
+**Authorization.** Commands that are hard to reverse or that change state outside the workspace need your approval:
+
+- destructive: `git reset --hard`, `git push --force`, `git clean -f`, `git checkout .`, `git rebase`, `git branch -D`, `rm -r`, `Remove-Item -Recurse`, `DROP TABLE`, `DELETE` without `WHERE`
+- external: `git push`, `npm publish`, `gh pr create|merge`, `kubectl apply`, `terraform apply`, `docker push`, deploy commands, `curl -X POST|PUT|PATCH|DELETE`
+
+A command runs without asking when your latest message names the operation in an affirmative clause: "push the branch" allows `git push`, "apague o diretório dist" allows `rm -r dist`. A deletion also needs its target named, so "remove the unused import" allows no `rm`. "Push it, but not with force" does not allow `git push --force`. Otherwise, in the interactive TUI and RPC modes, Relay asks with a confirmation dialog. In print and JSON modes the call is blocked, the agent asks you in chat, and a "yes" (or "sim", "ok", "go ahead") as your next message allows that exact command once.
+
+**Pair programming.** The agent works as a pair, not a code generator: you bring the what and the why, the agent brings the how. The system prompt carries three rules: ask when the goal or its reason is unclear; propose the simplest design that meets the stated requirements, and a more complex one only by naming the requirement that needs it; treat your context about the environment, services, or domain as authoritative over the model's assumptions. Interrupt a run to redirect it ([Change direction](usage.md#change-direction)).
+
+**Corrections.** A message that pushes back on the agent's approach after it has worked ("Não, simplifica…", "Para, isso tá complicado demais", "That's too complex", "Actually, use…") is recorded as a correction. The next request reminds the model to adopt it, prefer the simplest design that satisfies it, and not reintroduce what you rejected. Ordinary openings such as "Para o módulo X…" or "Não sei por que…" are not corrections.
+
+**Learnings and the living AGENTS.md.** Constraints and corrections are kept in the session file, so they survive compaction and resume, but a new session starts without them. `/harness` lists them under "Learnings (candidates for AGENTS.md)". Recording the lasting ones in AGENTS.md, as a "Common hurdles" entry with the symptom, cause, solution, and how to verify it, means the next session, with any model, starts with them. Relay never edits AGENTS.md on its own; ask the agent to record the entry, or use a prompt template such as this repository's [`.relay/prompts/hurdle.md`](../../../.relay/prompts/hurdle.md).
+
+**Question turns.** When your message only asks a question ("Why does the build fail on Windows?"), the first file edit in that turn is blocked with a request to answer first and propose the change. "Why does it fail? Please fix it." is a request, not a question.
+
+## Evidence
+
+During each request Relay records which files changed and which checks ran (tests, type checks, builds, linters) and whether they passed. A failing exit code is a failed check. When the agent's final message claims completion, Relay compares the claim with that record:
+
+| Status | Meaning |
+|---|---|
+| `verified` | Changes were made and a check passed after the last change, or only documentation changed. |
+| `unverified` | The message claims completion, but no check passed after the last change. |
+| `contradicted` | The message says checks pass, but the last check failed or none ran; or it says all tests pass, but the last check selected tests by name (`-t`, `--grep`, `-k`). |
+| `no-effect` | You requested a change and the message reports it done, but the tool calls only read state. |
+| `acknowledged` | The message states what was not verified or what failed. |
+
+For `unverified`, `contradicted`, and `no-effect`, Relay sends the agent one `[harness:evidence]` verification request instead of ending the run. That message appears in the transcript. If the next answer is still flagged, the run ends and Relay shows a warning.
+
+**Declared verification commands.** By default, common test, type-check, build, and lint commands count as checks. A project can declare its own with `harnessCore.verifyCommands`, for example `["npm run check", "./test.sh"]`. Then only commands that run one of them count, so `npx tsc` on one package does not stand in for the project's full check, and the verification request names the declared commands.
+
+**Masked exit codes.** A check counts only if its exit code reaches the tool. What follows the check can replace it: a pipe (`npm run check | tail`, unless `pipefail` is set), `||` (`npm test || true`), or a later command (`npm test; echo done`). Each of these exits 0 when the check fails, so such a run is not evidence. `&&` keeps the failure: `npm test && echo ok` counts.
+
+**Small slices.** Two signals, shown next to your latest message when they fire:
+
+- **Change size**: lines changed in the git working tree since your request began, against the last commit (added plus deleted lines; all lines of new untracked files). Above `harnessCore.maxChangedLines` (default 500), the agent is asked to verify and report this slice before starting more, and to propose how to split the rest.
+- **File growth**: when an edit takes a file past `harnessCore.maxFileLines` (default 1000), or grows a file already past it by 200 lines or more, the agent is asked to extract a cohesive part before adding more. A small edit to an already large file is not flagged.
+
+Outside a git repository the change-size signal is off; file growth still works. `/harness` shows the current numbers.
+
+## Context
+
+At each request, before the provider call:
+
+- The newest `harnessCore.contextKeepRecent` tool results (default 6) are sent verbatim.
+- Older results of at least 1,500 characters are replaced by a stub that names the call, its size and outcome, and whether the file changed later.
+- A digest of the replaced calls is restated next to your latest message, so the agent keeps track of progress.
+
+The session file is never changed; only the request is. Replacing an old message invalidates the provider's prompt cache after it, so replacement happens in batches of `harnessCore.contextBatchSize` results (default 6). Between batches the request prefix stays identical and the cache keeps hitting. Compaction still applies when the context approaches the model's limit; the context pillar makes that happen later.
+
+## Skills
+
+The skills section of the system prompt tells the model to treat a skill file as a router and to load the references and scripts it points to when a step needs them. During each run Relay records, per skill, how many resources were loaded (fanout), whether each load was followed by an action within three tool calls (effective uptake), when in the run loads happened, and revisits. `/harness` shows the last run's numbers and audits each `SKILL.md` skill for:
+
+- an entry file over 300 lines with no resources (consider splitting into references; keep strict formats and numeric contracts in the entry), or over 300 lines although it has resources
+- a `description` over 300 characters (it is all the model reads before deciding to load the skill, and it is paid for in every request)
+- references to files that do not exist
+- references without a reason or condition to load them
+- files in the skill directory that the entry never references
+
+## For SDK and extension authors
+
+The pillars live in `@relay-harness/agent-core` as `HarnessCore` and can be installed on any `Agent`:
+
+```typescript
+import { Agent, HarnessCore } from "@relay-harness/agent-core";
+
+const agent = new Agent({ streamFn });
+const uninstall = new HarnessCore({
+	alignment: { authorize: async (request) => confirm(request.effect.command) },
+	onEvent: (event) => console.log(event),
+}).install(agent);
+```
+
+In Relay, `session.harnessCore.core` exposes the constraint ledger, evidence ledger, context policy, and skill tracker.
+
+## Sources
+
+- Tang et al., *How Coding Agents Fail Their Users*, arXiv:2605.29442, 2026.
+- Advani, *From Confident Closing to Silent Failure: Characterizing False Success in LLM Agents*, arXiv:2606.09863, 2026.
+- Lodha et al., *Less Context, Better Agents*, arXiv:2606.10209, 2026.
+- *SkillJuror: Measuring How Agent Skill Organization Changes Runtime Behavior*, arXiv:2606.11543, 2026.

package/docs/how-relay-works.md

@@ -0,0 +1,49 @@
+# How Relay Works
+
+Relay coordinates model requests, tool execution, context assembly, and session storage. A session is Relay's record of a conversation, including messages, tool calls and results, model changes, compactions, and other events.
+
+Messages and events in a session form a tree. Each path through that tree is a branch. The branch ending at the current entry is the active branch and supplies the history for the next model request.
+
+## Agent loop
+
+A submitted message is added to the active branch. Relay builds a model request from the system prompt, active branch, available tools, and model settings, then sends it through the selected provider.
+
+The provider streams an assistant response, which can contain text and tool calls. Relay records the response, executes each tool call, and records the results. That completes one turn. If tool results or queued messages require another model request, Relay starts another turn. Otherwise, the run ends.
+
+Steering messages enter after the current assistant turn. Follow-up messages enter after the agent has finished its pending work. Aborting stops the current run and returns queued messages to the editor.
+
+## Context
+
+The active branch supplies conversation history. Relay converts its session entries into model-compatible user, assistant, and tool-result messages.
+
+Relay builds the system prompt from its base instructions and discovered context files. The request also carries tool definitions and skill descriptions.
+
+Full skill instructions are loaded on demand. Extensions can add instructions or transform context.
+
+Prompt templates expand editor input before it becomes a user message. Selected files, images, pasted text, and shell output can become message content.
+
+## Sessions
+
+Persistent sessions are JSONL files. Each tree entry has an ID and refers to its parent. The current entry identifies the active branch.
+
+Continuing from an earlier entry creates another branch in the same file. Forking and cloning copy selected history into a new session file.
+
+Model context is reconstructed from the active branch. Compaction inserts a summary entry that replaces older messages in subsequent model requests. The original entries remain in the session tree.
+
+## Interfaces
+
+Interactive mode renders session and agent events in the terminal. Print mode runs a prompt and writes the final response. JSON mode writes agent events as JSONL.
+
+RPC mode accepts JSONL commands on stdin and writes responses and events to stdout. The TypeScript SDK creates and controls agent sessions in process.
+
+All interfaces use the same agent and session mechanisms.
+
+## Extensions and resources
+
+Extensions are TypeScript modules loaded into the Relay process. Their factory functions register tools, commands, shortcuts, providers, event handlers, renderers, and terminal UI.
+
+Skills provide on-demand instructions and supporting files. Prompt templates provide reusable message text. Themes provide terminal colors. Relay packages distribute these resources through npm or git.
+
+## Trust and permissions
+
+Relay resolves project trust before loading project settings and resources. After the trust decision and project-resource loading, Relay loads context files. Enabled tools use the operating-system permissions of the Relay process. Extensions execute inside that process.

package/docs/index.md

@@ -0,0 +1,39 @@
+# Relay
+
+Relay is an extensible AI agent that works from your terminal. Give it a goal and a working folder, and it can inspect files, run commands, edit content, and work through multi-step tasks.
+
+Use Relay for software development, research notes, writing projects, data files, or hobby work. You can use Relay as is, prompt it to adapt itself to your workflow, or build other applications powered by Relay using the SDK.
+
+## Start using Relay
+
+New to Relay? Follow the [Quickstart](quickstart.md) to install Relay, connect a model, and complete your first task.
+
+If Relay is already installed, choose what you want to do:
+
+- [Use Relay interactively](usage.md) to add files, run commands, direct ongoing work, and export results.
+- [Choose a model](models.md) or connect a subscription, API key, local model, or compatible endpoint.
+- [Continue or branch a session](sessions.md) to resume work or explore another approach without losing history.
+- [Configure Relay](configuration.md) for your preferences, working folders, instructions, and reusable resources.
+- [Understand how Relay works](how-relay-works.md), including tools, context, sessions, and the agent loop.
+
+## Customize Relay
+
+Relay can reuse prompts, load specialized instructions, add executable integrations, change its terminal interface, connect model services, and distribute these resources as packages.
+Use the [Quickstart customization chooser](quickstart.md#choose-how-to-customize-relay) to select the smallest mechanism that meets your need.
+
+## Automate or embed Relay
+
+- Use [print mode](cli.md#invocation-and-output) for one-off and scripted tasks.
+- Use [JSON event stream mode](json.md) to consume structured events from one run.
+- Use [RPC mode](rpc.md) to control a separate Relay process.
+- Use the [TypeScript SDK](sdk.md) to run Relay inside an application.
+
+## Find reference and setup information
+
+Use the reference pages to look up [CLI options](cli.md), [settings](settings.md), [providers](providers.md), [keybindings](keybindings.md), and [environment variables](environment-variables.md).
+
+For platform-specific help, see [Terminal Setup](terminal-setup.md), [Windows](windows.md), [tmux](tmux.md), [Termux on Android](termux.md), or [Containerization](containerization.md).
+
+## Work safely
+
+Relay's tools and extensions run with the permissions of the Relay process. Project trust controls which project resources Relay loads, but it does not sandbox tool calls. Review [Security](security.md) before using untrusted files, repositories, extensions, or unattended automation.

package/docs/intake.md

@@ -0,0 +1,40 @@
+# Requirements Intake
+
+Tasks often arrive as one vague phrase ("change the calculation") or as text spread over several pages. An engineer cannot tell what to build, and asking one question at a time takes days. `/intake` reads the task, analyzes the code of the current project, and writes a Word questionnaire with every question the authors need to answer, in words a 12-year-old without technical knowledge understands.
+
+```
+/intake alterar cálculo
+/intake --out docs/questions.docx see notes/ticket-123.md and https://wiki.example.com/page
+```
+
+The questionnaire is written to `.relay/intake/<date>-<title>.docx` unless `--out` names another file. The agent replies with the path, the number of questions, and the main open points.
+
+## How it works
+
+1. **Read the description.** Files, folders and links the description names are read as part of it.
+2. **Analyze the code.** The agent searches for the words of the description, their synonyms and translations, and finds every place the request could mean. For "change the calculation" that is every calculation, with the screens, reports, exports and stored data each one touches. What the code answers is not asked.
+3. **Find the gaps.** A checklist covers which thing exactly, today versus wanted, inputs, expected results with real examples, rules and exceptions, people affected, ripple effects on other screens and reports, old data (retroactive or not), timing, messages, and how the authors will check the result.
+4. **Write the questionnaire.** The agent calls the `intake_questionnaire` tool with the questions. The tool rejects technical words (unless the glossary explains them), code names, file names, folder paths and sentences over 30 words, so the agent rewrites until a lay reader can answer.
+
+For "alterar cálculo" the questionnaire asks, among others: which calculation, offered as choices found in the code; which inputs change; examples of the expected result in a table to fill; whether reports and exports change too; whether past records must be recalculated, and from which date (asked only when the answer to the previous question is yes).
+
+## The document
+
+- The request as received, what was understood, and what the system does today, so the reader can correct mistakes.
+- Instructions on how to answer.
+- Questions grouped by topic. Each one says why it is asked and, when useful, how it works today.
+- Choice questions with ☐ boxes, plus "Other" and "I don't know"; yes/no questions; answer boxes; example tables to fill with real cases.
+- Follow-up questions marked "answer only if you answered X in question N", so one round is enough.
+- A glossary for the few words that cannot be avoided.
+
+Labels are in English, Portuguese or Spanish, following the language of the task description.
+
+## Using the tool directly
+
+`intake_questionnaire` has `deferred` exposure: it is not declared to the model until `/intake` loads it, so sessions that do not use it pay nothing for it. When [`tool_search`](cli.md#tools) is active, it can also load the tool when you ask for a requirements questionnaire in your own words. Once loaded, the tool stays declared on that branch.
+
+`/intake` also works in print and RPC mode:
+
+```bash
+relay -p "/intake alterar cálculo"
+```