@ai-outfitter/outfitter 1.11.0 → 1.13.0

package/docs/documentation/ai-outfitter.md

@@ -0,0 +1,259 @@
+# How AI Outfitter fits together
+
+Open, vendor-neutral tooling for configuring and operating agents: ramp a
+user, a team, or an organization from AI-assisted coding to an autonomous
+software development lifecycle.
+
+Everything here builds on one convention: an agent's context, tools, skills,
+and permissions are plain files in a `.agents/` directory — committed,
+reviewed, and shared like the rest of your code. The same plain-file definition
+can be shared across environments and model vendors; runtime support varies by
+harness, as shown in the
+[support matrix](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/support-matrix.md).
+The core is open source under MIT.
+
+## Why we built AI Outfitter
+
+We built AI Outfitter to give teams a shared path from local agent use to
+automated and governed workflows. Its defaults are customizable, so teams can
+begin at the rung that matches their current process.
+
+## The adoption ramp
+
+Five rungs, from AI-assisted coding to an autonomous lifecycle
+([full definition](https://github.com/ai-outfitter/outfitter/blob/main/docs/philosophy.md)).
+Each Outfitter component targets a rung, so you climb without rebuilding what
+got you here — and without adopting complexity too early. Rungs 2, 3, and 4
+each open with the **runbook** that gets you there: the concrete steps, and a
+success check you run rather than judge.
+
+1. **Assisted** — autocomplete and chat; a human's hands stay on the
+   keyboard. _You are here if_ you use autocomplete in an IDE.
+   There is nothing to govern yet — but the habit that matters starts here:
+   document what works and what doesn't in `AGENTS.md`/`CLAUDE.md`, and
+   keep it in the repo.
+   - [First-time CLI agent users](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/first-time-cli-agent-users.md#context-engineering)
+     — what belongs in a first `AGENTS.md`, and how to ask an agent to use
+     it.
+
+2. **Delegated** — a local agent does the task; you define the idea and
+   review the PR. _You are here if_ engineers run a coding agent in a
+   terminal and push the result. This is where configuration starts to
+   matter.
+   - **Runbook: [Share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md)**
+     — one pinned catalog the organization shares, instead of per-laptop
+     configuration.
+   - [outfitter](https://github.com/ai-outfitter/outfitter) — composes what
+     an agent knows and may do into a **profile**: plain files in your
+     `.agents/` folder, reviewed like code and portable across environments
+     and **harnesses** (the CLI that runs an agent: Claude Code, Pi, Codex).
+   - [deepwork](https://github.com/ai-outfitter/deepwork) — step-by-step
+     quality gates so the agent checks its own work.
+
+3. **Automated** — a workflow runs without your laptop: an issue, a message,
+   or a schedule triggers agents in CI, on a cluster, or on a remote server
+   you never sit at; adversarial review is part of the pipeline; session
+   logs are captured before merge. _You are here when_ you close your laptop
+   and the work keeps going. What promotes you is the trigger, not the
+   hardware: an agent you drive over SSH is rung 2 on a bigger machine.
+   - **Runbook: [Run it without your laptop](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/run-without-your-laptop.md)**
+     — an event triggers the workflow, its output lands through review, and
+     the session is captured.
+   - [actions](https://github.com/ai-outfitter/actions) — runs any profile
+     headless in GitHub Actions, on any trigger.
+   - [channels](https://github.com/ai-outfitter/channels) — pushes email,
+     Slack, Signal, and forge events (GitHub or GitLab activity) into an
+     agent session, so one message can start the same workflow.
+   - [agent-operator](https://github.com/ai-outfitter/agent-operator) —
+     hosts the same profiles on your own infrastructure, well before you
+     need its resident-agent story on the next rung.
+
+4. **Governed** — the organization shares one version-pinned catalog of
+   agents, skills, and policy; every agent action lands in an auditable
+   record; **[resident agents](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/in-cluster.md)**
+   — long-lived agents onboarded like teammates,
+   with their own accounts and boundaries — take on standing jobs. _You are
+   here when_ agents work across many teams, and the organization needs
+   shared policy — and proof of what every agent did.
+   - **Runbook: [Give the agent a residence](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/give-the-agent-a-residence.md)**
+     — a named, assignable agent with an account and somewhere to live.
+   - **Build your agent catalog: [Share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md)**
+     — the rung 2 runbook creates it and links to guidance on its layout,
+     version pinning, and governance. Our own
+     [.agents](https://github.com/ai-outfitter/.agents) is a worked example
+     you can read end to end.
+   - [agent-operator](https://github.com/ai-outfitter/agent-operator) —
+     provisions and supervises resident agents on your own infrastructure.
+   - [pensieve](https://github.com/ai-outfitter/pensieve) — designed to retain
+     evidence from agent sessions, including environments, agents, tools,
+     artifacts, and costs. That record can support audits, compliance reviews,
+     and evaluation workflows.
+
+5. **Self-improving** — the audit record feeds evals and improvement; humans
+   set goals and acceptance gates, agents own the middle. Rung 5 is where
+   the stack is thinnest today.
+   - [evals](https://github.com/ai-outfitter/evals) — evaluates changes to a
+     profile, model, or workflow with reproducible, attested benchmarks.
+   - [autoimprove](https://github.com/ai-outfitter/autoimprove) — improves
+     portable skills against measured outcomes.
+
+## Start with one workflow end to end
+
+One useful first workflow takes **a feature idea to a merged PR**, automated
+end to end, with every step leaving evidence. This is what rung 3 looks like
+up close.
+
+![A feature idea flows through plan, implement, and adversarial review to a merged PR, with every transition writing to the evidence record](./assets/feature-to-pr.svg)
+
+1. **Entry point.** Someone files an issue and assigns it to an agent — from
+   the forge, from chat, or from a planning session at a desk. Different
+   doors, same workflow.
+2. **Plan.** A planner profile with read-only tools turns the issue into a
+   spec artifact and posts it back to the issue, where a human can approve
+   it (we recommend an enforced spec system, like
+   [2119](https://github.com/Unsupervisedcom/2119), for more autonomous
+   workflows).
+3. **Implement.** An implementer profile picks up the approved spec in a
+   fresh container with exactly the tools the work needs — a different
+   agent, a clean context window, the same shared catalog.
+4. **Review.** An adversarial reviewer profile, which shares none of the
+   implementer's context, tries to break the change before any human reads
+   it.
+5. **Merge.** The PR arrives with its history attached: session transcripts,
+   tool calls, and diffs captured as artifacts before the environment that
+   produced them is torn down.
+
+The same shape handles other starting workflows. A vulnerability report
+instead of a feature idea turns the pipeline into governed security
+remediation: the scanner files the issue (most scanners already can), the
+planner scopes the fix, and the same steps carry it to a tested, approved
+PR. Bug reports run the same way with a triage step in front: an agent
+reproduces and prioritizes each report, and only the ones that clear triage
+enter the pipeline.
+
+Teams adopt the system through the same composition process: an engineer
+refines a skill in their own
+[`~/.agents`](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/local-development.md)
+against real work; the team mines
+[pensieve](https://github.com/ai-outfitter/pensieve) for the patterns behind
+successful and failing runs. When a change earns trust it moves by pull
+request into the org catalog, where every agent composes it by name. One
+person's improvement becomes everyone's default at the next pin bump — no
+one else reconfigures anything.
+
+## Start this afternoon
+
+You can begin with a local assessment and CLI trial before committing to an
+organization-wide rollout or additional infrastructure.
+
+### 1. See where you are
+
+The read-only assessment takes one afternoon. The
+[org-onboarding runbook](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/usecases/org-onboarding-sdlc-report.md)
+produces a baseline **SDLC report**: where your organization sits on the
+ramp, with evidence, gaps, and next-rung recommendations. Concretely: one
+engineer runs the `sdlc-report` skill from their own local agent with a
+read-only forge token. It reads through the API — never clones, never
+writes — and produces two local files you review before anyone else sees
+them. We ran it on this organization the day we wrote this page; the output
+is committed at
+[.agents/reports/sdlc](https://github.com/ai-outfitter/.agents/tree/main/reports/sdlc),
+so you can see exactly what you would get.
+
+### 2. Try the toolchain
+
+The first run takes about ten minutes.
+
+```bash
+npx @ai-outfitter/outfitter
+```
+
+This launches the Outfitter CLI with the
+[Pi](https://github.com/earendil-works/pi) harness bundled and walks you
+through composing your first agent profile from a starter catalog. You end
+in a working agent session, and everything it created is plain files under
+`~/.agents` — which you can read, edit, or delete afterward.
+
+### 3. Automate one workflow
+
+Pick feature-to-PR or bug-to-PR, keep it to
+one repository, and promote the profiles you already trust at a desk into
+[CI](https://github.com/ai-outfitter/actions). Work the runbooks in order —
+[share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md),
+[run it without your laptop](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/run-without-your-laptop.md),
+then [give the agent a residence](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/give-the-agent-a-residence.md).
+Each ends with the one concrete step that starts the next.
+
+Every runbook closes with a **Done when** section naming the signals the report
+above checks — for this one, `triggered-agents`, `protected-landing`, and
+`session-capture`. Re-run the report and it names whichever is still unmet.
+
+## Agent configuration as code
+
+Your agent setup is already configuration: system prompts, skills, MCP
+servers, model choices, permissions. Today that configuration lives per tool
+and per laptop, gets pasted between repositories, and drifts. Every other
+kind of configuration your organization depends on graduated from that stage
+years ago — into files, in a repository, behind review.
+
+The [`.agents` convention](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/concepts.md#the-agents-protocol)
+is an open standard for doing the same for agents:
+
+```text
+.agents/
+  agents.md            # shared operating context
+  system-prompt.md     # base system prompt
+  mcp.json             # MCP servers
+  models.json          # model configuration
+  agents/<id>/agent.md # agent identities + loadouts
+  skills/<id>/...      # capability packages
+  knowledge/           # reference documents
+  commands/            # slash commands
+```
+
+Because the configuration is Markdown and JSON, you can read, review, and
+audit it with ordinary repository tools. Layers merge by name — a project's
+`.agents/` over an engineer's `~/.agents/` over the organization's
+**[catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/catalogs.md)**,
+a shared collection pinned by version — so individuals keep their preferences and
+organizations keep their policy
+([conventions](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/conventions.md)).
+
+Composition beats accumulation. A profile is a selection from those files,
+and profiles stack: a personal baseline, a team convention, a project role,
+switched as the work changes. That keeps each profile tight, and tight
+profiles preserve the context headroom that turns into faster, better
+sessions.
+
+The directory is also the exit door. It is the source of truth, and it is
+useful without Outfitter. Vendor-neutral cuts in every direction — models,
+harnesses, and us. Swap model vendors freely. Run the catalog through any
+harness: Pi has the deepest runtime support today, with Claude Code tracked
+component by component in the
+[support matrix](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/support-matrix.md)
+— a Claude Code team starts on Claude Code, and the matrix shows the gaps
+before you hit them. And if you drop Outfitter itself, the catalog you
+built is still yours — plain files, still working.
+
+## Where this is today
+
+Outfitter and several supporting projects are in active development. Actions
+and the catalogs run AI Outfitter's own workloads today; rung 5 remains the
+least developed part of the stack. Check each linked repository for its current
+implementation status.
+
+The model is open core: the convention, the toolchain, and the defaults are
+MIT — modules you can rip out and replace — while some advanced capabilities
+ship under an enterprise license. If you are evaluating this for an
+organization, [open an issue](https://github.com/ai-outfitter/outfitter/issues)
+with what you found. The gaps you hit are the roadmap we want.
+
+## As you climb
+
+Two suggestions we make strongly, and follow ourselves:
+
+1. **Automate nothing you have not first done manually.**
+2. **Hand over control one layer at a time.**
+
+You never skip a step you don't understand, and nothing you build on one
+rung is thrown away on the next.

package/docs/documentation/assets/feature-to-pr.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 980 284" font-family="-apple-system, 'Segoe UI', Helvetica, Arial, sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 1 L 8 5 L 0 9 z" fill="#57606a"/>
+    </marker>
+    <marker id="arrdim" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 1 L 8 5 L 0 9 z" fill="#d4a72c"/>
+    </marker>
+  </defs>
+
+  <rect x="0.5" y="0.5" width="979" height="283" rx="12" fill="#ffffff" stroke="#d0d7de"/>
+
+  <!-- step boxes -->
+  <g>
+    <rect x="28" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="112" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">1 · ENTRY POINT</text>
+    <text x="112" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Issue assigned</text>
+    <text x="112" y="96" text-anchor="middle" font-size="11" fill="#57606a">from the forge, chat,</text>
+    <text x="112" y="110" text-anchor="middle" font-size="11" fill="#57606a">or a desk session</text>
+  </g>
+  <g>
+    <rect x="217" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="301" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">2 · PLAN</text>
+    <text x="301" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Planner agent</text>
+    <text x="301" y="96" text-anchor="middle" font-size="11" fill="#57606a">read-only tools →</text>
+    <text x="301" y="110" text-anchor="middle" font-size="11" fill="#57606a">spec posted for approval</text>
+  </g>
+  <g>
+    <rect x="406" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="490" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">3 · IMPLEMENT</text>
+    <text x="490" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Implementer agent</text>
+    <text x="490" y="96" text-anchor="middle" font-size="11" fill="#57606a">fresh container,</text>
+    <text x="490" y="110" text-anchor="middle" font-size="11" fill="#57606a">scoped tools, clean context</text>
+  </g>
+  <g>
+    <rect x="595" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="679" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">4 · REVIEW</text>
+    <text x="679" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Adversarial reviewer</text>
+    <text x="679" y="96" text-anchor="middle" font-size="11" fill="#57606a">shares no context,</text>
+    <text x="679" y="110" text-anchor="middle" font-size="11" fill="#57606a">tries to break the change</text>
+  </g>
+  <g>
+    <rect x="784" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="868" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">5 · MERGE</text>
+    <text x="868" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">PR, with history</text>
+    <text x="868" y="96" text-anchor="middle" font-size="11" fill="#57606a">transcripts &amp; diffs attached</text>
+    <text x="868" y="110" text-anchor="middle" font-size="11" fill="#57606a">before teardown</text>
+  </g>
+
+  <!-- horizontal arrows -->
+  <line x1="198" y1="80" x2="213" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="387" y1="80" x2="402" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="576" y1="80" x2="591" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="765" y1="80" x2="780" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- drop lines to the record -->
+  <line x1="112" y1="124" x2="112" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="301" y1="124" x2="301" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="490" y1="124" x2="490" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="679" y1="124" x2="679" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="868" y1="124" x2="868" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+
+  <!-- evidence record band -->
+  <rect x="28" y="166" width="924" height="52" rx="8" fill="#fff8c5" stroke="#d4a72c" stroke-dasharray="5 4"/>
+  <text x="490" y="188" text-anchor="middle" font-size="11" fill="#7d4e00" font-weight="600" letter-spacing="1">THE RECORD</text>
+  <text x="490" y="206" text-anchor="middle" font-size="12" fill="#7d4e00">session transcripts · tool calls · diffs · approvals — written at every transition</text>
+
+  <!-- footer caption -->
+  <text x="490" y="252" text-anchor="middle" font-size="12" fill="#57606a" font-style="italic">Each step is an agent profile from a shared catalog — designed to run the same at a desk, in CI, or in a cluster.</text>
+</svg>

package/docs/documentation/catalogs.md

@@ -1,6 +1,6 @@
 # Catalogs
 
-A catalog is a git repository that publishes a `.agents` payload — agents, skills, tasks, knowledge, commands — so a person, team, or organization can share it. You can bootstrap a machine or project from one, or add one as an ongoing source that Outfitter keeps synchronized.
+A catalog is a git repository that publishes a `.agents` payload — agents, skills, workflows, tasks, knowledge, commands — so a person, team, or organization can share it. You can bootstrap a machine or project from one, or add one as an ongoing source that Outfitter keeps synchronized.
 
 ```bash
 outfitter setup https://github.com/ncrmro/.agents
@@ -33,6 +33,8 @@ ncrmro/.agents/            # repository root
   tasks/
     weekly-kpis/task.md
   knowledge/
+  workflows/
+    engineer/workflow.yaml
   settings.yml             # Outfitter settings (optional; see settings.md)
   settings.local.yml       # gitignored machine-local overrides
 ```
@@ -83,6 +85,12 @@ Remote entries additionally accept:
 
 Resources from all sources resolve by slug behind local layers, following [layer precedence](./concepts.md#layer-precedence). Agent-local skills keep their owning-agent namespace through cache and source merging. Outfitter reports shadowed IDs so consumers can see which source supplies a selected resource.
 
+### Workflows are configuration, not an execution engine
+
+Each `workflows/<slug>/workflow.yaml` is a typed graph that names its human, agent, tool, and system actors. Agent actors reference ordinary catalog profiles. Node-level skill, prompt, and MCP assertions must already belong to the selected agent's composed closure. Nested workflow references resolve by slug and may not form cycles.
+
+`outfitter validate --strict` validates the graph and the complete composed dependency closure. `outfitter dump --workflow <slug>` produces a reviewable `.agents` bundle for distribution. Outfitter never schedules or executes the graph.
+
 ### Catalog dependencies (transitive sources)
 
 A catalog can depend on other catalogs by declaring `sources` in its own settings file

package/docs/documentation/cli.md

@@ -71,13 +71,15 @@ resolution tells you to run `outfitter sync`.
 
 List resolvable resources across all layers, with the winning source for each slug and any shadowed IDs.
 
-| Argument | Description                                                   |
-| -------- | ------------------------------------------------------------- |
-| `[kind]` | Optional filter: `agents`, `skills`, `knowledge`, `commands`. |
+| Argument | Description                                                                |
+| -------- | -------------------------------------------------------------------------- |
+| `[kind]` | Optional filter: `agents`, `skills`, `knowledge`, `commands`, `workflows`. |
+
+`--json` emits an object containing `ok`, `resources`, and `diagnostics`; diagnostics remain available when strict mode fails.
 
 ## `outfitter validate`
 
-Validate the effective resource set: protocol layout, frontmatter, unresolved slugs in agent loadouts, broken or escaping skill references, and settings schema.
+Validate the effective resource set: protocol layout, frontmatter, unresolved slugs in agent loadouts, broken or escaping skill references, workflow graphs and composed closures, and settings schema.
 
 | Option     | Description                              |
 | ---------- | ---------------------------------------- |
@@ -88,9 +90,20 @@ Validate the effective resource set: protocol layout, frontmatter, unresolved sl
 
 Write the composed resource tree as a self-contained `.agents/` directory for review, vendoring, or air-gapped use. Identical sources, refs, and selections produce byte-identical output; dumps never contain credentials, sessions, caches, or other mutable runtime state.
 
-| Option         | Description                                          |
-| -------------- | ---------------------------------------------------- |
-| `--agent <id>` | Restrict the dump to one agent's transitive closure. |
-| `--out <dir>`  | Destination directory (default `./.agents`).         |
+| Option            | Description                                                                    |
+| ----------------- | ------------------------------------------------------------------------------ |
+| `--agent <id>`    | Restrict the dump to one agent's transitive closure.                           |
+| `--workflow <id>` | Export one workflow, its nested workflows, and every referenced agent closure. |
+| `--out <dir>`     | Destination directory (default `./.agents`).                                   |
+
+Workflow dumps are non-executable configuration bundles. They contain the canonical workflow YAML, composed agent resources, and a hash/provenance manifest. A workflow dump refuses an existing destination instead of replacing user files.
 
 > **Tasks and `outfitter task bake`** — baking a task and its inputs into an immutable execution artifact — are the subject of a separate upcoming RFC and are not part of this command surface yet. See [Tasks](./tasks.md).
+
+`outfitter run` verifies these caches before composition. Use
+`--source-cache-policy <repair|locked|offline>` to override the configured startup policy.
+
+## `outfitter sources`
+
+Report local and remote source precedence, requested and resolved revisions, origins, and cache
+health. `outfitter sources --json` emits stable credential-redacted machine-readable output.

package/docs/documentation/containers.md

@@ -13,9 +13,6 @@ servers, or other use-case behavior. The default runtime user and group are
 both `1000` (named `outfitter`), with `/tmp` as the home directory and
 `/workspace` as the working directory.
 
-A Nix closure variant of the image is also published under the `-nix` suffix;
-see [the `-nix` variant](#the--nix-variant) below.
-
 ## Run a resident agent
 
 A resident container is an ordinary `outfitter run` whose harness stays in RPC
@@ -47,7 +44,7 @@ spec:
         fsGroup: 1000
       containers:
         - name: agent
-          # The primary Debian-based image; append -nix for the Nix variant.
+          # The published Debian-based image.
           image: ghcr.io/ai-outfitter/outfitter:<version>
           stdin: true
           workingDir: /workspace
@@ -85,8 +82,8 @@ The image is a normal Debian base: extend it with an ordinary Dockerfile.
 `apt-get` works, and so does `COPY`ing binaries. A dynamically linked binary
 runs when it matches the image — same architecture, glibc-linked, and its
 shared-library dependencies present. The standard ELF interpreter is where
-tools expect it (unlike the `-nix` variant), but the slim base ships a small
-library set: `apt-get install` a binary's runtime libraries when it needs more.
+tools expect it, but the slim base ships a small library set. Use `apt-get
+install` when a binary needs more runtime libraries.
 Switch to `root` for the layers that install, then drop back to `1000`:
 
 ```dockerfile
@@ -111,77 +108,3 @@ docker run --rm --entrypoint /bin/sh example-agent \
 
 The entrypoint stays `outfitter`; override `ENTRYPOINT` only when the derived
 image wraps the launch itself.
-
-## The `-nix` variant
-
-The Nix closure image that was previously the primary tag remains published
-for `lib.mkContainer` consumers:
-
-```text
-ghcr.io/ai-outfitter/outfitter:<version>-nix
-```
-
-It is built by the flake, includes the Nix CLI, Bash, core utilities, Git,
-SSH, and CA certificates, and its entrypoint is an absolute `/nix/store` path.
-It is not conventionally extensible — there is no apt, and foreign dynamic
-binaries do not run — so extend it through Nix instead: the flake exports
-`lib.mkContainer` for reproducible derivative images:
-
-```nix
-{
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
-    outfitter = {
-      url = "github:ai-outfitter/outfitter/v1.4.0";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
-  };
-
-  outputs =
-    { nixpkgs, outfitter, ... }:
-    let
-      system = "x86_64-linux";
-      pkgs = nixpkgs.legacyPackages.${system};
-    in
-    {
-      packages.${system}.default = outfitter.lib.mkContainer {
-        inherit pkgs;
-        outfitterPackage = outfitter.packages.${system}.outfitter;
-        name = "example-agent";
-        extraPackages = [
-          pkgs.jq
-          pkgs.ripgrep
-        ];
-      };
-    };
-}
-```
-
-Build and exercise the exact image:
-
-```sh
-nix build
-docker load < result
-docker run --rm example-agent:latest --version
-docker run --rm --entrypoint /bin/sh example-agent:latest \
-  -c 'nix --version && jq --version && rg --version'
-```
-
-Prefer adding known runtime packages through `extraPackages`. The resulting
-image stays reproducible, and it avoids the trap below.
-
-**Do not mount an empty volume over `/nix` of the `-nix` variant.** That image
-_is_ its Nix store: the entrypoint is an absolute store path and every binary
-in `/bin` is a symlink into `/nix/store`. Mounting a fresh volume there hides
-all of it, so the container cannot start — it fails before it could initialize
-the very store you mounted the volume to populate. (The primary Debian image
-has no `/nix` and is not affected.)
-
-Runtime installation in the `-nix` variant therefore needs one of:
-
-- a volume **pre-populated** with the image's closure, seeded from the image
-  before the agent starts (an init container copying `/nix` into the volume);
-- an **overlay** whose lower layer is the image's `/nix`, so the closure stays
-  visible while writes land in the upper layer; or
-- writable Nix **state** only — `/nix/var` and a per-user profile — leaving the
-  store itself as the image shipped it.

package/docs/documentation/dump-and-bake.md

@@ -9,6 +9,7 @@
 ```bash
 outfitter dump --out ./review
 outfitter dump --agent engineer --out ./engineer   # one agent's transitive closure only
+outfitter dump --workflow engineer --out ./workflow # graph + nested graphs + agent closures
 ```
 
 Use dumps to:
@@ -24,6 +25,7 @@ Use dumps to:
 - **Safe** — a dump may include reviewable source provenance, but never credentials, auth state, sessions, transcripts, caches, backups, mutable harness state, or symlinks escaping the tree.
 - **Protocol-shaped** — the output is a valid `.agents` payload usable by any protocol consumer, not just Outfitter. Any Outfitter-specific provenance metadata is namespaced, JSON-based, and removable without losing the underlying resources.
 - **Harness-discoverable** — selected agent-local skills are flattened into top-level `skills/<id>/` in the closure output, with their packaged references, scripts, and assets intact.
+- **Workflow-auditable** — workflow exports preserve canonical YAML and record every nested workflow, agent composition, file hash, and winning source in `.outfitter/workflow-composition.json`.
 
 ## Bake
 

package/docs/documentation/settings.md

@@ -41,6 +41,8 @@ remote_settings:
     ref: 9c47d1e2b8a05f36c4d7e90a12b3f8c5d6e71a04
 
 cache_directory: ./cache # optional; relative to this settings file
+source_cache:
+  policy: repair # repair (default), locked, or offline
 
 # Pseudonymous product analytics consent; defaults to true when absent.
 telemetry:
@@ -53,6 +55,9 @@ telemetry:
 - `remote_settings` — shared settings a repository distributes; cached locally and merged below your project and user settings, so anything you set locally wins.
 - `cache_directory` — the repository cache root used consistently by sync, remote settings, remote
   source resolution, and default-catalog setup. It defaults to `~/.agents/cache`; repositories live
+- `source_cache.policy` — verifies remote caches before `run`: `repair` reuses healthy caches and
+  atomically repairs unhealthy ones, `locked` also requires full commit pins, and `offline` never
+  accesses the network.
   below its `repos/` directory.
 - `telemetry.enabled` — the primary and sole persistent control for pseudonymous product analytics. Edit it directly to enable or disable telemetry. See [Telemetry](./telemetry.md) for consent precedence, automatic identifier cleanup, the event contract, and the current inert-build status.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {

package/src/schemas/settings.schema.json

@@ -11,6 +11,11 @@
       "description": "Whether a run stands on the machine's native harness configuration (inherit, the default) or on the projection alone (isolated). Honored only from home-scope settings."
     },
     "cache_directory": { "type": "string", "minLength": 1 },
+    "source_cache": {
+      "type": "object",
+      "properties": { "policy": { "enum": ["repair", "locked", "offline"] } },
+      "additionalProperties": false
+    },
     "state_persistence": {
       "type": "object",
       "description": "Maps adapter-declared state paths to a persistence strategy.",