@ai-outfitter/outfitter 1.5.0 → 1.7.0

package/docs/documentation/README.md

@@ -2,6 +2,19 @@
 
 Outfitter lays out conventions for iterating on and sharing agent configuration — agent profiles, skills, and loadouts. The docs follow that arc: **set up** your own, **understand** the pieces, **share** them across projects and your org, **automate** them on more surfaces, then contribute back. Each page keeps to one concept and links onward when you need the next one, so nothing here has to be read up front.
 
+Onboarding an organization? Start with
+[Onboard an organization with an SDLC report](./usecases/org-onboarding-sdlc-report.md) —
+one engineer runs the maturity assessment, then creates the org `.agents`
+repository with the baseline report as its first commit.
+
+## Climb the ramp (runbooks)
+
+One runbook per rung of [the adoption ramp](../philosophy.md#the-ramp-to-an-autonomous-lifecycle). Each starts where the previous one ended and closes with the one concrete step that begins the next rung. Their success checks are the signals an SDLC assessment reports, so "done" is something you run rather than something you judge.
+
+- [Share one catalog](../runbooks/share-one-catalog.md) — one pinned catalog the organization shares, instead of per-laptop configuration. (→ delegated)
+- [Run it without your laptop](../runbooks/run-without-your-laptop.md) — an event triggers the workflow, its output lands through review, and the session is captured. (→ automated)
+- [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) — a named, assignable agent with an account and somewhere to live. (→ governed)
+
 ## Start (you)
 
 - [Getting started](./getting-started.md) — install, first run, default agent.
@@ -36,7 +49,7 @@ The same composition runs on every surface; only the trigger changes.
 - [Container images](./containers.md) — run the published Debian-based image persistently, extend it with apt, or use the `-nix` variant.
 - [Recurring runs](./recurring-runs.md) — loops three ways: the local loop extension, Actions cron, cluster schedules.
 - [In-cluster agents](./in-cluster.md) — resident agents, CronJobs, and subagent Jobs via Link Operator.
-- [Hooks](./hooks.md) — harness hook wiring and the protocol gap.
+- [Hooks](./hooks.md) — harness hook wiring, launcher-scope system observers, and the protocol gap.
 - [Dump](./dump-and-bake.md) — deterministic, self-contained `.agents/` dumps.
 - [State persistence](./state.md)
 - [Adapter support matrix](./support-matrix.md)

package/docs/documentation/catalogs.md

@@ -83,6 +83,43 @@ 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.
 
+### Catalog dependencies (transitive sources)
+
+A catalog can depend on other catalogs by declaring `sources` in its own settings file
+(`settings.yml` at its payload root, or `.agents/settings.yml`). Outfitter resolves those
+declarations transitively: syncing and resolving a catalog also fetches and layers the catalogs it
+declares, so one pinned root pulls in its dependency closure.
+
+Transitive sources are deliberately the narrowest safe subset — a `github:` shorthand pinned to an
+immutable ref — while the [remote-catalog trust model](https://github.com/ai-outfitter/outfitter/issues/212)
+is defined. Anything else a catalog declares is skipped with a warning:
+
+- **`github:` shorthand only.** A transitive source must be a `github: owner/repo` shorthand. A
+  `uri:` source declared by a catalog is skipped, because a URI can name an arbitrary git transport
+  (for example a local path or a remote helper) that a dependency should not be able to choose on
+  your behalf. Keeping to `github:` also routes every transitive fetch that `outfitter sync`
+  performs through the same private-catalog gate as your own sources. (The one exception is the
+  first-party default catalog's own closure, fetched during setup — see the note below.)
+- **Whole repository only.** A transitive `github:` source may not carry a `path:` subpath, so a
+  declaration can never point outside the repository it fetches.
+- **Pinned only.** A transitive source must pin an immutable `ref:` — a full commit SHA, or a
+  version tag such as `v1.2.0`. A commit SHA is truly immutable; a version tag is a pin the
+  dependency's maintainer could later move, in which case the next `outfitter sync` fetches the
+  new commit and reports it as `updated`. Pin dependencies you rely on to a SHA when you need the
+  closure to never change underneath you.
+- **Content only.** A depended-on catalog contributes `.agents` payload resources. Nothing else in
+  its settings file — default agent, default harness, cache directory, `remote_settings` — takes
+  effect transitively.
+- **Lower precedence.** Every source you configure directly outranks every transitive source;
+  deeper dependencies rank below shallower ones.
+- Cycles and duplicates resolve once — the first occurrence wins and resolution terminates.
+
+A fresh `outfitter` install fetches this closure during setup, so a default profile whose skills
+live in a depended-on catalog works without a manual sync. Because the default catalog is the
+first-party catalog Outfitter ships (pinned in the CLI), its bootstrap fetches the declared closure
+directly; the interactive private-catalog prompt is a property of `outfitter sync`, which is where
+you add your own third-party sources.
+
 ## Organization control repositories
 
 An `owner/.outfitter` repository distributes organization-wide resources plus shared settings that Outfitter layers below each user's local settings:
@@ -104,7 +141,10 @@ Remote settings are cached locally and merged at lower precedence than your proj
 1. Local settings are validated. Remote settings repositories are cloned or updated first, then
    merged settings are reloaded.
 2. Remote sources (including any added by remote settings) are cloned or updated.
-3. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
+3. Sources declared by the synced catalogs themselves (see
+   [catalog dependencies](#catalog-dependencies-transitive-sources)) are fetched next, repeating
+   until the whole dependency closure is cached.
+4. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
 
 All repositories live under `<cache_directory>/repos/<encoded-uri-and-ref>/` (default
 `~/.agents/cache`). Pinned (`ref:`) sources stay on their selected ref until you change it; unpinned
@@ -119,6 +159,23 @@ synchronization; run sync explicitly when you want network updates.
 
 Private GitHub catalogs are an enterprise feature. When sync detects a private GitHub repository, it asks for confirmation before use and records the decision in your user settings. Review the Outfitter Enterprise license or your enterprise agreement before enabling private catalogs. Non-GitHub `uri:` sources use whatever git credentials your environment already has; credentials embedded in URIs are redacted from sync output.
 
+### How sync authenticates
+
+Outfitter does not collect, store, or validate credentials. It delegates to `git`, so a private catalog clones with whatever credentials the surrounding environment already gives `git` — which differs by where sync runs:
+
+| Where          | Credential                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your machine   | Your existing git configuration: SSH agent, credential helper, or `.netrc`.                                                                       |
+| GitHub Actions | The workflow token, configured for git — see [token-permissions.md](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md). |
+| A cluster pod  | Supplied by the deployment: `GIT_ASKPASS` over HTTPS, or `GIT_SSH_COMMAND` for a deploy key.                                                      |
+
+Two failure modes are worth knowing before you hit them:
+
+- **Credentials belong in the environment, not the URI.** Outfitter redacts credentials from a source URI before deriving its cache path, so a URI carrying a username produces a cache entry that later runs do not read. The source URI must be byte-identical everywhere it appears.
+- **`outfitter run` does not sync.** A runtime that has never synced has an empty cache and cannot resolve a profile from it, however good its credentials are.
+
+[The forge credential model](../architecture/forge-credential-model.md) covers which credential to use where, and why.
+
 ## Trust and review
 
 Adding a catalog source means trusting its authors with your agent runtime. A catalog's resources can shape prompts and policy (agents, `agents.md`, `system-prompt.md`), add MCP servers (`mcp.json`), and ship skills whose scripts execute on your machine.
@@ -129,6 +186,8 @@ Before adding a source, review it:
 2. Read every skill you will select, including its scripts and catalog-owned `file` references (see the [trust boundary](./skills.md#trust-boundary)).
 3. Review `mcp.json` — MCP servers are code with whatever access you grant them.
 4. Check `remote_settings` targets: a settings file can add further sources you did not review.
-5. Confirm the repository's ownership and that its maintainers are who you expect.
+5. Check the catalog's own `sources`: its pinned `github:` dependencies are fetched transitively, so
+   review each one like the catalog itself.
+6. Confirm the repository's ownership and that its maintainers are who you expect.
 
 **Pin a `ref:`** — ideally a full commit SHA — for any catalog you do not maintain yourself, and always for catalogs consumed in CI (see [Running tasks in GitHub Actions](./actions.md)). A pinned ref makes updates an explicit, reviewable action — bump the ref after reviewing the diff — instead of silently pulling whatever the catalog publishes next.

package/docs/documentation/cli.md

@@ -14,13 +14,14 @@ Resolve, compose, and launch an agent. `run` is the default command, so plain `o
 | Argument / Option     | Description                                                                      |
 | --------------------- | -------------------------------------------------------------------------------- |
 | `[agent]`             | Agent slug to run. Defaults to the settings `default_agent`.                     |
-| `--harness <harness>` | Harness to launch in: `pi` or `claude`. Defaults to `default_harness`.           |
+| `--harness <harness>` | Harness to launch in: `pi`, `claude`, or `codex`. Defaults to `default_harness`. |
 | `--strict`            | Fail instead of warning when the adapter cannot project part of the composition. |
 
 Any other arguments and unrecognized options are passed through to the launched harness:
 
 ```bash
 outfitter run engineer --harness claude
+outfitter run engineer --harness codex -- exec "review this repo"
 outfitter run persona-reviewer -- --print "summarize this repo"
 ```
 

package/docs/documentation/concepts.md

@@ -12,7 +12,7 @@ flowchart LR
   adapter --> harness[Harness]
 ```
 
-Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi or Claude Code).
+Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi, Claude Code, or Codex CLI).
 
 ## The `.agents` protocol
 
@@ -80,7 +80,7 @@ Listing, validation, running, and dumping all share one resolver. What `outfitte
 
 ## Adapters
 
-An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; a Claude Code adapter is supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
+An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; Claude Code and Codex CLI adapters are supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
 
 ## State persistence
 

package/docs/documentation/hooks.md

@@ -15,6 +15,39 @@ See the [Claude Code hooks documentation](https://code.claude.com/docs/en/hooks)
 
 Pi supports a bootstrap hook via its extension mechanism: an extension passed with `--extension` runs at session start and can register tools, providers, and runtime behavior. Outfitter's own onboarding flow uses this channel. For recurring per-event behavior, Pi extensions are the native surface.
 
+## System extension hooks
+
+An organization can make a local Pi observer load by default on every `outfitter run` by installing a system extension hook. Outfitter reads hook documents in lexical filename order from:
+
+1. `$OUTFITTER_SYSTEM_DIR/*.yml` when the variable is set (the test/development seam), or
+2. `/etc/outfitter/system.d/*.yml` on Linux, or
+3. `/Library/Application Support/Outfitter/system.d/*.yml` on macOS.
+
+Each file contributes extensions and environment additively; files do not override each other. Reusing the same environment key for the same harness in two files is an error rather than an implicit precedence rule. An absent directory is a no-op. An unreadable or malformed document, including one naming an extension path that does not exist, aborts the run whether or not `--strict` is set.
+
+```yaml
+name: pensieve
+harnesses:
+  pi:
+    extensions:
+      - /nix/store/example-pensieve/lib/pensieve/collectors/pi
+    env:
+      PENSIEVE_SINK: https://pensieve.example.com
+      PENSIEVE_INSTALL_SCOPE: launcher
+```
+
+Extension entries must be absolute paths that already exist. Outfitter resolves source-directory, hook-document, and extension symlinks to physical paths before loading them; a dangling link is fatal, and `OUTFITTER_SYSTEM_HOOK_SOURCE` records the physical source directory. Package and Git specifiers are rejected, so a launch never installs a system extension from the network. Only `name` and `harnesses` are accepted at the document root, and each harness entry can contain only `extensions` and `env`; a system hook cannot select an agent, harness, model, tool, skill, or prompt.
+
+For Pi, Outfitter prepends the configured `--extension <path>` arguments after projection on every launch, including `--mode rpc`, print, and other non-interactive launches. Hook documents cannot name the Outfitter-controlled `PI_CODING_AGENT_DIR` or `PI_CODING_AGENT_SESSION_DIR` variables. They also reject `NODE_OPTIONS`, `NODE_REPL_EXTERNAL_MODULE`, `OPENSSL_CONF`, `LD_PRELOAD`, `LD_AUDIT`, `LD_LIBRARY_PATH`, and every `DYLD_*` variable because those can change process loading before Pi starts. Other hook environment is below the launch plan's own environment but above the parent process environment at spawn. `harnesses.claude` and `harnesses.codex` documents validate but are ignored with a warning; Outfitter has no equivalent extension argument for those adapters. Their native managed configuration is the stronger policy surface.
+
+### Launcher scope, not managed scope
+
+This mechanism changes who owns the file that names an extension. It does not change Pi's configuration resolution because Pi never reads the system hook document. The accurate guarantee is **collection is on by default and the organization owns the configuration**, not that the session cannot turn collection off.
+
+The `--no-extensions` option does not disable explicitly passed `--extension` paths, so it does not bypass a system hook. A session can still execute Outfitter's bundled Pi binary directly, never going through the Outfitter launcher, or set `OUTFITTER_SYSTEM_DIR` to an empty directory. Every launch whose platform resolves a hook directory records that choice in `OUTFITTER_SYSTEM_HOOK_SOURCE`: the normal value is the resolved physical system path, while an override is stamped as `env-override:<resolved-physical-path>`. Downstream evidence can therefore distinguish the normal system source from the session-settable bypass.
+
+The normal Linux and macOS directories are root-owned. Outfitter deliberately fails closed on their operator errors: a malformed file should fail on a canary boot, while failing open could silently produce fleet sessions without collection. Those sessions must be treated as unattested rather than clean.
+
 ## Roadmap
 
 > **TODO (protocol gap):** hooks are the one behavioral surface the pinned protocol revision does not model, which means hook definitions cannot yet be expressed portably in a `.agents` tree and projected per harness. The path `agents/<agent-id>/hooks/<hook-id>/` is reserved for a future agent-local hook entity and deliberately has no resolution or projection behavior today. Outfitter may need to ship its own hooks extension that adapters translate to Claude `settings.json` hooks and Pi extensions respectively, or drive the concept into a future protocol revision. Until one of those lands, treat hooks as harness-native configuration and keep them thin: call scripts that live in the tree rather than embedding logic in hook definitions.

package/docs/documentation/in-cluster.md

@@ -11,6 +11,8 @@ The Link Operator runs Outfitter-composed agents inside a Kubernetes cluster. Th
 
 The operator never interprets a profile, reads a secret's contents, or invokes the model — it provisions and starts; the agent layer does the rest.
 
+Because the operator does not look inside a Secret, the credentials a resident agent carries are the deployment's decision. A resident agent needs two forge tokens rather than one: the notification wake path accepts only a classic token, while its repository work should carry the narrowest credential available. [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) is the procedure; [the forge credential model](../architecture/forge-credential-model.md) is the reasoning.
+
 ## Execution shapes
 
 | Shape                  | Kubernetes resource | Trigger                                                                                         |

package/docs/documentation/migration.md

@@ -21,7 +21,7 @@ This page is the manual migration reference, and the bundled Outfitter skill can
 | `<project>/.outfitter/local/settings.yml` (nested dir)  | `<project>/.agents/settings.local.yml` (flat, gitignored)                                                                                                                                        |
 | `profile_sources`                                       | `sources` supplying `.agents` payloads ([catalogs](./catalogs.md))                                                                                                                               |
 | `default_profile`                                       | `default_agent` naming an agent slug                                                                                                                                                             |
-| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude`)                                                                                                                      |
+| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude\|codex`)                                                                                                               |
 | `outfitter profile list` / `create` / `lint`            | `outfitter list agents` / author files directly / `outfitter validate`                                                                                                                           |
 | `profile_export` / `generated-system-prompt.md`         | `outfitter dump` ([Dump and bake](./dump-and-bake.md))                                                                                                                                           |
 | Free-form CI prompt + profile in `ai-outfitter/actions` | An agent run with structured inputs ([Actions](./actions.md)); the task/bake surface is a [future RFC](./tasks.md)                                                                               |

package/docs/documentation/personas.md

@@ -32,7 +32,7 @@ Neither tier is a resource Outfitter resolves; both are ordinary directories of
 
 ## Three ways to consume the same file
 
-- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different flags, so a hand-written passthrough only works on the harness it was written for, and fails silently on the other. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both.
+- **Appended at launch**: `outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md -- …` — the direct run is the underlying interface, and the reviewer adopts the file as its identity for that session only. Pass `--append-prompt` rather than spelling the harness flag yourself after `--`: pi and Claude Code take append-prompt documents through different native flags. Codex has no native append flag yet, so its adapter warns that the document is dropped. An agent using the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill can drive the same run in the background or synchronously and capture its report in a durable file. See [Persona reviews](./usecases/persona-reviews.md) for the runnable form of both supported identity projections.
 - **Pasted into a web agent**: upload or paste the file unchanged into claude.ai project knowledge or a ChatGPT project as stakeholder context. Same artifact, zero conversion.
 - **Ordinary reading context**: any agent doing product planning, research, or writing can read the file to know who the work is for.
 

package/docs/documentation/settings.md

@@ -22,7 +22,7 @@ In a standalone `.agents` repository the repository root is the tree, so the fil
 ```yaml
 # .agents/settings.yml
 default_agent: engineer # which agent runs by default
-default_harness: pi # which harness to launch: pi or claude
+default_harness: pi # which harness to launch: pi, claude, or codex
 
 # Where protocol resources come from, beyond this tree and ~/.agents.
 sources:

package/docs/documentation/state.md

@@ -190,6 +190,33 @@ The last form is how a resident or in-cluster agent keeps continuity across rest
 
 ## Claude Code state paths
 
+Claude credentials need a narrow adapter bridge in addition to the path-keyed state below. Claude
+reads `.credentials.json` and `.claude.json` directly from `CLAUDE_CONFIG_DIR`; the ephemeral
+projection gives `.credentials.json` no durable home, and `.claude.json`'s native location
+(`~/.claude.json`, outside `~/.claude`) does not share its config-dir-relative path. Outfitter
+seeds `.credentials.json` before launch. It seeds `oauthAccount` and `hasCompletedOnboarding` when
+those keys exist in durable state. It also seeds the current working directory's accepted-trust bit
+only when that exact trust decision already exists in durable state. Afterward it copies back the
+whole `.credentials.json` when changed and atomically merges `oauthAccount`. If the durable
+credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns
+instead of copying the projected credentials back. Claude MCP OAuth tokens
+live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so server
+authorizations acquired in an Outfitter-launched Claude session persist across runs through that
+whole-file copy-back. Outfitter never copies the full machine-local `~/.claude.json` into a
+projection or merges its other projected state back. Trust accepted inside an Outfitter session is
+therefore discarded, so Claude prompts for trust on every run in a workspace that was never trusted
+natively.
+
+Claude session history has a second narrow bridge because `CLAUDE_CONFIG_DIR` also redirects
+Claude's native `projects/` tree into the temporary projection. Before launch, Outfitter derives
+Claude's project slug from the absolute working directory and copies only that slug directory from
+`~/.claude/projects/`. This keeps other projects' transcripts out of the projection while making
+`claude --continue` and `claude --resume` see earlier native or Outfitter-launched sessions. After
+the run exits or throws, Outfitter merges every new or content-changed regular session file from
+the projection's slug directories back into `~/.claude/projects/` atomically with mode `0600`.
+Durable files are never deleted. A seed or copy-back failure emits a warning and does not replace
+Claude's exit code or error.
+
 The Claude Code adapter declares these paths:
 
 ```yaml

package/docs/documentation/support-matrix.md

@@ -1,6 +1,6 @@
 # Adapter support matrix
 
-What Outfitter can project per agent CLI. Pi is the primary and most complete adapter; Claude Code is supported with gaps.
+What Outfitter can project per agent CLI. Pi is the primary and most complete adapter; Claude Code and Codex CLI are supported with gaps.
 
 Status values:
 
@@ -12,31 +12,42 @@ 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 |
-| ------------------------------------------------------------------------ | --------- | ----------- |
-| Agent config directory                                                   | Supported | Supported   |
-| Session directory                                                        | Supported | Supported   |
-| Agent identity (`system-prompt.md`, `agents.md`, `agents/<id>/agent.md`) | Supported | Supported   |
-| Subagents (`agents/<id>` as harness delegates)                           | Supported | Supported   |
-| Skills (`skills/<id>`)                                                   | Supported | Partial     |
-| Commands (`commands/`)                                                   | Supported | Partial     |
-| Knowledge (`knowledge/`)                                                 | Supported | Partial     |
-| Model selection (`models.json`)                                          | Supported | Partial     |
-| MCP servers (`mcp.json`)                                                 | Supported | Supported   |
-| Extensions (agent `extensions:` loadout)                                 | Supported | Roadmap     |
-| Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     |
-| Credentials and environment                                              | Supported | Supported   |
-| DeepWork job selection                                                   | Supported | Roadmap     |
-| Hooks                                                                    | Partial   | Partial     |
-| Tool availability (agent `tools:` loadout)                               | Supported | Supported   |
-| Theme / UI presentation                                                  | Roadmap   | Roadmap     |
-| Working directory                                                        | Roadmap   | Roadmap     |
-| Pass-through arguments                                                   | Supported | Supported   |
-| Bootstrap hook                                                           | Supported | 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 | Partial     | Partial   |
+| MCP servers (`mcp.json`)                                                 | Supported | Supported   | Partial   |
+| Extensions (agent `extensions:` loadout)                                 | Supported | Roadmap     | Roadmap   |
+| 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   |
+
+## 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, extensions, plugins, and prompt templates remain unsupported and warn when selected.
+- **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.
+- **HTTP header safety** — `${ENV_NAME}` becomes an `env_http_headers` reference, while `Authorization: Bearer ${ENV_NAME}` becomes `bearer_token_env_var`. Other header values pass through `http_headers` and are visible in process arguments. Outfitter warns for every literal stdio environment or HTTP header entry exposed in argv, so use environment references for secrets.
 
 ## Claude Code notes
 
-- **Config and session state** — Outfitter points `CLAUDE_CONFIG_DIR` at the baked composition, declares Claude state paths (`settings.json`, `agents/`, `skills/`, `commands/`, `plugins/`, `projects/`) for [state persistence](./state.md), and can [symlink a ported `~/.claude`](./porting-claude.md) so native use keeps working.
+- **Config and session state** — Outfitter points `CLAUDE_CONFIG_DIR` at the baked composition. Before launch it copies only the current working directory's history from `~/.claude/projects/<project-slug>/` into the projection, so native `--continue` and `--resume` work without exposing other projects. After every successful or failed launch it atomically merges new or changed session files from every projected slug back into `~/.claude/projects/` with mode `0600`, never deleting durable history. Session bridge failures warn without masking the Claude exit. Outfitter also declares Claude state paths (`settings.json`, `agents/`, `skills/`, `commands/`, `plugins/`, `projects/`) for [state persistence](./state.md), and can [symlink a ported `~/.claude`](./porting-claude.md) so native use keeps working. MCP configuration from that port is no longer auto-discovered by Outfitter-launched Claude runs; those servers apply only when an agent selects them by slug. See the next bullet.
+- **Credentials, onboarding, and workspace trust** — before launch, Outfitter copies `~/.claude/.credentials.json` to the temporary root as `.credentials.json` with mode `0600`. The projected `.claude.json` contains `oauthAccount` and `hasCompletedOnboarding` when those keys are present in durable `~/.claude.json`. It also contains `projects[<cwd>].hasTrustDialogAccepted: true` only when that exact accepted trust decision already exists there; other projects and unrelated machine state are not copied. After any successful or failed launch, a `.credentials.json` changed by the run is copied back wholesale and `oauthAccount` is atomically merged into durable `.claude.json` without replacing unrelated keys. If the durable credentials also changed after seeding, Outfitter preserves that concurrent refresh and warns instead of copying back. MCP OAuth tokens live under `mcpOAuth` in `.credentials.json`, keyed by `<serverName>|<hash>`, so authorizations acquired in an Outfitter-launched Claude session persist across runs. Other projected `.claude.json` state, including trust accepted during the session, is discarded; a workspace that has never been trusted by native Claude therefore prompts again on every run.
+- **MCP servers** — every Claude launch passes the generated `mcp.json` through `--mcp-config` with `--strict-mcp-config`. MCP servers from user or project configuration, `.claude.json`, and plugins are therefore excluded; only servers selected by the composition are active.
 - **Subagents** — selected `agents/<id>` definitions are materialized into Claude's native agents directory.
 - **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.

package/docs/documentation/usecases/org-onboarding-sdlc-report.md

@@ -0,0 +1,143 @@
+# Onboard an organization with an SDLC report
+
+A runbook for the first engineer who brings agentic engineering to their
+organization. The output is two artifacts: a baseline **SDLC report** that
+says where the org sits on the [adoption ramp](../../philosophy.md), and the
+org's **`.agents` repository** with that report as its first commit. The
+report's gaps become the backlog; the repository becomes the place the org's
+agent configuration lives from day one.
+
+Who runs this: an engineer with read access to the org's repositories. No
+org-wide rollout, approval, or infrastructure is required, and no agent
+session either — the scan is one command. The whole runbook is one person,
+one sitting, read-only until you create the repository.
+
+## 1. Prerequisites
+
+- `npx` (node 20.19+) or Docker.
+- An authenticated `gh` CLI with read access to the org.
+- Optional but valuable: your existing local checkouts of org repositories.
+  The scanner reads them in addition to the forge API — local working trees
+  show practice the forge cannot see, such as `.agents/` trees in progress
+  and instruction files that were never committed.
+
+## 2. Run the assessment
+
+[`@ai-outfitter/link`](https://github.com/ai-outfitter/link) audits the org
+against the catalog's governance baseline. Write the report straight into
+the dated directory it will be committed from:
+
+```sh
+npx @ai-outfitter/link@1 report <org> \
+  --out ~/repos/<org>/.agents/reports/sdlc/$(date +%F)-initial
+```
+
+Or with Docker, if you would rather not install anything:
+
+```sh
+docker run --rm -e GH_TOKEN="$(gh auth token)" -v "$PWD:/work" \
+  ghcr.io/ai-outfitter/link:1 report <org>
+```
+
+Add your local checkouts as sources to widen the evidence — a single repo, an
+owner folder of clones, or a whole `~/repos/` root:
+
+```sh
+npx @ai-outfitter/link@1 report <org> ~/repos/<org>
+```
+
+The scan is read-only: it lists repositories, reads git trees, and reads
+effective branch rules. It never clones and never writes to the forge. It
+samples at most the 30 most recently pushed repositories, and takes seconds
+rather than minutes.
+
+Naming a target scopes the report to it, so the file you are about to commit
+into `<org>`'s repository describes `<org>` and nothing else.
+
+You get one file, `report.json`, plus a copy in
+`$XDG_DATA_HOME/outfitter-link/`. It contains, for each repository, a
+maturity-ramp placement (level 0–5), the tree-derived signals behind it
+(instruction files, `.agents/` trees, agent workflows, deploy manifests), and
+a per-rule audit against the governance baseline. At org level it carries the
+milestones that gate each rung, the `gaps` blocking the next one, and
+`evidence_limits` — what the scan could not see, which bounds every claim in
+it.
+
+Read the `gaps` before moving on. They name what blocks the next rung, not
+the top of the ramp.
+
+To see the report rendered, with the workflow definitions beside it, clone
+the repository and run `link web`.
+
+### What the scan does not measure
+
+The scanner decides everything from file trees and branch rules, so it is
+fast, free, and reproducible — two runs of the same org agree apart from the
+`generated_at` and `scanned_at` timestamps, which is what makes report diffs
+a progress measure. The cost is that it reads no pull request history and
+makes no judgments: no cycle time, no rework rate, no inventory of which
+harnesses and model vendors are actually in use, and no duplication analysis
+across teams.
+
+When you want those, run the `sdlc-report` skill on a local coding harness as
+a second, deeper pass. It answers the same question with an agent's judgment
+instead of a checker's rules, and it emits recommendations. Start with
+`link` — it is the cheap, repeatable baseline, and it is the one you will
+re-run.
+
+## 3. Create the org `.agents` repository
+
+Create `<org>/.agents` on your forge and commit the report as its first
+content. Repository hygiene, learned the hard way:
+
+- The repository MUST NOT be public — private or internal visibility only.
+  The report is an honest map of your org's gaps. (This organization
+  publishes its own report deliberately, as a worked example. That is a
+  choice about a reference; it is not the default.)
+- If the repository already exists, commit only the report files. Leave any
+  uncommitted work in the checkout untouched, and if the default branch is
+  behind or checked out elsewhere, say so rather than silently moving it.
+
+```text
+<org>/.agents/
+  README.md                      # what this repo is; link to the report
+  reports/
+    sdlc/
+      YYYY-MM-DD-initial/
+        report.json
+```
+
+The initial report is the baseline: re-run the scan after each change (a
+quarterly cadence works, or after each rung climb) into a new dated
+directory, and the diff between reports is your progress measure — milestones
+met and rung movements, not anecdotes.
+
+This repository is also where the org's shared agent configuration grows: an
+`agents.md` with shared operating rules, role agents, skills, and a pinned
+`settings.yml`, following the [organization catalog](./organization-profile-catalog.md)
+conventions. Starting it with the report means the catalog's first commit
+explains _why_ the org is adopting agents and what it will measure — every
+later addition traces back to a gap in the baseline.
+
+## 4. Act on the report
+
+1. Take the first entry in `gaps` and automate that one workflow end to end —
+   for example, feature idea → reviewed PR ([Actions](../actions.md),
+   [in-cluster](../in-cluster.md)).
+2. Add the shared resources the org lacks, so the next team composes instead
+   of rebuilding. A repo whose `signals.catalog` is false is a candidate.
+3. Wire session-log capture into the automated workflow before merge. The
+   `session-capture` milestone is unmet in almost every first report, and it
+   stays unmeasurable until workflows upload session artifacts behind a
+   required check. Owning that record is what makes the next report richer,
+   and it is the raw material for evals and improvement
+   ([philosophy](../../philosophy.md)).
+4. Schedule the re-run ([recurring runs](../recurring-runs.md)) and commit
+   each new report beside the baseline.
+
+## Boundaries
+
+The scan is read-only; creating the `.agents` repository in step 3 is the
+runbook's first write, done by you deliberately. The report contains repo
+names, paths, and counts, never credentials or session content. Treat it as
+internal: it is an honest map of your org's gaps.

package/docs/documentation/usecases/persona-reviews.md

@@ -91,7 +91,7 @@ outfitter run persona-reviewer --append-prompt docs/personas/platform-lead.md --
   > docs/persona-reviews/platform-lead-onboarding.md
 ```
 
-This is the portable interface: it works from the project containing the persona, does not assume a particular catalog checkout path, and does not assume a harness — `--append-prompt` projects the document through whichever flag pi or Claude Code actually reads. Repeat it to compose an identity from several documents; see [When one file is not enough](../personas.md#when-one-file-is-not-enough). One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
+This is the portable interface for pi and Claude Code: it works from the project containing the persona, does not assume a particular catalog checkout path, and projects `--append-prompt` through the native flag each harness reads. The Codex adapter has no native append flag and warns that the document is dropped. Repeat the option to compose an identity from several documents; see [When one file is not enough](../personas.md#when-one-file-is-not-enough). One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
 
 ### Optional orchestration with the skill
 

package/docs/philosophy.md

@@ -2,6 +2,14 @@
 
 Make, share, and switch the agent profiles your coding agents use — manually or programmatically. A profile is just an agent and the loadout it composes; there is no separate profile format.
 
+## Trust through evidence
+
+An agent is trusted the same way a new teammate is: small scopes, reviewed work, and a paper trail. Outfitter treats all three as configuration. A profile bounds what an agent can do per environment — the planning agent that has write tools at your desk has none in the cluster. Adversarial review is a workflow step rather than a virtue, and workflows are built so that every transition writes to the record.
+
+## Own your session data
+
+The session record — what was asked, what the agent did, what it touched, what the review found — serves you as much as it serves the auditor. It answers "what happened and was it allowed" for an audit, and the same records are the inputs to evals, policy tuning, and eventually training. Organizations that let session data evaporate at the end of each run discard the asset that makes the whole system improvable. Store clean records first and decide on dashboards later — dashboards can always be built over clean records; records cannot be reconstructed from dashboards.
+
 ## Expeditious agents
 
 An agent is defined by its agency: its ability to make good decisions on the way to completing a task. Outfitter exists to make agents _expeditious_ — not just effective, but fast.
@@ -23,3 +31,15 @@ The same mechanism scales up a stair-step:
 - **Enterprises** publish and pin curated catalogs, keeping agent configuration reviewable, versioned, and consistent across the organization.
 
 At every level the goal is the same: the right profile, at the right moment, with nothing extra along for the ride.
+
+## The ramp to an autonomous lifecycle
+
+Outfitter's destination is a fully autonomous software development lifecycle: humans define goals and acceptance gates, agents own the middle. Nobody jumps there in one step. Adoption is a ramp with five rungs, and each Outfitter component targets a rung, so a user or an organization climbs without discarding the previous rung. This section is the canonical definition; the org README and the `sdlc-report` assessment skill compress or extend it.
+
+1. **Assisted** — autocomplete and chat; a human's hands stay on the keyboard.
+2. **Delegated** — a local agent does the task; the human defines the idea and reviews the PR.
+3. **Automated** — a workflow runs without a laptop: an issue, a message, or a schedule triggers agents in CI or a cluster, and adversarial review is part of the pipeline.
+4. **Governed** — the organization shares one pinned catalog of agents, skills, and policy; every agent action lands in an auditable record; resident agents work as onboarded teammates.
+5. **Self-improving** — the audit record feeds evals and model improvement; humans set goals and acceptance gates, agents own the middle.
+
+Two rules keep the climb honest. Never automate a workflow you have not first done manually — run it as an agent-assisted skill until you understand it, then promote it. And expand scope by moving the human locus of control outward one layer at a time: first the implementation, then the review, then the idea, until what remains human is the goal and the gate.

package/package.json

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

@@ -5,7 +5,7 @@
   "type": "object",
   "properties": {
     "default_agent": { "type": "string", "minLength": 1 },
-    "default_harness": { "enum": ["pi", "claude"] },
+    "default_harness": { "enum": ["pi", "claude", "codex"] },
     "cache_directory": { "type": "string", "minLength": 1 },
     "state_persistence": {
       "type": "object",

package/src/schemas/system-extension-hook.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://outfitter.dev/schemas/system-extension-hook.schema.json",
+  "title": "Outfitter system extension hook",
+  "type": "object",
+  "required": ["name", "harnesses"],
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "harnesses": {
+      "type": "object",
+      "minProperties": 1,
+      "properties": {
+        "pi": { "$ref": "#/$defs/harnessHook" },
+        "claude": { "$ref": "#/$defs/harnessHook" },
+        "codex": { "$ref": "#/$defs/harnessHook" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "harnessHook": {
+      "type": "object",
+      "properties": {
+        "extensions": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^/" }
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+          "additionalProperties": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}