@ai-outfitter/outfitter 0.11.0 → 1.0.2

package/dist/validation/SchemaValidator.js

@@ -1,22 +1,13 @@
-// Validates parsed Outfitter YAML documents against bundled JSON Schemas.
+// Validates parsed Outfitter YAML/JSON documents against bundled JSON Schemas.
 import { readFileSync } from 'node:fs';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 const readSchema = (schemaFileName) => JSON.parse(readFileSync(new URL(`../schemas/${schemaFileName}`, import.meta.url), 'utf8'));
 const settingsSchema = readSchema('settings.schema.json');
-const profileSchema = readSchema('profile.schema.json');
-const profileSourceSchema = readSchema('profile-source.schema.json');
-const createAjv = () => {
-    const ajv = new Ajv2020({ allErrors: true });
-    ajv.addSchema(profileSourceSchema, 'profile-source.schema.json');
-    ajv.addSchema(profileSchema, 'profile.schema.json');
-    ajv.addSchema(settingsSchema, 'settings.schema.json');
-    return ajv;
-};
-const ajv = createAjv();
+const agentSchema = readSchema('agent.schema.json');
+const ajv = new Ajv2020({ allErrors: true });
 const validators = {
     settings: ajv.compile(settingsSchema),
-    profile: ajv.compile(profileSchema),
-    'profile-source': ajv.compile(profileSourceSchema),
+    agent: ajv.compile(agentSchema),
 };
 export const createValidationResult = (issues) => ({
     valid: issues.length === 0,

package/dist/validation/SchemaValidator.js.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaValidator.js","sourceRoot":"","sources":["../../src/validation/SchemaValidator.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAc3C,MAAM,UAAU,GAAG,CAAC,cAAsB,EAAW,EAAE,CACrD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,cAAc,cAAc,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7F,MAAM,cAAc,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAC1D,MAAM,aAAa,GAAG,UAAU,CAAC,qBAAqB,CAAC,CAAC;AACxD,MAAM,mBAAmB,GAAG,UAAU,CAAC,4BAA4B,CAAC,CAAC;AAErE,MAAM,SAAS,GAAG,GAAY,EAAE;IAC9B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,GAAG,CAAC,SAAS,CAAC,mBAAgC,EAAE,4BAA4B,CAAC,CAAC;IAC9E,GAAG,CAAC,SAAS,CAAC,aAA0B,EAAE,qBAAqB,CAAC,CAAC;IACjE,GAAG,CAAC,SAAS,CAAC,cAA2B,EAAE,sBAAsB,CAAC,CAAC;IACnE,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;AAExB,MAAM,UAAU,GAAyC;IACvD,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,cAA2B,CAAC;IAClD,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,aAA0B,CAAC;IAChD,gBAAgB,EAAE,GAAG,CAAC,OAAO,CAAC,mBAAgC,CAAC;CAChE,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAkC,EAAoB,EAAE,CAAC,CAAC;IAC/F,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;IAC1B,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAsB,EAAE,QAAiB,EAAoB,EAAE;IAC5F,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,sBAAsB,CAAE,QAAQ,CAAC,MAAiC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAmB,EAAE,CAAC,CAAC;IAC/D,IAAI,EAAE,KAAK,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY;IAC1D,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;CAC/B,CAAC,CAAC"}
+{"version":3,"file":"SchemaValidator.js","sourceRoot":"","sources":["../../src/validation/SchemaValidator.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAc3C,MAAM,UAAU,GAAG,CAAC,cAAsB,EAAW,EAAE,CACrD,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,cAAc,cAAc,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7F,MAAM,cAAc,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAEpD,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAE7C,MAAM,UAAU,GAAyC;IACvD,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,cAA2B,CAAC;IAClD,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,WAAwB,CAAC;CAC7C,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAAkC,EAAoB,EAAE,CAAC,CAAC;IAC/F,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;IAC1B,MAAM;CACP,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAsB,EAAE,QAAiB,EAAoB,EAAE;IAC5F,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,sBAAsB,CAAE,QAAQ,CAAC,MAAiC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AACjG,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAmB,EAAE,CAAC,CAAC;IAC/D,IAAI,EAAE,KAAK,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY;IAC1D,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;CAC/B,CAAC,CAAC"}

package/docs/architecture/state_writeback_strategy.md

@@ -1,82 +1,66 @@
 # State Writeback Strategy
 
-This document describes Outfitter's current model for handling writes that agent CLIs make inside a composite profile.
+This document describes Outfitter's model for handling writes that agent CLIs make inside a temporary projection — the generated configuration directory an adapter builds from a baked composition.
 
-A composite profile is temporary, but agent CLIs sometimes perform intentionally durable writes, such as logging in, installing plugins, changing settings, or updating MCP configuration.
-Outfitter makes those paths explicit: adapter-declared writable paths are materialized with a resolved `state_persistence` strategy before the child CLI starts, and non-persistent or unknown writes are diagnosed after the child exits.
+A projection is temporary, but agent CLIs sometimes perform intentionally durable writes, such as logging in, installing plugins, changing settings, or updating MCP configuration. Outfitter makes those paths explicit: adapter-declared writable paths are materialized with a resolved `state_persistence` strategy before the child CLI starts, and non-persistent or unknown writes are diagnosed after the child exits.
 
 ## Functional model
 
-Outfitter separates three kinds of files that may exist in a composite profile:
+Outfitter separates three kinds of files that may exist in a projection:
 
-1. **Generated runtime files**: files Outfitter assembles from settings, profiles, templates, and adapter rules.
-   Outfitter may regenerate these while the child agent is running when their source inputs change.
+1. **Generated runtime files**: files Outfitter assembles from the baked composition and adapter rules.
 2. **Declared state paths**: adapter-known files or directories the agent CLI may update intentionally, such as auth, settings, MCP config, plugins, caches, and sessions.
 3. **Unknown writes**: files or directories the agent creates outside the adapter-declared state paths.
 
-Only declared state paths can be made durable automatically.
-Unknown writes are never silently persisted because Outfitter does not know their intended owner, merge rules, or durable destination.
-Generated runtime files and declared state paths are deliberately handled separately so live profile/template updates do not erase or re-baseline agent state changes made during the same run.
+Only declared state paths can be made durable automatically. Unknown writes are never silently persisted because Outfitter does not know their intended owner, merge rules, or durable destination. Generated runtime files and declared state paths are deliberately handled separately so composition regeneration does not erase or re-baseline agent state changes made during the same run.
 
 The user-facing state update lifecycle is:
 
-1. **Choose a profile**.
-   Profile resolution determines the effective `state_persistence` map using normal profile precedence.
-2. **Resolve adapter defaults**.
-   For each path the selected adapter declares, Outfitter uses the profile override when present and otherwise uses the adapter default.
-3. **Prepare the composite profile**.
-   Durable paths are connected to a profile-managed or native CLI location; non-durable paths are created as normal temporary composite profile paths.
-4. **Run the agent**.
-   The agent CLI reads and writes the composite profile as if it were its normal configuration directory.
-5. **Classify changes after exit**.
-   Outfitter checks non-durable declared paths and unknown paths and reports or fails according to their strategies.
-6. **Clean up temporary state**.
-   Temporary composite profile contents are discarded; durable symlink targets remain in their profile or native CLI location.
+1. **Resolve settings.** Settings resolution determines the effective `state_persistence` map using normal settings precedence (`settings.local.yml` over `settings.yml`, project over user).
+2. **Resolve adapter defaults.** For each path the selected adapter declares, Outfitter uses the settings override when present and otherwise uses the adapter default.
+3. **Prepare the projection.** Durable paths are connected to a native CLI location; non-durable paths are created as normal temporary projection paths.
+4. **Run the agent.** The agent CLI reads and writes the projection as if it were its normal configuration directory.
+5. **Classify changes after exit.** Outfitter checks non-durable declared paths and unknown paths and reports, prompts, or fails according to their strategies.
+6. **Clean up temporary state.** Temporary projection contents are discarded; durable symlink targets remain in their native CLI location.
 
 ## Current behavior
 
-- Composite profiles remain temporary and reproducible by default.
+- Projections remain temporary and reproducible by default.
 - Outfitter does not do generic post-run copy-back or JSON/YAML merge-back.
-- Persistent state is represented by symlinking a composite profile path to a profile file/directory or to the native CLI fallback path.
-- Adapters may generate a concrete runtime file for a declared state path when they need deterministic launch-time reconciliation.
-  For example, the Pi adapter can generate a transformed `settings.json` that removes native `packages` entries already supplied by profile-controlled extensions, and then mark that declared path as `discard` for write detection during the run.
-- Every adapter-declared state path has a resolved strategy before launch: profile overrides win, otherwise the adapter `default_strategy` is used, except for adapter-generated reconciliation files that are intentionally treated as discarded runtime files.
-- Invalid or disallowed profile-requested `state_persistence` strategies fail before launch; adapter-internal reconciliation may still choose a one-run handling strategy for a generated runtime file.
+- Persistent state is represented by symlinking a projection path to the native CLI fallback path.
+- Adapters may generate a concrete runtime file for a declared state path when they need deterministic launch-time reconciliation. For example, the Pi adapter can generate a transformed `settings.json` that removes native `packages` entries already supplied by composition-controlled extensions, and then mark that declared path as `discard` for write detection during the run.
+- Every adapter-declared state path has a resolved strategy before launch: settings overrides win, otherwise the adapter `default_strategy` is used, except for adapter-generated reconciliation files that are intentionally treated as discarded runtime files.
+- Invalid or disallowed requested `state_persistence` strategies fail before launch; adapter-internal reconciliation may still choose a one-run handling strategy for a generated runtime file.
 - Non-persistent `warn` and `error` strategies are checked after the child CLI exits.
 - Unknown writes outside adapter-declared paths are checked with the adapter's `unknown` pseudo-path strategy.
-- `prompt` is reserved for a future interactive/control-plane workflow.
-  When accepted by a declaration today, it is treated as a non-persistent diagnostic like `warn`.
+- Baked artifacts and dumps never include declared state paths or their contents; state is runtime, not configuration.
 
 ## Non-goals
 
-- Outfitter does not implement generic copy-back from the composite profile to profiles.
+- Outfitter does not implement generic copy-back from the projection to `.agents` trees.
 - Outfitter does not implement generic structured merge-back.
 - Outfitter does not silently persist unknown writes.
 
-## Profile stack and native fallback
+## Settings resolution and native fallback
 
-State persistence is a normal profile setting.
-Its strategy overrides resolve through the same selected-profile stack as other profile data. When the user provides `--profile X`, only definitions of `X` and its explicit inheritance chain participate; the configured `default_profile` is selected only when no explicit profile is provided.
+State persistence is a normal Outfitter setting. Its strategy overrides resolve through the same settings precedence as other settings data:
 
 ```text
-project-local definition of selected profile
-project definition of selected profile
-user definition of selected profile
-URI/cache definitions of selected profile
-explicit inheritance
+<project>/.agents/settings.local.yml
+<project>/.agents/settings.yml
+~/.agents/settings.local.yml
+~/.agents/settings.yml
+cached remote settings
 Outfitter defaults
 ```
 
-Native CLI state is not represented as an extra profile layer.
-For `symlink` paths without a profile-provided source, 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/`.
-This native fallback is not a base profile: it does not participate in profile inheritance or merge precedence, and it cannot contribute controls or profile YAML.
-Claude Code `projects/` is additionally controlled by `controls.session_directory` or `controls.claude.session_directory` when set.
+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.
 
 ## Path-keyed adapter declarations
 
-Adapters declare writable state paths directly, using relative file paths as keys.
-Directory paths use a trailing slash.
-The same key is used for adapter coverage, `state_persistence` overrides, profile resource lookup, native fallback lookup, and composite profile materialization.
+Adapters declare writable state paths directly, using relative file paths as keys. Directory paths use a trailing slash. The same key is used for adapter coverage, `state_persistence` overrides, native fallback lookup, and projection materialization.
 
 The Pi adapter currently declares:
 
@@ -90,11 +74,12 @@ state_paths:
     default_strategy: symlink
     allowed_strategies: [symlink, warn, error, prompt]
     note: >-
-      When profile-controlled Pi extensions duplicate native settings packages,
-      Outfitter may generate a transformed runtime settings.json and treat this
-      declared path as discard for that launch. That discard handling is
-      adapter-internal; users still cannot request settings.json: discard
-      because discard is not listed in allowed_strategies.
+      When composition-controlled Pi extensions duplicate native settings
+      packages, Outfitter may generate a transformed runtime settings.json and
+      treat this declared path as discard for that launch. That discard
+      handling is adapter-internal; users still cannot request
+      settings.json: discard because discard is not listed in
+      allowed_strategies.
 
   keybindings.json:
     default_strategy: symlink
@@ -190,43 +175,9 @@ state_paths:
     allowed_strategies: [discard, warn, error, prompt]
 ```
 
-## Profile layout for state files
-
-State files live under the relevant CLI-specific profile folder:
-
-```text
-profiles/
-  default/
-    profile.yml
-    cli_specific/
-      pi/
-        auth.json
-        settings.json
-        keybindings.json
-        plugins/
-      claude/
-        settings.json
-        skills/
-        commands/
-        plugins/
-```
-
-Except for special adapter paths described below, when a selected strategy is `symlink`, Outfitter searches the resolved profile folders from highest to lowest precedence for `cli_specific/<adapter>/<state-path>`.
-If a profile contains the file or directory, Outfitter symlinks the composite profile path to that source.
-
-For most Pi paths, if no profile source exists, Outfitter falls back to the corresponding native Pi agent path under `~/.pi/agent`.
-Missing native fallback files/directories are created so the composite profile symlink has a durable destination.
-
-Pi `utilities/` and `bin/` are special cache-backed paths: both resolve to `<cache_directory>/utilities` instead of profile or native Pi state.
-This keeps pi-managed helper binaries reusable across temporary composite profiles without treating them as user-editable profile files.
-
-For most Claude Code paths, if no profile source exists, Outfitter falls back to the corresponding native Claude Code path under `~/.claude`.
-Claude Code `projects/` is special: `controls.claude.session_directory` overrides generic `controls.session_directory`, and the selected session directory becomes the `projects/` symlink source.
-If neither session-directory control is present, `projects/` falls back to `~/.claude/projects`.
-
 ## `state_persistence`
 
-Profiles may override persistence by mapping adapter-declared paths to strategy names:
+Settings may override persistence by mapping adapter-declared paths to strategy names:
 
 ```yaml
 state_persistence:
@@ -238,11 +189,9 @@ state_persistence:
   unknown: warn
 ```
 
-The values are concrete strategy names.
-`state_persistence` only needs overrides; omitted paths use the adapter declaration's `default_strategy`.
+The values are concrete strategy names. `state_persistence` only needs overrides; omitted paths use the adapter declaration's `default_strategy`.
 
-`state_persistence` is validated by the profile JSON Schema at read boundaries.
-Outfitter also validates the resolved strategy against the adapter declaration before launch.
+`state_persistence` is validated by the settings JSON Schema at read boundaries. Outfitter also validates the resolved strategy against the adapter declaration before launch.
 
 Functional examples:
 
@@ -256,7 +205,7 @@ state_persistence:
 ```
 
 ```yaml
-# CI profile: fail if pi changes settings, MCP config, or unknown files.
+# CI settings: fail if pi changes settings, MCP config, or unknown files.
 state_persistence:
   settings.json: error
   mcp.json: error
@@ -265,25 +214,25 @@ state_persistence:
 ```
 
 ```yaml
-# Exploratory profile: allow plugin experiments but report them after exit.
+# Exploratory settings: allow plugin experiments but report them after exit.
 state_persistence:
   plugins/: warn
   unknown: warn
 ```
 
-## Composite profile materialization
+## Projection materialization
 
 Before launch, Outfitter processes each adapter-declared state path:
 
-1. Resolve the path's strategy from profile `state_persistence` overrides, then the adapter `default_strategy`.
+1. Resolve the path's strategy from `state_persistence` overrides, then the adapter `default_strategy`.
 2. Validate that the strategy is allowed for that path.
-3. Resolve a source path through the profile hierarchy when the strategy is `symlink`.
-4. Materialize the composite profile path.
+3. Resolve the native fallback source when the strategy is `symlink`; missing native fallback files/directories are created so the symlink has a durable destination.
+4. Materialize the projection path.
 5. Record a baseline fingerprint for non-persistent and unknown write detection.
 
-For `symlink`, Outfitter creates a symlink from the composite profile path to the resolved profile or native CLI source.
+For `symlink`, Outfitter creates a symlink from the projection path to the resolved native CLI source. For `discard`, `warn`, `error`, and `prompt`, Outfitter creates normal temporary projection paths where needed and observes whether they changed.
 
-For `discard`, `warn`, `error`, and `prompt`, Outfitter creates normal temporary composite profile paths where needed and observes whether they changed.
+Pi `utilities/` and `bin/` are special cache-backed paths: both resolve to `<cache_directory>/utilities` instead of native Pi state, keeping pi-managed helper binaries reusable across temporary projections. Claude Code `projects/` uses the configured session directory when set, otherwise `~/.claude/projects`.
 
 ## Unknown writes
 
@@ -294,57 +243,40 @@ state_persistence:
   unknown: warn
 ```
 
-Supported `unknown` strategies are non-persistent only:
-
-- `discard`
-- `warn`
-- `error`
-- `prompt`
-
-`unknown` does not support `symlink`, because there is no declared durable destination.
+Supported `unknown` strategies are non-persistent only: `discard`, `warn`, `error`, and `prompt`. `unknown` does not support `symlink`, because there is no declared durable destination; `unknown: prompt` reports as a warning with an explanation.
 
 ## Strategy selection guide
 
-Use `symlink` when a write is part of durable agent setup, such as logging in, editing native settings, updating MCP config, or installing plugins that should be reused.
-Use `discard` when the data is useful only during the current run, such as cache entries or throwaway sessions.
-Use `warn` when mutation is acceptable but should be visible to the user.
-Use `error` when mutation means the run was not reproducible enough, especially in CI or locked-down project profiles.
-Use `prompt` only as a forward-compatible declaration for future interactive handling.
+Use `symlink` when a write is part of durable agent setup, such as logging in, editing native settings, updating MCP config, or installing plugins that should be reused. Use `discard` when the data is useful only during the current run, such as cache entries or throwaway sessions. Use `warn` when mutation is acceptable but should be visible to the user. Use `error` when mutation means the run was not reproducible enough, especially in CI or locked-down projects. Use `prompt` when the user should decide interactively after each run.
 
 ## Strategies
 
 ### `symlink`
 
-Outfitter resolves the state path through the profile hierarchy, then the native CLI fallback, and symlinks that source into the composite profile.
-Persistence happens because the CLI writes through the symlink to an intentional file or directory.
+Outfitter resolves the state path to its native CLI fallback and symlinks that source into the projection. Persistence happens because the CLI writes through the symlink to an intentional file or directory.
 
 ### `discard`
 
-Writes are allowed in the composite profile and are thrown away when the composite profile is deleted.
-Outfitter does not emit diagnostics for changed `discard` paths.
+Writes are allowed in the projection and are thrown away when the projection is deleted. Outfitter does not emit diagnostics for changed `discard` paths.
 
 ### `warn`
 
-Writes are allowed, discarded, and reported after the child exits.
-`--strict` makes these warnings fatal.
+Writes are allowed, discarded, and reported after the child exits. `--strict` makes these warnings fatal.
 
 ### `error`
 
-Writes are allowed during the child process but cause Outfitter to fail after the child exits if the path changed.
-This is useful for CI and strict reproducibility.
+Writes are allowed during the child process but cause Outfitter to fail after the child exits if the path changed. This is useful for CI and strict reproducibility.
 
 ### `prompt`
 
-`prompt` is reserved for a future interactive/control-plane workflow.
-Current implementations that allow it treat writes as non-persistent diagnostics, equivalent to `warn`, with the strategy name preserved in the message.
+When a `prompt` path changed and both stdin and stdout are interactive terminals, Outfitter asks after the child exits: **persist** (copy the change to the durable destination once), **discard**, or **always** (persist and record a `symlink` override in the editable settings scope). Outfitter never mutates a synced catalog cache; when the active configuration is remote, the change is persisted once with a warning that the choice could not be recorded. In non-interactive sessions, `prompt` falls back to `warn` with an explicit `prompt skipped: non-interactive` notice.
 
 ## Rationale
 
 Path-keyed state declarations keep the model simple:
 
 - the adapter declares the paths it knows the CLI may write and their default strategies;
-- profiles may provide files at those same paths;
 - the native fallback exposes native CLI files at those same paths;
 - `state_persistence` says what to do with each path.
 
-This avoids ambiguous writeback behavior and gives users a clear rule: if a CLI write should persist, configure that composite profile path as `symlink` and provide or accept the profile/native file that should receive the mutation.
+This avoids ambiguous writeback behavior and gives users a clear rule: if a CLI write should persist, configure that projection path as `symlink` and accept the native file that should receive the mutation. Configuration flows the other direction — from the `.agents` tree into the projection — and never back.

package/docs/documentation/README.md

@@ -1,24 +1,45 @@
 # Outfitter documentation
 
-User-facing Outfitter documentation.
+User-facing Outfitter documentation. These docs describe the [RFC #165](https://github.com/ai-outfitter/outfitter/issues/165) dotagents end state.
+
+## Getting started
 
 - [Getting started](./getting-started.md)
 - [Concepts](./concepts.md)
 - [CLI reference](./cli.md)
 - [First-time CLI agent users](./first-time-cli-agent-users.md)
-- [Switching to Outfitter](./switching-to-outfitter.md)
-- [Profiles](./profiles.md)
-- [Skills](./skills.md) — Define project and profile-bundled skills, route to specialized resources, and compose external references.
-- [Best practices](./best-practices.md) — Prefer a few stable profiles and many focused, progressively disclosed skills.
-- [Profile repositories](./profile-repository.md) — Publish and consume shareable profiles and standalone skills.
-- [Iterating on local and worktree profiles](./iterating-on-profiles.md)
-- [Running profiles in GitHub Actions](./actions.md)
-- [Adapter support matrix](./support-matrix.md)
+
+## Core concepts
+
+- [Settings](./settings.md) — Scopes, schema, and the flat `settings.local.yml` override file.
+- [Agents](./agents.md) — The `agents/<id>/agent.md` resource and its loadout — what you run.
+- [Agent profiles](./profiles.md) — Why an agent and its loadout _is_ the profile.
+- [Personas](./personas.md) — The base-agent-plus-persona-documents review convention.
+- [Subagents](./subagents.md) — Agents projected as harness delegates; leader-agent delegation.
+- [Skills](./skills.md) — Capability packages with progressive disclosure, references, and routing.
+- [Tasks](./tasks.md) — Placeholder for a separate upcoming RFC.
+
+## Operations
+
+- [Catalogs](./catalogs.md) — Publish and consume shareable `.agents` payloads; standalone and colocated layouts.
+- [Dump](./dump-and-bake.md) — Deterministic, self-contained `.agents/` dumps.
+- [Running an agent in GitHub Actions](./actions.md)
+- [Hooks](./hooks.md) — Harness hook wiring and the protocol gap.
 - [State persistence](./state.md)
+- [Adapter support matrix](./support-matrix.md)
+
+## Adopting Outfitter
+
+- [Switching to Outfitter](./switching-to-outfitter.md)
+- [Porting a Claude Code setup](./porting-claude.md) — Port `~/.claude` into `~/.agents/` with a symlink back.
+- [Local dotagents development](./local-development.md) — A personal standalone `.agents` repo that trickles upstream.
+- [Migration from legacy profiles](./migration.md)
+- [Iterating on an agent](./iterating-on-profiles.md)
+- [Best practices](./best-practices.md)
 - [Philosophy](../philosophy.md)
 
 ## Use cases
 
-- [Organization profile catalog](./usecases/organization-profile-catalog.md) — Publish shared team roles so new users can start with organization-approved defaults.
-- [Engineering profile catalog](./usecases/engineering.md) — Package coding, platform, and review profiles for repeatable engineering workflows.
-- [Persona reviews](./usecases/persona-reviews.md) — Create customer personas to get feedback on ideas, documentation, and designs.
+- [Organization catalog](./usecases/organization-profile-catalog.md) — Publish shared org resources and defaults through an `owner/.outfitter` control repository.
+- [Engineering catalog](./usecases/engineering.md) — Package engineering agents and skills for repeatable workflows.
+- [Persona reviews](./usecases/persona-reviews.md) — A base review agent plus customer-persona documents for feedback on ideas, docs, and designs.

package/docs/documentation/actions.md

@@ -1,6 +1,6 @@
-# Running profiles in GitHub Actions
+# Running an agent in GitHub Actions
 
-[`ai-outfitter/actions`](https://github.com/ai-outfitter/actions) runs an Outfitter profile non-interactively inside a GitHub Actions workflow. Outfitter assembles the profile exactly as it does locally — context, prompts, skills, controls — and launches the agent CLI in headless print mode (`pi -p`), so the agent does one unit of work per workflow run and exits. Wire it to any trigger and a profile becomes a CI agent: a PR reviewer, a scheduled commit auditor, an issue triager.
+[`ai-outfitter/actions`](https://github.com/ai-outfitter/actions) runs an Outfitter [agent](./agents.md) non-interactively inside a GitHub Actions workflow. The Action asks Outfitter to resolve and compose the selected agent — the same loadout it would compose locally — then launches the harness in headless print mode, so the agent does one unit of work per workflow run and exits. Wire it to any trigger and an agent becomes a CI worker: a PR reviewer, a scheduled commit auditor, an issue triager.
 
 ```yaml
 # .github/workflows/issue-triage.yml
@@ -20,78 +20,61 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: ai-outfitter/actions@v1
+      - uses: ai-outfitter/actions@v2
         with:
-          profile: issue-triage
-          profile-source: ${{ github.workspace }}/profiles
-          prompt: >-
-            Triage issue #${{ github.event.issue.number }} in
-            ${{ github.repository }} following your process.
+          agent: issue-triage
+          source: ${{ github.workspace }}/.agents # or owner/.agent + a pinned ref
+          inputs: |
+            issue_number: ${{ github.event.issue.number }}
+            repository: ${{ github.repository }}
 ```
 
-The action installs `@ai-outfitter/outfitter`, writes a minimal `~/.outfitter/settings.yml` on the runner, syncs remote catalogs if needed, then runs `outfitter run --profile <profile> --agent pi -- -p "<prompt>"`. The runner is discarded afterwards; nothing persists except what the agent pushed through its token.
+The Action consumes an agent ID, a local or pinned remote source, structured inputs, and runtime-only options (harness, credentials, working directory). It does not reproduce composition logic itself — it goes through Outfitter's resolver so a CI run and a local run compose identically given the same sources and refs.
 
-Profiles can come from the checked-out repository itself (a path, as above), an `owner/repo` catalog shorthand, or any git URI — the same [profile repository](./profile-repository.md) sources Outfitter supports locally. Pin `profile-source-ref` for catalogs you don't own.
+> **Note:** a dedicated **task**-bake path — freezing a named work contract and its typed inputs into an immutable artifact before launch — is the subject of a [separate upcoming RFC](./tasks.md). Until then the Action runs an agent with structured inputs; the `inputs:` shape above is forward-compatible with that work.
 
-## Pass GitHub trigger context
+## Division of ownership
 
-`trigger_context` is a convention for the initial prompt passed by an
-`ai-outfitter/actions` workflow. It is not an Outfitter object and Outfitter does
-not create or parse it. GitHub Actions interpolates the selected `github`
-expression values before invoking Outfitter, giving the profile metadata that
-the workflow — not the event author — chose to pass. That does not make every
-value trustworthy: branch and tag names, labels, titles, and logins are
-user-influenced, so route on them as opaque identifiers and never treat them
-as instructions.
+The workflow YAML owns the GitHub side; the agent owns the work:
 
-```yaml
-- uses: ai-outfitter/actions@v1
-  with:
-    profile: platform
-    prompt: |
-      Handle this GitHub event according to the profile's skill activation rules.
-
-      trigger_context:
-        repository: ${{ github.repository }}
-        event_name: ${{ github.event_name }}
-        issue_number: ${{ github.event.issue.number || '' }}
-```
+| Workflow YAML owns                         | Agent owns                          |
+| ------------------------------------------ | ----------------------------------- |
+| Triggers (`on:`)                           | The objective and prompt            |
+| Checkout                                   | Identity and posture                |
+| `permissions:` and credentials             | Its loadout: skills, subagents, mcp |
+| Execution identity                         | How it uses its inputs              |
+| Trusted event identifiers passed as inputs | Completion behavior                 |
+| GitHub-specific result handling            |                                     |
 
-Include only the identifiers the profile's routing rules need for the
-workflow's declared events (for example `sha`, `issue_labels`, or a
-deployment's `environment_url` when those events are in play). Add a
-workflow-owned discriminator, such as `report_kind: weekly-kpi`, when GitHub's
-event metadata cannot distinguish scheduled behaviors.
+Pass only the identifiers the agent expects (numbers, SHAs, repository names, workflow-owned discriminators). Never interpolate issue bodies, PR bodies, comments, diffs, or fetched page content into inputs — user-influenced values like titles and branch names are opaque identifiers, not instructions. A selected skill retrieves untrusted source material itself with trusted tools.
 
-Keep the profile's mapping from this metadata to skills short and keep task
-procedures in the skills themselves. See
-[Keep routing concise](./best-practices.md#keep-routing-concise) for that design
-boundary.
+## Setup: the `outfitter-actions` skill
 
-Do not interpolate issue bodies, pull request bodies, comments, diffs,
-deployment logs, or fetched page content into `trigger_context`. Pass stable
-identifiers, select the relevant skill, and let that skill retrieve only the
-untrusted source material it needs with trusted tools.
+The workflow surface is installed and maintained by the `outfitter-actions` setup skill shipped in the `ai-outfitter/actions` catalog, which includes the reusable workflow template (`template/github-action.yml`). Run it in an agent session to create or update your project's workflows.
+
+The setup skill consolidates compatible agents into as few workflows as practical: separate workflows are justified only by different triggers, permissions, credentials, isolation, or other GitHub-enforced boundaries. Domain skills such as `reports` or `issue-triage` do not ship their own workflow templates.
 
 ## Zero-key inference with GitHub Models
 
-CI agents don't need a paid provider key. [GitHub Models](https://docs.github.com/en/github-models) serves hosted models authenticated by the workflow's own `GITHUB_TOKEN`: grant `models: read` in the `permissions:` block, commit a pi provider config pointing at `https://models.github.ai/inference` with `"apiKey": "$GITHUB_TOKEN"`, install it to `~/.pi/agent/models.json` before the action step, and select the provider in the profile's `controls`. The action's README documents the full recipe, including model-selection gotchas (catalog availability, tool-call wire compatibility, and models too weak to hold an agentic loop).
+CI agents don't need a paid provider key. [GitHub Models](https://docs.github.com/en/github-models) serves hosted models authenticated by the workflow's own `GITHUB_TOKEN`: grant `models: read` in the `permissions:` block and point the tree's `models.json` at `https://models.github.ai/inference` with `"apiKey": "$GITHUB_TOKEN"`. The Action's README documents the full recipe, including model-selection gotchas (catalog availability, tool-call wire compatibility, and models too weak to hold an agentic loop).
 
 Mind the rate limits: the included tier is sized for event-driven, one-shot jobs. Concurrent runs of a large model can 429; high-volume review loops need a provider key.
 
-## Write profiles for headless runs
+## Write agents for headless runs
 
-A profile that behaves well interactively can still fail silently in CI. Lessons from running triage agents in production:
+A composition that behaves well interactively can still fail silently in CI. Lessons from running triage agents in production:
 
-- **Stdout is invisible.** In print mode nobody reads what the agent says — only its side effects matter. Instruct the profile to _do_ things with `gh` (comment, label, push) and name the exact commands; otherwise models will print the deliverable as their answer and exit green.
+- **Stdout is invisible.** In print mode nobody reads what the agent says — only its side effects matter. Make the agent's completion criteria name the exact `gh` side effects (comment, label, push); otherwise models will print the deliverable as their answer and exit green.
 - **Quote-safe posting.** When the agent posts text derived from untrusted input (issue bodies, diffs) back through `gh`, require a quoted heredoc plus `--body-file`, never inline `--body "..."` — backticks in a double-quoted body are executed by the shell.
-- **Verify side effects, not exit codes.** A green run is not proof of work. Add a post-agent step that asserts the expected side effects landed — the action ships [`scripts/validate-triage.sh`](https://github.com/ai-outfitter/actions/blob/main/scripts/validate-triage.sh) as a reference for triage-style jobs.
-- **Hard limits in the profile.** Enumerate exactly what the agent may do (which labels, how many comments, no closing/editing) and treat fetched content as data to classify, never instructions.
+- **Verify side effects, not exit codes.** A green run is not proof of work. Add a post-agent step that asserts the expected side effects landed — the Action ships [`scripts/validate-triage.sh`](https://github.com/ai-outfitter/actions/blob/main/scripts/validate-triage.sh) as a reference for triage-style jobs.
+- **Hard limits in the contract.** Enumerate exactly what the agent may do (which labels, how many comments, no closing/editing) in the agent's own definition, and treat fetched content as data to classify, never instructions.
 
 ## Scope the token
 
-The agent runs arbitrary `gh`/`git`/shell with whatever token you hand it, against untrusted input. Prefer the workflow's own `GITHUB_TOKEN` with an explicit least-privilege `permissions:` block; use a fine-grained PAT from a dedicated machine account only when the agent needs its own identity. Never use a human's PAT. The action's [token-permissions](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md) and [bot-account](https://github.com/ai-outfitter/actions/blob/main/docs/bot-account.md) guides cover this in depth, including prompt-injection trust boundaries.
+The agent runs arbitrary `gh`/`git`/shell with whatever token you hand it, against untrusted input. Prefer the workflow's own `GITHUB_TOKEN` with an explicit least-privilege `permissions:` block; use a fine-grained PAT from a dedicated machine account only when the agent needs its own identity. Never use a human's PAT. The Action's [token-permissions](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md) and [bot-account](https://github.com/ai-outfitter/actions/blob/main/docs/bot-account.md) guides cover this in depth, including prompt-injection trust boundaries.
+
+Pin remote sources consumed in CI to full commit SHAs — see [Trust and review](./catalogs.md#trust-and-review).
 
 ## More examples
 
-The action's [`examples/`](https://github.com/ai-outfitter/actions/tree/main/examples) directory covers scheduled commit review, PR ready-for-review reviews, sensitive-path audits, assigned-task agents, and zero-key issue triage on GitHub Models. A complete live setup — workflow, profile, provider config, and validation — runs in [`ai-outfitter/default-profiles`](https://github.com/ai-outfitter/default-profiles) as its own issue-triage agent.
+The Action's [`examples/`](https://github.com/ai-outfitter/actions/tree/main/examples) directory covers scheduled commit review, PR ready-for-review reviews, sensitive-path audits, assigned-task agents, and zero-key issue triage on GitHub Models. A complete live setup runs in [`ai-outfitter/.outfitter`](https://github.com/ai-outfitter/.outfitter) as the organization's own `weekly-kpis` agent.