npm - @h-rig/product-ad-website - Versions diffs - 0.0.6-alpha.283 - Mend

@h-rig/product-ad-website 0.0.6-alpha.283

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.md +3 -0
package/package.json +52 -0
package/site/assets/favicon.svg +1 -0
package/site/assets/og-card.png +0 -0
package/site/assets/rig.css +199 -0
package/site/assets/rig.js +66 -0
package/site/assets/search-index.json +1 -0
package/site/assets/site.css +46 -0
package/site/assets/site.js +510 -0
package/site/cli/index.html +88 -0
package/site/config/index.html +256 -0
package/site/docs/agent-tools/index.html +129 -0
package/site/docs/architecture/index.html +42 -0
package/site/docs/capabilities/index.html +84 -0
package/site/docs/entities/index.html +68 -0
package/site/docs/environment/index.html +62 -0
package/site/docs/faq/index.html +17 -0
package/site/docs/fleet-irc/index.html +44 -0
package/site/docs/gate/index.html +128 -0
package/site/docs/getting-started/index.html +50 -0
package/site/docs/glossary/index.html +31 -0
package/site/docs/index.html +68 -0
package/site/docs/operator/index.html +49 -0
package/site/docs/packages/index.html +36 -0
package/site/docs/pi-extensions/index.html +15 -0
package/site/docs/recipes/index.html +28 -0
package/site/docs/runs/index.html +35 -0
package/site/docs/security/index.html +29 -0
package/site/docs/server/index.html +27 -0
package/site/docs/swarm-commander/index.html +41 -0
package/site/docs/task-sources/index.html +129 -0
package/site/docs/troubleshooting/index.html +23 -0
package/site/docs/validators/index.html +177 -0
package/site/index.html +1653 -0
package/site/plugins/examples/index.html +419 -0
package/site/plugins/index.html +193 -0
package/site/skills/index.html +140 -0
package/site/variants/deck/index.html +1 -0

package/site/config/index.html ADDED Viewed

@@ -0,0 +1,256 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>rig.config.ts reference // RIG</title><meta property="og:image" content="https://how.rig-does.work/assets/og-card.png"><meta name="twitter:card" content="summary_large_image"><meta name="description" content="Every field of the project config, validated by defineConfig at load time."><meta property="og:title" content="rig.config.ts reference // RIG"><meta property="og:description" content="Every field of the project config, validated by defineConfig at load time."><link rel="stylesheet" href="../assets/rig.css?v=v9"><link rel="stylesheet" href="../assets/site.css?v=v9"><link rel="icon" type="image/svg+xml" href="../assets/favicon.svg"></head><body><canvas id="docfield"></canvas><nav class="nav"><div class="nav-in"><a class="brand" href="../index.html"><span class="mk"></span><span class="blk">Rig</span></a><button class="burger" onclick="document.getElementById('nl').classList.toggle('open')">menu</button><div class="nav-links" id="nl"><button class="nsearch" type="button" onclick="rigSearchOpen()">search<kbd>&#8984;K</kbd></button><a href="../index.html" class="">overview</a><a href="../docs/index.html" class="">docs</a><a href="../plugins/index.html" class="">plugins</a><a href="../skills/index.html" class="">skills</a><a href="../cli/index.html" class="">cli</a><a href="../config/index.html" class="active">config</a><a href="https://github.com/humanity-org/rig" class="ext">github</a></div></div></nav><div class="docwrap"><aside class="sidebar"><div class="grp">START</div><a href="../docs/index.html" class="">docs home</a><a href="../docs/capabilities/index.html" class="">capabilities</a><a href="../docs/getting-started/index.html" class="">getting started</a><div class="grp">RUN</div><a href="../docs/runs/index.html" class="">the run lifecycle</a><a href="../docs/operator/index.html" class="">operator guide</a><a href="../docs/swarm-commander/index.html" class="">swarm commander</a><a href="../docs/fleet-irc/index.html" class="">drone messages</a><a href="../docs/agent-tools/index.html" class="">agent tools</a><a href="../docs/gate/index.html" class="">the merge gate</a><a href="../docs/troubleshooting/index.html" class="">troubleshooting</a><div class="grp">ARCHITECTURE</div><a href="../docs/architecture/index.html" class="">how rig works</a><a href="../docs/entities/index.html" class="">entities & data model</a><a href="../docs/server/index.html" class="">OMP relay/web</a><a href="../docs/security/index.html" class="">security & trust</a><a href="../docs/environment/index.html" class="">environment variables</a><div class="grp">EXTEND</div><a href="../plugins/index.html" class="">plugin authoring</a><a href="../plugins/examples/index.html" class="">plugin examples</a><a href="../docs/pi-extensions/index.html" class="">OMP/Pi extensions</a><a href="../skills/index.html" class="">skills</a><a href="../docs/task-sources/index.html" class="">task sources</a><a href="../docs/validators/index.html" class="">validators & hooks</a><div class="grp">OPERATE</div><a href="../cli/index.html" class="">cli reference</a><a href="../config/index.html" class="active">rig.config.ts</a><a href="../docs/recipes/index.html" class="">recipes</a><a href="../docs/glossary/index.html" class="">glossary</a><a href="../docs/faq/index.html" class="">faq</a><div class="grp">ENGINE</div><a href="../docs/packages/index.html" class="">packages</a></aside><main class="doc"><h1>rig.config.ts</h1>
+<p class="lede">Rig configures a project two ways. The happy path is declarative <code>.rig/rigfig.toml</code> plain data. The power path is <code>.rig/rig.config.ts</code> TypeScript through <code>defineConfig</code> for project-specific plugin extras. Both resolve to the same <code>RigConfig</code>; the Rig application supplies one first-party graph in either mode.</p>
+<h2 id="where-it-lives">Where it lives <span class="ns">// discovery &amp; validation</span></h2>
+<p>Config lives under <code>.rig/</code> in the <b>project root</b> &mdash; the directory bare <code>rig</code> opens, or the one you hand it with <code>rig --workspace &lt;path&gt;</code>. The schema is <code>RigConfig</code> from <code>@rig/contracts</code>; <code>defineConfig</code> validates it at load time and throws a descriptive message on an invalid field. <code>rig init</code> scaffolds a <code>rigfig.toml</code> for you. Two forms are accepted:</p>
+<ul>
+<li><b><code>.rig/rigfig.toml</code></b> &mdash; declarative project data consumed with the application-owned plugin graph.</li>
+<li><b><code>.rig/rig.config.ts</code></b> &mdash; TypeScript for executable project plugin extras that plain data cannot carry.</li>
+</ul>
+<div class="note"><b>Session, attach, transport, and auth state are not in this file.</b> Private run-attach credentials are resolved at runtime and never enter config. The OS sandbox is <b>in</b> this schema &mdash; it is the <code>workspace.sandbox</code> field, <code>enforce</code> by default (see <a href="#sandbox-host">sandbox host requirements</a>).</div>
+<h2 id="defaults">Field defaults at a glance <span class="ns">// what you get if you omit it</span></h2>
+<p>The application graph is always present. Project-specific <code>plugins</code> default to an empty list; every optional policy block below uses the displayed schema default.</p>
+<table class="t"><thead><tr><th>field</th><th>required?</th><th>default when omitted</th></tr></thead>
+<tbody>
+<tr><td><code>project</code></td><td>required</td><td>&mdash; (<code>name</code> required; <code>repo?</code> optional)</td></tr>
+<tr><td><code>plugins</code></td><td>optional</td><td><code>[]</code> project extras; first-party plugins come from the application graph</td></tr>
+<tr><td><code>taskSource</code></td><td>required</td><td>&mdash; (<code>kind</code> required)</td></tr>
+<tr><td><code>workspace.checkout</code></td><td>optional</td><td><code>"worktree"</code></td></tr>
+<tr><td><code>workspace.sandbox</code></td><td>optional</td><td><code>"enforce"</code> (OS sandbox on by default)</td></tr>
+<tr><td><code>runtime.harness</code></td><td>optional</td><td><code>"pi"</code> (the only accepted value)</td></tr>
+<tr><td><code>runtime.mode</code></td><td>optional</td><td><code>"yolo"</code></td></tr>
+<tr><td><code>planning.mode</code></td><td>optional</td><td><code>"auto"</code></td></tr>
+<tr><td><code>automation.maxValidationAttempts</code></td><td>optional</td><td><code>30</code></td></tr>
+<tr><td><code>automation.maxPrFixIterations</code></td><td>optional</td><td><code>100500</code> (effectively unbounded)</td></tr>
+<tr><td><code>review.mode</code></td><td>optional</td><td>see <a href="#review">review</a> &middot; provider <code>"github"</code></td></tr>
+</tbody></table>
+<div class="note">The <b>strict merge gate is always on regardless of these defaults.</b> Even with <code>review.mode: "off"</code>, every Rig-owned merge still demands passing GitHub reviews and status checks, and pins the merge to the exact reviewed commit via <code>gh pr merge --match-head-commit &lt;sha&gt;</code> &mdash; a commit pushed after the gate clears makes the merge fail. See <a href="../docs/gate/index.html">the merge gate</a>.</div>
+<h2 id="minimal-github-project">Minimal GitHub project</h2>
+<p>The declarative <code>.rig/rigfig.toml</code> is what <code>rig init</code> writes. Each plugin owns the section it needs:</p>
+<pre class="code"><span class="c"># .rig/rigfig.toml</span>
+[project]
+name = <span class="s">"demo"</span>
+repo = <span class="s">"you/your-repo"</span>
+[taskSource]
+kind = <span class="s">"github-issues"</span>
+owner = <span class="s">"you"</span>
+repo = <span class="s">"your-repo"</span>
+state = <span class="s">"open"</span>
+[workspace]
+mainRepo = <span class="s">"."</span>
+checkout = <span class="s">"worktree"</span>
+sandbox = <span class="s">"enforce"</span></pre>
+<p>The equivalent power-path <code>.rig/rig.config.ts</code> expresses the same project data in TypeScript. The Rig application always supplies its one first-party plugin graph; <code>plugins</code> contains only project-specific extras:</p>
+<pre class="code"><span class="k">import</span> { defineConfig } <span class="k">from</span> <span class="s">"@rig/core"</span>;
+<span class="k">export default</span> <span class="f">defineConfig</span>({
+  project: { name: <span class="s">"demo"</span>, repo: <span class="s">"you/your-repo"</span> },
+  taskSource: { kind: <span class="s">"github-issues"</span>, owner: <span class="s">"you"</span>, repo: <span class="s">"your-repo"</span>, state: <span class="s">"open"</span> },
+  workspace: { mainRepo: <span class="s">"."</span>, checkout: <span class="s">"worktree"</span>, sandbox: <span class="s">"enforce"</span> },
+});</pre>
+<h2 id="top-level-fields">Top-level fields</h2>
+<table class="t"><thead><tr><th>field</th><th>type</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>project</code></td><td><code>{ name, repo? }</code></td><td>The project identity. <code>name</code> (string) is required; <code>repo?</code> ("owner/repo" slug) is the canonical task/workflow identity for GitHub-backed projects and Rig session entries.</td></tr>
+<tr><td><code>plugins</code></td><td><code>RigPlugin[]</code></td><td>Project-specific plugin extras. The application-owned first-party graph is always present; Rig does not scan disk for additional plugins.</td></tr>
+<tr><td><code>taskSource</code></td><td><code>{ kind, &hellip; }</code></td><td>Where work comes from: <code>github-issues</code>, <code>linear</code>, or a plugin-contributed kind. The factory for the kind must come from a loaded plugin.</td></tr>
+<tr><td><code>workspace</code></td><td><code>{ mainRepo, checkout, sandbox, &hellip; }</code></td><td>Git checkout strategy, OS sandbox mode, and scope normalization. Defaults to <code>{ mainRepo: ".", checkout: "worktree", sandbox: "enforce" }</code>.</td></tr>
+<tr><td><code>runtime</code></td><td>object</td><td>Harness, model, mode, Pi/OMP packages, agent roles, timeouts.</td></tr>
+<tr><td><code>planning</code> / <code>automation</code> / <code>pr</code> / <code>merge</code> / <code>review</code> / <code>issueAnalysis</code> / <code>github</code></td><td>object</td><td>Optional policy blocks (below).</td></tr>
+</tbody>
+</table>
+<p>Duplicate plugin ids are caught early: if two loaded plugins register the same id for the same registration type, the engine throws a duplicate-id error at startup. See <a href="../plugins/index.html">plugin authoring</a> for what a plugin can contribute.</p>
+<h2 id="task-source">taskSource <span class="ns">// required &middot; where work comes from</span></h2>
+<pre class="code">taskSource: {
+  kind: <span class="s">"github-issues"</span>,
+  owner: <span class="s">"your-org"</span>,
+  repo: <span class="s">"your-repo"</span>,
+  state: <span class="s">"open"</span>,               <span class="c">// "open" | "closed" | "all" (default "open")</span>
+  <span class="c">// labels: ["task"],                // all required; default []</span>
+  <span class="c">// options: { assignee: "@me" },     // source-side assignee filter</span>
+}</pre>
+<p>The only required key is <code>kind</code> (a string). It selects the canonical task adapter for dispatch and runtime provisioning &mdash; every kind resolves through executable factories contributed by loaded plugins. The first-party <code>github-issues</code> fields:</p>
+<table class="t"><thead><tr><th>field</th><th>type</th><th>default</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>owner</code></td><td>string</td><td>required</td><td>GitHub org or user.</td></tr>
+<tr><td><code>repo</code></td><td>string</td><td>required</td><td>Repository name, without the owner prefix.</td></tr>
+<tr><td><code>labels</code></td><td>string[]</td><td><code>[]</code></td><td>Only issues carrying <b>all</b> these labels become tasks.</td></tr>
+<tr><td><code>state</code></td><td>"open" | "closed" | "all"</td><td><code>"open"</code></td><td>Which issue states to enumerate.</td></tr>
+</tbody></table>
+<p>It requires the <code>gh</code> CLI authenticated with read access: <code>gh issue list</code> enumerates tasks, <code>gh issue edit</code> updates labels as tasks progress. See <a href="../docs/task-sources/index.html">task sources</a> for the full label convention (<code>scope:&lt;glob&gt;</code>, <code>role:&lt;id&gt;</code>, <code>validator:&lt;id&gt;</code>, lifecycle labels).</p>
+<p>The second first-party source is <b>Linear</b>, contributed by <code>@rig/linear-plugin</code>. Add <code>linear()</code> to <code>plugins</code> and put its config under the <code>options</code> bag &mdash; the documented extension point plugin factories read. The API key comes from <code>LINEAR_API_KEY</code> (or <code>linear({ apiKey })</code>), never config:</p>
+<pre class="code">taskSource: {
+  kind: <span class="s">"linear"</span>,
+  options: { teamKey: <span class="s">"ENG"</span>, states: [<span class="s">"Todo"</span>], labels: [<span class="s">"rig"</span>] },
+}</pre>
+<div class="note"><b>The task source needs its plugin loaded.</b> <code>github-issues</code> is supplied by the Rig application graph; <code>linear</code> needs <code>plugins: [linear()]</code> (or the <code>rigfig.toml</code> Linear section). Without a factory for the configured <code>kind</code>, task listing fails with <i>&ldquo;No task source factory registered&rdquo;</i>. GitHub Issues and Linear are the only first-party sources &mdash; there is no local task database or file-backed source.</div>
+<h2 id="workspace">workspace <span class="ns">// checkout &amp; sandbox</span></h2>
+<pre class="code">workspace: {
+  mainRepo: <span class="s">"."</span>,
+  checkout: <span class="s">"worktree"</span>,   <span class="c">// "worktree" | "directory"</span>
+  sandbox: <span class="s">"enforce"</span>,     <span class="c">// "enforce" (default) | "auto" | "off"</span>
+  <span class="c">// scopeNormalization: { ... }   // optional glob normalization</span>
+}</pre>
+<p><code>mainRepo</code> is the path to the repo the agent works in; relative paths resolve from the project root. <code>checkout</code> selects the git strategy. It is hygiene for parallel work, not the security boundary; <code>sandbox</code> controls that boundary.</p>
+<table class="t"><thead><tr><th>checkout</th><th>behavior</th></tr></thead>
+<tbody>
+<tr><td><code>"worktree"</code></td><td>The default. Creates a <code>git worktree</code> per run; agents work in the worktree, the main repo stays clean, and parallel runs never collide. Requires <code>mainRepo</code> to be a git repository.</td></tr>
+<tr><td><code>"directory"</code></td><td>Copies the repo into a temp directory. Slower, no shared git history. Useful when worktrees are unavailable.</td></tr>
+</tbody></table>
+<p>Docker/container isolation was declared but never implemented, so it is not in the public schema.</p>
+<table class="t"><thead><tr><th>sandbox</th><th>behavior</th></tr></thead>
+<tbody>
+<tr><td><code>"enforce"</code></td><td>The default. Runs the agent inside the OS sandbox (macOS seatbelt / Linux bwrap) and <b>refuses to run</b> unsandboxed when no backend is available &mdash; fail-closed.</td></tr>
+<tr><td><code>"auto"</code></td><td>Degrades to unsandboxed with a warning when no backend is available.</td></tr>
+<tr><td><code>"off"</code></td><td>Explicitly opts out of the OS sandbox.</td></tr>
+</tbody></table>
+<h3 id="scope-normalization">workspace.scopeNormalization <span class="ns">// optional &middot; nested-monorepo paths</span></h3>
+<p>Most projects don&rsquo;t need this &mdash; flat layouts (<code>src/foo/bar.ts</code>) match scope rules directly. You need it only when the engine sees paths like <code>repos/inner-repo/src/foo/bar.ts</code> but the operator wrote scope rules like <code>src/foo/**</code>. The shape:</p>
+<pre class="code">workspace: {
+  mainRepo: <span class="s">"."</span>,
+  checkout: <span class="s">"worktree"</span>,
+  scopeNormalization: {
+    <span class="c">// strip these prefixes when normalizing a path for scope-match;</span>
+    <span class="c">// applied in order, each strips at most once</span>
+    stripPrefixes: [<span class="s">"repos/inner-repo/"</span>],
+    <span class="c">// re-attach these prefixes when probing alternative paths</span>
+    searchPrefixes: [{
+      prefix: <span class="s">"repos/inner-repo/"</span>,
+      matchStartsWith: [<span class="s">"packages/"</span>, <span class="s">"services/"</span>],
+      matchExact: [<span class="s">"CODEOWNERS"</span>, <span class="s">"docker-compose.yml"</span>],
+    }],
+  },
+}</pre>
+<table class="t"><thead><tr><th>key</th><th>type</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>stripPrefixes</code></td><td>string[]</td><td>Prefixes stripped (in order, once each) before scope matching.</td></tr>
+<tr><td><code>searchPrefixes[].prefix</code></td><td>string</td><td>Prefix re-attached when a file might exist under either the stripped or prefixed form.</td></tr>
+<tr><td><code>searchPrefixes[].matchStartsWith</code></td><td>string[]</td><td>Apply the prefix only to paths starting with one of these.</td></tr>
+<tr><td><code>searchPrefixes[].matchExact</code></td><td>string[]</td><td>Apply the prefix to these exact paths.</td></tr>
+</tbody></table>
+<p>Without <code>scopeNormalization</code>, paths flow through unchanged &mdash; the safe default for projects where the project root <i>is</i> the monorepo.</p>
+<h2 id="runtime">runtime <span class="ns">// optional &middot; OMP harness &amp; model</span></h2>
+<pre class="code">runtime: {
+  harness: <span class="s">"pi"</span>,             <span class="c">// "pi" — the only accepted value (default "pi")</span>
+  mode: <span class="s">"yolo"</span>,             <span class="c">// "yolo" | "approval-required" (default "yolo")</span>
+  model: <span class="s">"team-default"</span>,    <span class="c">// optional model override (string)</span>
+  pi: { packages: [<span class="s">"pi-subagents"</span>, <span class="s">"pi-web-access@1.2.0"</span>] },
+  agentRoles: { <span class="s">"std:coder"</span>: { model: <span class="s">"team-default"</span> } },
+  timeouts: { <span class="c">/* Record&lt;string, number&gt; — accepted but NOT consumed */</span> },
+}</pre>
+<table class="t"><thead><tr><th>field</th><th>type</th><th>default</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>harness</code></td><td>"pi"</td><td><code>"pi"</code></td><td>The coding-agent executor. Pi is the only supported live harness &mdash; older Codex/Claude adapter names are deliberately not accepted, since dispatched runs execute on Pi regardless.</td></tr>
+<tr><td><code>mode</code></td><td>"yolo" | "approval-required"</td><td><code>"yolo"</code></td><td>Autonomous vs. approval-gated execution.</td></tr>
+<tr><td><code>model</code></td><td>string</td><td>unset</td><td>Optional model override for the harness.</td></tr>
+<tr><td><code>pi.packages</code></td><td>string[]</td><td>unset</td><td>Pi extension packages every session loads (see below).</td></tr>
+<tr><td><code>agentRoles</code></td><td>Record&lt;string, unknown&gt;</td><td>unset</td><td>Map of plugin-registered role id &rarr; config (see below).</td></tr>
+<tr><td><code>timeouts</code></td><td>Record&lt;string, number&gt;</td><td>unset</td><td>Schema-accepted, <b>not consumed</b> (see below).</td></tr>
+</tbody></table>
+<p>The generated starter config defaults to the OMP/Pi happy path (<code>harness: "pi"</code>, <code>mode: "yolo"</code>). <code>runtime.pi.packages</code> is written into the workspace&rsquo;s <code>.pi/settings.json</code> (Pi&rsquo;s native per-project package list) when the workspace is prepared; OMP/Pi installs missing packages at session start, locally and on workers. Removing one from config removes it from settings. Discover community extensions with <code>rig pi search &lt;term&gt;</code>; operator-local additions go through <code>rig pi add &lt;source&gt;</code> &mdash; see <a href="../docs/pi-extensions/index.html">OMP/Pi extensions</a>.</p>
+<p><code>runtime.agentRoles</code> is a map of role id to config, used to override the model for a role registered by a loaded plugin (for example <code>"std:coder": { model: "team-default" }</code>). Keys must match registered role ids; unknown keys are ignored.</p>
+<div class="note"><b><code>runtime.timeouts</code> is accepted but currently has no effect.</b> The field is schema-accepted (<code>Record&lt;string, number&gt;</code>) for forward compatibility, but the current runtime consumes no timeout keys from it &mdash; session and validator timeouts are governed by runtime policy and environment variables (for example <code>RIG_VALIDATION_TIMEOUT_MS</code>, see <a href="../docs/environment/index.html">environment variables</a>), not by this map. Setting values here is harmless but inert.</div>
+<div class="note"><b>Attach transport is not a config field.</b> Detached-run terminal/web attach uses <code>wss://where.rig-does.work</code> by default. Rig resolves private attach credentials at runtime; config selects placement and relay endpoints, not sessions.</div>
+<div class="note"><b>Agent git is unscoped by default.</b> Agents stage and commit everything changed inside the task worktree &mdash; the worktree boundary, the scope-guard write hook, and the mandatory PR review gate are the controls. Scoped manifest staging is explicit opt-in via <code>rig-agent git commit --scoped</code>.</div>
+<h2 id="planning">planning <span class="ns">// optional &middot; plan-stage policy</span></h2>
+<pre class="code">planning: {
+  mode: <span class="s">"auto"</span>,                <span class="c">// "auto" | "always" | "off" (default "auto")</span>
+  <span class="c">// requireForLabels: ["epic"],    // always plan for these labels</span>
+  <span class="c">// skipForLabels: ["chore"],      // never plan for these labels</span>
+}</pre>
+<p><code>auto</code> lets the workflow engine classify whether a task needs an explicit plan from issue metadata, risk, and labels before the OMP session starts work. <code>always</code> forces a plan stage; <code>off</code> skips it.</p>
+<h2 id="automation-pr-merge">automation / pr / merge <span class="ns">// optional &middot; the autonomous loop</span></h2>
+<pre class="code">automation: {
+  maxValidationAttempts: <span class="s">30</span>,    <span class="c">// validation retry cap (default 30)</span>
+  maxPrFixIterations: <span class="s">100500</span>,   <span class="c">// PR fix loop cap — effectively unbounded by default</span>
+};
+pr: {
+  mode: <span class="s">"auto"</span>,                <span class="c">// "auto" | "ask" | "off"</span>
+  watchChecks: <span class="k">true</span>,
+  autoFixChecks: <span class="k">true</span>,
+  autoFixReview: <span class="k">true</span>,
+  <span class="c">// pendingTimeoutMs / pendingPollMs — how long and how often to wait on pending checks</span>
+};
+merge: {
+  mode: <span class="s">"auto"</span>,                <span class="c">// "auto" | "off" | "pr-ready" (stop once the PR is gate-ready)</span>
+  method: <span class="s">"repo-default"</span>,      <span class="c">// "repo-default" | "squash" | "merge" | "rebase"</span>
+  deleteBranch: <span class="s">"repo-default"</span>, <span class="c">// "repo-default" | boolean</span>
+  allowedFailures: [],          <span class="c">// explicit allowlist of acceptable failing checks</span>
+  <span class="c">// bypass: true               // admin-merge past branch protection (off by default)</span>
+};</pre>
+<table class="t"><thead><tr><th>field</th><th>type</th><th>default</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>automation.maxValidationAttempts</code></td><td>number</td><td><code>30</code></td><td>Validation retry cap before a task is marked needs-attention.</td></tr>
+<tr><td><code>automation.maxPrFixIterations</code></td><td>number</td><td><code>100500</code></td><td>PR-fix loop cap &mdash; effectively unbounded, for Rig-owned automerge convergence.</td></tr>
+<tr><td><code>pr.mode</code></td><td>"auto" | "ask" | "off"</td><td>&mdash;</td><td>Whether Rig opens / drives the PR.</td></tr>
+<tr><td><code>pr.watchChecks</code></td><td>boolean</td><td>&mdash;</td><td>Watch CI checks after opening the PR.</td></tr>
+<tr><td><code>pr.autoFixChecks</code> / <code>autoFixReview</code></td><td>boolean</td><td>&mdash;</td><td>Steer Pi to fix failing checks / actionable review feedback.</td></tr>
+<tr><td><code>pr.pendingTimeoutMs</code> / <code>pendingPollMs</code></td><td>number</td><td>&mdash;</td><td>How long to wait on pending checks, and the poll interval.</td></tr>
+<tr><td><code>merge.mode</code></td><td>"auto" | "off" | "pr-ready"</td><td>&mdash;</td><td><code>pr-ready</code> stops once the PR is gate-ready instead of merging.</td></tr>
+<tr><td><code>merge.method</code></td><td>"repo-default" | "squash" | "merge" | "rebase"</td><td>&mdash;</td><td>The merge method passed to <code>gh pr merge</code>.</td></tr>
+<tr><td><code>merge.deleteBranch</code></td><td>"repo-default" | boolean</td><td>&mdash;</td><td>Delete the branch after merge.</td></tr>
+<tr><td><code>merge.allowedFailures</code></td><td>string[]</td><td><code>[]</code></td><td>Explicit allowlist of acceptable failing check names.</td></tr>
+<tr><td><code>merge.bypass</code></td><td>boolean</td><td>off</td><td>Admin-merge past branch protection where permitted.</td></tr>
+</tbody></table>
+<p>The happy path is autonomous once you dispatch from the <code>/fleet</code> card, <code>rig run dispatch &lt;taskId&gt;</code>, or ask the Swarm Commander model role: validate, steer the detached OMP drone on deterministic failures, open a PR, watch checks/review, merge using repo defaults, and close the issue. Branch protection and repo rules are obeyed by default, and merge is pinned to the gate-verified head SHA. See <a href="../docs/gate/index.html">the merge gate spec</a>.</p>
+<h2 id="review">review <span class="ns">// optional &middot; completion gate</span></h2>
+<pre class="code">review: {
+  mode: <span class="s">"required"</span>,            <span class="c">// "off" | "advisory" | "required"</span>
+  provider: <span class="s">"github"</span>,          <span class="c">// GitHub reviews + status checks (the default provider)</span>
+}</pre>
+<p>The <b>completion review gate</b> &mdash; the verdict on task completion: <code>off</code> skips it, <code>advisory</code> reports without blocking, <code>required</code> makes a failing review block completion. The <b>strict merge gate is separate and always on</b>: every Rig-owned merge demands passing GitHub reviews and status checks before <code>gh pr merge</code> is even attempted, and pins the merge to the reviewed head SHA, regardless of this setting. The gate policy is owned by the swappable <code>@rig/pr-review-plugin</code> (default provider <code>github</code>). Inspect or change the completion policy with <code>rig review show</code> / <code>rig review set</code>. The full evidence model is on <a href="../docs/gate/index.html">the merge gate page</a>.</p>
+<h2 id="github">github <span class="ns">// optional &middot; issue &amp; project sync</span></h2>
+<pre class="code">github: {
+  projects: {
+    enabled: <span class="k">true</span>,
+    projectId: <span class="s">"PVT_..."</span>,
+    statusFieldId: <span class="s">"PVTSSF_..."</span>,
+    statuses: { running: <span class="s">"In Progress"</span>, prOpen: <span class="s">"In Review"</span>, done: <span class="s">"Done"</span> },
+  },
+}</pre>
+<p>GitHub Projects status sync is a separate, optional switch &mdash; first-class when enabled. The workflow engine updates the configured Project v2 Status field at run start, PR open, CI/review fixing, merging, done, and needs-attention, using the <code>statuses</code> map you provide (any subset of <code>running</code>, <code>prOpen</code>, <code>ciFixing</code>, <code>merging</code>, <code>done</code>, <code>needsAttention</code>). Project status sync is driven solely by <code>projects.enabled</code>.</p>
+<h2 id="issue-analysis">issueAnalysis <span class="ns">// optional &middot; continuous triage</span></h2>
+<pre class="code">issueAnalysis: {
+  enabled: <span class="k">true</span>,
+  harness: <span class="s">"pi"</span>,
+  mode: <span class="s">"continuous"</span>,        <span class="c">// "continuous" | "off"</span>
+}</pre>
+<p>Turn this on and the workflow engine keeps a drone on triage: it reads GitHub issues through OMP/Pi, maintains Rig-owned metadata blocks and labels, and proposes or creates <code>rig:generated</code> issues &mdash; never touching the human-authored body.</p>
+<h2 id="declarative-toml">Declarative rigfig.toml <span class="ns">// the happy path</span></h2>
+<p><code>.rig/rigfig.toml</code> is plain data with no executable plugin logic. The application supplies the one first-party graph; the file carries project sections such as <code>[project]</code>, <code>[taskSource]</code>, <code>[workspace]</code>, <code>[runtime]</code>, <code>[planning]</code>, <code>[automation]</code>, <code>[merge]</code>, <code>[pr]</code>, <code>[github]</code>, and <code>[issueAnalysis]</code>. Reach for <code>.rig/rig.config.ts</code> only when project-specific executable factories, task sources, or validators are required.</p>
+<h2 id="sandbox-host">Sandbox host requirements <span class="ns">// what workspace.sandbox needs</span></h2>
+<p>The OS sandbox is the <code>workspace.sandbox</code> field, <code>"enforce"</code> by default &mdash; it fails closed when the host lacks a usable backend rather than silently degrading. Check the host that will execute runs with <code>rig doctor</code>:</p>
+<table class="t"><thead><tr><th>host</th><th>strict backend requirement</th></tr></thead>
+<tbody>
+<tr><td>Linux</td><td><code>bubblewrap</code> / <code>bwrap</code>, with <code>bwrap --ro-bind / / --proc /proc --dev /dev -- true</code> passing. Ubuntu 24.04 / AppArmor-restricted hosts may need <code>kernel.apparmor_restrict_unprivileged_userns=0</code>.</td></tr>
+<tr><td>macOS</td><td>the built-in seatbelt (<code>sandbox-exec</code>) available on PATH.</td></tr>
+</tbody></table>
+<p><code>sandbox: "auto"</code>, <code>sandbox: "off"</code>, <code>RIG_RUNTIME_SANDBOX=off</code>, and <code>RIG_SANDBOX_BACKEND=none</code> are degraded mode &mdash; useful while diagnosing host setup, but unsandboxed and not strict run evidence. See <a href="../docs/security/index.html">security &amp; trust</a> and <a href="../docs/environment/index.html">environment variables</a>.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><b><a href="../docs/entities/index.html">Entities &amp; data model</a></b> &mdash; the Task, Run, and Worktree shapes the config feeds into.</li>
+<li><b><a href="../docs/gate/index.html">The strict merge gate</a></b> &mdash; the always-on verdict that <code>merge</code> and <code>review</code> sit on top of.</li>
+<li><b><a href="../docs/runs/index.html">Runs &amp; OMP sessions</a></b> &mdash; the runtime path this config feeds: bounded CNet projection, Swarm Commander model role, and <code>/fleet</code>/<code>/tasks</code>/<code>/drone</code>.</li>
+<li><b><a href="../docs/environment/index.html">Environment variables</a></b> &mdash; the runtime knobs (timeouts, tokens, adapters) that live outside the schema.</li>
+<li><b><a href="../plugins/index.html">Plugin authoring</a></b> &mdash; how the <code>plugins</code> array contributes task sources, validators, roles, and CLI commands.</li>
+</ul>
+<div class="nextnav"><a href="../cli/index.html"><span class="dir">&larr; Back</span><span class="ttl">CLI reference</span></a><a href="../docs/recipes/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Recipes</span></a></div>
+</main></div><footer><div class="wrap"><div class="foot"><div class="col"><h5>orchestrate</h5><a href="../docs/getting-started/index.html">getting started</a><a href="../docs/runs/index.html">the run lifecycle</a><a href="../docs/operator/index.html">operator guide</a><a href="../docs/gate/index.html">the merge gate</a></div><div class="col"><h5>extend</h5><a href="../plugins/index.html">plugin authoring</a><a href="../skills/index.html">skills guide</a><a href="../docs/pi-extensions/index.html">OMP/Pi extensions</a><a href="../docs/packages/index.html">packages</a></div><div class="col"><h5>live</h5><a href="../index.html">the home rig</a><a href="../cli/index.html">cli reference</a><a href="https://where.rig-does.work/install">install script</a></div><div class="sig">Rig is the OMP session extension.<br><span class="blk">You are the operator.</span><br>release: rig --version</div></div></div></footer><script>document.querySelectorAll('[data-tab]').forEach(function(t){t.onclick=function(){document.querySelectorAll('[data-tab]').forEach(function(x){x.classList.remove('on')});document.querySelectorAll('[data-cmd]').forEach(function(x){x.style.display='none'});t.classList.add('on');var c=document.querySelector('[data-cmd="'+t.dataset.tab+'"]');if(c)c.style.display='flex';};});document.querySelectorAll('.cp').forEach(function(b){b.onclick=function(){var code=b.parentElement.querySelector('code');if(navigator.clipboard)navigator.clipboard.writeText(code.innerText);var o=b.innerText;b.innerText='copied';setTimeout(function(){b.innerText=o;},1200);};});</script><script src="../assets/rig.js"></script><script src="../assets/site.js?v=v9"></script></body></html>

package/site/docs/agent-tools/index.html ADDED Viewed

@@ -0,0 +1,129 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Agent tools // RIG</title><meta property="og:image" content="https://how.rig-does.work/assets/og-card.png"><meta name="twitter:card" content="summary_large_image"><meta name="description" content="Drone in-session Rig tools: rig_task, rig_git, rig_repo_sync, rig_profile, rig_review, and operator messaging."><meta property="og:title" content="Agent tools // RIG"><meta property="og:description" content="Typed Rig in-session tools for drones, with op matrices, flags, IRC, and safety rules."><link rel="stylesheet" href="../../assets/rig.css?v=v9"><link rel="stylesheet" href="../../assets/site.css?v=v9"><link rel="icon" type="image/svg+xml" href="../../assets/favicon.svg"></head><body data-doc-theme="toolgrid"><canvas id="docfield"></canvas><nav class="nav"><div class="nav-in"><a class="brand" href="../../index.html"><span class="mk"></span><span class="blk">Rig</span></a><button class="burger" onclick="document.getElementById('nl').classList.toggle('open')">menu</button><div class="nav-links" id="nl"><button class="nsearch" type="button" onclick="rigSearchOpen()">search<kbd>&#8984;K</kbd></button><a href="../../index.html" class="">overview</a><a href="../../docs/index.html" class="active">docs</a><a href="../../plugins/index.html" class="">plugins</a><a href="../../skills/index.html" class="">skills</a><a href="../../cli/index.html" class="">cli</a><a href="../../config/index.html" class="">config</a><a href="https://github.com/humanity-org/rig" class="ext">github</a></div></div></nav><div class="docwrap"><aside class="sidebar"><div class="grp">START</div><a href="../../docs/index.html" class="">docs home</a><a href="../../docs/capabilities/index.html" class="">capabilities</a><a href="../../docs/getting-started/index.html" class="">getting started</a><div class="grp">RUN</div><a href="../../docs/runs/index.html" class="">the run lifecycle</a><a href="../../docs/operator/index.html" class="">operator guide</a><a href="../../docs/swarm-commander/index.html" class="">swarm commander</a><a href="../../docs/fleet-irc/index.html" class="">drone messages</a><a href="../../docs/agent-tools/index.html" class="active">agent tools</a><a href="../../docs/gate/index.html" class="">the merge gate</a><a href="../../docs/troubleshooting/index.html" class="">troubleshooting</a><div class="grp">ARCHITECTURE</div><a href="../../docs/architecture/index.html" class="">how rig works</a><a href="../../docs/entities/index.html" class="">entities & data model</a><a href="../../docs/server/index.html" class="">OMP relay/web</a><a href="../../docs/security/index.html" class="">security & trust</a><a href="../../docs/environment/index.html" class="">environment variables</a><div class="grp">EXTEND</div><a href="../../plugins/index.html" class="">plugin authoring</a><a href="../../plugins/examples/index.html" class="">plugin examples</a><a href="../../docs/pi-extensions/index.html" class="">OMP/Pi extensions</a><a href="../../skills/index.html" class="">skills</a><a href="../../docs/task-sources/index.html" class="">task sources</a><a href="../../docs/validators/index.html" class="">validators & hooks</a><div class="grp">OPERATE</div><a href="../../cli/index.html" class="">cli reference</a><a href="../../config/index.html" class="">rig.config.ts</a><a href="../../docs/recipes/index.html" class="">recipes</a><a href="../../docs/glossary/index.html" class="">glossary</a><a href="../../docs/faq/index.html" class="">faq</a><div class="grp">ENGINE</div><a href="../../docs/packages/index.html" class="">packages</a></aside><main class="doc"><h1>Agent tools</h1>
+<p class="lede">A drone inside a Rig run does not probe the raw CLI. It gets a small typed tool pack: task state, scoped git, repo sync, runtime profile, review policy, and operator messaging. Every call is a schema&rsquo;d op; unknown ops refuse with <code>NEEDS_CLARIFICATION</code> instead of becoming argv.</p>
+<h2 id="tool-pack">Tool pack <span class="ns">// detached-drone controls</span></h2>
+<table class="t"><thead><tr><th>tool</th><th>what it controls</th><th>execution seam</th></tr></thead><tbody>
+<tr><td><code>rig_task</code></td><td>Current task facts, scope, dependency state, artifacts, validation, task lookup, and closeout evidence records.</td><td>Builds a typed <code>rig-agent</code> argv array.</td></tr>
+<tr><td><code>rig_git</code></td><td>Run-scoped git status, preflight, branch sync, commit, snapshot, and PR open.</td><td>Builds <code>rig-agent git ...</code> with only declared flags.</td></tr>
+<tr><td><code>rig_repo_sync</code></td><td>Repo-sync lifecycle: sync, ensure, pins, verify, discover, baseline.</td><td>Builds <code>rig-agent repo-sync ...</code>.</td></tr>
+<tr><td><code>rig_profile</code></td><td>Worker runtime/model/plugin profile for the run.</td><td>Builds <code>rig-agent profile ...</code>.</td></tr>
+<tr><td><code>rig_review</code></td><td>Review mode and provider policy.</td><td>Builds <code>rig-agent review ...</code>.</td></tr>
+<tr><td><code>irc</code></td><td>Drone-to-operator fleet messages and run inbox reads.</td><td>Appends/reads run journal IRC messages.</td></tr>
+</tbody></table>
+<p>The five <code>rig_*</code> tools are registered by the run worker extension after the IRC tool. They resolve <code>$RIG_AGENT_BIN</code>, run inside <code>$RIG_TASK_WORKSPACE</code> or the session cwd, spawn with <code>shell:false</code>, return stdout on success, and return structured <code>COMMAND_FAILED</code> details on non-zero exit.</p>
+<h2 id="rig-task">rig_task <span class="ns">// task state and artifacts</span></h2>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>argv</th></tr></thead><tbody>
+<tr><td><code>info</code></td><td>none</td><td><code>rig-agent info</code></td></tr>
+<tr><td><code>scope</code></td><td><code>files?: boolean</code></td><td><code>rig-agent scope [--files]</code></td></tr>
+<tr><td><code>deps</code></td><td>none</td><td><code>rig-agent deps</code></td></tr>
+<tr><td><code>status</code></td><td>none</td><td><code>rig-agent status</code></td></tr>
+<tr><td><code>artifacts</code></td><td>none</td><td><code>rig-agent artifacts</code></td></tr>
+<tr><td><code>artifact-dir</code></td><td>none</td><td><code>rig-agent artifact-dir</code></td></tr>
+<tr><td><code>project-root</code></td><td>none</td><td><code>rig-agent project-root</code></td></tr>
+<tr><td><code>monorepo-root</code></td><td>none</td><td><code>rig-agent monorepo-root</code></td></tr>
+<tr><td><code>artifact-write</code></td><td><code>filename</code> and exactly one of <code>file</code> or <code>content</code></td><td><code>rig-agent artifact-write &lt;filename&gt; [--file &lt;file&gt;]</code>; <code>content</code> is stdin</td></tr>
+<tr><td><code>validate</code></td><td>none</td><td><code>rig-agent validate</code></td></tr>
+<tr><td><code>lookup</code></td><td><code>id</code></td><td><code>rig-agent lookup &lt;id&gt;</code></td></tr>
+<tr><td><code>record</code></td><td><code>type: decision|failure</code>, <code>text</code></td><td><code>rig-agent record &lt;type&gt; &lt;text&gt;</code></td></tr>
+<tr><td><code>help</code></td><td>none</td><td><code>rig-agent help</code></td></tr>
+<tr><td><code>completion-verification</code></td><td>none</td><td><code>rig-agent completion-verification</code></td></tr>
+<tr><td><code>completition-verification</code></td><td>none</td><td><code>rig-agent completition-verification</code> &mdash; alias for the correct spelling</td></tr>
+</tbody></table>
+<pre class="code">rig_task({ "op": "scope", "files": true })
+rig_task({ "op": "artifact-write", "filename": "proof.txt", "content": "typecheck passed\n" })
+rig_task({ "op": "record", "type": "decision", "text": "kept provider writeback read-only" })</pre>
+<div class="note"><b>Artifact write guard:</b> <code>artifact-write</code> accepts <i>exactly one</i> source: <code>file</code> maps to <code>--file</code>, <code>content</code> goes to stdin. Both or neither is a schema refusal.</div>
+<h2 id="rig-git">rig_git <span class="ns">// scoped branch discipline</span></h2>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>argv</th></tr></thead><tbody>
+<tr><td><code>status</code></td><td><code>task?</code></td><td><code>rig-agent git status [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>changed</code></td><td><code>task?</code>, <code>scoped?</code></td><td><code>rig-agent git changed [--task &lt;id&gt;] [--scoped]</code></td></tr>
+<tr><td><code>preflight</code></td><td><code>task?</code>, <code>strict?</code></td><td><code>rig-agent git preflight [--task &lt;id&gt;] [--strict]</code></td></tr>
+<tr><td><code>sync-branch</code></td><td><code>task?</code></td><td><code>rig-agent git sync-branch [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>ensure-branch</code></td><td><code>task?</code></td><td><code>rig-agent git ensure-branch [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>commit</code></td><td><code>task?</code>, <code>target?: monorepo|project|both</code>, <code>message?</code>, <code>allowEmpty?</code>, <code>scoped?</code></td><td><code>rig-agent git commit [--task &lt;id&gt;] [--target ...] [--message ...] [--allow-empty] [--scoped]</code></td></tr>
+<tr><td><code>snapshot</code></td><td><code>task?</code>, <code>output?</code></td><td><code>rig-agent git snapshot [--task &lt;id&gt;] [--output &lt;path&gt;]</code></td></tr>
+<tr><td><code>open-pr</code></td><td><code>task?</code>, <code>target?: monorepo|project</code>, <code>reviewer?</code>, <code>base?</code>, <code>title?</code>, <code>body?</code>, <code>draft?</code></td><td><code>rig-agent git open-pr [--task &lt;id&gt;] [--target ...] [--reviewer ...] [--base ...] [--title ...] [--body ...] [--draft]</code></td></tr>
+</tbody></table>
+<pre class="code">rig_git({ "op": "changed", "scoped": true })
+rig_git({ "op": "preflight", "strict": true })
+rig_git({ "op": "commit", "target": "project", "message": "tighten IRC proof", "scoped": true })
+rig_git({ "op": "open-pr", "target": "project", "draft": true, "base": "main" })</pre>
+<p>This is the drone&rsquo;s branch discipline panel. It is still git underneath, but the drone never builds arbitrary shell.</p>
+<h2 id="rig-repo-sync">rig_repo_sync <span class="ns">// remote repo pin line</span></h2>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>argv</th></tr></thead><tbody>
+<tr><td><code>sync</code></td><td><code>task?</code></td><td><code>rig-agent repo-sync sync [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>ensure</code></td><td><code>task?</code></td><td><code>rig-agent repo-sync ensure [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>pins</code></td><td><code>task?</code></td><td><code>rig-agent repo-sync pins [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>verify</code></td><td><code>task?</code></td><td><code>rig-agent repo-sync verify [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>discover</code></td><td><code>task?</code></td><td><code>rig-agent repo-sync discover [--task &lt;id&gt;]</code></td></tr>
+<tr><td><code>baseline</code></td><td><code>task?</code>, <code>refresh?</code></td><td><code>rig-agent repo-sync baseline [--task &lt;id&gt;] [--refresh]</code></td></tr>
+</tbody></table>
+<pre class="code">rig_repo_sync({ "op": "pins" })
+rig_repo_sync({ "op": "baseline", "refresh": true })</pre>
+<p>Use it when the sortie spans repos and the drone needs to prove the pin state before committing.</p>
+<h2 id="rig-profile">rig_profile <span class="ns">// worker profile</span></h2>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>argv</th></tr></thead><tbody>
+<tr><td><code>show</code></td><td><code>compact?</code></td><td><code>rig-agent profile show [--compact]</code></td></tr>
+<tr><td><code>set</code></td><td>Either <code>preset: claude-code|codex-cli|codex-app-server</code> or custom <code>model?</code>, <code>runtime?</code>, <code>plugin?</code></td><td><code>rig-agent profile set &lt;preset&gt;</code> or <code>rig-agent profile set [--model ...] [--runtime ...] [--plugin ...]</code></td></tr>
+</tbody></table>
+<pre class="code">rig_profile({ "op": "show", "compact": true })
+rig_profile({ "op": "set", "preset": "codex-cli" })
+rig_profile({ "op": "set", "model": "gpt-5.5", "runtime": "pi", "plugin": "rig-run-worker" })</pre>
+<div class="note"><b>Schema guard:</b> <code>profile set</code> accepts a preset or the custom option trio, not both. That is enforced before argv construction.</div>
+<h2 id="rig-review">rig_review <span class="ns">// merge-gate review mode</span></h2>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>argv</th></tr></thead><tbody>
+<tr><td><code>show</code></td><td>none</td><td><code>rig-agent review show</code></td></tr>
+<tr><td><code>set</code></td><td><code>mode: off|advisory|required</code>, <code>provider?: github</code></td><td><code>rig-agent review set &lt;mode&gt; [--provider github]</code></td></tr>
+</tbody></table>
+<pre class="code">rig_review({ "op": "show" })
+rig_review({ "op": "set", "mode": "required", "provider": "github" })</pre>
+<h2 id="irc">irc <span class="ns">// drone-to-operator comms</span></h2>
+<p>The drone-side <code>irc</code> tool is the fiber line back to the operator. It is available only inside a Rig run session (<code>RIG_RUN_PROCESS=1</code>); outside that context it refuses with <code>CONFLICT</code>.</p>
+<table class="t"><thead><tr><th>op</th><th>params</th><th>behavior</th></tr></thead><tbody>
+<tr><td><code>send</code> or omitted</td><td><code>to?</code>, <code>message?</code>, <code>body?</code>, <code>replyTo?</code></td><td>Appends an <code>irc-message</code> envelope to the run journal. v1 accepts only <code>to: "operator"</code>; omitted means operator. Returns a local seq receipt.</td></tr>
+<tr><td><code>inbox</code></td><td><code>sinceSeq?</code>, <code>limit?</code></td><td>Reads run IRC messages from the run read model. Limit defaults to 20 and clamps to 50.</td></tr>
+</tbody></table>
+<pre class="code">irc({ "message": "Blocked on missing Redis URL for this sortie." })
+irc({ "op": "send", "replyTo": "0a4...", "body": "Applied the operator direction; re-running closeout." })
+irc({ "op": "inbox", "sinceSeq": 120, "limit": 10 })</pre>
+<p>The drone tool cannot DM another drone or a Commander mailbox. Foreground direction uses the exact run&rsquo;s generated CNet action; the Commander role can invoke that action during an operator turn.</p>
+<h2 id="safety">Safety model <span class="ns">// refusal before argv</span></h2>
+<ul>
+<li><b>Discriminated ops.</b> Every <code>rig_*</code> tool is a Zod discriminated union on <code>op</code>. Unknown ops return <code>NEEDS_CLARIFICATION</code>.</li>
+<li><b>Strict params.</b> Each op schema is strict; stray flags are validation errors, not best-effort argv.</li>
+<li><b>No shell passthrough.</b> Successful parses build string arrays and call <code>spawn(binary, argv, { shell:false })</code>.</li>
+<li><b>Run-bound workspace.</b> Command cwd comes from <code>RIG_TASK_WORKSPACE</code>, falling back to the session cwd.</li>
+<li><b>Raw help nuance.</b> The raw <code>rig-agent</code> command has a <code>help</code> subcommand, but no <code>--help</code> discovery surface. The in-session tools are the discoverable surface: schema, labels, renderers, and refusal messages.</li>
+</ul>
+<pre class="code">rig_git({ "op": "rm-rf", "path": "/" })
+// NEEDS_CLARIFICATION: rig_git refuses unknown op `rm-rf`
+rig_task({ "op": "artifact-write", "filename": "x.txt", "file": "a.txt", "content": "b" })
+// NEEDS_CLARIFICATION: artifact-write requires exactly one source</pre>
+<h2 id="receipts">Receipts</h2>
+<ul>
+<li><code>packages/run-plugin/src/worker/extension.ts</code> registers <code>irc</code> first, then the five <code>rig_*</code> tools, and activates <code>irc</code> when <code>RIG_RUN_PROCESS=1</code>.</li>
+<li><code>packages/run-plugin/src/worker/rig-agent-tools.ts</code> defines the op schemas, argv builders, refusal behavior, env/cwd resolution, <code>shell:false</code> spawn, and tool registration.</li>
+<li><code>packages/run-plugin/src/worker/irc-tool.ts</code> defines drone <code>irc</code> params, journal binding, send, inbox, and v1 operator-only delivery.</li>
+<li><code>packages/omp-extension-plugin/src/cnet/extension.ts</code> exposes foreground operations as generated discoverable CNet tools rather than a second IRC control deck.</li>
+</ul>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../operator/index.html">Operator guide</a> &mdash; how runs are steered from ground control.</li>
+<li><a href="../fleet-irc/index.html">Drone messages</a> &mdash; the narrow operator/drone journal lane.</li>
+<li><a href="../swarm-commander/index.html">Swarm commander</a> &mdash; model-role tools around the same run read model.</li>
+<li><a href="../gate/index.html">Merge gate</a> &mdash; where validation and review verdicts stop the sortie.</li>
+<li><a href="../../plugins/examples/index.html">Plugin examples</a> &mdash; custom validator, task source, and Pi extension package.</li>
+</ul>
+<div class="nextnav"><a href="../../docs/fleet-irc/index.html"><span class="dir">&larr; Back</span><span class="ttl">Drone messages</span></a><a href="../../docs/gate/index.html"><span class="dir">Next &rarr;</span><span class="ttl">The strict merge gate</span></a></div>
+</main></div><footer><div class="wrap"><div class="foot"><div class="col"><h5>orchestrate</h5><a href="../../docs/getting-started/index.html">getting started</a><a href="../../docs/runs/index.html">the run lifecycle</a><a href="../../docs/operator/index.html">operator guide</a><a href="../../docs/gate/index.html">the merge gate</a></div><div class="col"><h5>extend</h5><a href="../../plugins/index.html">plugin authoring</a><a href="../../skills/index.html">skills guide</a><a href="../../docs/pi-extensions/index.html">OMP/Pi extensions</a><a href="../../docs/packages/index.html">packages</a></div><div class="col"><h5>live</h5><a href="../../index.html">the home rig</a><a href="../../cli/index.html">cli reference</a><a href="https://where.rig-does.work/install">install script</a></div><div class="sig">Rig is the OMP session extension.<br><span class="blk">You are the operator.</span><br>release: rig --version</div></div></div></footer><script src="../../assets/rig.js"></script><script src="../../assets/site.js?v=v9"></script></body></html>

package/site/docs/architecture/index.html ADDED Viewed

@@ -0,0 +1,42 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Architecture // RIG</title><meta property="og:image" content="https://how.rig-does.work/assets/og-card.png"><meta name="twitter:card" content="summary_large_image"><meta name="description" content="Rig opens foreground OMP with a plugin-composed CNet runtime; Commander is a model role, runs are detached OMP drones, and attach targets one exact run."><meta property="og:title" content="Architecture // RIG"><meta property="og:description" content="Rig opens foreground OMP with a plugin-composed CNet runtime; Commander is a model role, runs are detached OMP drones, and attach targets one exact run."><link rel="stylesheet" href="../../assets/rig.css?v=v9"><link rel="stylesheet" href="../../assets/site.css?v=v9"><link rel="icon" type="image/svg+xml" href="../../assets/favicon.svg"></head><body data-doc-theme="layers"><canvas id="docfield"></canvas><nav class="nav"><div class="nav-in"><a class="brand" href="../../index.html"><span class="mk"></span><span class="blk">Rig</span></a><button class="burger" onclick="document.getElementById('nl').classList.toggle('open')">menu</button><div class="nav-links" id="nl"><button class="nsearch" type="button" onclick="rigSearchOpen()">search<kbd>&#8984;K</kbd></button><a href="../../index.html" class="">overview</a><a href="../../docs/index.html" class="active">docs</a><a href="../../plugins/index.html" class="">plugins</a><a href="../../skills/index.html" class="">skills</a><a href="../../cli/index.html" class="">cli</a><a href="../../config/index.html" class="">config</a><a href="https://github.com/humanity-org/rig" class="ext">github</a></div></div></nav><div class="docwrap"><aside class="sidebar"><div class="grp">START</div><a href="../../docs/index.html" class="">docs home</a><a href="../../docs/capabilities/index.html" class="">capabilities</a><a href="../../docs/getting-started/index.html" class="">getting started</a><div class="grp">RUN</div><a href="../../docs/runs/index.html" class="">the run lifecycle</a><a href="../../docs/operator/index.html" class="">operator guide</a><a href="../../docs/swarm-commander/index.html" class="">swarm commander</a><a href="../../docs/fleet-irc/index.html" class="">drone messages</a><a href="../../docs/agent-tools/index.html" class="">agent tools</a><a href="../../docs/gate/index.html" class="">the merge gate</a><a href="../../docs/troubleshooting/index.html" class="">troubleshooting</a><div class="grp">ARCHITECTURE</div><a href="../../docs/architecture/index.html" class="active">how rig works</a><a href="../../docs/entities/index.html" class="">entities & data model</a><a href="../../docs/server/index.html" class="">OMP relay/web</a><a href="../../docs/security/index.html" class="">security & trust</a><a href="../../docs/environment/index.html" class="">environment variables</a><div class="grp">EXTEND</div><a href="../../plugins/index.html" class="">plugin authoring</a><a href="../../plugins/examples/index.html" class="">plugin examples</a><a href="../../docs/pi-extensions/index.html" class="">OMP/Pi extensions</a><a href="../../skills/index.html" class="">skills</a><a href="../../docs/task-sources/index.html" class="">task sources</a><a href="../../docs/validators/index.html" class="">validators & hooks</a><div class="grp">OPERATE</div><a href="../../cli/index.html" class="">cli reference</a><a href="../../config/index.html" class="">rig.config.ts</a><a href="../../docs/recipes/index.html" class="">recipes</a><a href="../../docs/glossary/index.html" class="">glossary</a><a href="../../docs/faq/index.html" class="">faq</a><div class="grp">ENGINE</div><a href="../../docs/packages/index.html" class="">packages</a></aside><main class="doc">
+    <h1>Architecture</h1>
+    <p class="lede">Rig is a plugin-based product over a 3-package mechanism floor. Bare <code>rig</code> opens foreground OMP with the CNet extension; dispatch creates supervised, detached OMP drone sessions. The Swarm Commander is a model role inside the foreground session.</p>
+    <h2 id="runtime-authority">The mechanism floor <span class="ns">// three packages, nothing else</span></h2>
+    <p>Only three packages are not plugins. <code>@rig/contracts</code> is the dependency root (schemas, types, IPC/panel shapes). <code>@rig/core</code> is the config + plugin-composition library (<code>defineConfig</code>/<code>definePlugin</code>, the plugin host); it is harness-agnostic, not a product host or runtime. <code>@rig/kernel-seed</code> is the irreducible bootstrap seed &mdash; the plugin ABI and capability resolver. Everything else is composed above the floor: the Rig application <code>apps/rig</code> (<code>@rig/rig</code>) owns the process entrypoints, argv routing, and the standard plugin graph, and every product surface &mdash; session extensions, runs, tasks, transport, config &mdash; is a plugin it composes.</p>
+    <pre class="code"><span class="f">rig</span>  <span class="c">// apps/rig (@rig/rig) — process entrypoints · argv routing · plugin graph · official build</span>
+  <span class="p">↳</span> <span class="f">@rig/kernel-seed</span>  <span class="c">// bootstrap seed · plugin ABI · capability resolver</span>
+       <span class="p">↳</span> <span class="f">@rig/product-entrypoint-plugin</span>  <span class="c">// bare rig · foreground OMP launch/resume · help</span>
+       <span class="p">↳</span> <span class="f">@rig/omp-extension-plugin</span>  <span class="c">// CNet runtime · inline cards · model control · generated tools · attach effects</span>
+<span class="f">/fleet</span> · <span class="f">/tasks</span> · <span class="f">/drone [ref]</span>  <span class="c">// materialize inline CNet cards</span>
+<span class="f">rig attach &lt;run-id&gt; [--web]</span>
+  <span class="p">↳</span> exact detached drone ⇒ private credential resolved internally
+       <span class="p">↳</span> collab relay <span class="w">wss://where.rig-does.work</span></pre>
+    <h2 id="process-map">Process map <span class="ns">// what runs where</span></h2>
+    <table class="t"><thead><tr><th>piece</th><th>role</th><th>authority</th></tr></thead><tbody>
+      <tr><td><code>rig</code></td><td>The Rig application (<code>apps/rig</code>, <code>@rig/rig</code>). Owns the process entrypoints (<code>bin/rig</code>), argv routing, the standard plugin graph, and the official build invocation; every command comes from the domain plugin that owns it.</td><td>Composes and dispatches into the plugin graph.</td></tr>
+      <tr><td><code>@rig/executable-binary-target-plugin</code></td><td>Build-time executable assembly + target-specific standard/tailored ArtifactSet compiler that <code>apps/rig</code> invokes. It reads a build descriptor and never imports the app &mdash; it is not the CLI launcher.</td><td>None at runtime; produces the compiled binary.</td></tr>
+      <tr><td>Foreground OMP + Rig</td><td>Bare <code>rig</code> opens the interactive OMP runtime for the workspace and loads the bundled Rig extension. OMP owns cwd, transcript, tools, prompts, participants, and native history.</td><td>The foreground conversation and CNet authority.</td></tr>
+      <tr><td>Swarm Commander</td><td>A model role inside that foreground OMP session. The Rig extension supplies bounded current context and generated discoverable tools; it is not a process or attachable session.</td><td>The same foreground OMP turn and journal.</td></tr>
+      <tr><td>Detached drone</td><td>One supervised OMP run session (<code>runId === sessionId</code>) placed locally or remotely. Its journal drives its CNet projection.</td><td>Live run state in its OMP JSONL session journal.</td></tr>
+      <tr><td>Inline CNet surface</td><td><code>@rig/omp-extension-plugin</code> hosts the CNet reducer, transcript projection, model control, generated tools, and <code>/fleet</code>, <code>/tasks</code>, <code>/drone</code> aliases.</td><td>Bounded operator projection over plugin-owned state.</td></tr>
+      <tr><td>Exact-run attach</td><td><code>rig attach &lt;run-id&gt; [--web]</code> and the selected run&rsquo;s CNet actions resolve a private credential for that detached drone only.</td><td>The target drone session; never foreground Rig or Commander.</td></tr>
+      <tr><td><code>apps/rig-relay-registry</code></td><td>Standalone deployed service (<code>@rig/rig-relay-registry</code>, depends only on <code>@rig/contracts</code>): a content-blind, in-memory collab relay + run-projection registry. It moves encrypted frames and indexes run projections.</td><td>Transport + discovery only; authority stays in each drone&rsquo;s OMP session journal.</td></tr>
+      <tr><td>Headless CLI</td><td>The exact command groups (doctor, stats, inspect, pipeline, graph&hellip;) run the same domain operations non-interactively.</td><td>A first-class scripting/CI/agent adapter over the same state.</td></tr>
+    </tbody></table>
+    <h2 id="packages">Package layering <span class="ns">// floor + ~30 plugins</span></h2>
+    <p>The Bun workspace keeps imports flowing one way: floor packages out to plugins, never back. <code>@rig/core</code> owns <code>defineConfig</code>, <code>definePlugin</code>, and the plugin host; <code>@rig/kernel-seed</code> owns the plugin ABI. The Rig application <code>apps/rig</code> owns the process entrypoints, argv routing, first-party graph, and official build. <code>@rig/executable-binary-target-plugin</code> only compiles target executables from that app. Product entrypoint, OMP CNet runtime, run lifecycle, and transport behavior remain owned by their focused plugins.</p>
+    <p>The application-owned first-party graph is always present. Project-specific plugins may be added through <code>.rig/rig.config.ts</code>; OMP/Pi packages declared in <code>runtime.pi.packages</code> supply live-session tools and commands. Nothing is auto-scanned.</p>
+    <h2 id="plugins">Plugin contributions <span class="ns">// everything is a plugin</span></h2>
+    <p>Plugins contribute validators, hooks, skills, agent roles, repo sources, task fields, task sources, CLI commands, lifecycle stages, capabilities, read models, blocker classifiers, session extensions, CNet queries/actions, and seed entrypoints. They are explicit packages composed by config and validated at construction. CNet query/action registrations become inline operator surfaces and generated model tools; unrelated OMP tools and slash commands still belong in OMP/Pi extension packages.</p>
+    <h2 id="state">State model <span class="ns">// derived, not stored</span></h2>
+    <p>A run is a detached OMP (Pi) session &mdash; <code>runId === sessionId</code> and run state is folded from that session&rsquo;s JSONL journal. <code>@rig/run-plugin</code> owns the journal codec and read-model presentation. Task state is <em>derived from the source on read</em> &mdash; GitHub Issues or Linear &mdash; so there is no local task database. CNet items carry operator actions; attach targets the selected run by id while the underlying credential remains private transport data.</p>
+    <div class="nextnav"><a href="../../docs/troubleshooting/index.html"><span class="dir">&larr; Back</span><span class="ttl">Troubleshooting</span></a><a href="../../docs/entities/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Entities & data model</span></a></div>
+  </main></div><footer><div class="wrap"><div class="foot"><div class="col"><h5>orchestrate</h5><a href="../../docs/getting-started/index.html">getting started</a><a href="../../docs/runs/index.html">the run lifecycle</a><a href="../../docs/operator/index.html">operator guide</a><a href="../../docs/gate/index.html">the merge gate</a></div><div class="col"><h5>extend</h5><a href="../../plugins/index.html">plugin authoring</a><a href="../../skills/index.html">skills guide</a><a href="../../docs/pi-extensions/index.html">OMP/Pi extensions</a><a href="../../docs/packages/index.html">packages</a></div><div class="col"><h5>live</h5><a href="../../index.html">the home rig</a><a href="../../cli/index.html">cli reference</a><a href="https://where.rig-does.work/install">install script</a></div><div class="sig">Rig is the OMP session extension.<br><span class="blk">You are the operator.</span><br>release: rig --version</div></div></div></footer><script src="../../assets/rig.js"></script><script src="../../assets/site.js?v=v9"></script></body></html>