@ai-outfitter/outfitter 1.14.0 → 1.16.0

package/dist/version/NodeVersionGuard.js

@@ -0,0 +1,50 @@
+// Refuses to run on a Node release below the published `engines.node` floor.
+//
+// npm treats an engines mismatch as a warning, so `npm install -g` and `npx` succeed on
+// old Node. Outfitter's own commands then work, and the process only crashes deep inside
+// the bundled pi once `run` or `setup` spawns it (issue #368). This guard turns that stack
+// trace into a one-line message before any command, including the telemetry notice, runs.
+import { readFileSync } from 'node:fs';
+// Always yields three parts so comparisons never index past the end.
+const parseVersion = (version) => {
+    const [major = 0, minor = 0, patch = 0] = version
+        .replace(/^v/u, '')
+        .split('.')
+        .map((part) => Number.parseInt(part, 10) || 0);
+    return [major, minor, patch];
+};
+// `engines.node` is required by OFTR-001.1 to be an unbounded `>=x.y.z` range, so only
+// that shape is supported. Anything else is treated as satisfied rather than blocking.
+const parseMinimum = (range) => {
+    const match = /^>=\s*v?(\d+\.\d+\.\d+)$/u.exec(range.trim());
+    return match === null ? undefined : parseVersion(match[1]);
+};
+export const readRequiredNodeRange = () => {
+    const packageJsonPath = new URL('../../package.json', import.meta.url);
+    const manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return manifest.engines.node;
+};
+export const checkNodeVersion = (current, required) => {
+    const minimum = parseMinimum(required);
+    if (minimum === undefined)
+        return { required, current, satisfied: true };
+    const actual = parseVersion(current);
+    const first = minimum.findIndex((part, index) => part !== actual[index]);
+    const satisfied = first === -1 || actual[first] > minimum[first];
+    return { required, current, satisfied };
+};
+export const formatNodeVersionError = (check) => [
+    `Outfitter requires Node ${check.required} but found v${check.current}.`,
+    'Upgrade Node (for example with `nvm install --lts`) and run the command again.',
+].join('\n');
+/**
+ * Prints the upgrade message and returns false when the running Node is below the
+ * published floor. Callers must not import or spawn pi before this returns true.
+ */
+export const enforceNodeVersion = (current = process.versions.node, required = readRequiredNodeRange(), writeError = console.error) => {
+    const check = checkNodeVersion(current, required);
+    if (!check.satisfied)
+        writeError(formatNodeVersionError(check));
+    return check.satisfied;
+};
+//# sourceMappingURL=NodeVersionGuard.js.map

package/dist/version/NodeVersionGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeVersionGuard.js","sourceRoot":"","sources":["../../src/version/NodeVersionGuard.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,wFAAwF;AACxF,yFAAyF;AACzF,2FAA2F;AAC3F,0FAA0F;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAQvC,qEAAqE;AACrE,MAAM,YAAY,GAAG,CAAC,OAAe,EAAqC,EAAE;IAC1E,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,OAAO;SAC9C,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;SAClB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF,uFAAuF;AACvF,uFAAuF;AACvF,MAAM,YAAY,GAAG,CAAC,KAAa,EAAiD,EAAE;IACpF,MAAM,KAAK,GAAG,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAW,EAAE;IAChD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAEhE,CAAC;IACF,OAAO,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;AAC/B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,OAAe,EAAE,QAAgB,EAAoB,EAAE;IACtF,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAEzE,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,MAAM,SAAS,GAAG,KAAK,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAC1C,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,KAAuB,EAAU,EAAE,CACxE;IACE,2BAA2B,KAAK,CAAC,QAAQ,eAAe,KAAK,CAAC,OAAO,GAAG;IACxE,gFAAgF;CACjF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEf;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,UAAkB,OAAO,CAAC,QAAQ,CAAC,IAAI,EACvC,WAAmB,qBAAqB,EAAE,EAC1C,aAAwC,OAAO,CAAC,KAAK,EAC5C,EAAE;IACX,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,UAAU,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,SAAS,CAAC;AACzB,CAAC,CAAC"}

package/docs/architecture/state_writeback_strategy.md

@@ -68,7 +68,7 @@ Outfitter defaults
 
 Native CLI state is not a configuration layer. For `symlink` paths, the selected adapter resolves a native fallback location directly, such as `~/.pi/agent/...` for most Pi state paths, `~/.claude/...` for most Claude Code state paths, or `<cache_directory>/utilities` for Pi `utilities/` and `bin/`. The native fallback does not participate in resource resolution or merge precedence and cannot contribute resources. Claude Code `projects/` is additionally controlled by the session-directory setting when set.
 
-For a [ported Claude Code setup](../documentation/porting-claude.md), configuration entries under `~/.claude` are symlinks into `~/.agents/`, so a durable write through the projection's `skills/` link lands in the protocol tree. The porting arrangement is created by setup; the state machinery just follows the links.
+For a [linked Claude Code home](../documentation/linking-harnesses.md), managed configuration entries under `~/.claude` are symlinks into `~/.agents/`, so a durable write through the projection's `skills/` link lands in the protocol tree. The links are created by `outfitter link`, not setup; the state machinery just follows them.
 
 ## Path-keyed adapter declarations
 

package/docs/documentation/README.md

@@ -23,7 +23,7 @@ One runbook per rung of [the adoption ramp](../philosophy.md#the-ramp-to-an-auto
 - [Getting started](./getting-started.md) — install, first run, default agent.
 - [First-time CLI agent users](./first-time-cli-agent-users.md) — new to agent CLIs entirely.
 - [Switching to Outfitter](./switching-to-outfitter.md) — adopt from an existing agent-CLI setup.
-- [Porting a Claude Code setup](./porting-claude.md) — `~/.claude` into `~/.agents/` with symlinks back.
+- [Linking into Claude Code and Codex](./linking-harnesses.md) — `outfitter link` places managed links to the tree in `~/.claude` and `~/.codex`.
 
 ## Understand (the model)
 

package/docs/documentation/catalogs.md

@@ -89,7 +89,42 @@ Resources from all sources resolve by slug behind local layers, following [layer
 
 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.
+A workflow can publish output declarations. Output names must start with a lowercase letter and
+otherwise follow the workflow node ID pattern. An output's `type` is an optional plain label: an
+action node declares it directly, while a nested-workflow node maps one of the nested workflow's
+declared outputs and inherits its label:
+
+```yaml
+outputs:
+  pull-request:
+    from: draft # an action node in this workflow
+    type: pull-request
+  review-verdict:
+    from: review # a nested-workflow node in this workflow
+    output: verdict # declared by the nested workflow
+```
+
+The conventional labels for forge objects are `pull-request`, `git-commit`, `git-branch`, and
+`issue`, so workflows use consistent names for the same kinds of objects. An organization may use
+any slug as an output type label. A mapped output inherits the nested output's resolved label,
+including through multiple nesting levels.
+
+A node's `needs` list expresses ordering only among nodes in the same workflow. Cross-task
+prerequisites are an execution engine's responsibility: the engine evaluates them against declared
+outputs rather than treating a workflow node edge as a task dependency.
+
+`outfitter validate --strict` validates the graph, output mappings, and complete composed dependency
+closure. `outfitter dump --workflow <slug>` produces a reviewable `.agents` bundle for distribution.
+Outfitter never schedules or executes the graph. See
+[OFTR-013: Workflow Contract](../requirements/OFTR-013-workflow-contract.md) for the normative
+contract.
+
+#### Recording values
+
+Outfitter declares outputs but does not record or validate their concrete values; that belongs to the
+execution engine. A runtime carrying a value over A2A should use `outfitter-task/v1` artifact metadata
+with `output` set to the declared name, `type` set to its resolved label, and `value` set to the
+concrete value.
 
 ### Catalog dependencies (transitive sources)
 

package/docs/documentation/cli.md

@@ -42,13 +42,14 @@ outfitter --resume      # equivalent to: outfitter run -- --resume
 
 ## `outfitter setup [source]`
 
-Open the bundled Pi walkthrough using the original setup wording and sequence. Choose **Use the
-default Outfitter profile catalog**, **Create your own profile**, or **Provide a different catalog
-to import**; complete that branch; choose a home/project settings target; then choose the default
-CLI agent. Pi/Outfitter is preselected. Passing `[source]` retains the original direct-source path
+Open the bundled Pi walkthrough. Choose a featured profile from the default catalog (Engineer,
+Founder, or Software Factory; Engineer is preselected), open **More profiles** for the rest, or
+**Import a different .agents catalog**; complete that branch; choose a home/project
+settings target; then choose the default CLI agent. Pi/Outfitter is preselected. To use a custom
+profile instead, write `.agents/agents/<id>/agent.md` and set `default_agent`. Passing `[source]` retains the original direct-source path
 and starts at target selection. Pi hosts the deterministic setup UI without a model provider and
 does not port or symlink harness configuration. The default picker always comes from
-`ai-outfitter/default-profiles` at the immutable Release Please version tag pinned by the installed
+`ai-outfitter/community-profiles` at the immutable Release Please version tag pinned by the installed
 Outfitter version; setup fetches or reuses that release through the normal source cache and writes
 the same GitHub/ref pair to settings. It never reads a sibling checkout or a packaged catalog
 fallback.
@@ -75,7 +76,7 @@ List resolvable resources across all layers, with the winning source for each sl
 | -------- | -------------------------------------------------------------------------- |
 | `[kind]` | Optional filter: `agents`, `skills`, `knowledge`, `commands`, `workflows`. |
 
-`--json` emits an object containing `ok`, `resources`, and `diagnostics`; diagnostics remain available when strict mode fails.
+`--json` emits an object containing `ok`, `resources`, and `diagnostics`; diagnostics remain available when strict mode fails. Each workflow resource entry also contains a name-sorted `outputs` object with resolved output labels, or `{}` when the workflow declares none. Non-JSON output is unchanged. See [OFTR-013: Workflow Contract](../requirements/OFTR-013-workflow-contract.md).
 
 ## `outfitter validate`
 
@@ -96,13 +97,47 @@ Write the composed resource tree as a self-contained `.agents/` directory for re
 | `--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.
+Workflow dumps are non-executable configuration bundles. They contain the canonical workflow YAML, composed agent resources, and a hash/provenance manifest whose `workflows[]` entries record resolved `outputs`. 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 link`
+
+Project composed resources and native defaults into Pi, Claude Code, and Codex homes, so plain
+`pi`, `claude`, and `codex` sessions carry shared configuration
+without going through `outfitter run`. `run` still uses a temporary projection; `link` is the
+opt-in persistent one. See [Linking into Claude Code and Codex](./linking-harnesses.md).
+
+| Option             | Description                                                                                                                       |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>` | Harness home to link into: `pi`, `claude`, or `codex` (repeatable). Defaults to every harness on `PATH` or with an existing home. |
+| `--agent <id>`     | Agent whose composed closure to link (repeatable).                                                                                |
+| `--workflow <id>`  | Enabled workflow whose agent closures to link (repeatable).                                                                       |
+| `--all`            | Link every resolvable agent, with its skills and commands.                                                                        |
+| `--dry-run`        | Report what would change (`would create`, `would update`, `would prune`) without touching the home.                               |
+| `--remove`         | Remove every entry this command created and forget it.                                                                            |
+| `--strict`         | Exit non-zero on warnings, conflicts, or skipped entries.                                                                         |
+
+```bash
+outfitter link                                    # enabled workflows + default_agent, every installed harness
+outfitter link --workflow engineer --harness claude
+outfitter link --all --dry-run
+outfitter link --remove
+```
+
+With no selection the scope is every enabled workflow root (`workflows:` in settings) plus
+`default_agent`. Each scoped agent is composed the same way `run` and `dump` compose it, and its
+subagents join the closure. The harness home is `$CLAUDE_CONFIG_DIR` (default `~/.claude`) or
+`$CODEX_HOME` (default `~/.codex`); an explicit `--harness` creates the home if it is missing.
+
+Ownership is recorded in `<harness home>/.outfitter/links.json`. `link` never overwrites, adopts, or
+deletes anything it did not create: an unmanaged file, directory, or symlink in the way is reported
+as a `conflict` and left alone. Re-running is idempotent (`unchanged`), a managed link whose target
+vanished is `pruned`, and MCP servers already registered in the harness are left as they are.
+
 ## `outfitter sources`
 
 Report local and remote source precedence, requested and resolved revisions, origins, and cache

package/docs/documentation/conventions.md

@@ -15,7 +15,7 @@ Each layer inherits the one above it. ID-addressed resources — agents, skills,
 | Layer            | Location                                                                      | Holds                                                                                       |
 | ---------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | Community        | e.g. `ai-outfitter/community-profiles`                                        | Reviewed building blocks — skills and reference agents anyone can mix and match.            |
-| Curated defaults | e.g. `ai-outfitter/default-profiles`                                          | The pinned, curated assembly — starter agents users adopt as-is.                            |
+| Curated defaults | e.g. `ai-outfitter/community-profiles`                                        | The pinned, curated assembly — starter agents users adopt as-is.                            |
 | Organization     | `owner/.outfitter` [control repo](./usecases/organization-profile-catalog.md) | Bespoke org agents, shared `agents.md`, org-specific skills (brand voice, RBAC, endpoints). |
 | User / project   | `~/.agents`, `<repo>/.agents`                                                 | Personal and repo overrides, loadout-added references, same-ID resource overrides.          |
 

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

@@ -25,7 +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`.
+- **Workflow-auditable** — workflow exports preserve canonical YAML and record every nested workflow, its resolved `outputs`, agent composition, file hash, and winning source in `.outfitter/workflow-composition.json`. Each `workflows[]` entry has an `outputs` object (empty when none are declared). The manifest records only outputs that resolve, and `outfitter validate --strict` is the gate that reports declarations which do not. See [OFTR-013: Workflow Contract](../requirements/OFTR-013-workflow-contract.md).
 
 ## Bake
 

package/docs/documentation/getting-started.md

@@ -20,11 +20,13 @@ outfitter run           # launch with your defaults
 
 Set `default_agent` in `.agents/settings.yml` to one of your [agent](./agents.md) slugs; that agent's own loadout selects the skills, subagents, model, and so on it runs with. You're done.
 
-If your configuration lives in `~/.claude` instead, `outfitter setup` can port it into `~/.agents/` and symlink it back so Claude Code keeps working natively — see [Porting a Claude Code setup](./porting-claude.md).
+If your configuration lives in `~/.claude` instead, move it into `~/.agents/` and run `outfitter link` so Claude Code reads the tree natively — see [Linking into Claude Code and Codex](./linking-harnesses.md).
 
 ## First-time setup
 
-Bootstrap from the Outfitter [default catalog](https://github.com/ai-outfitter/.agent), then launch the default agent:
+Bootstrap from the Outfitter
+[default catalog](https://github.com/ai-outfitter/community-profiles), then launch
+the default agent:
 
 ```bash
 outfitter setup

package/docs/documentation/linking-harnesses.md

@@ -0,0 +1,88 @@
+# Linking into Pi, Claude Code, and Codex
+
+`outfitter run` projects a composition into a temporary directory for one launch. `outfitter link` is the persistent form: it places managed resources and native defaults inside a harness's own home, so plain `pi`, `claude`, and `codex` sessions can use the shared configuration with no Outfitter in the loop.
+
+```bash
+outfitter link                                      # every enabled workflow + default_agent, into every installed harness
+outfitter link --workflow engineer --harness claude # one workflow's agent closures, Claude only
+outfitter link --all --dry-run                      # preview linking every resolvable agent
+```
+
+The `.agents` tree stays the source of truth. Links point into it; nothing is copied and diverged.
+
+## Scope
+
+With no selection, `link` takes what settings already opted into: every enabled workflow root (`workflows:` in `settings.yml`) plus `default_agent`. `--workflow` must name an enabled workflow; `--agent` names any resolvable agent; `--all` widens the scope to every resolvable agent. Each scoped agent is composed by the same composer `run` and `dump` use, and every subagent it delegates to joins the closure — with its own skills, commands, and MCP servers.
+
+The harness home is `$PI_CODING_AGENT_DIR` (default `~/.pi/agent`) for Pi, `$CLAUDE_CONFIG_DIR` (default `~/.claude`) for Claude Code, and `$CODEX_HOME` (default `~/.codex`) for Codex. Without `--harness`, every harness whose executable is on `PATH` or whose home exists is linked; an explicit `--harness` creates the home if it is missing.
+
+## What lands where
+
+| Tree resource                               | Pi home         | Claude Code home                       | Codex home          | How               |
+| ------------------------------------------- | --------------- | -------------------------------------- | ------------------- | ----------------- |
+| Winning tree-root `agents.md`               | — (warning)     | `CLAUDE.md`                            | `AGENTS.md`         | symlink           |
+| Skill `skills/<slug>/`                      | `skills/<slug>` | `skills/<slug>`                        | `skills/<slug>`     | symlink           |
+| Composed agent (scoped agent and delegates) | — (warning)     | `agents/<slug>.md`                     | — (warning)         | generated         |
+| Command (catalog and agent-local)           | — (warning)     | `commands/<slug>.md`                   | `prompts/<slug>.md` | symlink           |
+| Selected MCP server                         | — (warning)     | `claude mcp add-json ... --scope user` | `codex mcp add ...` | registered        |
+| `harness_defaults` leaf                     | `settings.json` | `settings.json`                        | `config.toml`       | managed per value |
+
+- **Symlinked** entries resolve to the winning file or directory in the tree, so editing the tree edits what the harness reads.
+- **Generated** entries are written, not linked. A Claude agent definition is a single Markdown file, but an Outfitter agent's identity is composed — system prompt, shared context, appended prompt fragments, inherited bodies — with frontmatter carrying `name`, `description`, `model`, `tools`, and `skills`. `link` writes that composition into `agents/<slug>.md` under a `Generated by outfitter link` marker. Edit the tree and relink; edits to the generated file are replaced. Codex has no native agent definitions, so agent identities are reported as a warning and not linked there.
+- **Registered** entries go through the harness's own CLI so the harness owns the record. Claude takes the protocol definition verbatim at user scope. Codex takes what `codex mcp add` can express: stdio `command`, `args`, and literal `--env` values; HTTP `--url`, with `Authorization: Bearer ${VAR}` mapped to `--bearer-token-env-var`. Other headers and `${VAR}` env references are warned about and dropped rather than mis-registered.
+
+Prompt fragments are not linked as standalone files: they are composed into each generated agent document. The always-on shared context is the `agents.md` link.
+
+## What stays native
+
+Runtime and account state is not configuration and is not touched:
+
+- auth and account state
+- sessions and project history (`projects/`)
+- native settings not declared under `harness_defaults`; permissions, model, and hooks remain harness-native unless explicitly shared there
+- plugins, caches, debug output
+
+This is the same boundary [state persistence](./state.md) enforces at run time: configuration lives in the tree, mutable state lives with the harness.
+
+## Ownership and conflicts
+
+`link` records what it created in `<harness home>/.outfitter/links.json` and only ever acts on entries in that manifest. It never overwrites, adopts, or deletes anything it did not create. Each entry reports one status:
+
+| Status      | Meaning                                                                                                                                                                           |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `created`   | Written or registered for the first time.                                                                                                                                         |
+| `updated`   | A manifest entry whose target or content changed; only owned entries are ever updated.                                                                                            |
+| `unchanged` | Already correct. MCP servers already present in the harness are `unchanged` and never modified.                                                                                   |
+| `conflict`  | An unmanaged file, directory, or symlink is in the way — including an unmanaged symlinked parent such as a whole `skills -> ...` directory link. The message says what to unlink. |
+| `skipped`   | The harness CLI is not on `PATH`, or its `mcp add` failed.                                                                                                                        |
+| `pruned`    | A managed symlink whose target vanished was removed and forgotten.                                                                                                                |
+
+Conflicts are reported, not resolved: move or unlink the unmanaged entry yourself, then relink. `--strict` exits 1 on any warning, conflict, or skipped entry, which is the form to use in scripts.
+
+## Relinking
+
+`link` is idempotent. After editing the tree, adding a skill to an agent, or bumping a source, run it again: unchanged entries stay put, changed generated files are rewritten, new closure members are created, and links whose targets disappeared are pruned. A second run with nothing changed reports everything `unchanged`.
+
+`--dry-run` prints `would create`, `would update`, and `would prune` without touching the home; the only harness commands it runs are read-only (`mcp get`).
+
+## Removing
+
+```bash
+outfitter link --remove
+```
+
+Removes exactly the manifest entries — symlinks, generated agent files, individual native setting values, and MCP servers it added (through `mcp remove`) — and forgets them. Managed containers (`skills/`, `agents/`, `commands/`, `prompts/`) are removed when they are left empty. Anything unmanaged beside them is untouched.
+
+## Migrating an existing `~/.claude`
+
+`outfitter setup` does not port `~/.claude`. To bring an existing Claude Code setup under the tree: move your `skills/`, `agents/`, and `commands/` into `~/.agents/` (or a git repo linked there — see [Local development](./local-development.md)), reshaping agents as `agents/<id>/agent.md` and `CLAUDE.md` as `agents.md`; remove any whole-directory symlinks such as `~/.claude/skills -> ...`, since `link` manages entries, not containers; then run `outfitter link --all`. Reference the migrated resources by slug from an agent's loadout like any protocol resource:
+
+```
+<!-- ~/.agents/agents/daily/agent.md -->
+---
+name: daily
+skills: [wiki, code-review] # formerly ~/.claude/skills/*
+---
+```
+
+`outfitter list` shows what resolved; `outfitter run daily --harness claude` launches through Outfitter; plain `claude` reads the links.

package/docs/documentation/local-development.md

@@ -31,10 +31,8 @@ The committed `settings.yml` consumes shared catalogs **pinned to exact commits*
 default_agent: founder
 
 sources:
-  - github: ai-outfitter/.agent
-    ref: 2f9c1ab0d3e44b6f9d2c8a17e5b40c91d6f3a8e2
   - github: ai-outfitter/community-profiles
-    ref: 8d04c7a1f2e94b3c6a5d80e17f4b29c3d1e6a075
+    ref: 32311cbf9eb17ae812c2ab5e91fa5f34d5946ca6 # v1.7.0
   - path: . # this repository's own resources win last
 ```
 
@@ -47,9 +45,9 @@ When you are changing an upstream catalog itself, override its source in the git
 ```yaml
 # settings.local.yml (gitignored — machine-specific absolute paths)
 sources:
-  - path: /home/ncrmro/repos/unsupervised/ai-outfitters/default-profiles
-  - path: /home/ncrmro/repos/unsupervised/ai-outfitters/worktrees/actions/main
-  - path: /home/ncrmro/repos/ncrmro/.agents
+  - path: /home/developer/src/ai-outfitter/community-profiles
+  - path: /home/developer/src/ai-outfitter/actions
+  - path: /home/developer/.agents
 ```
 
 Because `settings.local.yml` overlays its sibling with higher [precedence](./settings.md#precedence), your machine resolves live working trees while every other consumer of the repo keeps resolving the pinned SHAs. Worktrees keep an iteration branch isolated:
@@ -67,7 +65,7 @@ git worktree add ../worktrees/feat/sharper-review -b feat/sharper-review
 4. Relaunch `outfitter` and test the behavior (a running session keeps the composition it started with).
 5. Fold settled changes back to their home:
    - personal → commit to your `.agents` repo;
-   - shared → commit in the upstream checkout, push, and open a PR against the catalog (`ai-outfitter/default-profiles`, `ai-outfitter/actions`, your org's `.outfitter`, …).
+   - shared → commit in the upstream checkout, push, and open a PR against the catalog (`ai-outfitter/community-profiles`, `ai-outfitter/actions`, your org's `.agents`, …).
 6. After the upstream PR merges: remove the local `path:` override, bump the pinned `ref:` in `settings.yml`, and `outfitter sync`.
 
 ## Consuming your repo from projects

package/docs/documentation/migration.md

@@ -45,4 +45,4 @@ The name is supported; the previous profile layout inside it is not.
 
 ## Claude Code users
 
-If your pre-Outfitter configuration lives in `~/.claude` rather than `.outfitter/`, skip this page — use [Porting a Claude Code setup](./porting-claude.md) instead.
+If your pre-Outfitter configuration lives in `~/.claude` rather than `.outfitter/`, skip this page — use [Linking into Claude Code and Codex](./linking-harnesses.md) instead.

package/docs/documentation/settings.md

@@ -27,8 +27,8 @@ isolation: inherit # inherit (default) or isolated; see below. Honored only from
 
 # Where protocol resources come from, beyond this tree and ~/.agents.
 sources:
-  - github: ai-outfitter/.agent # owner/repo shorthand
-    ref: 2f9c1ab0d3e44b6f9d2c8a17e5b40c91d6f3a8e2 # pin a commit, tag, or branch
+  - github: ai-outfitter/community-profiles # owner/repo shorthand
+    ref: v1.7.0 # pin a commit, tag, or branch
     # path: optional subdirectory containing the payload
   - uri: git+https://git.example.com/team/agents.git
     ref: v1.2.0
@@ -52,6 +52,22 @@ source_cache:
 # Pseudonymous product analytics consent; defaults to true when absent.
 telemetry:
   enabled: false
+
+# Additive loadout entries composed into every agent ahead of its own loadout.
+agent_defaults:
+  extensions:
+    - git:github.com/ai-outfitter/pensieve@4b1e0d2c9a7f35e86b0d1c4a92f6e3d5a8b7c601
+  skills:
+    - organization-practices
+  mcp:
+    - github
+  append_system_prompt:
+    - file: prompts/organization.md
+
+# Native harness settings shared by every agent run.
+harness_defaults:
+  pi:
+    httpIdleTimeoutMs: 3600000
 ```
 
 - `default_agent` / `default_harness` — which agent plain `outfitter` runs, and the harness it launches in.
@@ -66,6 +82,8 @@ telemetry:
   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.
+- `agent_defaults` — additive loadout entries composed into **every** agent ahead of its own loadout; see [Agent defaults](#agent-defaults) below.
+- `harness_defaults` — native Pi, Claude Code, or Codex settings applied to every run of that harness; see [Harness defaults](#harness-defaults) below.
 
 ## Precedence
 
@@ -78,4 +96,51 @@ Higher wins:
 5. Cached remote settings (in configured order)
 6. Built-in defaults
 
-Scalar settings override. `sources` follows last-wins ordering per scope so a higher-precedence file replaces the complete lower-precedence list. `workflows` is additive: loaded settings contribute an ordered-set union, and repeated slugs across files collapse to their first occurrence.
+Scalar settings override. `sources` follows last-wins ordering per scope so a higher-precedence file replaces the complete lower-precedence list. `workflows` and `agent_defaults` are additive ordered-set unions. `harness_defaults` deep-merges by harness, with higher-precedence leaves replacing lower-precedence leaves.
+
+## Agent defaults
+
+`agent_defaults` composes one set of additive loadout entries into every agent — local runs, Actions, and dumps alike — so an organization declares a shared extension, skill, MCP server, plugin, delegate, or appended prompt fragment once instead of duplicating it into every `agents/<id>/agent.md`:
+
+```yaml
+agent_defaults:
+  extensions:
+    - git:github.com/ai-outfitter/pensieve@4b1e0d2c9a7f35e86b0d1c4a92f6e3d5a8b7c601
+  skills:
+    - organization-practices
+  mcp:
+    - github
+  plugins:
+    - org-plugin
+  subagents:
+    - org-reviewer
+  append_system_prompt:
+    - file: prompts/organization.md # resolved like agent prompt sources: catalog `file`, active-project `repo_file`
+```
+
+Composition rules:
+
+- Defaults compose **before** each agent's own loadout — like a root-most ancestor ahead of the whole inheritance chain — using the same deterministic parent-first ordering and stable de-duplication as inherited agent loadouts. An agent that lists the same slug itself never duplicates it, and the settings layer wins first-encounter conflicts.
+- Selections resolve catalog-wide across layers, never through an agent's local namespace.
+- Only the additive loadout fields above are supported. Per-agent controls such as `model`, `thinking`, and `tools` stay agent-owned; `agents.md` remains shared prompt context, not a configuration manifest.
+- `outfitter run`, `outfitter dump`, and `outfitter validate` compose the same effective defaults. Unresolved references are validation findings and composition warnings named `agent_defaults …`, and `outfitter dump` records the settings-layer provenance in `.outfitter/composition.json` plus a `settings.yml` carrying the merged defaults, so a dumped tree stays self-contained.
+- Settings without `agent_defaults` behave exactly as before. The block is backend-neutral: no backend-specific keys, endpoints, or credentials.
+
+## Harness defaults
+
+`harness_defaults` keeps organization- or project-wide native coding-harness policy beside the portable agent catalog without putting harness-specific keys in every agent profile:
+
+```yaml
+harness_defaults:
+  pi:
+    httpIdleTimeoutMs: 3600000
+  claude:
+    includeCoAuthoredBy: false
+  codex:
+    features:
+      apps: false
+```
+
+The keys below each harness are passed through as that harness's native settings. `outfitter run` merges Pi and Claude defaults into its temporary `settings.json`; a Pi profile's own configuration overlay remains higher precedence. Codex receives flattened `--config key=TOML` arguments. `outfitter link` manages the same values individually in Pi or Claude `settings.json` and Codex `config.toml`, leaving every unrelated native setting untouched. An unmanaged value is never adopted or overwritten.
+
+Every loaded settings scope may contribute defaults. Objects deep-merge from low to high precedence, while arrays and scalar leaves replace. `outfitter dump` carries the effective block into the dumped tree. Unknown harness names are rejected; supported names are `pi`, `claude`, and `codex`.

package/docs/documentation/state.md

@@ -246,6 +246,6 @@ state_persistence:
 
 When a path uses `symlink`, the durable destination is the native CLI state location — `~/.pi/agent/...` for Pi, `~/.claude/...` for Claude Code. The native location is not another configuration layer: it does not participate in resolution or merge precedence; it only provides a durable destination for state paths.
 
-For a [ported Claude Code setup](./porting-claude.md), `~/.claude` configuration entries are themselves symlinks into `~/.agents/`, so persisted configuration state lands in the protocol tree while session and auth state stays native.
+For a [linked Claude Code home](./linking-harnesses.md), the managed `~/.claude` configuration entries are themselves symlinks into `~/.agents/`, so persisted configuration state lands in the protocol tree while session and auth state stays native.
 
 For the complete adapter contract and rationale, see [State writeback strategy](../architecture/state_writeback_strategy.md).

package/docs/documentation/support-matrix.md

@@ -45,11 +45,12 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - **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.
+- **Persistent links** — [`outfitter link`](./linking-harnesses.md) places managed skills, custom prompts (from commands), the shared-context `AGENTS.md`, and MCP servers registered through `codex mcp add` into `$CODEX_HOME` (default `~/.codex`), so plain `codex` sessions carry the composition without a launch. Agent identities are warned about and not linked, since Codex has no native agent definitions.
 
 ## Claude Code notes
 
 - **Your configuration comes first** — by default a Claude run stands on the configuration already on the machine. Outfitter sets no `CLAUDE_CONFIG_DIR`; it declares the baked composition a Claude plugin and passes it through `--plugin-dir`, so the session keeps your workspace trust, `~/.claude/settings.json` permissions, credentials, plugins, and configured MCP servers, and the profile's skills, subagents, and prompts layer on top. Nothing is seeded and nothing is copied back, because Claude is reading and writing its real configuration directory throughout. Pass `--isolated`, or set `isolation: isolated` in your `~/.agents/settings.yml`, to launch from the composition alone — the reproducible form for CI and containers, and what the remaining bullets in this section describe. If the installed Claude is too old to load a plugin directory, Outfitter falls back to an isolated run and says so rather than failing the launch.
-- **Isolated config and session state** — an isolated run 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.
+- **Isolated config and session state** — an isolated run 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), MCP servers configured in `~/.claude` are not 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`. 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`.
@@ -59,6 +60,7 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 - **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.
 - **Bundled Outfitter skill** — every launch also publishes Outfitter's own self-documentation skill as a bundled plugin, so the agent can explain Outfitter and this launch's configuration.
+- **Persistent links** — [`outfitter link`](./linking-harnesses.md) places managed skills, generated agent definitions, commands, the shared-context `CLAUDE.md`, and user-scope MCP servers into `$CLAUDE_CONFIG_DIR` (default `~/.claude`), so plain `claude` sessions carry the composition without a launch.
 
 ## Pi notes
 

package/docs/documentation/switching-to-outfitter.md

@@ -6,7 +6,7 @@ This guide is for people who already use Pi, Claude Code, Codex, Cursor, or anot
 
 **You already have a `.agents/` directory.** You're done with the hard part — Outfitter reads the protocol directly. Set `default_agent` in `.agents/settings.yml` to one of your [agent](./agents.md) slugs — the agent's own loadout selects its skills, subagents, and knowledge — and run `outfitter`. Nothing is converted or re-authored.
 
-**Your setup lives in `~/.claude`.** Let `outfitter setup` port it into `~/.agents/` and symlink it back so Claude Code keeps working natively — see [Porting a Claude Code setup](./porting-claude.md). Your ported skills, agents, and commands are then referenceable by slug like any protocol resource.
+**Your setup lives in `~/.claude`.** Move it into `~/.agents/` and run `outfitter link` so Claude Code keeps working natively from the tree — see [Linking into Claude Code and Codex](./linking-harnesses.md). Your migrated skills, agents, and commands are then referenceable by slug like any protocol resource.
 
 Starting from neither? `outfitter setup` bootstraps from the default catalog — see [Getting started](./getting-started.md).
 

package/docs/documentation/usecases/shared-conventions.md

@@ -40,7 +40,7 @@ The value is ambiguity reduction: every agent — and every skill that clones, o
 
 ## Reaching native harness runs
 
-Composition only helps runs that go through it — the rule should also reach a bare `claude` session that never touches Outfitter. The porting design ([Porting a Claude Code setup](../porting-claude.md)) maps `~/.claude/CLAUDE.md` to `~/.agents/agents.md` with a symlink back, so native Claude Code reads the protocol tree and editing either view edits the same file; managed porting and persistent harness symlinks — including the generalization of projecting composed shared context into each harness's home-level memory file — are deferred to [#187](https://github.com/ai-outfitter/outfitter/issues/187).
+Composition only helps runs that go through it — the rule should also reach a bare `claude` session that never touches Outfitter. [`outfitter link`](../linking-harnesses.md) symlinks `~/.claude/CLAUDE.md` (and `~/.codex/AGENTS.md`) to the winning `~/.agents/agents.md`, so native Claude Code and Codex read the protocol tree and editing the tree edits what they see. This is the persistent projection [#187](https://github.com/ai-outfitter/outfitter/issues/187) deferred; setup still creates no links.
 
 ## Payoff
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {
@@ -47,6 +47,7 @@
     "cross-spawn": "^7.0.6",
     "liquidjs": "^10.27.0",
     "posthog-node": "^5.49.1",
+    "smol-toml": "^1.8.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/src/schemas/settings.schema.json

@@ -103,7 +103,54 @@
     "custom_settings": {
       "type": "object",
       "description": "Arbitrary YAML-compatible values exposed to Outfitter composition templates as outfitter.custom_settings."
+    },
+    "agent_defaults": {
+      "type": "object",
+      "description": "Additive loadout entries composed into every agent before its own loadout, using the same deterministic ordering and stable de-duplication as inherited agent loadouts.",
+      "properties": {
+        "extensions": { "$ref": "#/$defs/slugList" },
+        "skills": { "$ref": "#/$defs/slugList" },
+        "mcp": { "$ref": "#/$defs/slugList" },
+        "plugins": { "$ref": "#/$defs/slugList" },
+        "subagents": { "$ref": "#/$defs/slugList" },
+        "append_system_prompt": {
+          "oneOf": [
+            { "$ref": "#/$defs/promptSource" },
+            { "type": "array", "items": { "$ref": "#/$defs/promptSource" } }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "harness_defaults": {
+      "type": "object",
+      "description": "Harness-native settings applied to every composed agent and persistently reconciled by outfitter link.",
+      "properties": {
+        "pi": { "$ref": "#/$defs/nativeSettings" },
+        "claude": { "$ref": "#/$defs/nativeSettings" },
+        "codex": { "$ref": "#/$defs/nativeSettings" }
+      },
+      "additionalProperties": false
     }
   },
-  "additionalProperties": true
+  "additionalProperties": true,
+  "$defs": {
+    "slugList": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "promptSource": {
+      "type": "object",
+      "oneOf": [{ "required": ["file"] }, { "required": ["repo_file"] }],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "repo_file": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "nativeSettings": {
+      "type": "object",
+      "description": "A harness-native settings document. Native keys are validated by the selected harness release."
+    }
+  }
 }