@ai-outfitter/outfitter 0.7.2 → 0.9.0

package/dist/fs/SafeSymlink.js

@@ -0,0 +1,50 @@
+// Creates symlinks with a Windows-only fallback for environments that deny symlink creation.
+import { copyFileSync, cpSync, symlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+// Windows without Developer Mode rejects symlink creation with EPERM. Directories fall
+// back to junctions, which need no privilege but require an absolute target; files (and
+// directories whose junction also fails) fall back to a one-way copy with a warning
+// because agent writes to the copy cannot persist back to the source. On POSIX platforms
+// a permission error is a real filesystem problem, so it is rethrown instead of being
+// silently downgraded to a copy.
+export const createSafeSymlink = (input, dependencies = {}) => {
+    const symlink = dependencies.symlink ?? symlinkSync;
+    /* v8 ignore next -- the process platform default is direct runtime behavior; tests inject a platform. */
+    const platform = dependencies.platform ?? process.platform;
+    try {
+        symlink(input.sourcePath, input.outputPath, input.directory ? 'dir' : 'file');
+    }
+    catch (error) {
+        if (platform !== 'win32' || !isSymlinkPermissionError(error)) {
+            throw error;
+        }
+        createWindowsSafeSymlinkFallback(symlink, input, dependencies.warn);
+    }
+};
+const createWindowsSafeSymlinkFallback = (symlink, input, warn) => {
+    if (input.directory) {
+        try {
+            symlink(resolve(input.sourcePath), input.outputPath, 'junction');
+            return;
+        }
+        catch (error) {
+            if (!isSymlinkPermissionError(error)) {
+                throw error;
+            }
+        }
+    }
+    copySafeSymlinkFallback(input, warn);
+};
+const copySafeSymlinkFallback = (input, warn) => {
+    if (input.directory) {
+        cpSync(input.sourcePath, input.outputPath, { recursive: true });
+    }
+    else {
+        copyFileSync(input.sourcePath, input.outputPath);
+    }
+    /* v8 ignore next -- console fallback is direct CLI behavior; tests inject a warn writer. */
+    (warn ?? console.error)(`${input.label} could not be symlinked (symlinks are unavailable on this platform); ` +
+        `copied '${input.sourcePath}' instead, so writes to it will not persist back.`);
+};
+const isSymlinkPermissionError = (error) => error instanceof Error && 'code' in error && (error.code === 'EPERM' || error.code === 'EACCES');
+//# sourceMappingURL=SafeSymlink.js.map

package/dist/fs/SafeSymlink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SafeSymlink.js","sourceRoot":"","sources":["../../src/fs/SafeSymlink.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAepC,uFAAuF;AACvF,wFAAwF;AACxF,oFAAoF;AACpF,yFAAyF;AACzF,sFAAsF;AACtF,iCAAiC;AACjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAuB,EAAE,eAAwC,EAAE,EAAQ,EAAE;IAC7G,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,IAAI,WAAW,CAAC;IACpD,yGAAyG;IACzG,MAAM,QAAQ,GAAG,YAAY,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAE3D,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAChF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7D,MAAM,KAAK,CAAC;QACd,CAAC;QAED,gCAAgC,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;IACtE,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,gCAAgC,GAAG,CACvC,OAA2B,EAC3B,KAAuB,EACvB,IAA6C,EACvC,EAAE;IACR,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,uBAAuB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC,CAAC;AAEF,MAAM,uBAAuB,GAAG,CAAC,KAAuB,EAAE,IAA6C,EAAQ,EAAE;IAC/G,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;SAAM,CAAC;QACN,YAAY,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACnD,CAAC;IAED,4FAA4F;IAC5F,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CACrB,GAAG,KAAK,CAAC,KAAK,uEAAuE;QACnF,WAAW,KAAK,CAAC,UAAU,mDAAmD,CACjF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,wBAAwB,GAAG,CAAC,KAAc,EAAW,EAAE,CAC3D,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC"}

package/dist/settings/SettingsLoader.d.ts

@@ -28,6 +28,7 @@ export interface SettingsDiscoveryInput {
 export declare const createSettingsLoadPlan: (locations: readonly SettingsLocation[]) => SettingsLoadPlan;
 export declare const discoverSettingsLoadPlan: (input: SettingsDiscoveryInput) => SettingsLoadPlan;
 export declare const discoverRemoteSettingsLoadPlan: (homeDirectory: string, remoteSettings: readonly RemoteSettingsReference[]) => SettingsLoadPlan;
+export declare const resolveCachedRemoteSettingsPath: (homeDirectory: string, source: RemoteSettingsReference) => string;
 export declare const loadSettingsFiles: (plan: SettingsLoadPlan) => SettingsLoadResult;
 export declare const loadSettings: (plan: SettingsLoadPlan) => LoadedSettings;
 export declare const loadSettingsWithCachedRemoteSettings: (input: SettingsDiscoveryInput, remoteSettingsReferencesOverride?: readonly RemoteSettingsReference[]) => LoadedSettings;

package/dist/settings/SettingsLoader.js

@@ -14,6 +14,15 @@ export const discoverSettingsLoadPlan = (input) => createSettingsLoadPlan([
     { scope: 'project-local', path: join(input.projectDirectory, '.outfitter', 'local', 'settings.yml') },
 ]);
 export const discoverRemoteSettingsLoadPlan = (homeDirectory, remoteSettings) => discoverRemoteSettingsLocations(homeDirectory, remoteSettings).plan;
+export const resolveCachedRemoteSettingsPath = (homeDirectory, source) => {
+    const repositoryPath = createRemoteRepositoryCachePath(homeDirectory, source);
+    const configuredPath = resolveRemoteRepositorySubpath(repositoryPath, source.path);
+    if (existsSync(configuredPath) || source.path !== 'settings.yml') {
+        return configuredPath;
+    }
+    const nestedOutfitterSettingsPath = resolveRemoteRepositorySubpath(repositoryPath, '.outfitter/settings.yml');
+    return existsSync(nestedOutfitterSettingsPath) ? nestedOutfitterSettingsPath : configuredPath;
+};
 export const loadSettingsFiles = (plan) => {
     const files = [];
     const issues = [];
@@ -54,7 +63,7 @@ const discoverRemoteSettingsLocations = (homeDirectory, remoteSettings) => {
         try {
             locations.push({
                 scope: 'remote',
-                path: resolveRemoteRepositorySubpath(createRemoteRepositoryCachePath(homeDirectory, source), source.path),
+                path: resolveCachedRemoteSettingsPath(homeDirectory, source),
             });
         }
         catch (error) {

package/dist/settings/SettingsLoader.js.map

@@ -1 +1 @@
-{"version":3,"file":"SettingsLoader.js","sourceRoot":"","sources":["../../src/settings/SettingsLoader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SettingsLoader.js","sourceRoot":"","sources":["../../src/settings/SettingsLoader.ts"],"names":[],"mappings":"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"}

package/doc/architecture/state_writeback_strategy.md

@@ -0,0 +1,350 @@
+# State Writeback Strategy
+
+This document describes Outfitter's current model for handling writes that agent CLIs make inside a composite profile.
+
+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.
+
+## Functional model
+
+Outfitter separates three kinds of files that may exist in a composite profile:
+
+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.
+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.
+
+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.
+
+## Current behavior
+
+- Composite profiles 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.
+- 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`.
+
+## Non-goals
+
+- Outfitter does not implement generic copy-back from the composite profile to profiles.
+- Outfitter does not implement generic structured merge-back.
+- Outfitter does not silently persist unknown writes.
+
+## Profile stack 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.
+
+```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
+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.
+
+## 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.
+
+The Pi adapter currently declares:
+
+```yaml
+state_paths:
+  auth.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, error, prompt]
+
+  settings.json:
+    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.
+
+  keybindings.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, warn, error, prompt]
+    note: >-
+      Outfitter generates a transformed runtime keybindings.json so Shift+Tab
+      can switch Outfitter modes and Ctrl+Shift+T can cycle Pi thinking levels.
+      The generated runtime file is treated as discard for that launch.
+
+  mcp.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, warn, error, prompt]
+
+  models.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, warn, error, prompt]
+
+  trust.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, warn, error, prompt]
+
+  plugins/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error, prompt]
+
+  cache/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  sessions/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  npm/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  git/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  tmp/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard]
+
+  utilities/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  bin/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  unknown:
+    default_strategy: warn
+    allowed_strategies: [discard, warn, error, prompt]
+```
+
+The Claude Code adapter currently declares:
+
+```yaml
+state_paths:
+  settings.json:
+    default_strategy: symlink
+    allowed_strategies: [symlink, warn, error, prompt]
+
+  agents/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error, prompt]
+
+  skills/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error, prompt]
+
+  commands/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error, prompt]
+
+  plugins/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error, prompt]
+
+  projects/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  debug/:
+    default_strategy: symlink
+    allowed_strategies: [symlink, discard, warn, error]
+
+  unknown:
+    default_strategy: warn
+    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:
+
+```yaml
+state_persistence:
+  auth.json: symlink
+  settings.json: symlink
+  plugins/: symlink
+  cache/: discard
+  sessions/: discard
+  unknown: warn
+```
+
+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.
+
+Functional examples:
+
+```yaml
+# Persist logins and settings, but make caches and sessions run-local.
+state_persistence:
+  auth.json: symlink
+  settings.json: symlink
+  cache/: discard
+  sessions/: discard
+```
+
+```yaml
+# CI profile: fail if pi changes settings, MCP config, or unknown files.
+state_persistence:
+  settings.json: error
+  mcp.json: error
+  plugins/: error
+  unknown: error
+```
+
+```yaml
+# Exploratory profile: allow plugin experiments but report them after exit.
+state_persistence:
+  plugins/: warn
+  unknown: warn
+```
+
+## Composite profile 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`.
+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.
+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 `discard`, `warn`, `error`, and `prompt`, Outfitter creates normal temporary composite profile paths where needed and observes whether they changed.
+
+## Unknown writes
+
+The `unknown` pseudo-path controls writes outside adapter-declared paths:
+
+```yaml
+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.
+
+## 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.
+
+## 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.
+
+### `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.
+
+### `warn`
+
+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.
+
+### `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.
+
+## 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.

package/doc/documentation/README.md

@@ -0,0 +1,21 @@
+# Outfitter documentation
+
+User-facing Outfitter documentation.
+
+- [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)
+- [Profile repositories](./profile-repository.md)
+- [Iterating on local and worktree profiles](./iterating-on-profiles.md)
+- [Adapter support matrix](./support-matrix.md)
+- [State persistence](./state.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.

package/doc/documentation/cli.md

@@ -0,0 +1,74 @@
+# CLI reference
+
+Global options:
+
+| Option          | Description                  |
+| --------------- | ---------------------------- |
+| `-V, --version` | Print the Outfitter version. |
+| `-h, --help`    | Show help for a command.     |
+
+## `outfitter run [args...]`
+
+Assemble a composite profile and launch the selected agent CLI. `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. |
+
+Any other arguments and unrecognized options are passed through to the launched agent CLI:
+
+```bash
+outfitter run --profile engineer --agent claude
+outfitter -p data_analyst -- --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. |
+
+## `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.
+
+### `outfitter profile list`
+
+List available Outfitter profiles.
+
+| Option  | Description                                                       |
+| ------- | ----------------------------------------------------------------- |
+| `--all` | Include template profiles that are intended only for inheritance. |
+
+### `outfitter profile create <name>`
+
+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.
+
+| Option     | Description                              |
+| ---------- | ---------------------------------------- |
+| `--strict` | Exit non-zero when warnings are present. |
+| `--json`   | Print diagnostics as JSON.               |
+
+## `outfitter welcome`
+
+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.

package/doc/documentation/concepts.md

@@ -0,0 +1,54 @@
+# Concepts
+
+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]
+```
+
+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.
+
+## Profile
+
+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).
+
+## Composite profile
+
+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).
+
+## Catalog / profile source
+
+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).
+
+## 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.
+
+## Controls
+
+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.
+
+## 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.
+
+## 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).
+
+## Layer precedence
+
+When several layers define the same profile or setting, higher layers win:
+
+1. Project-local (`.outfitter/local/`)
+2. Project (`.outfitter/`)
+3. User (`~/.outfitter/`)
+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.