@ai-outfitter/outfitter 0.7.2 → 0.8.0

package/dist/cli/commands/setup/SetupStarterSource.js

@@ -0,0 +1,133 @@
+// Resolves and validates setup starter sources: local .outfitter folders, remote git caches, and starter settings.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import spawn from 'cross-spawn';
+import { createRemoteRepositoryCachePath, normalizeGitUri, redactProfileSourceUriCredentials, } from '../../../profiles/ProfileCache.js';
+import { isValidProfileId } from '../../../profiles/ProfileLoader.js';
+import { createSettingsLoadPlan, loadSettingsFiles } from '../../../settings/SettingsLoader.js';
+import { formatSettingsIssue, } from './SetupTypes.js';
+export const prepareStarterLayout = (homeDirectory, projectDirectory, setupSourceUri, synchronizer = createGitSetupSourceSynchronizer()) => {
+    const localOutfitterPath = resolveLocalSetupSourceOutfitterPathFromUri(setupSourceUri, projectDirectory);
+    if (localOutfitterPath !== undefined) {
+        const settingsPath = join(localOutfitterPath, 'settings.yml');
+        validateStarterSettingsIfPresent(existsSync(settingsPath) ? settingsPath : undefined);
+        return {
+            cachePath: localOutfitterPath,
+            settingsPath: existsSync(settingsPath) ? settingsPath : undefined,
+            profilesPath: firstExistingPath(join(localOutfitterPath, 'profiles')),
+            sourceKind: 'local-live',
+            sourceOutfitterPath: localOutfitterPath,
+        };
+    }
+    const cachePath = createSetupSourceCachePath(homeDirectory, setupSourceUri);
+    synchronizer.sync(setupSourceUri, cachePath);
+    const settingsPath = firstExistingPath(join(cachePath, 'settings.yml'), join(cachePath, '.outfitter', 'settings.yml'));
+    validateStarterSettingsIfPresent(settingsPath);
+    const preferredProfilesPath = settingsPath?.endsWith(join('.outfitter', 'settings.yml'))
+        ? join(cachePath, '.outfitter', 'profiles')
+        : join(cachePath, 'profiles');
+    const profilesPath = firstExistingPath(preferredProfilesPath, join(cachePath, 'profiles'), join(cachePath, '.outfitter', 'profiles'));
+    return { cachePath, settingsPath, profilesPath, sourceKind: 'remote-cache' };
+};
+const createSetupSourceCachePath = (homeDirectory, setupSourceUri) => createRemoteRepositoryCachePath(homeDirectory, { uri: setupSourceUri });
+const createGitSetupSourceSynchronizer = () => ({
+    sync(uri, cachePath) {
+        mkdirSync(dirname(cachePath), { recursive: true });
+        if (existsSync(cachePath)) {
+            runGit(['-C', cachePath, 'pull', '--ff-only'], uri);
+            return;
+        }
+        runGit(['clone', '--', normalizeGitUri(uri), cachePath], uri);
+    },
+});
+const runGit = (args, sensitiveUri) => {
+    const result = spawn.sync('git', args, { stdio: 'pipe', encoding: 'utf8' });
+    if (result.status !== 0) {
+        /* v8 ignore next -- the final fallback only applies if git emits no stdout or stderr. */
+        throw new Error(redactSensitiveText((result.stderr || result.stdout || `git ${args.join(' ')} failed`).trim(), sensitiveUri));
+    }
+};
+const redactSensitiveText = (message, uri) => message
+    .split(uri)
+    .join(redactProfileSourceUriCredentials(uri))
+    .split(normalizeGitUri(uri))
+    .join(redactProfileSourceUriCredentials(normalizeGitUri(uri)));
+const firstExistingPath = (...paths) => paths.find((path) => existsSync(path));
+export const validateStarterSettingsIfPresent = (settingsPath) => {
+    if (settingsPath === undefined) {
+        return;
+    }
+    const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'user', path: settingsPath }]));
+    if (loaded.issues.length > 0) {
+        throw new Error(`Cannot setup from invalid starter settings: ${loaded.issues.map(formatSettingsIssue).join('; ')}`);
+    }
+};
+export const readStarterDefaultProfileId = (settingsPath) => {
+    if (settingsPath === undefined) {
+        return 'engineer';
+    }
+    const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'user', path: settingsPath }]));
+    return loaded.files[0]?.settings.defaultProfile ?? 'engineer';
+};
+export const readStarterExplicitDefaultProfileId = (settingsPath) => {
+    if (settingsPath === undefined) {
+        return undefined;
+    }
+    const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'user', path: settingsPath }]));
+    return loaded.files[0]?.settings.defaultProfile;
+};
+export const readUserDefaultProfileId = (files) => files.find((file) => file.location.scope === 'user')?.settings.defaultProfile ?? 'engineer';
+export const ensureExistingUserSettingsDefaultProfile = (settingsPath, files, defaultProfileId) => {
+    const userSettings = files.find((file) => file.location.scope === 'user');
+    if (userSettings === undefined || userSettings.settings.defaultProfile !== undefined) {
+        return;
+    }
+    const content = readFileSync(settingsPath, 'utf8');
+    writeFileSync(settingsPath, `${content}\ndefault_profile: ${defaultProfileId}\n`);
+};
+export const assertValidDefaultProfileId = (profileId) => {
+    if (!isValidProfileId(profileId)) {
+        throw new Error(`Default profile '${profileId}' is not a filesystem-safe Outfitter profile id.`);
+    }
+};
+export const createDefaultSettingsContent = (defaultProfileId = 'engineer') => [
+    `default_profile: ${defaultProfileId}`,
+    'profile_sources:',
+    '  - github: ai-outfitter/default-profiles',
+    '    path: profiles',
+    '  - path: ./profiles',
+    '',
+].join('\n');
+export const createInitialSettingsIfMissing = (settingsPath, starterSettingsPath) => {
+    if (existsSync(settingsPath)) {
+        return false;
+    }
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, starterSettingsPath === undefined
+        ? createDefaultSettingsContent()
+        : readStarterSettingsContent(starterSettingsPath));
+    return true;
+};
+export const readStarterSettingsContent = (starterSettingsPath) => {
+    const content = readFileSync(starterSettingsPath, 'utf8');
+    const loaded = loadSettingsFiles(createSettingsLoadPlan([{ scope: 'user', path: starterSettingsPath }]));
+    if (loaded.files[0]?.settings.defaultProfile !== undefined) {
+        return content;
+    }
+    return `default_profile: engineer\n${content}`;
+};
+/* v8 ignore start -- local setup-source path probing is covered by filesystem integration tests. */
+export const resolveLocalSetupSourceOutfitterPath = (input) => input.setupSourceUri === undefined
+    ? undefined
+    : resolveLocalSetupSourceOutfitterPathFromUri(input.setupSourceUri, input.projectDirectory);
+export const resolveLocalSetupSourceOutfitterPathFromUri = (setupSourceUri, projectDirectory) => {
+    if (isRemoteSetupSourceUri(setupSourceUri)) {
+        return undefined;
+    }
+    const sourcePath = isAbsolute(setupSourceUri) ? setupSourceUri : resolve(projectDirectory, setupSourceUri);
+    const outfitterPath = sourcePath.endsWith('.outfitter') ? sourcePath : join(sourcePath, '.outfitter');
+    return existsSync(outfitterPath) ? outfitterPath : undefined;
+};
+const isRemoteSetupSourceUri = (source) => /^[a-z][a-z0-9+.-]*:/iu.test(source) && !isAbsolute(source);
+/* v8 ignore stop */
+//# sourceMappingURL=SetupStarterSource.js.map

package/dist/cli/commands/setup/SetupStarterSource.js.map

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

package/dist/cli/commands/setup/SetupTypes.d.ts

@@ -0,0 +1,91 @@
+import type { SyncCommandDependencies, SyncCommandResult } from '../SyncCommand.js';
+import type { WelcomeCommandDependencies, WelcomeCommandResult } from '../WelcomeCommand.js';
+export interface SetupCommandInput {
+    readonly homeDirectory: string;
+    readonly projectDirectory: string;
+    readonly setupSourceUri?: string;
+}
+export interface SetupCommandResult {
+    readonly settingsPath: string;
+    readonly defaultProfilePath: string;
+    readonly createdSettings: boolean;
+    readonly copiedStarterProfileFiles: number;
+    readonly createdDefaultProfile: boolean;
+    readonly syncResult: SyncCommandResult;
+    readonly welcomeResult?: WelcomeCommandResult;
+    readonly messages: readonly string[];
+}
+export interface SetupSourceSynchronizer {
+    sync(uri: string, cachePath: string): void;
+}
+export interface SetupSourceLaunchInput {
+    readonly homeDirectory: string;
+    readonly projectDirectory: string;
+    readonly profileId?: string;
+}
+export interface SetupPiOnboardingLaunchInput {
+    readonly homeDirectory: string;
+    readonly projectDirectory: string;
+    readonly setupSourceUri?: string;
+}
+export type SetupSourcePostImportAction = 'start' | 'exit';
+export type SetupSourcePostImportLaunchTarget = 'selected' | 'default';
+export type SetupCommandDependencies = SyncCommandDependencies & WelcomeCommandDependencies & {
+    readonly setupSourceSynchronizer?: SetupSourceSynchronizer;
+    readonly selectDefaultProfile?: (profiles: readonly SetupProfileChoice[], currentDefault: string) => Promise<string>;
+    readonly selectSetupSourceImportTarget?: (choices: readonly SetupSourceImportTargetChoice[], defaultTarget: SetupSourceImportTarget) => Promise<SetupSourceImportTarget>;
+    readonly selectSetupSourceLaunchAction?: (profileId: string, launchTarget: SetupSourcePostImportLaunchTarget) => Promise<SetupSourcePostImportAction>;
+    readonly selectSetupSourceImportMode?: (choices: readonly SetupSourceImportModeChoice[], defaultMode: SetupSourceImportMode) => Promise<SetupSourceImportMode>;
+    readonly launchSetupSourceProfile?: (input: SetupSourceLaunchInput) => Promise<void>;
+    readonly launchPiOnboarding?: (input: SetupPiOnboardingLaunchInput) => Promise<{
+        readonly exitCode: number;
+    }>;
+    readonly runWelcome?: (input: SetupCommandInput, dependencies: SetupCommandDependencies) => Promise<WelcomeCommandResult | undefined>;
+};
+export interface SetupProfileChoice {
+    readonly id: string;
+    readonly label?: string;
+    readonly description?: string;
+}
+export type SetupSourceImportTarget = 'home' | 'project';
+export type SetupSourceImportMode = 'copy' | 'symlink';
+export interface SetupSourceImportTargetChoice {
+    readonly target: SetupSourceImportTarget;
+    readonly label: string;
+    readonly description: string;
+}
+export interface SetupSourceImportModeChoice {
+    readonly mode: SetupSourceImportMode;
+    readonly label: string;
+    readonly description: string;
+}
+export declare const setupSourceImportModeChoices: readonly SetupSourceImportModeChoice[];
+export declare const setupSourceImportTargetChoices: readonly SetupSourceImportTargetChoice[];
+export interface StarterLayout {
+    readonly cachePath: string;
+    readonly settingsPath?: string;
+    readonly profilesPath?: string;
+    readonly sourceKind: 'local-live' | 'remote-cache';
+    readonly sourceOutfitterPath?: string;
+}
+export interface SetupSourceOnboardingResult {
+    readonly importTarget: SetupSourceImportTarget;
+    readonly selectedProfileId: string;
+    readonly importMode: SetupSourceImportMode;
+}
+export interface AppliedSetupSourceImport {
+    readonly settingsPath: string;
+    readonly settingsDescription: string;
+    readonly profilesPath: string;
+    readonly createdSettings: boolean;
+    readonly copiedStarterProfileFiles: number;
+    readonly copiedStarterResourceFiles: number;
+    readonly selectedProfileAlreadyExists: boolean;
+    readonly selectedProfileConflictMessage?: string;
+    readonly symlinkedOutfitter: boolean;
+}
+export declare const formatSettingsIssue: (issue: {
+    readonly filePath: string;
+    readonly path: string;
+    readonly message: string;
+}) => string;

package/dist/cli/commands/setup/SetupTypes.js

@@ -0,0 +1,26 @@
+export const setupSourceImportModeChoices = [
+    {
+        mode: 'copy',
+        label: 'Copy snapshot',
+        description: 'copy profiles into the selected .outfitter folder; safest for normal use',
+    },
+    {
+        mode: 'symlink',
+        label: 'Symlink for development',
+        description: 'link the selected .outfitter folder to the local source so shared profile edits apply immediately',
+    },
+];
+export const setupSourceImportTargetChoices = [
+    {
+        target: 'home',
+        label: 'User home',
+        description: 'install profiles into ~/.outfitter for all repositories on this machine',
+    },
+    {
+        target: 'project',
+        label: 'Current project',
+        description: 'install profiles into this project .outfitter folder only',
+    },
+];
+export const formatSettingsIssue = (issue) => `${issue.filePath}#${issue.path} ${issue.message}`;
+//# sourceMappingURL=SetupTypes.js.map

package/dist/cli/commands/setup/SetupTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SetupTypes.js","sourceRoot":"","sources":["../../../../src/cli/commands/setup/SetupTypes.ts"],"names":[],"mappings":"AAyFA,MAAM,CAAC,MAAM,4BAA4B,GAA2C;IAClF;QACE,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,0EAA0E;KACxF;IACD;QACE,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,yBAAyB;QAChC,WAAW,EAAE,mGAAmG;KACjH;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAA6C;IACtF;QACE,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE,yEAAyE;KACvF;IACD;QACE,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,2DAA2D;KACzE;CACF,CAAC;AA4BF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAInC,EAAU,EAAE,CAAC,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC"}

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.