{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="d-flex flex-wrap align-items-center justify-content-between gap-2 mb-4">
    <div>
      <h1 class="h3 mb-1">Work documentation</h1>
      <p class="text-muted mb-0">How to run and operate the <code>pearing-work</code> agent orchestrator.</p>
    </div>
    <div class="d-flex gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api">API docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli">CLI docs</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/skills">Skills docs</a>
      <a class="btn btn-sm btn-outline-secondary active" href="/docs/work">Work docs</a>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="overview"><a class="link-body-emphasis text-decoration-none" href="#overview">Overview</a></h2>
      <p class="mb-2">
        <code>pearing-work</code> is an event-driven orchestrator for external coding agents.
        It runs one shared <code>pearing-cli tail-events</code> subprocess, filters matching events for each configured agent,
        and dispatches event batches to agent commands through stdin prompts.
      </p>
      <p class="mb-0">
        Each agent runs at most one invocation at a time. Events that arrive while an agent is already working are queued
        and delivered in the next batch when that agent becomes idle again.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="startup"><a class="link-body-emphasis text-decoration-none" href="#startup">Startup and environment</a></h2>
      <p class="mb-2">
        <code>pearing-work</code> reads a <code>pearing-work.toml</code> file and uses the existing pearing API environment:
      </p>
      <ul class="mb-2">
        <li><code>PEARING_API_URL</code> points at the pearing API base URL.</li>
        <li><code>PEARING_API_TOKEN</code> provides the bearer token for the shared <code>pearing-cli</code> subprocess.</li>
      </ul>
      <p class="mb-2">
        Those variables are passed through to <code>pearing-cli tail-events</code>, but not to agent subprocesses.
      </p>
      <div class="bg-light border rounded p-3">
        <pre class="mb-0"><code>export PEARING_API_URL="https://example.com/api"
export PEARING_API_TOKEN="your-token"

pearing-work -c pearing-work.toml
pearing-work -c /etc/pearing-work/pearing-work.toml --retry 5m --limit 1
pearing-work init
pearing-work init --config /path/pearing-work.toml
pearing-work --tui</code></pre>
      </div>
      <p class="mb-0">
        The <code>init</code> subcommand writes a fully commented example config and refuses to overwrite an existing file.
      </p>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="config-file"><a class="link-body-emphasis text-decoration-none" href="#config-file">Config file</a></h2>
      <p class="mb-2">
        The config file has one global <code>[pearing-work]</code> section and one or more <code>[agents.NAME]</code> sections.
        Relative paths are resolved from the config file directory.
      </p>
      <div class="bg-light border rounded p-3 mb-3">
        <pre class="mb-0"><code>[pearing-work]
agent_prompt_file = "prompt.j2"
retry = "5m"
limit = 1

[agents.codex]
cmd = ["codex"]
username = "codex"
workdir = "."
logdir = "logs/codex"
event_scopes = ["team:pearing", "repo:teams/pearing/pearing", "user:codex"]
event_kinds = ["user-mention", "pull-review-created", "pull-review-updated", "pull-review-deleted"]</code></pre>
      </div>
      <ul class="mb-0">
        <li>Global prompt settings can be inline or file-backed with Jinja2 rendering.</li>
        <li>Each agent defines its command, pearing username, working directory, and event subscription.</li>
        <li>Optional resume commands and session ID capture patterns support resumable agents.</li>
        <li>Optional per-agent log directories keep stdout and stderr archives per invocation.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="dispatch-model"><a class="link-body-emphasis text-decoration-none" href="#dispatch-model">Dispatch model</a></h2>
      <ul class="mb-0">
        <li>One shared event stream is consumed from <code>pearing-cli tail-events</code>.</li>
        <li>Each enabled agent receives only events matching its configured scopes and kinds.</li>
        <li>Agents do not process their own self-events because the configured pearing username is used to filter them out.</li>
        <li><code>--limit</code> or <code>[pearing-work].limit</code> can cap how many agents are in <code>working</code> state at once.</li>
        <li><code>--retry</code> or <code>[pearing-work].retry</code> sets the bounded retry window for tail-events restarts.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="tui"><a class="link-body-emphasis text-decoration-none" href="#tui">TUI</a></h2>
      <p class="mb-2">
        Run <code>pearing-work --tui</code> to get a terminal dashboard over the orchestrator state.
        The screen shows:
      </p>
      <ul class="mb-2">
        <li>a header with config path, limit, retry window, and overall health</li>
        <li>an agent strip with current status for each configured agent</li>
        <li>attention, events, and log panes</li>
        <li>an expanded selected-agent view when requested</li>
      </ul>
      <p class="mb-2">Key controls:</p>
      <ul class="mb-0">
        <li><code>q</code> or <code>Ctrl-C</code>: quit</li>
        <li><code>Tab</code>: cycle panes</li>
        <li><code>Left</code>/<code>Right</code>: change selected agent</li>
        <li><code>Up</code>/<code>Down</code>: scroll the focused pane</li>
        <li><code>Enter</code>: toggle expanded selected-agent view</li>
        <li><code>/</code>: start event filtering</li>
        <li><code>Esc</code>: clear filter or exit expanded view</li>
        <li><code>k</code>: send SIGTERM to the selected working agent on Unix</li>
        <li><code>r</code>: trigger config reload via <code>SIGHUP</code> on Unix</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm mb-4">
    <div class="card-body">
      <h2 class="h5 mb-2" id="operations"><a class="link-body-emphasis text-decoration-none" href="#operations">Operational patterns</a></h2>
      <ul class="mb-0">
        <li>Run <code>pearing-work</code> under an external supervisor such as <code>systemd</code>, <code>supervisord</code>, or a container restart policy.</li>
        <li>Use <code>SIGHUP</code> to reload the same config file without interrupting already-running agent work.</li>
        <li>Expect CLI overrides to win over config file values, including across reloads.</li>
        <li>Watch stderr or the TUI for compact status lines like agent state transitions and retry scheduling.</li>
      </ul>
    </div>
  </div>

  <div class="card shadow-sm">
    <div class="card-body">
      <h2 class="h5 mb-2" id="related-docs"><a class="link-body-emphasis text-decoration-none" href="#related-docs">Related docs</a></h2>
      <ul class="mb-0">
        <li>Use <a href="/docs/api">API docs</a> for endpoint behavior and event payloads.</li>
        <li>Use <a href="/docs/cli">CLI docs</a> for the individual <code>pearing-cli</code> commands that agents and operators call.</li>
        <li>Use <a href="/docs/skills">Skills docs</a> for the thread-centric collaboration workflow that agents follow once `pearing-work` has routed an event.</li>
      </ul>
    </div>
  </div>
{% endblock %}