@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/docs/documentation/agents.md

@@ -0,0 +1,109 @@
+# Agents
+
+An agent is the protocol's identity resource — and, in Outfitter, the thing you run. A directory under `agents/<id>/` holds an `agent.md` definition and an optional `config.json`. Together they carry both _who the agent is_ and _what it runs with_: its skills, MCP servers, subagents, extensions, plugins, model, thinking level, and tool policy. That whole bundle — identity plus loadout — is what earlier drafts called a "profile." There is no separate profile resource; **an agent is the profile**. See [Profiles](./profiles.md).
+
+```text
+.agents/
+  agents/
+    engineer/
+      agent.md
+      config.json   # optional
+      skills/       # capabilities private to engineer
+        release-debug/SKILL.md
+      hooks/        # reserved for a future portable hook entity
+    code-reviewer/
+      agent.md
+```
+
+## agent.md
+
+`agent.md` describes the identity in markdown — who the agent is, its policy and posture, how it approaches work — and declares its loadout in frontmatter:
+
+```markdown
+---
+name: engineer
+description: Implements features and fixes with a bias toward small, verifiable changes.
+skills: [wiki, research]
+subagents: [code-reviewer]
+extensions: [outfitter-mode]
+plugins: [git-tools]
+mcp: [github]
+model: gpt-5.2
+thinking: high
+tools:
+  allow: [read, edit, bash]
+---
+
+# Engineer
+
+You implement changes directly, keep diffs small, and verify before claiming done...
+```
+
+Keep the prose focused on durable identity and behavior. Per-capability procedures belong in [skills](./skills.md); the frontmatter only _selects_ resources by slug — it never copies their content.
+
+### Loadout fields
+
+| Field        | Selects                                                                      |
+| ------------ | ---------------------------------------------------------------------------- |
+| `skills`     | [Skill](./skills.md) slugs made available to the run.                        |
+| `mcp`        | MCP servers from the tree's `mcp.json` to enable.                            |
+| `subagents`  | Agent slugs projected as harness delegates. See [Subagents](./subagents.md). |
+| `extensions` | Pi extensions to load. First-class, per the adapter.                         |
+| `plugins`    | Pi plugins to load. First-class, per the adapter.                            |
+| `model`      | Provider/model from `models.json`.                                           |
+| `thinking`   | Thinking/effort level.                                                       |
+| `tools`      | Allowed/denied tool policy for the run.                                      |
+
+Every value is a slug resolved across layers. Skills first check `agents/<agent>/skills/<slug>/` across layer precedence, then fall back to catalog-wide `skills/<slug>/`. This lets an agent own private implementation capabilities without exposing them to every agent in the catalog. See [Skills](./skills.md#agent-local-skills).
+
+`knowledge` and `commands` resolve the same way — an agent may keep private files under `agents/<agent>/knowledge/` and `agents/<agent>/commands/`, local-first over the catalog-wide trees. `subagents` are always catalog-wide (a delegate is a shared agent). `extensions`/`plugins` are harness-native passthroughs with no on-disk namespace, and `model`/`thinking`/`tools` are per-agent already via `config.json` merge.
+
+## Pi configuration overlay
+
+An agent may own native Pi configuration under `agents/<agent>/pi/`. Outfitter overlays that folder into the temporary `PI_CODING_AGENT_DIR` before launching Pi, so native files keep their standard names and formats:
+
+```text
+agents/founder/
+├── agent.md
+└── pi/
+    ├── settings.json
+    ├── keybindings.json
+    ├── models.json
+    └── themes/
+```
+
+The overlay is file-based. Source layers are applied from lowest to highest precedence, so a workspace `agents/founder/pi/keybindings.json` replaces the same file from a global or remote catalog while unrelated lower-layer files remain present. Outfitter does not follow symlinks from the overlay. The folder is ignored when the selected harness is not Pi.
+
+Outfitter writes generated identity and composed skills after applying the native overlay, and seeds durable Pi credentials immediately before launch. Those runtime-owned resources therefore cannot be replaced accidentally by a profile overlay.
+
+Two per-agent surfaces are **discovered but not yet projected** (adapter parity is tracked in [#183](https://github.com/ai-outfitter/outfitter/issues/183)): `agents/<agent>/mcp.json` (merges by server id over the tree-root `mcp.json`) and the reserved `agents/<agent>/hooks/` namespace (see [Hooks](./hooks.md)). Both surface a validation warning when present so a selection placed there is never silently dropped.
+
+## config.json
+
+The optional `config.json` carries structured or harness-specific configuration that is awkward in frontmatter, following the protocol's schema for the pinned revision. JSON files merge across layers per the protocol's JSON merge behavior, so a workspace layer can adjust one field of a globally defined agent — swap the model, add an extension — without copying the whole definition.
+
+## Tree-level context
+
+Two files at the tree root complement agent definitions:
+
+- `agents.md` — shared operating context that applies to every run from this tree.
+- `system-prompt.md` — the base system prompt an agent's identity layers on top of.
+
+## Running an agent
+
+Select an agent by slug; choose the harness with `--harness`:
+
+```bash
+outfitter run engineer
+outfitter run engineer --harness claude
+```
+
+`default_agent` in [settings](./settings.md) sets what plain `outfitter` runs.
+
+## Resolution
+
+Agents resolve by slug across layers — workspace, global, then remote sources — with merge-by-ID semantics: a workspace `agents/engineer/` overrides a global or remote one. Agent-local skills merge by their owner and slug using the same layer order. `outfitter list agents` shows every resolvable agent and its winning source; `outfitter list skills --agent engineer` shows its effective skill namespace; `outfitter validate` reports broken loadout slugs and shadowed definitions.
+
+## Agents as delegates
+
+The same agent definition can also be selected as a [subagent](./subagents.md) in another agent's `subagents` list — a delegate the run can hand focused work to. A leader agent's loadout is where that delegation is declared.

package/docs/documentation/best-practices.md

@@ -1,27 +1,26 @@
 # Best practices
 
-Outfitter works best with a few stable profiles and many focused skills.
-Profiles define who the agent is and the boundaries it operates within. Skills
-define what the agent can progressively learn to do.
+Outfitter works best with a few stable [agents](./agents.md) and many focused skills. An agent defines who it is, the boundaries it operates within, and — through its loadout — what it composes. Skills define what the agent can progressively learn to do.
 
-## Prefer a few profiles and many skills
+The target shape for a project:
 
-Create a profile for a durable identity or policy boundary — engineering,
-platform operations, support, a customer persona. A profile owns model and
-provider controls, operating policy and safety boundaries, tools and
-permissions, conventions, and the short rules for selecting skills.
+- zero authored profile files ([an agent and its loadout is the profile](./profiles.md));
+- a small set of reusable agents;
+- one [skill](./skills.md) per capability rather than one skill per trigger;
+- one reusable DeepWork job per multi-step procedure where needed;
+- the minimum GitHub workflow set required by trigger and permission boundaries;
+- only the transitive resource closure required by the selected agent when [dumping](./dump-and-bake.md).
 
-Add a skill when the new behavior is a capability within an existing identity:
-issue planning, code review, deployment smoke testing, KPI reporting, release
-preparation. Adding a new situation SHOULD usually add a skill and a concise
-activation rule, not another profile. Reserve profile inheritance for genuine
-control and policy composition; do not require consumers to inherit a profile
-merely to access one of its skills.
+## Prefer a few agents and many skills
 
-Prefer one profile with many skills:
+Create an agent for a durable identity or policy boundary — engineering, platform operations, support. An agent owns operating policy and safety boundaries, conventions, the short rules for selecting skills, and its loadout.
+
+Add a skill when the new behavior is a capability within an existing identity: issue planning, code review, deployment smoke testing, KPI reporting, release preparation. Adding a new situation SHOULD usually add a skill and a concise activation rule, not another agent.
+
+Prefer one agent with many skills:
 
 ```text
-platform profile
+platform agent
 ├── issue-planning skill
 ├── issue-implementation skill
 ├── kpi-reporting skill
@@ -29,48 +28,23 @@ platform profile
 └── failed-deployment-triage skill
 ```
 
-Avoid separate `issue-planner`, `deployment-reviewer`, and `kpi-reporter`
-profiles when they share the same platform identity, permissions, and tools.
-Adding release notes later should add a `release-notes` skill to the platform
-profile, not a `release-notes-agent` profile with copies of the same controls.
+Avoid separate `issue-planner`, `deployment-reviewer`, and `kpi-reporter` agents when they share the same platform identity, permissions, and tools. Adding release notes later should add a `release-notes` skill, not a `release-notes-agent` with copies of the same policy.
 
-Separate profiles are appropriate when the policy boundary differs. An
-engineering agent may edit code, run tests, and push branches; a customer
-support agent may read customer conversations and draft replies but must not
-modify repositories. Those are different identities with different data access,
-tools, and write permissions, so separate `engineering` and `support` profiles
-are appropriate — and each can still expose many focused skills.
+Separate agents are appropriate when the policy boundary differs. An engineering agent may edit code, run tests, and push branches; a customer support agent may read customer conversations and draft replies but must not modify repositories. Those are different identities with different data access and write permissions — and each can still expose many focused skills.
 
 ## Keep skills focused
 
-Give each skill one recognizable capability and a description precise enough
-for an agent to decide when it applies. Keep common policy in the profile
-rather than repeating it across every skill.
+Give each skill one recognizable capability and a description precise enough for an agent to decide when it applies. Keep common policy in the agent definition rather than repeating it across every skill.
 
-Focused does not mean tiny. Err on the side of one larger skill that
-[routes to different references](./skills.md#skills-as-routers) over many
-near-duplicate skills: split a skill only when its description can no longer
-say when it applies. Point references at existing human-maintained
-documentation rather than writing new agent-only copies, and use
-[profile-added references](./skills.md#profile-added-references) to specialize
-a shared skill instead of forking it.
+Focused does not mean tiny. Err on the side of one larger skill that [routes to different references](./skills.md#skills-as-routers) over many near-duplicate skills: split a skill only when its description can no longer say when it applies. Point references at existing human-maintained documentation rather than writing new agent-only copies, and use [loadout-added references](./skills.md#loadout-added-references) to specialize a shared skill instead of forking it.
 
 ## Use references for human documentation
 
-Keep canonical architecture, policy, and operating documents in normal `docs/`
-locations where people already maintain and review them. Declare those files as
-skill `references` instead of copying them into skill directories, and read
-them only after the skill activates so every run does not pay the context cost
-of every possible workflow. See
-[External references](./skills.md#external-references) for the reference format
-and trust rules.
+Keep canonical architecture, policy, and operating documents in normal `docs/` locations where people already maintain and review them. Declare those files as skill `references` instead of copying them into skill directories, and read them only after the skill activates so every run does not pay the context cost of every possible workflow. See [External references](./skills.md#external-references) for the reference format and trust rules.
 
 ## Keep routing concise
 
-A profile's system prompt can map stable runtime signals to relevant skills.
-Keep these activation rules short; detailed procedures belong in the selected
-skills and their references, never repeated in the profile prompt (see
-[Where context and instructions live](./skills.md#where-context-and-instructions-live)).
+An agent can map stable runtime signals to relevant skills. Keep these activation rules short; detailed procedures belong in the selected skills and their references, never repeated in the agent (see [Where context and instructions live](./skills.md#where-context-and-instructions-live)).
 
 ```text
 Select only the skill relevant to the current task.
@@ -79,27 +53,15 @@ Select only the skill relevant to the current task.
 - Recurring repository activity report: use kpi-reporting.
 - Successful environment awaiting verification: use deployment-review.
 - Failed environment update: use failed-deployment-triage.
-Load detailed task content only after selecting the skill.
+Load detailed content only after selecting the skill.
 ```
 
-When an integration launches the profile, pass only the trusted identifiers and
-runtime metadata needed to choose a skill. Keep untrusted source material out
-of the activation rules and let the selected skill retrieve only what it needs
-with trusted tools.
+When an integration invokes an agent headlessly, pass only the trusted identifiers it expects. Keep untrusted source material out of inputs and let the selected skill retrieve only what it needs with trusted tools.
 
 ## Keep automation reusable
 
-For agentic automation, prefer a small number of reusable workflows that pass
-concise runtime metadata to the same stable execution profile. Let that profile
-activate the appropriate skill. One profile and one workflow can then support
-issue planning, implementation, scheduled reporting, deployment review, and
-future situations; adding a capability becomes a skill change instead of
-another near-duplicate profile and automation job.
+For agentic automation, prefer a small number of reusable workflows that run [agents with structured inputs](./actions.md). Consolidate compatible agents into as few workflows as practical; separate workflows are justified only by different triggers, permissions, credentials, or isolation boundaries. Adding a capability becomes a skill change instead of another near-duplicate workflow.
 
 ## Review the trust chain
 
-Profiles and skills can influence agent behavior and tool use. Follow
-[Trust and review](./profile-repository.md#trust-and-review) for catalog
-sources, keep secrets out of profiles, skills, references, and prompts, and run
-`outfitter profile lint --strict` in CI to catch broken skill IDs and
-references before they reach an agent run.
+Resources influence agent behavior and tool use. Follow [Trust and review](./catalogs.md#trust-and-review) for catalog sources, pin refs (full SHAs for CI), keep secrets out of agents, skills, references, and prompts, and run `outfitter validate --strict` in CI to catch broken slugs and references before they reach an agent run.

package/docs/documentation/catalogs.md

@@ -0,0 +1,126 @@
+# Catalogs
+
+A catalog is a git repository that publishes a `.agents` payload — agents, skills, tasks, knowledge, commands — so a person, team, or organization can share it. You can bootstrap a machine or project from one, or add one as an ongoing source that Outfitter keeps synchronized.
+
+```bash
+outfitter setup https://github.com/ncrmro/.agents
+```
+
+The repository names are discovery and distribution conventions; the payload is always the same protocol-shaped tree (pinned protocol revision [`502a9d5`](https://github.com/aj47/dotagentsprotocol-website/blob/502a9d5f886d0aad8d3da83c03354bdfa4b389e7/src/components/Structure.astro)):
+
+| Convention                        | Purpose                                                                          |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `owner/.agents` or `owner/.agent` | A shareable personal or team catalog.                                            |
+| `owner/.outfitter`                | An organization/control repository distributing org-wide resources and settings. |
+
+## Standalone `.agents` repositories (preferred)
+
+The primary catalog pattern is a standalone repository whose **root is the payload** — the flat dotagents layout:
+
+```text
+ncrmro/.agents/            # repository root
+  agents.md
+  system-prompt.md
+  agents/
+    engineer/
+      agent.md
+      skills/                 # skills private to engineer
+        release-debug/SKILL.md
+    founder/agent.md
+  skills/
+    wiki/SKILL.md
+    research/SKILL.md
+  tasks/
+    weekly-kpis/task.md
+  knowledge/
+  settings.yml             # Outfitter settings (optional; see settings.md)
+  settings.local.yml       # gitignored machine-local overrides
+```
+
+This is the same layout as `~/.agents/` — a standalone catalog is simply a global layer under version control. That makes it the natural home for personal dotagents development: clone it as `~/.agents` (or point your settings at the checkout), iterate locally, and open pull requests to move improvements upstream into shared catalogs. See [Local development](./local-development.md) for the full workflow.
+
+## Colocated `.agents/` directories (fallback)
+
+When agent configuration should travel with a codebase, colocate the payload as a `.agents/` subdirectory beside the code:
+
+```text
+payments-service/
+  .agents/
+    agents/
+    skills/
+    settings.yml
+  src/
+  docs/
+```
+
+The colocated tree doubles as the protocol's workspace overlay: its resources merge by ID over the global and remote layers for anyone running in that project. Prefer the standalone pattern for anything you intend to share across projects; prefer colocation only for resources that are meaningless outside the one repository.
+
+## Consuming a catalog
+
+Add the repository to `sources` in your [settings](./settings.md):
+
+```yaml
+# ~/.agents/settings.yml
+sources:
+  - github: my-org/.agent # owner/repo shorthand
+    ref: 2f9c1ab0d3e44b6f9d2c8a17e5b40c91d6f3a8e2 # pin a commit, tag, or branch
+  - github: my-org/payments-service
+    ref: v1.2.0
+    path: .agents # colocated payload inside the repo
+  - uri: git+https://git.example.com/team/agents.git # any git URI
+```
+
+Each source entry is one of:
+
+- `path:` — a local directory (no `ref`; read live from disk).
+- `github:` — an `owner/repo` GitHub shorthand.
+- `uri:` — any git-cloneable URI, for non-GitHub hosts.
+
+Remote entries additionally accept:
+
+- `ref:` — a tag, branch, or commit to pin. With a `ref`, `outfitter sync` fetches exactly that ref. Without one, sync fast-forwards the default branch.
+- `path:` — the payload directory inside the repository, for colocated layouts.
+
+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.
+
+## Organization control repositories
+
+An `owner/.outfitter` repository distributes organization-wide resources plus shared settings that Outfitter layers below each user's local settings:
+
+```yaml
+# ~/.agents/settings.yml
+remote_settings:
+  - github: my-org/.outfitter
+    path: .agents/settings.yml # file path inside the repo
+    ref: 9c47d1e2b8a05f36c4d7e90a12b3f8c5d6e71a04
+```
+
+Remote settings are cached locally and merged at lower precedence than your project and user settings, so anything you set locally wins. This is how an organization distributes shared sources, agents, and defaults without controlling each user's machine. See the [organization catalog use case](./usecases/organization-profile-catalog.md).
+
+## Syncing and updating
+
+`outfitter sync` synchronizes every remote source into the local cache:
+
+1. Remote settings repositories are cloned or updated first, then 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.
+
+Pinned (`ref:`) sources stay on their pinned ref until you change it; unpinned sources fast-forward on every sync.
+
+## Private repositories
+
+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.
+
+## 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.
+
+Before adding a source, review it:
+
+1. Read the agent definitions, `agents.md`, and `system-prompt.md` you will compose.
+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.
+
+**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

@@ -1,5 +1,7 @@
 # CLI reference
 
+> **Status: RFC [#165](https://github.com/ai-outfitter/outfitter/issues/165) target.** This reference describes the dotagents end-state command surface. The currently released CLI still implements the legacy profile commands; implementation PRs replace them incrementally.
+
 Global options:
 
 | Option          | Description                  |
@@ -7,68 +9,64 @@ Global options:
 | `-V, --version` | Print the Outfitter version. |
 | `-h, --help`    | Show help for a command.     |
 
-## `outfitter run [args...]`
+## `outfitter run [agent] [args...]`
 
-Assemble a composite profile and launch the selected agent CLI. `run` is the default command, so plain `outfitter` and `outfitter run` are equivalent.
+Resolve, compose, and launch an agent. `run` is the default command, so plain `outfitter` and `outfitter run` are equivalent.
 
-| Option                    | Description                                                                |
-| ------------------------- | -------------------------------------------------------------------------- |
-| `-p, --profile <profile>` | Outfitter profile id to run. Defaults to the settings `default_profile`.   |
-| `--agent <agent>`         | Agent adapter to launch: `pi` or `claude`. Defaults to `default_agent`.    |
-| `--strict`                | Fail instead of warning when controls cannot be translated by the adapter. |
+| 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`.           |
+| `--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 agent CLI:
+Any other arguments and unrecognized options are passed through to the launched harness:
 
 ```bash
-outfitter run --profile engineer --agent claude
-outfitter -p data_analyst -- --print "summarize this repo"
+outfitter run engineer --harness claude
+outfitter run reviewer -- --print "summarize this repo"
 ```
 
-On a first interactive launch with no `~/.outfitter/settings.yml`, `outfitter` starts Pi-native onboarding instead of a normal run.
-
 ## `outfitter setup [source]`
 
-Create initial Outfitter settings and a default profile. Setup launches Pi with the Outfitter onboarding extension and finishes profile selection inside the agent session (see [Getting started](./getting-started.md)).
-
-| Argument   | Description                                                                                                    |
-| ---------- | -------------------------------------------------------------------------------------------------------------- |
-| `[source]` | Optional setup source: a local path or a git URL of a [profile repository](./profile-repository.md) to import. |
+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
+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
+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.
 
 ## `outfitter sync`
 
-Synchronize URI-backed profile and remote settings sources into the local cache (`~/.outfitter/cache/`). Takes no options. Reports a per-source status of `updated`, `unchanged`, `skipped`, or `failed`, and validates synced profile sources.
-
-## `outfitter profile`
-
-List and manage Outfitter profiles.
+Synchronize remote sources and remote settings into the local cache. Reports a per-source status of `updated`, `unchanged`, `skipped`, or `failed`, and validates synced sources.
 
-### `outfitter profile list`
+## `outfitter list [kind]`
 
-List available Outfitter profiles.
+List resolvable resources across all layers, with the winning source for each slug and any shadowed IDs.
 
-| Option  | Description                                                       |
-| ------- | ----------------------------------------------------------------- |
-| `--all` | Include template profiles that are intended only for inheritance. |
+| Argument | Description                                                   |
+| -------- | ------------------------------------------------------------- |
+| `[kind]` | Optional filter: `agents`, `skills`, `knowledge`, `commands`. |
 
-### `outfitter profile create <name>`
+## `outfitter validate`
 
-Create a new Outfitter profile skeleton.
-
-| Argument / option | Description                                               |
-| ----------------- | --------------------------------------------------------- |
-| `<name>`          | Filesystem-safe profile name.                             |
-| `--scope <scope>` | Destination scope: `user`, `project`, or `project-local`. |
-| `--path <path>`   | Destination profile source directory.                     |
-
-### `outfitter profile lint`
-
-Validate profiles, inheritance, and typed prompt includes.
+Validate the effective resource set: protocol layout, frontmatter, unresolved slugs in agent loadouts, broken or escaping skill references, and settings schema.
 
 | Option     | Description                              |
 | ---------- | ---------------------------------------- |
 | `--strict` | Exit non-zero when warnings are present. |
 | `--json`   | Print diagnostics as JSON.               |
 
-## `outfitter welcome`
+## `outfitter dump`
+
+Write the composed resource tree as a self-contained `.agents/` directory for review, vendoring, or air-gapped use. Identical sources, refs, and selections produce byte-identical output; dumps never contain credentials, sessions, caches, or other mutable runtime state.
+
+| Option         | Description                                          |
+| -------------- | ---------------------------------------------------- |
+| `--agent <id>` | Restrict the dump to one agent's transitive closure. |
+| `--out <dir>`  | Destination directory (default `./.agents`).         |
 
-Run Outfitter welcome onboarding prompts in the terminal. This is a legacy compatibility command: current onboarding runs natively inside Pi (via `outfitter setup` or the first-run `outfitter` launch), and `welcome` remains for environments that need the older terminal prompt flow. Requires an interactive TTY. Takes no options.
+> **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).

package/docs/documentation/concepts.md

@@ -4,51 +4,94 @@ How an `outfitter` launch goes from configuration files to a running agent:
 
 ```mermaid
 flowchart LR
-  A[Settings] --> B[Profile sources]
-  B --> C[Profile stack]
-  C --> D[Composite profile]
-  D --> E[Adapter]
-  E --> F[Agent CLI]
+  A[Settings] --> B[Sources]
+  B --> C[.agents layers]
+  C --> D[Resolver]
+  D --> E[Composed agent]
+  E --> F[Adapter]
+  F --> G[Harness]
 ```
 
-Settings tell Outfitter where profiles come from; profile sources supply profile definitions; the definitions for the selected profile form an ordered stack; the merged stack is written out as a composite profile; an adapter translates that composite profile into agent-specific files, flags, and environment variables; and the agent CLI launches with the result.
+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).
+
+## The `.agents` protocol
+
+Outfitter stores and exchanges all agent configuration in the vendor-neutral [Dotagents `.agents` protocol](https://dotagentsprotocol.com/) (pinned at revision [`502a9d5`](https://github.com/aj47/dotagentsprotocol-website/blob/502a9d5f886d0aad8d3da83c03354bdfa4b389e7/src/components/Structure.astro)). Outfitter does not define its own authored configuration format: a `.agents/` tree is useful without Outfitter, and any existing `.agents/` tree is usable by Outfitter without conversion.
+
+```text
+.agents/
+  agents.md            # shared operating context
+  system-prompt.md     # base system prompt
+  mcp.json             # MCP server configuration
+  models.json          # model configuration
+  agents/<id>/agent.md # agent definitions (+ optional config.json)
+  agents/<id>/skills/  # skills private to one agent (also knowledge/, commands/)
+  agents/<id>/mcp.json # per-agent MCP config (discovered; projection deferred, #183)
+  agents/<id>/hooks/   # reserved namespace (not yet resolved)
+  skills/<id>/...      # Agent Skills packages
+  tasks/<id>/task.md   # named execution contracts
+  knowledge/...        # reference documents
+  commands/...         # slash commands
+```
+
+## Resources
+
+The protocol resources Outfitter resolves and composes:
+
+- **Agent** — a definition at `agents/<id>/agent.md` (plus optional `config.json`) describing an identity _and_ its loadout: the skills, subagents, MCP servers, extensions, plugins, model, thinking level, and tools it runs with. The agent is what you run. See [Agents](./agents.md).
+- **Skill** — a capability package under catalog-wide `skills/<id>/` or agent-local `agents/<agent-id>/skills/<id>/`, with instructions, references, scripts, and assets. See [Skills](./skills.md).
+- **Knowledge** and **commands** — reference documents and slash commands shared across runs.
+
+> Tasks — `tasks/<id>/task.md` execution contracts, structured inputs, and baking — are the subject of a separate upcoming RFC and are not part of this end state. See [Tasks](./tasks.md).
 
-## Profile
+## Profiles, personas, and subagents
 
-A profile is a named, reusable YAML definition of how an agent should be outfitted: model and provider, thinking level, system and append prompts, skills, extensions, subagents, DeepWork jobs, CLI arguments, and environment variables. Profiles can inherit from other profiles and can live as a flat `<id>.yml` file or a directory with a `profile.yml` plus bundled resources. See [Profiles](./profiles.md).
+Three related terms, none of which is a settings key or a separate file format:
 
-## Composite profile
+- A **[profile](./profiles.md)** is just an agent and its loadout. "The engineer profile" is the `engineer` agent with everything it composes. There is no `profile.yml` and no `profiles:` map — the loadout lives on the agent.
+- A **[persona](./personas.md)** is a _convention_, not a resource: a base review agent (a base prompt plus how-to-review instructions) that reads an interchangeable persona description document — for example `docs/user-personas/coyote-road-runner-chaser.md` — as input. Swapping the input document swaps the persona.
+- A **[subagent](./subagents.md)** is an agent projected into the harness's native delegation mechanism, selected in another agent's `subagents` loadout. A leader agent delegates to local coding-harness subagents or to issue- and action-backed subagents.
 
-A composite profile is the temporary runtime configuration directory Outfitter assembles for one profile and one agent CLI run. It contains the generated files the agent needs, is created under the system temp directory, and is owned by Outfitter for the lifetime of the run — durable state is handled separately (see state persistence below).
+The same agent definition can be run directly or selected as a subagent elsewhere; its loadout decides what it composes.
 
-## Catalog / profile source
+## Layers
 
-A profile source is any place profiles are loaded from: a local directory (`path:`), a GitHub repository (`github: owner/repo`), or a git URI (`uri:`). A shared repository of profiles is called a catalog (or profile repository). Remote sources are cached under `~/.outfitter/cache/` and updated with `outfitter sync`; they support `ref` pinning and `only`/`except` filters. See [Profile repositories](./profile-repository.md).
+Resources resolve across layers, following the protocol's overlay semantics:
+
+1. `<project>/.agents/` — the workspace layer, committed with a project.
+2. `~/.agents/` — the global layer for one developer.
+3. Remote sources — pinned `.agents` payloads from [catalog repositories](./catalogs.md), in configured order.
+
+Resources merge **by ID**: a workspace `skills/wiki/` overrides a global or remote `skills/wiki/`. Agent-local skills merge by owner and ID, so `agents/actions/skills/debug/` is distinct from `agents/reviewer/skills/debug/`; the selected agent's local winner takes precedence over catalog-wide `skills/debug/`. JSON files such as `mcp.json` and `models.json` follow the protocol's JSON merge behavior. Standalone `.agents` repositories — where the repository root _is_ the payload — are the primary way to develop and share layers; see [Catalogs](./catalogs.md) and [Local development](./local-development.md).
 
 ## Settings scopes
 
-Outfitter reads `settings.yml` from three local scopes — user (`~/.outfitter/settings.yml`), project (`<project>/.outfitter/settings.yml`), and project-local (`<project>/.outfitter/local/settings.yml`, for personal, uncommitted overrides) — plus cached remote settings supplied by `remote_settings` entries. Settings declare the default profile and agent, profile sources, and other launch behavior.
+Outfitter's own settings live inside the `.agents` tree as `settings.yml`, with a flat, gitignored `settings.local.yml` beside it for personal machine-local overrides:
+
+- `~/.agents/settings.yml` — user defaults, plus optional `~/.agents/settings.local.yml`.
+- `<project>/.agents/settings.yml` — committed project settings.
+- `<project>/.agents/settings.local.yml` — personal, uncommitted overrides for that project. This flat file replaces the old nested project-local directory scope.
 
-## Controls
+Settings declare the default agent and harness, resource sources, and launch behavior — not resource selection, which lives on the agent. Removing the settings files leaves a pure protocol tree. See [Settings](./settings.md).
 
-Controls are the generic, agent-neutral knobs a profile sets: `model`, `provider`, `thinking`, `system_prompt`, `append_system_prompt`, `skills`, `extensions`, `args`, `environment`, and more. Profiles can also nest adapter-specific overrides under `controls.pi` or `controls.claude` when one agent needs different values.
+## One resolver
+
+Listing, validation, running, and dumping all share one resolver. What `outfitter list` shows is what `outfitter run` launches and what `outfitter dump` writes. See [Dump](./dump-and-bake.md).
 
 ## Adapters
 
-An adapter translates generic controls 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 a control it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md) for per-adapter coverage.
+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).
 
 ## State persistence
 
-Agents write state during a run — auth, native settings, plugins, sessions. Each adapter declares the state paths it understands and how writes are handled (`symlink`, `discard`, `warn`, `error`, or `prompt`), so useful state survives future runs without Outfitter silently copying unknown files. See [State persistence](./state.md).
+Agents write state during a run — auth, native settings, plugins, sessions. Each adapter declares the state paths it understands and how writes are handled (`symlink`, `discard`, `warn`, `error`, or `prompt`), so useful state survives future runs. See [State persistence](./state.md).
 
 ## Layer precedence
 
-When several layers define the same profile or setting, higher layers win:
+When several layers define the same resource ID or setting, higher layers win:
 
-1. Project-local (`.outfitter/local/`)
-2. Project (`.outfitter/`)
-3. User (`~/.outfitter/`)
+1. Project-local settings (`<project>/.agents/settings.local.yml`)
+2. Project (`<project>/.agents/`)
+3. User (`~/.agents/`, with `settings.local.yml` above `settings.yml`)
 4. Cached remote sources (in configured source order)
 5. Built-in defaults
-
-For profiles, explicitly inherited profiles slot between cached remote sources and built-in defaults, in declared order.