@ai-outfitter/outfitter 0.11.0 → 1.0.2

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

@@ -0,0 +1,30 @@
+# Dump
+
+`outfitter dump` is an output of Outfitter's resolver — the same resolver that backs `list`, `validate`, and `run`, so what you inspect is exactly what executes.
+
+## Dump
+
+`outfitter dump` writes the composed resource tree as a plain `.agents/` directory you can commit, diff, and review through a normal pull request:
+
+```bash
+outfitter dump --out ./review
+outfitter dump --agent engineer --out ./engineer   # one agent's transitive closure only
+```
+
+Use dumps to:
+
+- **Review** exactly what an organization or project composition resolves to before approving a source bump.
+- **Vendor** a self-contained tree into a repository for air-gapped or provenance-sensitive environments.
+- **Debug** layer and merge behavior by diffing dumps before and after a change.
+
+## Guarantees
+
+- **Deterministic** — identical sources, refs, and selections produce byte-identical output.
+- **Self-contained** — the dumped tree resolves with no remote sources and no cache.
+- **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.
+
+## Bake
+
+> **Status: future RFC.** Baking a repeatable unit of work and its structured inputs into an immutable execution artifact for headless runs is part of the [tasks](./tasks.md) design, which is being specified separately. Dump above already gives a deterministic, self-contained tree for an agent; the additional guarantees baking adds around inputs and task contracts are deferred to that RFC.

package/docs/documentation/first-time-cli-agent-users.md

@@ -14,7 +14,7 @@ You may inspect files, edit code, and run project tests.
 Ask before deleting files, changing dependencies, touching credentials, or publishing anything.
 ```
 
-Permissions are the safety boundary. A good session says what the agent may do, what it must ask about, and what evidence proves the job is done. Outfitter’s default profile catalog is meant to provide useful defaults, but you still own the trust decision for each project and command.
+Permissions are the safety boundary. A good session says what the agent may do, what it must ask about, and what evidence proves the job is done. Outfitter’s default catalog is meant to provide useful defaults, but you still own the trust decision for each project and command.
 
 Good first permission rules:
 
@@ -45,11 +45,11 @@ Read AGENTS.md, the README, package scripts, and the failing test before editing
 Then propose a three-step plan with acceptance criteria.
 ```
 
-Outfitter profiles can store reusable personal context, while `AGENTS.md` keeps project context in the repo. Pi also supports extension-provided tools and skills; the default profile catalog may include skills that add project-governance, review, or browser/testing instructions to the session.
+Your `~/.agents` tree stores reusable personal context, while `AGENTS.md` (or a project's `.agents/agents.md`) keeps project context in the repo. Pi also supports extension-provided tools and skills; the default catalog may include skills that add project-governance, review, or browser/testing instructions to the session.
 
 ## Planning mode
 
-Planning mode is provided by the plan Pi extension installed in the current Outfitter profile. In the default Outfitter Pi setup, use the plan-mode keybinding (`Shift+Tab`) to toggle from build mode into plan mode before broad changes. Plan mode keeps the agent in an investigation/design posture: read, inspect, and propose; do not write the implementation yet.
+Planning mode is provided by the plan Pi extension installed in the current Outfitter composition. In the default Outfitter Pi setup, use the plan-mode keybinding (`Shift+Tab`) to toggle from build mode into plan mode before broad changes. Plan mode keeps the agent in an investigation/design posture: read, inspect, and propose; do not write the implementation yet.
 
 Use the plan-mode keybinding when:
 
@@ -92,7 +92,7 @@ Subagents are useful for:
 - comparing approaches;
 - keeping risky experiments away from the main checkout.
 
-Whether subagents are available depends on the active Pi/Outfitter profile and extensions. The default profile catalog may include subagent definitions or guidance; vanilla agent CLIs differ in what they provide out of the box.
+Whether subagents are available depends on the active composition and extensions — see [Subagents](./subagents.md). The default catalog may include subagent definitions or guidance; vanilla agent CLIs differ in what they provide out of the box.
 
 ## Skills
 
@@ -104,13 +104,13 @@ Try inside Pi:
 /skill:generated-daily-report
 ```
 
-Then provide the goal or inputs the skill asks for. Other examples might be project review, browser testing, release notes, or incident summaries, depending on what the active profile installed.
+Then provide the goal or inputs the skill asks for. Other examples might be project review, browser testing, release notes, or incident summaries, depending on what the active agent installed.
 
-Skills may come from Pi packages, from the Outfitter default profile catalog, or from a project-local `.outfitter` profile. If a skill is not active, ask Pi what skills it can see before relying on it.
+Skills may come from Pi packages, from the Outfitter default catalog, or from a project's `.agents/skills/` directory. If a skill is not active, ask Pi what skills it can see before relying on it.
 
 ## Extensions and tools
 
-Extensions add tools and UI affordances to Pi. For example, an extension can expose a browser tool, a structured question UI, a GitHub helper, or an Outfitter setup command. These are not all vanilla Pi features; they appear when the active profile loads the relevant Pi package or extension.
+Extensions add tools and UI affordances to Pi. For example, an extension can expose a browser tool, a structured question UI, a GitHub helper, or an Outfitter setup command. These are not all vanilla Pi features; they appear when the active composition loads the relevant Pi package or extension.
 
 Ask:
 
@@ -134,4 +134,4 @@ You may read files and run non-destructive discovery commands.
 Ask before deleting files, changing dependencies, pushing, publishing, or touching credentials.
 ```
 
-After a few sessions, move the reusable parts into an Outfitter profile so every launch starts with your preferred operating style.
+After a few sessions, move the reusable parts into an [agent](./agents.md) definition in your `~/.agents` tree so every launch starts with your preferred operating style.

package/docs/documentation/getting-started.md

@@ -9,30 +9,44 @@ outfitter --help
 
 Outfitter launches agent CLIs; install the agents you plan to use separately.
 
+## Already have a `.agents/` directory?
+
+You're most of the way there. Outfitter reads the [Dotagents `.agents` protocol](./concepts.md#the-agents-protocol) directly — your existing agents, skills, knowledge, and commands are usable by slug with no conversion:
+
+```bash
+outfitter list          # see what resolves from ~/.agents and <project>/.agents
+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).
+
 ## First-time setup
 
-Set up profiles from the Outfitter [default profiles repo](https://github.com/ai-outfitter/default-profiles), then launch the default profile:
+Bootstrap from the Outfitter [default catalog](https://github.com/ai-outfitter/.agent), then launch the default agent:
 
 ```bash
 outfitter setup
 outfitter
 ```
 
-If you are new to Claude Code, Codex, Pi, and agent CLIs, start with [First-time CLI agent users](./first-time-cli-agent-users.md) for YOLO mode, permissions, context engineering, planning mode, subagents, skills, and extension basics. If you already have an agent workflow, use [Switching to Outfitter](./switching-to-outfitter.md) to migrate the smallest durable set of habits first.
+If you are new to Claude Code, Codex, Pi, and agent CLIs, start with [First-time CLI agent users](./first-time-cli-agent-users.md). If you already have an agent workflow, use [Switching to Outfitter](./switching-to-outfitter.md) to adopt the smallest durable set first.
 
-Learn how shared setup sources work in [Profile repositories](./profile-repository.md), then see [Profiles](./profiles.md) for profile composition, inheritance, and prompt examples.
+Learn how shared sources work in [Catalogs](./catalogs.md), then see [Agents](./agents.md), [Agent profiles](./profiles.md), and [Personas](./personas.md) for composition.
 
 ## Common commands
 
 ```bash
-outfitter run --profile engineering-default
-outfitter run --agent claude --profile support
+outfitter run engineer
+outfitter run reviewer --harness claude
 outfitter sync
-outfitter profile list
-outfitter profile create regulated --scope user
+outfitter list agents
+outfitter validate
+outfitter dump --out ./review
 ```
 
-See the [CLI reference](./cli.md) for every command and flag, and [Concepts](./concepts.md) for how settings, profiles, and adapters fit together. (`outfitter welcome` also exists as a legacy compatibility command for the older terminal onboarding prompts; current onboarding runs inside Pi via `outfitter setup`.)
+See the [CLI reference](./cli.md) for every command and flag, and [Concepts](./concepts.md) for how settings, resources, and adapters fit together.
 
 ## Other install options
 
@@ -47,3 +61,9 @@ Try without a global install:
 ```bash
 npx --yes @ai-outfitter/outfitter@latest --help
 ```
+
+Run directly from the repository's Nix flake:
+
+```bash
+nix run github:ai-outfitter/outfitter -- --help
+```

package/docs/documentation/hooks.md

@@ -0,0 +1,20 @@
+# Hooks
+
+Hooks let deterministic code run at fixed points in an agent session — before tool calls, after edits, at session start — independent of what the model decides. The `.agents` protocol does not yet define a hooks resource, so hook wiring is harness-specific today. This page documents what works per adapter and where this is heading.
+
+## Claude Code
+
+Claude Code hooks live in its native `settings.json` (`hooks` key), matching tool events to shell commands. Outfitter projects hook configuration into the composite `settings.json` it generates for a Claude launch, so a composition can ship hooks the same way it ships skills:
+
+- Keep hook scripts in a skill's `scripts/` directory or under `commands/`, so they travel with the tree and pass through the same [trust review](./catalogs.md#trust-and-review) as other executable content.
+- Machine-specific hook wiring stays in your local layer and is projected as harness-native config (the Claude `settings.json` Outfitter composes for that launch), not in a `settings.yml` key — the protocol schema defines no hooks field. Keep it out of shared catalogs.
+
+See the [Claude Code hooks documentation](https://code.claude.com/docs/en/hooks) for event types and matcher syntax.
+
+## Pi
+
+Pi supports a bootstrap hook via its extension mechanism: an extension passed with `--extension` runs at session start and can register tools, providers, and runtime behavior. Outfitter's own onboarding flow uses this channel. For recurring per-event behavior, Pi extensions are the native surface.
+
+## Roadmap
+
+> **TODO (protocol gap):** hooks are the one behavioral surface the pinned protocol revision does not model, which means hook definitions cannot yet be expressed portably in a `.agents` tree and projected per harness. The path `agents/<agent-id>/hooks/<hook-id>/` is reserved for a future agent-local hook entity and deliberately has no resolution or projection behavior today. Outfitter may need to ship its own hooks extension that adapters translate to Claude `settings.json` hooks and Pi extensions respectively, or drive the concept into a future protocol revision. Until one of those lands, treat hooks as harness-native configuration and keep them thin: call scripts that live in the tree rather than embedding logic in hook definitions.

package/docs/documentation/iterating-on-profiles.md

@@ -1,109 +1,95 @@
-# Iterating on local and worktree profiles
+# Iterating on an agent
 
-This guide covers the edit-run-inspect loop for profiles: switching to a profile you can edit, iterating on it locally or in a git worktree of a profile catalog, and verifying the result.
-It is written for people and for Outfitter-managed agents — if you are an agent reading this, the "Improving your own profile" section describes how to modify the profile you were launched with.
+This guide covers the edit-run-inspect loop for an [agent profile](./profiles.md): switching to an agent you can edit, iterating on its loadout and the resources it selects — locally or in a git worktree of a catalog — and verifying the result.
 
-## Where editable profiles live
+It is written for people and for Outfitter-managed agents — if you are an agent reading this, see [For Outfitter-managed agents](./local-development.md#for-outfitter-managed-agents) for how to improve the configuration you were launched with.
 
-Outfitter resolves profiles from every configured `profile_sources` entry.
-Three scopes are directly editable on the current machine:
+## Where editable resources live
 
-| Scope         | Profiles                               | Settings                                  | Use for                                   |
-| ------------- | -------------------------------------- | ----------------------------------------- | ----------------------------------------- |
-| user          | `~/.outfitter/profiles/`               | `~/.outfitter/settings.yml`               | Personal defaults shared across projects  |
-| project       | `<project>/.outfitter/profiles/`       | `<project>/.outfitter/settings.yml`       | Checked-in behavior the whole team gets   |
-| project-local | `<project>/.outfitter/local/profiles/` | `<project>/.outfitter/local/settings.yml` | Machine-private overrides and experiments |
+Outfitter resolves resources from every configured layer. Two are directly editable on the current machine:
 
-Profiles synced from a remote catalog (`github:` or `uri:` profile sources) land in the Outfitter cache.
-Do not edit the cache — `outfitter sync` overwrites it.
-To iterate on a catalog profile, work in a local checkout of the catalog instead (see the worktree section below).
+| Scope   | Resources            | Settings                                                  | Use for                                  |
+| ------- | -------------------- | --------------------------------------------------------- | ---------------------------------------- |
+| user    | `~/.agents/`         | `~/.agents/settings.yml` (+ `settings.local.yml`)         | Personal defaults shared across projects |
+| project | `<project>/.agents/` | `<project>/.agents/settings.yml` (+ `settings.local.yml`) | Checked-in behavior the whole team gets  |
 
-## Switching profiles
+An agent and its loadout live in `agents/<id>/` in one of those layers. Machine-private launch choices — which agent runs by default, where sources resolve from — belong in the flat, gitignored `settings.local.yml` of either scope; it overlays its sibling with the same schema.
 
-- One launch: `outfitter run --profile <id> [-- <agent args>]`
-- Future launches: set `default_profile: <id>` in the settings scope you want it to apply to.
-- List what is resolvable right now: `outfitter profile list` (add `--all` to include inheritance-only templates).
+Resources synced from a remote catalog land in the Outfitter cache. Do not edit the cache — `outfitter sync` overwrites it. To iterate on a catalog resource, work in a local checkout of the catalog instead (see the worktree section below).
 
-Profile changes apply on the next launch.
-A running session keeps the composite profile it started with, so after editing a profile you must restart `outfitter` to load the result.
+## Switching agents
+
+- One launch: `outfitter run <id> [-- <agent args>]`
+- Future launches: set `default_agent: <id>` in the settings scope you want it to apply to.
+- List what is resolvable right now: `outfitter list agents`.
+
+Changes apply on the next launch. A running session keeps the composition it started with, so after editing you must restart `outfitter` to load the result.
 
 ## The iteration loop
 
-1. Create or locate an editable profile:
+1. Create or copy an experimental agent in a layer you can edit, and trim its loadout to what you are testing:
 
-   ```sh
-   outfitter profile create my_experiment --scope project-local
+   ```
+   <!-- .agents/agents/experiment/agent.md -->
+   ---
+   name: experiment
+   description: Behavior I am trying out.
+   skills: [wiki]
+   model: gpt-5.2
+   thinking: high
+   ---
+
+   <the behavior you are trying out>
    ```
 
-To iterate on an existing profile without touching it, create a new profile that inherits from it:
+   Point your next launch at it either way:
 
-```yaml
-# .outfitter/local/profiles/my_experiment/profile.yml
-id: my_experiment
-label: My Experiment
-inherits:
-  - engineer
-controls:
-  append_system_prompt:
-    - |
-      <the behavior you are trying out>
-```
+   ```yaml
+   # .agents/settings.local.yml
+   default_agent: experiment
+   ```
 
-2. Point your next launch at it, either with `outfitter run --profile my_experiment` or by setting `default_profile: my_experiment` in `.outfitter/local/settings.yml`.
+2. Launch it: `outfitter run experiment`, or rely on the `default_agent` override above.
 
 3. Validate before launching:
 
    ```sh
-   outfitter profile lint --strict
+   outfitter validate --strict
    ```
 
-This reports schema and inheritance errors, missing typed prompt include files, and raw append-prompt strings that look like file paths.
+   This reports protocol layout errors, unresolved loadout slugs, and broken skill references.
+
+4. Inspect what the agent actually received:
 
-4. Inspect what the agent actually received.
-   With `profile_export: true` in the active settings, Outfitter writes the composed system prompt next to the profile (`generated-system-prompt.md` in a directory profile, `<id>.generated-system-prompt.md` beside a flat profile).
-   Diff it between iterations to confirm a change landed.
+   ```sh
+   outfitter dump --agent experiment --out /tmp/inspect
+   ```
 
-5. Restart and test the behavior, then fold the settled changes back into the profile the experiment inherited from.
+   Diff dumps between iterations to confirm a change landed — the dump is exactly what run composes.
 
-## Iterating on a catalog profile in a git worktree
+5. Restart and test the behavior, then fold the settled changes back into the agent or skill you were iterating on, and remove the experiment.
 
-Shared profiles usually come from a catalog repository (see [Profile repositories](./profile-repository.md)) referenced as a `github:` source.
-To change one:
+## Iterating on a catalog resource in a git worktree
+
+Shared resources usually come from a [catalog](./catalogs.md) referenced as a pinned `github:` source. To change one:
 
 1. Clone the catalog, or add a worktree to an existing clone so the iteration branch stays isolated:
 
    ```sh
-   cd ~/repos/acme/profile-catalog/main
+   cd ~/repos/acme/agents-catalog/main
    git worktree add ../worktrees/feat/sharper-review-prompts -b feat/sharper-review-prompts
    ```
 
-2. Point a machine-private profile source at the worktree in `.outfitter/local/settings.yml` (or `~/.outfitter/settings.yml`).
-   Local `path:` sources take the same layout as the catalog:
+2. Point a machine-private source at the worktree in `settings.local.yml` (project or user scope):
 
    ```yaml
-   # .outfitter/local/settings.yml
-   profile_sources:
-     - path: ~/repos/acme/profile-catalog/worktrees/feat/sharper-review-prompts/profiles
+   # .agents/settings.local.yml
+   sources:
+     - path: ~/repos/acme/agents-catalog/worktrees/feat/sharper-review-prompts
    ```
 
-3. Iterate with the loop above: edit in the worktree, `outfitter profile lint --strict`, relaunch, inspect the prompt export.
-
-4. Commit in the worktree, push, and open a pull request against the catalog.
-   After it merges, remove the local `path:` override, run `outfitter sync` to refresh the cached catalog, and remove the worktree.
-
-Because the override lives in project-local settings, teammates and CI keep resolving the published catalog while you iterate.
-
-## Improving your own profile (for Outfitter-managed agents)
-
-If you are an agent launched by Outfitter, your instructions, tools, skills, and extensions came from a profile, and you can improve that profile the same way you improve code — but the change only takes effect for future sessions, never the current one.
+3. Iterate with the loop above: edit in the worktree, `outfitter validate --strict`, relaunch, diff the dump.
 
-1. Identify your active profile.
-   The launch header and `outfitter profile list` show profile ids; your composite profile directory contains `outfitter/profile.json` with the id, label, and merged controls you were launched with.
-2. Find the editable source for that profile with the scope table above.
-   If the profile comes from a remote catalog, do not edit the cache — use the worktree flow above, or create a local profile that `inherits` from it and layer the improvement on top.
-3. Make the smallest change that captures the improvement: a new `append_system_prompt` entry for a behavior correction, a `skills` entry for a reusable procedure, or a control override (model, thinking level, environment) for launch mechanics.
-4. Validate with `outfitter profile lint --strict`, and review the `profile_export` prompt output when prompt text changed.
-5. Tell the user what you changed and why, and that the change applies when they restart `outfitter` (or launch `outfitter run --profile <id>`).
-   You cannot reload your own profile mid-session.
+4. Commit in the worktree, push, and open a pull request against the catalog. After it merges, remove the local `path:` override, bump the pinned `ref:`, run `outfitter sync`, and remove the worktree.
 
-Prefer durable, reviewable improvements: put team-relevant changes in the project or catalog profile through a pull request, and keep personal or experimental changes in user or project-local scope.
+Because the override lives in `settings.local.yml`, teammates and CI keep resolving the published catalog while you iterate. This is the same trickle-up workflow as [Local development](./local-development.md), applied to one change.

package/docs/documentation/local-development.md

@@ -0,0 +1,84 @@
+# Local dotagents development
+
+The recommended way to develop agent configuration is a **personal standalone `.agents` repository** — a repo whose root is the protocol payload (for example [`ncrmro/.agents`](https://github.com/ncrmro/.agents)). You iterate there with full git history, point your machine at local checkouts while you work, and open pull requests to move settled improvements upstream into shared catalogs. Changes trickle up instead of living forever in one person's home directory.
+
+## The repository
+
+```text
+ncrmro/.agents/
+  agents.md
+  agents/
+    founder/agent.md
+    engineer/agent.md
+  skills/
+  settings.yml           # committed: pinned upstream sources, default agent
+  settings.local.yml     # gitignored: this machine's overrides
+  .gitignore             # settings.local.yml, *.generated-*
+```
+
+Clone it as your global layer, or point your user settings at the checkout:
+
+```bash
+git clone git@github.com:ncrmro/.agents.git ~/.agents
+```
+
+## Committed settings: pin upstream
+
+The committed `settings.yml` consumes shared catalogs **pinned to exact commits**, so the repository is reproducible on any machine:
+
+```yaml
+# settings.yml (committed)
+default_agent: founder
+
+sources:
+  - github: ai-outfitter/.agent
+    ref: 2f9c1ab0d3e44b6f9d2c8a17e5b40c91d6f3a8e2
+  - github: ai-outfitter/community-profiles
+    ref: 8d04c7a1f2e94b3c6a5d80e17f4b29c3d1e6a075
+  - path: . # this repository's own resources win last
+```
+
+Bumping a pin is an ordinary reviewed commit: sync, diff the upstream change, update the SHA.
+
+## Local settings: point at checkouts
+
+When you are changing an upstream catalog itself, override its source in the gitignored `settings.local.yml` to an absolute path of your local checkout:
+
+```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
+```
+
+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:
+
+```sh
+cd ~/repos/acme/agents-catalog/main
+git worktree add ../worktrees/feat/sharper-review -b feat/sharper-review
+```
+
+## The loop
+
+1. Edit resources — an `agent.md`, a skill — in whichever checkout owns them.
+2. Validate: `outfitter validate --strict`.
+3. Inspect what a run would actually receive: `outfitter dump --agent founder --out /tmp/inspect` and diff between iterations.
+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`, …).
+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
+
+A project that wants your personal layer doesn't need anything special — `~/.agents` _is_ the global layer. For project-specific wiring, a project's `.agents/settings.local.yml` can also point a source at your checkout, keeping teammates and CI on the published pins while you iterate.
+
+## For Outfitter-managed agents
+
+If you are an agent launched by Outfitter, your instructions, skills, and subagents came from resolved `.agents` layers, and you can improve them like code — the change takes effect for future sessions, never the current one:
+
+1. `outfitter list` shows each resolved resource and its winning source.
+2. Never edit the sync cache — it is overwritten. Edit the checkout the source points at, or the user/workspace layer that shadows it.
+3. Make the smallest change that captures the improvement, run `outfitter validate --strict`, and tell the user what you changed, why, and that it applies on restart.
+4. Put team-relevant changes in the upstream catalog through a pull request; keep personal or experimental changes in the personal repo or `settings.local.yml` scope.

package/docs/documentation/migration.md

@@ -0,0 +1,39 @@
+# Migration from legacy profiles
+
+Earlier Outfitter versions used an authored profile system: `.outfitter/` directories, `profile.yml` files, profile inheritance, and `--profile` pointing at profile definitions. [RFC #165](https://github.com/ai-outfitter/outfitter/issues/165) replaces that system with the Dotagents `.agents` protocol as a hard cut: the end-state runtime has **no knowledge of the old format** — no compatibility reader, no migration command, no deprecated aliases. (These docs describe that target; the released CLI still runs the legacy profile format during the transition.) This page is the manual migration reference, and the bundled Outfitter skill can walk an agent session through it interactively.
+
+## Mapping
+
+| Legacy                                                  | End state                                                                                                                                                                                        |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.outfitter/profiles/<id>/profile.yml` (or `<id>.yml`)  | Split into resources: identity → `agents/<id>/agent.md`, procedures → `skills/`; the loadout lives in that [agent](./profiles.md)'s frontmatter / `config.json` — there is no separate selection |
+| `controls.system_prompt` / `append_system_prompt`       | `system-prompt.md`, `agents.md`, and the agent's `agent.md` body                                                                                                                                 |
+| `controls.model`, `provider`, `thinking`                | `models.json` (and per-agent `config.json`)                                                                                                                                                      |
+| `controls.skills`                                       | The agent's `skills:` loadout; skills live at `skills/<id>/`                                                                                                                                     |
+| `controls.extensions`, `args`, `environment`            | Harness configuration projected by adapters; MCP servers → `mcp.json`                                                                                                                            |
+| Profile inheritance (`inherits:`)                       | Layer merge-by-ID, plus shared context in `system-prompt.md` / `agents.md`                                                                                                                       |
+| `template: true` base profiles                          | A base agent whose shared context lives in `system-prompt.md` / `agents.md` (or a base agent selected as a delegate)                                                                             |
+| `~/.outfitter/settings.yml`                             | `~/.agents/settings.yml`                                                                                                                                                                         |
+| `<project>/.outfitter/settings.yml`                     | `<project>/.agents/settings.yml`                                                                                                                                                                 |
+| `<project>/.outfitter/local/settings.yml` (nested dir)  | `<project>/.agents/settings.local.yml` (flat, gitignored)                                                                                                                                        |
+| `profile_sources`                                       | `sources` supplying `.agents` payloads ([catalogs](./catalogs.md))                                                                                                                               |
+| `default_profile`                                       | `default_agent` naming an agent slug                                                                                                                                                             |
+| `outfitter run --profile <file-based id>`               | `outfitter run <agent-id>` (choose the harness with `--harness pi\|claude`)                                                                                                                      |
+| `outfitter profile list` / `create` / `lint`            | `outfitter list agents` / author files directly / `outfitter validate`                                                                                                                           |
+| `profile_export` / `generated-system-prompt.md`         | `outfitter dump` ([Dump and bake](./dump-and-bake.md))                                                                                                                                           |
+| Free-form CI prompt + profile in `ai-outfitter/actions` | An agent run with structured inputs ([Actions](./actions.md)); the task/bake surface is a [future RFC](./tasks.md)                                                                               |
+
+## Procedure
+
+1. **Inventory** your `.outfitter/profiles`. For each profile, separate what it contains: identity/policy prose, capability procedures, model/provider config, tool wiring.
+2. **Create resources**: one `agents/<id>/agent.md` per durable identity; one `skills/<id>/` per capability (most `append_system_prompt` procedure text belongs in skills); shared context into `agents.md`; model config into `models.json`; MCP into `mcp.json`.
+3. **Rebuild as agents**: for each profile people actually ran, create an `agents/<id>/agent.md` whose frontmatter (or `config.json`) loadout selects the new resources by slug. Set `default_agent` to the one you run most. Inheritance chains become shared context in `system-prompt.md` / `agents.md` (or a base agent selected as a delegate), not an ordered selection.
+4. **Move settings**: relocate `~/.outfitter/settings.yml` content into `~/.agents/settings.yml`, project settings into `<project>/.agents/settings.yml`, and anything under `.outfitter/local/` into a flat `.agents/settings.local.yml` (gitignore it). Rename `profile_sources` to `sources`; sources must now publish `.agents` payloads.
+5. **Validate**: `outfitter validate --strict`, then `outfitter dump` and review the tree.
+6. **Delete** the `.outfitter/` directory once the dump matches expectations.
+
+A remote repository _named_ `.outfitter` remains a supported convention for organization control repos — but only when it publishes the new protocol payload. 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.

package/docs/documentation/personas.md

@@ -0,0 +1,41 @@
+# Personas
+
+A persona is not a resource or a settings key — it is a **convention** built from ordinary pieces:
+
+1. A **base review agent** — a normal [agent](./agents.md) whose prompt says how to review something (an app, docs, a UX flow): what to look at, what evidence to cite, what output shape to return.
+2. Interchangeable **persona description documents** — plain markdown files with attributes in frontmatter and a short bio underneath. They come in two kinds you **mix and match**: a **role** (a reusable job archetype — goals, anxieties, buying triggers shared across a customer segment) and an **individual** (a named person with demographics — birthdate, income, education, hobbies, skills — who inherits one or more roles and adds their own voice). Give each the concreteness a [Lean Canvas](https://leanstack.com/lean-canvas) customer segment gets.
+
+You run the base agent and feed it the persona files to adopt: a role, refined by an individual. Swapping the files swaps the persona; the base agent — the review rules — stays fixed. Nothing new is added to the protocol: it is one agent plus a folder of description files. See [Persona reviews](./usecases/persona-reviews.md) for the full shape.
+
+```text
+customer-review/
+  agents/
+    reviewer/agent.md          # base: how to review, what to return
+  settings.yml
+docs/user-personas/
+  roles/                       # reusable job archetypes
+    staff-engineer.md
+    founder-operator.md
+  individuals/                 # named people, each naming one or more roles
+    marcus-bell.md
+    dana-okafor.md
+```
+
+## Why a convention, not a key
+
+Modeling personas as their own resource — or as a `personas:` list you compose in order — duplicates what an agent already is and grows the surface area of the system. Agents are exactly what that machinery was reaching for. Keeping personas as "base agent + description document" means a team maintains one review agent and a directory of cheap markdown files, instead of a fleet of near-identical agents.
+
+## Running a persona review
+
+Point the base agent at the artifact and name the persona files to adopt — a role refined by an individual:
+
+```bash
+outfitter run reviewer -- --print \
+  "Adopt docs/user-personas/roles/founder-operator.md refined by \
+   docs/user-personas/individuals/dana-okafor.md. Review README.md and \
+   docs/getting-started.md and return the standard review shape."
+```
+
+Because the base agent fixes the output shape, feedback from different persona documents stays directly comparable.
+
+See [Persona reviews](./usecases/persona-reviews.md) for a complete catalog example.

package/docs/documentation/porting-claude.md

@@ -0,0 +1,54 @@
+# Porting a Claude Code setup
+
+If your agent configuration lives in `~/.claude`, Outfitter can port it into `~/.agents/` — the protocol's global layer — and symlink it back so Claude Code keeps working natively while the `.agents` tree becomes the source of truth.
+
+```bash
+outfitter setup
+```
+
+Setup detects an existing `~/.claude` directory (when no `~/.agents/` tree exists yet) and offers the port. Nothing is destroyed: originals are moved, not copied-and-diverged, and the symlinks keep native Claude Code behavior identical.
+
+## What gets ported
+
+| `~/.claude` content      | `~/.agents/` destination | Symlinked back? |
+| ------------------------ | ------------------------ | --------------- |
+| `agents/<id>.md`         | `agents/<id>/agent.md`   | Yes             |
+| `skills/<id>/`           | `skills/<id>/`           | Yes             |
+| `commands/`              | `commands/`              | Yes             |
+| `CLAUDE.md`              | `agents.md`              | Yes             |
+| MCP server configuration | `mcp.json`               | Yes             |
+
+After the port, `~/.claude/skills` is a symlink into `~/.agents/skills`, and so on — Claude Code reads exactly what it read before, from the protocol tree. Editing either view edits the same files.
+
+## What stays native
+
+Runtime and account state is not configuration and stays in `~/.claude` untouched:
+
+- auth and account state
+- sessions and project history (`projects/`)
+- plugins, caches, debug output
+- `settings.json` — permissions, model, and hooks remain harness-native; see [Hooks](./hooks.md) for how hook wiring relates to the tree
+
+This is the same boundary [state persistence](./state.md) enforces at run time: configuration lives in the tree, mutable state lives with the harness.
+
+## After porting
+
+Your resources are now protocol resources. Reference them by slug from an agent's loadout like anything else:
+
+```
+<!-- ~/.agents/agents/daily/agent.md -->
+---
+name: daily
+skills: [wiki, code-review] # formerly ~/.claude/skills/*
+---
+```
+
+- `outfitter list` shows everything that resolved from the ported tree.
+- `outfitter run daily --harness claude` launches Claude Code through Outfitter with the same material, now composable with catalogs and other layers.
+- Plain `claude` continues to work as before, through the symlinks.
+
+Consider putting `~/.agents` under version control as a standalone repository — see [Local development](./local-development.md).
+
+## Projects
+
+The same port applies per project: a `<repo>/.claude` directory ports to `<repo>/.agents/` (the workspace layer) with symlinks back, and a `CLAUDE.md` at the repo root can become `.agents/agents.md`. Commit the `.agents/` tree; gitignore `.agents/settings.local.yml`.