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/docs/security/index.html ADDED Viewed

@@ -0,0 +1,29 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Security &amp; trust // 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="Current Rig security model: OMP session authority, encrypted relay links, package pins, fail-closed sandboxing, and headless CLI boundaries."><meta property="og:title" content="Security &amp; trust // RIG"><meta property="og:description" content="Current Rig security model: OMP session authority, encrypted relay links, package pins, fail-closed sandboxing, and headless CLI boundaries."><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="shield"><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="">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="active">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>Security &amp; trust</h1>
+<p class="lede">Security follows the current architecture: OMP owns live session state, the collab relay carries encrypted links, Rig packages are explicit, and the exact CLI runs the same scoped operations as the session.</p>
+<h2 id="session-authority">Session authority</h2>
+<p>Live authority is the OMP session: cwd, prompts, tools, transcript, participants, and loaded OMP/Pi packages. The Rig session surfaces display and route that state instead of replacing it with a separate live service.</p>
+<h2 id="relay">Relay trust</h2>
+<p>Shared sessions use <code>wss://where.rig-does.work</code>. Room secrets belong in join-link fragments, not server logs or repo files. The relay coordinates encrypted transport and presence; it is not the source of truth for work state.</p>
+<h2 id="packages">Explicit packages</h2>
+<ul>
+<li>The <code>apps/rig</code> application owns the first-party plugin graph. Projects add executable extras through <code>.rig/rig.config.ts</code> or select plugin-owned data in <code>.rig/rigfig.toml</code>; nothing is discovered by scanning arbitrary package directories.</li>
+<li>OMP/Pi packages are pinned in <code>runtime.pi.packages</code> or <code>.pi/settings.json</code> for live-session capabilities.</li>
+<li>Task sources are GitHub Issues and Linear only; task state is derived from the source on read, with no local task database.</li>
+</ul>
+<h2 id="sandbox">The execution harness</h2>
+<p>Every run &mdash; <code>/fleet</code> dispatch, Swarm Commander dispatch, and ad-hoc agent runs alike &mdash; goes through the same fully-provisioned harness:</p>
+<ul>
+<li>a per-run isolated git worktree, isolated runtime home, and isolated credentials, so parallel runs never share writable state (the isolation backend is owned by the swappable isolation plugin);</li>
+<li>per-run compiled binaries materialized into the runtime &mdash; the rig-agent toolbelt, controlled-bash, and hooks &mdash; so the agent never invokes ambient host tooling directly;</li>
+<li>an OS sandbox (macOS seatbelt / Linux bwrap), <b>enforced by default</b> (<code>workspace.sandbox = "enforce"</code>). It fails closed: if the host cannot provide a backend, the run refuses rather than silently downgrading. Runtime command policy is enforced through a single policy-guard hook channel owned by the guard plugin.</li>
+</ul>
+<p>Tokens stay in per-project private state or scoped per-run injection, never task payloads or committed files.</p>
+<h2 id="gate">Merge gate</h2>
+<p>The merge gate is GitHub reviews plus status checks, owned by the swappable PR-review plugin (default provider <code>github</code>). The merge is pinned 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.</p>
+<h2 id="headless-cli">The headless CLI</h2>
+<p>The exact task/run/service commands and terminal diagnostics are a first-class headless adapter over the same scoped operations, for release checks, scripts, CI, and agents. Interactively, the same work runs through bare <code>rig</code>, inline CNet items, <code>/fleet</code>, <code>/tasks</code>, <code>/drone</code>, exact-run attach, and <code>rig doctor</code>.</p>
+<h2 id="see-also">See also</h2>
+<div class="note">Trust mechanics connect to <a href="../server/index.html"><b>OMP relay + web</b></a>, <a href="../environment/index.html"><b>environment variables</b></a>, <a href="../pi-extensions/index.html"><b>OMP/Pi extensions</b></a>, and <a href="../gate/index.html"><b>the strict merge gate</b></a>.</div>
+<div class="nextnav"><a href="../../docs/server/index.html"><span class="dir">&larr; Back</span><span class="ttl">OMP relay + web</span></a><a href="../../docs/environment/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Environment variables</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/server/index.html ADDED Viewed

@@ -0,0 +1,27 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>OMP relay + web // 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 transports detached drone sessions over the relay; operators attach to one exact run by id, and local or remote only selects placement."><meta property="og:title" content="OMP relay + web // RIG"><meta property="og:description" content="Rig transports detached drone sessions over the relay; operators attach to one exact run by id, and local or remote only selects placement."><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="multiroot"><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="">how rig works</a><a href="../../docs/entities/index.html" class="">entities & data model</a><a href="../../docs/server/index.html" class="active">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>OMP relay + web</h1>
+<p class="lede">The relay transports encrypted detached-drone sessions. The public product surface is run-addressed attach: choose one exact run in the CNet or use <code>rig attach &lt;run-id&gt; [--web]</code>; Rig keeps the raw collab credential internal.</p>
+    <h2 id="relay-authority">Relay, not authority</h2>
+    <p>The relay moves encrypted frames between a detached drone and its attached clients. It does not own transcript, cwd, tools, packages, or run state. If a browser tab closes or a network link drops, that drone&rsquo;s OMP session remains authoritative; foreground Rig rediscovers it by run id and rebuilds the CNet projection. Dispatch, placement, discovery, and attach resolution are owned by <code>@rig/transport-plugin</code>.</p>
+    <table class="t"><thead><tr><th>surface</th><th>purpose</th></tr></thead><tbody>
+      <tr><td>Selected endpoint</td><td><code>.rig/state/connection.json</code> chooses local or remote placement for a detached drone; <code>RIG_REMOTE_ALIAS</code> overrides it for one launch.</td></tr>
+      <tr><td><code>rig attach &lt;run-id&gt;</code></td><td>Attaches this terminal to the exact live detached drone after Rig resolves its private credential.</td></tr>
+      <tr><td><code>rig attach &lt;run-id&gt; --web</code></td><td>Opens web attach for that exact detached drone without exposing its private transport credential.</td></tr>
+      <tr><td><code>wss://where.rig-does.work</code></td><td>Default encrypted transport for detached-run discovery and attach; private credentials remain client-side runtime state.</td></tr>
+    </tbody></table>
+    <h2 id="multiroot">Multi-root hosting</h2>
+    <p>A running server can host multiple project roots concurrently. Select an endpoint in <code>.rig/state/connection.json</code> or set <code>RIG_REMOTE_ALIAS</code> to place a detached run on another host. Placement changes where the drone executes, not the CNet workflow, model role, or attach semantics.</p>
+    <h2 id="doctor">Readiness checks <span class="ns">// rig doctor</span></h2>
+    <p><code>rig doctor</code> probes the pieces operators actually depend on: OMP session discovery, Rig extension load, relay reachability, package pins, and sandbox seams. It is a CLI command; inside the session use <code>/fleet</code> to inspect the aggregate, <code>/drone</code> for one exact run, and inline attention items for pending operator input.</p>
+    <h2 id="web">Install and web endpoints</h2>
+    <p>The same domain serves the install script and the collab web viewer. Product copy should point operators to <code>curl -fsSL https://where.rig-does.work/install | bash</code>, then bare <code>rig</code>. It should not ask them to choose or start a separate long-lived service before using the Rig session.</p>
+    <h2 id="headless-service">Headless service commands</h2>
+    <p>The <code>rig server</code> and <code>rig run</code> command groups are first-class headless entry points for automation, scripts, and remote deployments. The interactive model is foreground OMP plus the CNet runtime, with detached drones supervised behind it and the Swarm Commander acting only as a model role.</p>
+    <div class="nextnav"><a href="../../docs/entities/index.html"><span class="dir">&larr; Back</span><span class="ttl">Entities & data model</span></a><a href="../../docs/security/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Security & trust</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/swarm-commander/index.html ADDED Viewed

@@ -0,0 +1,41 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Swarm Commander // RIG</title><meta name="description" content="The Swarm Commander model role inside foreground OMP: bounded CNet context, generated discoverable tools, and exact receipts."><meta property="og:title" content="Swarm Commander // RIG"><meta property="og:description" content="The Swarm Commander model role inside foreground OMP: bounded CNet context, generated discoverable tools, and exact receipts."><meta property="og:image" content="https://how.rig-does.work/assets/og-card.png"><meta name="twitter:card" content="summary_large_image"><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="rails"><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="active">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="">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>Swarm Commander</h1>
+    <p class="lede">Swarm Commander is the configured model role inside foreground OMP. It is not a process, supervisor, session, or attach target. CNet remains useful without the role.</p>
+    <h2 id="what-it-is">What it receives</h2>
+    <table class="t"><thead><tr><th>input</th><th>contract</th></tr></thead><tbody>
+      <tr><td>current projection</td><td>A bounded snapshot of currently visible CNet items at the provider call, including item ids, revisions, targets, summaries, and enabled actions.</td></tr>
+      <tr><td>query tools</td><td>Discoverable tools generated from every <code>CNetQuery</code> contributed by the loaded Rig plugins.</td></tr>
+      <tr><td>action tools</td><td>Discoverable tools generated from every <code>CNetAction</code>; calls must use the observed item id, target, and base revision.</td></tr>
+      <tr><td>receipts</td><td>Exact durable query or action outcomes written through CNet into the same OMP transcript.</td></tr>
+    </tbody></table>
+    <h2 id="how-to-use">How to use it</h2>
+    <p>Speak normally. The role discovers the tools provided by this tailored Rig binary rather than relying on a fixed, hardcoded tool deck.</p>
+    <pre class="code"><span class="p">operator</span> Show ready tasks and dispatch task 132.
+<span class="p">swarmer</span> I&rsquo;ll query the configured task source, then use the enabled run dispatch action.
+<span class="p">cnet</span> dispatch applied · task 132 · run 8a31e7</pre>
+    <pre class="code"><span class="p">operator</span> Tell run 41c to rerun only TaskList.spec.ts.
+<span class="p">swarmer</span> I&rsquo;ll materialize the exact run and submit its Send direction action.
+<span class="p">cnet</span> direction accepted · run 41c · exact session receipt</pre>
+    <h2 id="tool-surface">Generated tool surface</h2>
+    <p>Tool names are derived from each contribution id and are intentionally not documented as stable commands. Query tools accept a typed target and query input. Action tools additionally require the exact projected item id and base revision. A tailored <code>.rig/rig.config.ts</code> binary therefore exposes only the CNet operations supplied by its embedded plugins and overrides.</p>
+    <div class="note"><b>Discovery is part of the contract.</b> The model searches by each contribution&rsquo;s title and description. It should never call hardcoded fleet, run-control, or inbox tool names.</div>
+    <h2 id="wake-mechanics">Operator turns only</h2>
+    <p>The current product does not install an autonomous Commander wake loop or a separate standing-order store. Instructions such as <q>keep one drone on ready bugs</q> are ordinary OMP conversation context until the operator asks the model to act.</p>
+    <h2 id="how-it-works">How it works</h2>
+    <p><code>@rig/omp-extension-plugin</code> installs the model-turn context and generated discoverable tools. The CNet coordinator routes each query or action to the plugin that owns its registration, then appends the request and exact outcome to OMP&rsquo;s normal JSONL session history.</p>
+    <p>The role never writes run state directly. Detached drone state remains in each drone&rsquo;s own OMP JSONL journal; task state remains in the configured source; the foreground CNet is their typed projection and action surface.</p>
+    <h2 id="honest-limits">Honest limits</h2>
+    <ul>
+      <li>The bounded context is not complete history. The model uses generated queries when it needs a full current item.</li>
+      <li>An action can apply only to an observed item revision. Stale or mismatched targets refuse instead of guessing.</li>
+      <li>A transport send is not success. CNet reports applied only after the owning capability returns the exact durable receipt.</li>
+      <li>Removing the Commander role does not remove CNet, inline cards, model control, or detached drone execution.</li>
+    </ul>
+  <div class="nextnav"><a href="../../docs/operator/index.html"><span class="dir">&larr; Back</span><span class="ttl">Operator guide</span></a><a href="../../docs/fleet-irc/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Drone messages</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/task-sources/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>Task sources // 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="Where Rig's tasks come from — the GitHub Issues and Linear sources field by field, how state is derived on read, how lifecycle updates flow back to the source, and how a plugin contributes a custom kind."><meta property="og:title" content="Task sources // RIG"><meta property="og:description" content="Where Rig's tasks come from — the GitHub Issues and Linear sources field by field, how state is derived on read, how lifecycle updates flow back to the source, and how a plugin contributes a custom kind."><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="feeds"><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="">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="active">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>Task sources</h1>
+<p class="lede">Where the work comes from. A task source turns whatever your team already tracks &mdash; GitHub Issues, Linear, your own kind &mdash; into <code>TaskRecord</code>s the swarm can dispatch. Task state is <b>derived from the source on read</b>; there is no local task database. Config picks one source by <code>kind</code>; the application graph and project extras contribute the factories.</p>
+<h2 id="model">The dispatch model</h2>
+<p>One source per rig. At boot, Rig resolves <code>config.taskSource.kind</code> against the executable factories contributed by loaded plugins and instantiates exactly one. <code>kind</code> is an <b>open string</b> in the contract &mdash; <code>"github-issues"</code> and <code>"linear"</code> ship first-party (the tasks capability is owned by <code>@rig/tasks-plugin</code>, the GitHub source by <code>@rig/github-provider-plugin</code>, and Linear by <code>@rig/linear-plugin</code>), and any plugin can contribute a <code>"jira"</code>, <code>"asana"</code>, or your own on equal footing. If no loaded plugin contributes the configured kind, dispatch fails loudly (<a href="../troubleshooting/index.html#symptoms">common-symptoms checks &rarr;</a>).</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>({
+  taskSource: { kind: <span class="s">"github-issues"</span>, owner: <span class="s">"acme"</span>, repo: <span class="s">"api"</span> },
+});</pre>
+<p>GitHub Issues is part of the application-owned graph. Other sources, including Linear, are ordinary project plugin extras selected by <code>kind</code>.</p>
+<p>Whatever the backend, every source produces the same <code>TaskRecord</code> shape &mdash; id, status, deps, scope, validators, role &mdash; so the rest of the engine never knows where a task came from.</p>
+<h2 id="task-record">The TaskRecord contract <span class="ns">// what a source must produce</span></h2>
+<p>A task source has one job: turn whatever your team tracks into <code>TaskRecord</code>s. The contract (<code>@rig/contracts</code>, <code>task-source.ts</code>) is deliberately small &mdash; three required fields and an open bag for everything else. The engine reads the three it knows about; the rest passes through onto the task for plugins, the operator surfaces, and your own validators to use.</p>
+<table class="t"><thead><tr><th>field</th><th>type</th><th>required</th><th>meaning</th></tr></thead>
+<tbody>
+<tr><td><code>id</code></td><td><code>string</code></td><td><b>yes</b></td><td>Stable task identifier. github-issues uses the issue number; Linear uses the issue identifier.</td></tr>
+<tr><td><code>deps</code></td><td><code>string[]</code></td><td><b>yes</b></td><td>Ids this task is blocked on. The queue won&rsquo;t schedule a task until its deps clear. Defaults to <code>[]</code> when a source omits it.</td></tr>
+<tr><td><code>status</code></td><td><code>string</code></td><td><b>yes</b></td><td>Open string, but the lifecycle understands <code>ready</code>, <code>in_progress</code>, <code>blocked</code>, <code>open</code>, <code>closed</code> and the rest of the <a href="../entities/index.html#status">task status set &rarr;</a>.</td></tr>
+<tr><td><code>[extra]</code></td><td><code>unknown</code></td><td>no</td><td>Anything else &mdash; <code>title</code>, <code>body</code>, <code>scope</code>, <code>role</code>, <code>validators</code>, <code>url</code>, <code>sourceIssueId</code>, your own fields &mdash; rides along untouched.</td></tr>
+</tbody></table>
+<p>The structured fields the standard sources populate from labels and body markers:</p>
+<table class="t"><thead><tr><th>field</th><th>derived from</th></tr></thead>
+<tbody>
+<tr><td><code>scope</code></td><td>Every <code>scope:&lt;glob&gt;</code> label &mdash; where the worker is expected to operate.</td></tr>
+<tr><td><code>role</code></td><td>The first <code>role:&lt;id&gt;</code> label &mdash; resolved to a model via agent-role registrations.</td></tr>
+<tr><td><code>validators</code>, <code>validation</code></td><td>Every <code>validator:&lt;id&gt;</code> label &mdash; deterministic gates the run must pass.</td></tr>
+<tr><td><code>parentChildDeps</code></td><td>A <code>parents: #3</code> body line (github only) &mdash; parent links.</td></tr>
+<tr><td><code>sourceIssueId</code>, <code>url</code>, <code>issueType</code></td><td>github only &mdash; <code>owner/repo#N</code>, the issue URL, and the <code>type:</code>/<code>epic</code> label.</td></tr>
+</tbody></table>
+<div class="note">The contract requires only <code>id</code>, <code>deps</code>, and <code>status</code>. <b>Everything else is optional and open.</b> A minimal valid record is <code>{ "id": "T-1", "deps": [], "status": "ready" }</code> &mdash; a source can be as thin as that and still dispatch.</div>
+<h2 id="linear">The Linear source</h2>
+<p>Kind <code>"linear"</code> (<code>@rig/linear-plugin</code>): issues on a Linear team become tasks over the Linear API. <code>options.teamKey</code> is <b>required</b> &mdash; the factory throws <code>task source linear: options.teamKey is required</code> otherwise. The same <code>scope:</code>/<code>validator:</code>/<code>role:</code> label conventions the GitHub source uses apply here too, so the same task file can move between trackers unchanged.</p>
+<table class="t"><thead><tr><th>option</th><th>semantics</th></tr></thead>
+<tbody>
+<tr><td><code>options.teamKey</code></td><td>Required &mdash; the Linear team key, e.g. <code>"ENG"</code>.</td></tr>
+<tr><td><code>options.apiKey</code></td><td>Linear API key; defaults to <code>LINEAR_API_KEY</code> resolved at call time.</td></tr>
+<tr><td><code>options.states</code></td><td>Filter: workflow-state names, e.g. <code>["Todo", "In Progress"]</code>.</td></tr>
+<tr><td><code>options.assignee</code></td><td>Filter by assignee &mdash; email (anything containing <code>@</code>) or display name.</td></tr>
+<tr><td><code>options.labels</code></td><td>Filter: only issues carrying the listed labels are tasks.</td></tr>
+<tr><td><code>options.listLimit</code></td><td>Max issues. At the limit Rig <b>fails loudly</b> (&ldquo;refusing to silently truncate matching issues&rdquo;) rather than dropping tasks &mdash; narrow <code>states</code>/<code>labels</code>/<code>assignee</code> or raise the cap.</td></tr>
+</tbody></table>
+<p>Status is derived from the issue&rsquo;s workflow-state <i>type</i> &mdash; Linear&rsquo;s state taxonomy has no blocked/failed concept, so those Rig statuses are surfaced via comments instead of mangling the workflow state.</p>
+<h2 id="github-issues">The github-issues source</h2>
+<p>Kind <code>"github-issues"</code>: issues in <code>owner</code>/<code>repo</code> (both required) become tasks, via the <code>gh</code> CLI. Pull requests are filtered out of issue lists. The same <code>scope:</code>/<code>validator:</code>/<code>role:</code> label prefixes apply, plus a few issue-native conventions: a <code>depends-on: #12, #14</code> line in the body becomes <code>deps</code>, a <code>parents: #3</code> line becomes parent links, <code>type:</code> labels (or the <code>epic</code> label) set the issue type, and the issue number is the task id.</p>
+<table class="t"><thead><tr><th>config</th><th>semantics</th></tr></thead>
+<tbody>
+<tr><td><code>owner</code>, <code>repo</code></td><td>Required &mdash; the factory throws <code>task source github-issues: owner is required</code> otherwise.</td></tr>
+<tr><td><code>labels</code></td><td>Filter: only issues carrying all listed labels are tasks.</td></tr>
+<tr><td><code>state</code></td><td><code>"open"</code> (default), <code>"closed"</code>, or <code>"all"</code>.</td></tr>
+<tr><td><code>options.assignee</code></td><td>Filter by assignee; falls back to <code>RIG_GITHUB_ASSIGNEE</code>.</td></tr>
+<tr><td><code>options.timeoutMs</code></td><td>Timeout for every <code>gh</code> call. Default 15&thinsp;000.</td></tr>
+<tr><td><code>options.listLimit</code></td><td>Max issue-list rows, default 1&thinsp;000. At the limit Rig <b>fails loudly</b> (&ldquo;refusing to silently truncate matching issues&rdquo;) instead of dropping tasks.</td></tr>
+</tbody></table>
+<p>Task status reads from labels &mdash; <code>ready</code>, <code>blocked</code>, <code>in-progress</code>, <code>under-review</code>, <code>failed</code>, <code>cancelled</code> &mdash; and a closed issue is status <code>closed</code> regardless of labels.</p>
+<h3 id="state-all">What <code>state: "all"</code> does <span class="ns">// re-including done work</span></h3>
+<p>The <code>state</code> field maps straight to <code>gh issue list --state</code>. The default <code>"open"</code> hides anything closed. Set <code>"all"</code> and the list re-includes closed issues &mdash; <b>including the ones Rig already finished and closed with the <code>rig:done</code> label.</b> Nothing dedupes or filters them: a closed issue is mapped to status <code>closed</code> by <code>statusFor()</code> <i>before</i> labels are even consulted, so a re-included <code>rig:done</code> issue arrives as a <code>closed</code> task, not as <code>ready</code> work. The queue treats <code>closed</code> as terminal, so it won&rsquo;t re-dispatch them &mdash; but they will show up in <code>rig task list</code>. Use <code>"all"</code> when you want completed history in the graph (reporting, dependency resolution against finished work); keep <code>"open"</code> for a clean active queue.</p>
+<p><b>Auth.</b> The application-owned GitHub provider supplies both credential paths. <code>createStateGitHubCredentialProvider</code> reads the signed-in token Rig stores (<code>github-auth.json</code> under <code>RIG_STATE_DIR</code>, or an explicit <code>RIG_GITHUB_AUTH_STATE_FILE</code>). <code>createEnvGitHubCredentialProvider</code> reads <code>RIG_GITHUB_SELECTED_TOKEN</code> for normal repo operations &mdash; public repos work with no token at all, and ambient host <code>GH_TOKEN</code>/<code>GITHUB_TOKEN</code> are deliberately <i>cleared</i> for selected-repo calls so host credentials only flow through explicit admin-fallback resolution. Runtime authentication sits outside task-source config; see the <a href="../environment/index.html">environment variables boundary &rarr;</a>.</p>
+<h2 id="writeback">Explicit source-field writeback</h2>
+<p>Task sources aren&rsquo;t read-only. As a run progresses and completes (or fails), the server posts projected source fields and comments back through the source&rsquo;s <code>updateTask</code> method. For GitHub issues that means:</p>
+<ul>
+<li><b>Status labels swap atomically</b> &mdash; the managed plain set (<code>ready</code> &hellip; <code>cancelled</code>) plus the <code>rig:</code> lifecycle set (<code>rig:running</code> &rarr; <code>rig:pr-open</code> &rarr; <code>rig:ci-fixing</code> &rarr; <code>rig:merging</code> &rarr; <code>rig:done</code>, or <code>rig:needs-attention</code>). Missing labels are created on the fly.</li>
+<li><b>One sticky status comment</b>, found by its <code>rig:status-comment</code> marker and updated in place &mdash; no comment spam.</li>
+<li><b>A Rig-owned metadata block</b> between markers in the issue body, updated without touching human-authored content.</li>
+<li><b>Issue closed</b> when the task reaches <code>closed</code>.</li>
+</ul>
+<p>The mapping from task status to the two GitHub label sets is fixed &mdash; each status resolves to at most one plain status label and at most one <code>rig:</code> lifecycle label:</p>
+<table class="t"><thead><tr><th>task status</th><th>plain label</th><th>rig: label</th><th>issue action</th></tr></thead>
+<tbody>
+<tr><td><code>in_progress</code></td><td><code>in-progress</code></td><td><code>rig:running</code></td><td>&mdash;</td></tr>
+<tr><td><code>under_review</code></td><td><code>under-review</code></td><td><code>rig:pr-open</code></td><td>&mdash;</td></tr>
+<tr><td><code>ci_fixing</code></td><td><code>under-review</code></td><td><code>rig:ci-fixing</code></td><td>&mdash;</td></tr>
+<tr><td><code>merging</code></td><td><code>under-review</code></td><td><code>rig:merging</code></td><td>&mdash;</td></tr>
+<tr><td><code>failed</code> / <code>blocked</code> / <code>needs_attention</code></td><td><code>blocked</code></td><td><code>rig:needs-attention</code></td><td>&mdash;</td></tr>
+<tr><td><code>ready</code></td><td><code>ready</code></td><td>(none)</td><td>&mdash;</td></tr>
+<tr><td><code>cancelled</code></td><td><code>cancelled</code></td><td>(none)</td><td>&mdash;</td></tr>
+<tr><td><code>open</code></td><td>(none)</td><td>(none)</td><td>&mdash;</td></tr>
+<tr><td><code>closed</code></td><td>(none)</td><td><code>rig:done</code></td><td><code>gh issue close</code></td></tr>
+</tbody></table>
+<p>The swap is atomic in effect: every other status label in both sets is removed first, then the target labels are added. Missing labels are created on the fly (color <code>6f42c1</code>, &ldquo;Task status managed by Rig&rdquo;) so a fresh repo needs no setup.</p>
+<p>The Linear source projects the same intent through its own writeback &mdash; workflow-state and a sticky status comment. Either way the source of truth stays where your team already looks.</p>
+<div class="pi-term" data-title="pi &mdash; worker brain (attached)" data-rows="12">
+<script type="application/json">[
+{"t":"u","s":"when you finish task #42, what happens back on the github issue?"},
+{"t":"think","ms":1300},
+{"t":"out","s":"The server posts it through the task source: status labels swap to rig:done, the sticky status comment updates in place, and the issue closes."},
+{"t":"dim","s":"one comment per issue — found by the rig:status-comment marker, edited in place"},
+{"t":"u","s":"and if validation never passes?"},
+{"t":"out","s":"rig:needs-attention. The run goes terminal with errorText set, and the issue stays open for you."},
+{"t":"pause","ms":2600}
+]</script>
+<div class="pi-term-status-data" hidden data-path="~/work/acme/.worktrees/42 (rig/42)" data-stats="&uarr;21k &darr;864 R102k $0.000 (sub) 14.6%/128k (auto)" data-model="worker brain &bull; thinking off"></div>
+</div>
+<h2 id="custom">Custom kinds</h2>
+<p>Bring your own backend. A task source is a plugin contribution with two halves on a single entry: declarative metadata (what schemas can represent) and an executable factory that builds the source. The factory receives the full <code>TaskSourceConfig</code> &mdash; pull plugin-specific fields from the <code>options</code> bag &mdash; and the first-party Linear plugin follows exactly this shape:</p>
+<pre class="code"><span class="k">import</span> { definePlugin } <span class="k">from</span> <span class="s">"@rig/core"</span>;
+<span class="k">export default function</span> <span class="f">jiraPlugin</span>() {
+  <span class="k">return</span> <span class="f">definePlugin</span>({
+    name: <span class="s">"rig-jira"</span>, version: <span class="s">"0.1.0"</span>,
+    <span class="c">// single-channel: metadata AND the executable factory on one entry</span>
+    contributes: { taskSources: [{ id: <span class="s">"jira:issues"</span>, kind: <span class="s">"jira"</span>, description: <span class="s">"Jira issues"</span>,
+      <span class="f">factory</span>(config) {
+        <span class="c">// plugin-specific fields ride in config.options; top-level fields are reserved</span>
+        <span class="k">const</span> project = config.options?.project;
+        <span class="k">if</span> (!project) <span class="k">throw new</span> <span class="f">Error</span>(<span class="s">"task source jira: options.project is required"</span>);
+        <span class="k">return</span> <span class="f">createJiraSource</span>({ project });
+      } }] },
+  });
+}</pre>
+<p>The application&rsquo;s sources don&rsquo;t know about <code>"jira"</code>; this plugin&rsquo;s factory does, and because <code>kind</code> is an open string the engine dispatches it with no special-casing &mdash; add it as a project plugin and set <code>taskSource: { kind: "jira", options: { project: "API" } }</code>. Plugin-specific config always rides in the documented <code>options</code> bag; the top-level <code>TaskSourceConfig</code> fields are reserved for the built-ins. The full contribution surface &mdash; validators, hooks, skills, agent roles, CLI commands &mdash; is on the <a href="../../plugins/index.html">plugin authoring page</a>.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="../../plugins/index.html"><b>Plugin authoring</b></a> &mdash; the full contribution surface and how <code>definePlugin</code>&rsquo;s declarative + runtime channels fit together.</li>
+<li><a href="../entities/index.html"><b>Entities &amp; data model</b></a> &mdash; where a <code>TaskRecord</code> lands in the task graph, and the full task-status set.</li>
+<li><a href="../../config/index.html"><b>rig.config.ts</b></a> &mdash; the <code>taskSource</code> block, the <code>options</code> bag, and every adjacent config field.</li>
+<li><a href="../environment/index.html"><b>Environment variables</b></a> &mdash; the GitHub token and assignee variables the credential providers read.</li>
+<li><a href="../validators/index.html"><b>Validators &amp; hooks</b></a> &mdash; where the <code>validator:</code> labels resolve to the gates a run must pass.</li>
+</ul>
+<div class="nextnav"><a href="../../skills/index.html"><span class="dir">&larr; Back</span><span class="ttl">Skills</span></a><a href="../../docs/validators/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Validators & hooks</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/troubleshooting/index.html ADDED Viewed

@@ -0,0 +1,23 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Troubleshooting // 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 troubleshooting: run rig doctor, inspect bounded CNet projections, verify exact-run attach, and read the run-plugin view against the authoritative OMP JSONL journal."><meta property="og:title" content="Troubleshooting // RIG"><meta property="og:description" content="Rig troubleshooting: run rig doctor, inspect bounded CNet projections, verify exact-run attach, and read the run-plugin view against the authoritative OMP JSONL journal."><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="signal"><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="active">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>Troubleshooting</h1>
+<p class="lede">Start from the CLI diagnostic and the CNet. <code>rig doctor</code> checks discovery, relay/web, package pins, and sandbox seams; <code>/fleet</code> materializes the aggregate, and <code>/drone</code> materializes one run&rsquo;s current status and controls.</p>
+<h2 id="first-moves">First moves</h2>
+<ul>
+<li>Run <code>rig doctor</code> from the CLI.</li>
+<li>Run <code>/fleet</code> to materialize the current fleet projection inline.</li>
+<li>Run <code>/drone [ref]</code> to materialize one exact run and use its enabled controls or attach actions.</li>
+<li>For attach problems, confirm the detached run is live and address it by its exact run id.</li>
+</ul>
+<h2 id="symptoms">Common symptoms</h2>
+<table class="t"><thead><tr><th>symptom</th><th>likely cause</th><th>fix</th></tr></thead><tbody>
+<tr><td><code>/fleet</code>, <code>/tasks</code>, or <code>/drone</code> is missing</td><td>Rig extension was not loaded into the OMP session</td><td>Relaunch with bare <code>rig</code>; then run <code>rig doctor</code>.</td></tr>
+<tr><td>Run attach fails</td><td>Run is not live, is stale, or has not registered its private attach session</td><td>Refresh <code>/drone &lt;run-id&gt;</code>, then retry <code>rig attach &lt;run-id&gt; [--web]</code>. Do not substitute a transport credential.</td></tr>
+<tr><td>Capabilities differ between operators</td><td>Packages were added locally instead of pinned for the team</td><td>Commit <code>runtime.pi.packages</code> or <code>.pi/settings.json</code>.</td></tr>
+<tr><td>A run needs input</td><td>An approval or question is pending</td><td>Use the corresponding inline attention item; <code>/drone [ref]</code> shows the run&rsquo;s current state and controls.</td></tr>
+<tr><td>Automation sees stale run data</td><td>Reading an old run-plugin projection</td><td>Refresh the CNet query; the detached drone&rsquo;s OMP JSONL session journal is authoritative.</td></tr>
+</tbody></table>
+<h2 id="cli-diagnostics">CLI diagnostics</h2>
+<p>The headless CLI and its <code>--json</code> projections are first-class for CI, release checks, and agents. Treat them as views of run state, not as the source of live OMP session state.</p>
+<div class="note"><b>Still stuck?</b> Capture <code>rig doctor</code> output, the run id from <code>/fleet</code>, and the exact state and package facts materialized by <code>/drone</code>.</div>
+<div class="nextnav"><a href="../../docs/gate/index.html"><span class="dir">&larr; Back</span><span class="ttl">The strict merge gate</span></a><a href="../../docs/architecture/index.html"><span class="dir">Next &rarr;</span><span class="ttl">Architecture</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>