@ai-outfitter/outfitter 1.10.0 → 1.12.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/cli.md

@@ -94,3 +94,11 @@ Write the composed resource tree as a self-contained `.agents/` directory for re
 | `--out <dir>`  | Destination directory (default `./.agents`).         |
 
 > **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/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/docs/documentation/support-matrix.md

@@ -12,33 +12,35 @@ When a composition requests something an adapter cannot project, Outfitter warns
 
 Tasks and bake are not in this matrix — they are the subject of a [separate upcoming RFC](./tasks.md).
 
-| What Outfitter projects                                                  | Pi        | Claude Code | Codex CLI |
-| ------------------------------------------------------------------------ | --------- | ----------- | --------- |
-| Agent config directory                                                   | Supported | Supported   | Roadmap   |
-| Session directory                                                        | Supported | Supported   | Roadmap   |
-| Agent identity (`system-prompt.md`, `agents.md`, `agents/<id>/agent.md`) | Supported | Supported   | Roadmap   |
-| Subagents (`agents/<id>` as harness delegates)                           | Supported | Supported   | Roadmap   |
-| Skills (`skills/<id>`)                                                   | Supported | Partial     | Roadmap   |
-| Commands (`commands/`)                                                   | Supported | Partial     | Roadmap   |
-| Knowledge (`knowledge/`)                                                 | Supported | Partial     | Roadmap   |
-| Model selection (`models.json`)                                          | Supported | Partial     | Partial   |
-| MCP servers (`mcp.json`)                                                 | Supported | Supported   | Partial   |
-| Extensions (agent `extensions:` loadout)                                 | Supported | Pi only     | Pi only   |
-| Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     | Roadmap   |
-| Credentials and environment                                              | Supported | Supported   | Roadmap   |
-| DeepWork job selection                                                   | Supported | Roadmap     | Roadmap   |
-| Hooks                                                                    | Partial   | Partial     | Roadmap   |
-| Tool availability (agent `tools:` loadout)                               | Supported | Supported   | Roadmap   |
-| Theme / UI presentation                                                  | Roadmap   | Roadmap     | Roadmap   |
-| Working directory                                                        | Roadmap   | Roadmap     | Roadmap   |
-| Pass-through arguments                                                   | Supported | Supported   | Supported |
-| Bootstrap hook                                                           | Supported | Roadmap     | Roadmap   |
+| What Outfitter projects                                                  | Pi        | Claude Code | Codex CLI  |
+| ------------------------------------------------------------------------ | --------- | ----------- | ---------- |
+| Agent config directory                                                   | Supported | Supported   | Roadmap    |
+| Session directory                                                        | Supported | Supported   | Roadmap    |
+| Agent identity (`system-prompt.md`, `agents.md`, `agents/<id>/agent.md`) | Supported | Supported   | Roadmap    |
+| Subagents (`agents/<id>` as harness delegates)                           | Supported | Supported   | Roadmap    |
+| Skills (`skills/<id>`)                                                   | Supported | Partial     | Roadmap    |
+| Commands (`commands/`)                                                   | Supported | Partial     | Roadmap    |
+| Knowledge (`knowledge/`)                                                 | Supported | Partial     | Roadmap    |
+| Model selection (`models.json`)                                          | Supported | Supported¹  | Supported² |
+| MCP servers (`mcp.json`)                                                 | Supported | Supported   | Partial    |
+| Extensions (agent `extensions:` loadout)                                 | Supported | Pi only     | Pi only    |
+| Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     | Roadmap    |
+| Credentials and environment                                              | Supported | Supported   | Roadmap    |
+| DeepWork job selection                                                   | Supported | Roadmap     | Roadmap    |
+| Hooks                                                                    | Partial   | Partial     | Roadmap    |
+| Tool availability (agent `tools:` loadout)                               | Supported | Supported   | Roadmap    |
+| Theme / UI presentation                                                  | Roadmap   | Roadmap     | Roadmap    |
+| Working directory                                                        | Roadmap   | Roadmap     | Roadmap    |
+| Pass-through arguments                                                   | Supported | Supported   | Supported  |
+| Bootstrap hook                                                           | Supported | Roadmap     | Roadmap    |
+
+¹ Canonical `anthropic-messages` providers. ² Canonical `openai-responses` providers. Other dialects warn and fail under `--strict` rather than changing endpoints.
 
 ## Codex CLI notes
 
 - **Launch mode** — Outfitter launches `codex` directly. Pass-through arguments choose the native mode: no subcommand keeps the interactive CLI shape, while `-- exec ...` selects non-interactive `codex exec`.
 - **Agent identity and appended prompts** — Codex has no native identity projection yet: launches drop the composed identity/system prompt and any `--append-prompt` documents, supplied documents produce a separate warning, and `--strict` aborts before execution.
-- **Model selection (Partial)** — an agent's model maps to `-m`. Provider maps have no projection element and produce no warning. Thinking, tools, skills, subagents, plugins, and prompt templates remain unsupported and warn when selected.
+- **Model selection** — an agent's `provider/model` selection resolves from layered `models.json`. OpenAI Responses providers map to native `model_provider`, `base_url`, `env_key`, header, wire API, and `-m` overrides. Unsupported dialects warn and omit the target instead of reusing its model ID against Codex's default endpoint. Thinking, tools, skills, subagents, plugins, and prompt templates remain unsupported and warn when selected.
 - **Extensions (Pi only)** — `extensions:` names pi extension packages, so a Codex or Claude Code launch installs none of them. This is a property of the element, not a gap a user can close, so it produces no warning and does not fail under `--strict`.
 - **MCP servers (Partial)** — selected stdio fields (`command`, `args`, `env`, `cwd`) and streamable HTTP fields (`url`, `headers`) become repeated TOML-valued `-c mcp_servers.<id>.<key>=...` overrides. Server ids must contain only letters, digits, `_`, or `-`; other ids cannot be expressed by Codex `-c` key paths and are skipped with a warning. Legacy SSE and other HTTP transport types are also skipped with a warning. User and project `config.toml` servers remain active because Codex has no strict MCP isolation mode, so every launch warns that projection is additive, even when no servers are selected.
 - **Stdio environment safety** — `${ENV_NAME}` becomes an `env_vars` reference only when the stdio `env` key is also `ENV_NAME`; a reference that would rename the variable is dropped with a warning. Literal values pass through `env` and are visible in process arguments.
@@ -52,7 +54,7 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - **MCP servers** — every Claude launch passes the generated `mcp.json` through `--mcp-config`. An inherited run stops there, so the composition's servers merge with the ones already configured on the machine: selecting a server says what the profile needs, not what the user may not have. An isolated run adds `--strict-mcp-config`, which excludes MCP servers from user or project configuration, `.claude.json`, and plugins so only the composition's servers are active.
 - **Subagents** — selected `agents/<id>` definitions are materialized into the composition's agents directory. An inherited run loads them under the plugin's name (`<profile>:<subagent>`); an isolated run finds them natively under `CLAUDE_CONFIG_DIR`.
 - **Skills (Partial)** — selected skills are materialized into the config directory's skills surface; remaining gaps are tracked per release. The bundled Outfitter skill ships through the plugin channel.
-- **Model selection (Partial)** — model maps to `--model` and thinking level to `--effort`; provider selection is not projected for Claude and warns if requested.
+- **Model selection** — an agent's `provider/model` selection resolves from layered `models.json`. Anthropic Messages providers map to native `--model`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and custom-header controls. Unsupported dialects warn and omit the target instead of reusing its model ID against Claude's default endpoint. Thinking level maps to `--effort`.
 - **Hooks** — Outfitter does not project hook configuration for Claude, and there is no portable protocol hooks resource yet. An inherited run keeps the hooks in your own `~/.claude/settings.json`; an isolated run has none. See [Hooks](./hooks.md).
 - **Tool availability** — `tools.allow` (after `tools.deny` removes entries) maps to both `--tools` (_availability_: an unlisted builtin is not in the session) and `--allowedTools` (_permission_: the granted tools are pre-approved, so a headless session is not stopped by a prompt); `tools.deny` always maps to `--disallowedTools`, including when both are declared, and a bare denied name removes the tool from context per Claude's docs. An allowlist that `tools.deny` empties maps to `--tools ""`, Claude's documented "disable all tools" form. Caveat: per the CLI reference, `--tools` governs the built-in set only — MCP tools (`mcp__server__*`) are unaffected and are governed by which MCP servers the loadout selects, so `--tools ""` is not exactly pi's zero-tool session when MCP servers are present. Claude's behavior here comes from `claude --help` and the CLI reference, not local measurement.
 - **DeepWork jobs** — job selection is Pi-only today and warns on Claude.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.10.0",
+  "version": "1.12.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.",