@ai-outfitter/outfitter 1.4.0 → 1.6.0

package/dist/system/SystemExtensionHook.d.ts

@@ -0,0 +1,34 @@
+import type { AgentLaunchPlan } from '../projection/Projection.js';
+import type { Harness } from '../settings/Settings.js';
+export interface SystemExtensionHarnessHook {
+    readonly extensions?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+export interface SystemExtensionHook {
+    readonly filePath: string;
+    readonly name: string;
+    readonly harnesses: Partial<Readonly<Record<Harness, SystemExtensionHarnessHook>>>;
+}
+export interface SystemExtensionHookSource {
+    readonly directory: string;
+    readonly stamp: string;
+}
+export interface LoadedSystemExtensionHooks {
+    readonly hooks: readonly SystemExtensionHook[];
+    readonly source?: SystemExtensionHookSource;
+}
+export interface AttachedSystemExtensionHooks {
+    readonly launch: AgentLaunchPlan;
+    readonly warnings: readonly string[];
+}
+export interface SystemExtensionHookDiscoveryInput {
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+}
+export declare const resolveSystemExtensionHookSource: (input?: SystemExtensionHookDiscoveryInput) => SystemExtensionHookSource | undefined;
+export declare const readSystemExtensionHooks: (input?: SystemExtensionHookDiscoveryInput) => LoadedSystemExtensionHooks;
+/**
+ * Prepends every system Pi extension after projection, including for RPC/print launches. Hook env
+ * stays beneath the projected plan env so it cannot replace Outfitter's runtime/session paths.
+ */
+export declare const attachSystemExtensionHooks: (plan: AgentLaunchPlan, loaded?: LoadedSystemExtensionHooks) => AttachedSystemExtensionHooks;

package/dist/system/SystemExtensionHook.js

@@ -0,0 +1,190 @@
+// Reads root-owned system extension hooks for post-projection launch-plan mutation. This is a
+// launcher-scope mechanism, not a managed configuration scope: Pi never reads these files, so they
+// do not change Pi's configuration resolution order. A session can still bypass the launcher with
+// the bundled Pi binary directly or point OUTFITTER_SYSTEM_DIR at an empty directory. The honest
+// guarantee is that collection is on by default and the organization owns the file naming the
+// collector, not that a session cannot turn collection off.
+//
+// Hook documents fail closed because only an operator can create files in the normal root-owned
+// locations. A malformed file is therefore an operator error caught on a canary boot; failing open
+// would silently run the fleet without collection, which downstream verifiers must classify as
+// unattested rather than clean. Hook environment also denies Node and native dynamic-loader
+// controls: they could execute code before Pi starts and change what runs rather than what observes.
+// Symlinks are resolved to physical paths and dangling links are fatal. Ownership and mode checks
+// stay with deployment policy because supported paths include platform-specific package stores and
+// the explicit development override, which do not share one portable owner or permission model.
+import { lstatSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { validateSchema } from '../validation/SchemaValidator.js';
+import { parseYamlDocument } from '../validation/YamlDocument.js';
+const linuxSystemDirectory = '/etc/outfitter/system.d';
+const macosSystemDirectory = '/Library/Application Support/Outfitter/system.d';
+const protectedPiEnvironmentVariables = new Set(['PI_CODING_AGENT_DIR', 'PI_CODING_AGENT_SESSION_DIR']);
+const runtimeControlEnvironmentVariables = new Set([
+    'LD_AUDIT',
+    'LD_LIBRARY_PATH',
+    'LD_PRELOAD',
+    'NODE_OPTIONS',
+    'NODE_REPL_EXTERNAL_MODULE',
+    // Node reads this before startup and OpenSSL configuration can activate an
+    // arbitrary native provider, so it executes code exactly like the loaders above.
+    'OPENSSL_CONF',
+]);
+export const resolveSystemExtensionHookSource = (input = {}) => {
+    const environment = input.environment ?? process.env;
+    const override = environment.OUTFITTER_SYSTEM_DIR;
+    if (override !== undefined)
+        return { directory: override, stamp: `env-override:${override}` };
+    switch (input.platform ?? process.platform) {
+        case 'darwin':
+            return { directory: macosSystemDirectory, stamp: macosSystemDirectory };
+        case 'linux':
+            return { directory: linuxSystemDirectory, stamp: linuxSystemDirectory };
+        default:
+            return undefined;
+    }
+};
+const formatValidationIssues = (filePath, issues) => issues.map((issue) => `${filePath}#${issue.path} ${issue.message}`).join('; ');
+const resolvePhysicalPath = (path, errorMessage) => {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        throw new Error(`${errorMessage}: ${String(error)}`, { cause: error });
+    }
+};
+const resolveExtensionPaths = (document, filePath) => {
+    const harnesses = {};
+    for (const [harness, hook] of Object.entries(document.harnesses)) {
+        if (hook.extensions === undefined) {
+            harnesses[harness] = hook;
+            continue;
+        }
+        harnesses[harness] = {
+            ...hook,
+            extensions: hook.extensions.map((extensionPath) => {
+                if (!isAbsolute(extensionPath) || lstatSync(extensionPath, { throwIfNoEntry: false }) === undefined) {
+                    throw new Error(`Invalid system extension hook '${filePath}': extension path does not exist: ${extensionPath}`);
+                }
+                return resolvePhysicalPath(extensionPath, `Invalid system extension hook '${filePath}': extension path cannot be resolved: ${extensionPath}`);
+            }),
+        };
+    }
+    return { ...document, harnesses };
+};
+const assertNoProtectedPiEnvironment = (document, filePath) => {
+    for (const hook of Object.values(document.harnesses)) {
+        for (const name of Object.keys(hook.env ?? {})) {
+            if (protectedPiEnvironmentVariables.has(name.toUpperCase())) {
+                throw new Error(`Invalid system extension hook '${filePath}': environment variable '${name}' is reserved by Outfitter.`);
+            }
+        }
+    }
+};
+const assertNoRuntimeControlEnvironment = (document, filePath) => {
+    for (const hook of Object.values(document.harnesses)) {
+        for (const name of Object.keys(hook.env ?? {})) {
+            const normalizedName = name.toUpperCase();
+            if (runtimeControlEnvironmentVariables.has(normalizedName) || normalizedName.startsWith('DYLD_')) {
+                throw new Error(`Invalid system extension hook '${filePath}': environment variable '${name}' controls process loading and is forbidden.`);
+            }
+        }
+    }
+};
+const readSystemExtensionHook = (filePath) => {
+    if (lstatSync(filePath, { throwIfNoEntry: false }) === undefined) {
+        /* v8 ignore next -- the path was returned by the immediately preceding readdirSync call. */
+        throw new Error(`System extension hook '${filePath}' disappeared while loading.`);
+    }
+    const physicalFilePath = resolvePhysicalPath(filePath, `System extension hook '${filePath}' cannot be resolved`);
+    let content;
+    try {
+        content = readFileSync(physicalFilePath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`System extension hook '${physicalFilePath}' is unreadable: ${String(error)}`, { cause: error });
+    }
+    const parsed = parseYamlDocument(content, physicalFilePath);
+    if (!parsed.ok) {
+        throw new Error(`Invalid system extension hook '${physicalFilePath}': ${parsed.issue.message}`);
+    }
+    const validation = validateSchema('system-extension-hook', parsed.document);
+    if (!validation.valid) {
+        throw new Error(`Invalid system extension hook: ${formatValidationIssues(physicalFilePath, validation.issues)}`);
+    }
+    const document = parsed.document;
+    assertNoProtectedPiEnvironment(document, physicalFilePath);
+    assertNoRuntimeControlEnvironment(document, physicalFilePath);
+    return { filePath: physicalFilePath, ...resolveExtensionPaths(document, physicalFilePath) };
+};
+const assertNoEnvironmentCollisions = (hooks) => {
+    const owners = new Map();
+    for (const hook of hooks) {
+        for (const harness of ['pi', 'claude', 'codex']) {
+            for (const name of Object.keys(hook.harnesses[harness]?.env ?? {})) {
+                const key = `${harness}:${name}`;
+                const owner = owners.get(key);
+                if (owner !== undefined) {
+                    throw new Error(`Invalid system extension hooks: environment '${name}' for '${harness}' is declared by both '${owner}' and '${hook.filePath}'.`);
+                }
+                owners.set(key, hook.filePath);
+            }
+        }
+    }
+};
+export const readSystemExtensionHooks = (input = {}) => {
+    const source = resolveSystemExtensionHookSource(input);
+    if (source === undefined)
+        return { hooks: [] };
+    const sourceEntry = lstatSync(source.directory, { throwIfNoEntry: false });
+    if (sourceEntry === undefined)
+        return { hooks: [], source };
+    const physicalDirectory = resolvePhysicalPath(source.directory, `System extension hook source '${source.directory}' cannot be resolved`);
+    const sourceStat = statSync(physicalDirectory);
+    if (!sourceStat.isDirectory()) {
+        throw new Error(`System extension hook source '${physicalDirectory}' is not a directory.`);
+    }
+    const physicalSource = {
+        directory: physicalDirectory,
+        stamp: `${source.stamp.slice(0, source.stamp.length - source.directory.length)}${physicalDirectory}`,
+    };
+    const filePaths = readdirSync(physicalDirectory)
+        .filter((name) => name.endsWith('.yml'))
+        .sort()
+        .map((name) => join(physicalDirectory, name));
+    const hooks = filePaths.map(readSystemExtensionHook);
+    assertNoEnvironmentCollisions(hooks);
+    return { hooks, source: physicalSource };
+};
+const unsupportedHarnessWarnings = (hooks) => hooks.flatMap((hook) => ['claude', 'codex']
+    .filter((harness) => hook.harnesses[harness] !== undefined)
+    .map((harness) => `warning: System extension hook '${hook.name}' configures unsupported harness '${harness}'; ignoring it.`));
+/**
+ * Prepends every system Pi extension after projection, including for RPC/print launches. Hook env
+ * stays beneath the projected plan env so it cannot replace Outfitter's runtime/session paths.
+ */
+export const attachSystemExtensionHooks = (plan, loaded = readSystemExtensionHooks()) => {
+    const warnings = unsupportedHarnessWarnings(loaded.hooks);
+    if (loaded.source === undefined)
+        return { launch: plan, warnings };
+    const piHooks = loaded.hooks.flatMap((hook) => (hook.harnesses.pi === undefined ? [] : [hook.harnesses.pi]));
+    const extensionArgs = plan.command === 'pi'
+        ? piHooks.flatMap((hook) => (hook.extensions ?? []).flatMap((path) => ['--extension', path]))
+        : [];
+    const hookEnvironment = plan.command === 'pi'
+        ? piHooks.reduce((environment, hook) => ({ ...environment, ...hook.env }), {})
+        : {};
+    return {
+        launch: {
+            ...plan,
+            args: [...extensionArgs, ...plan.args],
+            env: {
+                ...hookEnvironment,
+                OUTFITTER_SYSTEM_HOOK_SOURCE: loaded.source.stamp,
+                ...plan.env,
+            },
+        },
+        warnings,
+    };
+};
+//# sourceMappingURL=SystemExtensionHook.js.map

package/dist/system/SystemExtensionHook.js.map

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

package/dist/validation/SchemaValidator.d.ts

@@ -1,4 +1,4 @@
-export type SchemaName = 'settings' | 'agent';
+export type SchemaName = 'settings' | 'agent' | 'system-extension-hook';
 export interface ValidationIssue {
     readonly path: string;
     readonly message: string;

package/dist/validation/SchemaValidator.js

@@ -4,10 +4,12 @@ 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 agentSchema = readSchema('agent.schema.json');
+const systemExtensionHookSchema = readSchema('system-extension-hook.schema.json');
 const ajv = new Ajv2020({ allErrors: true });
 const validators = {
     settings: ajv.compile(settingsSchema),
     agent: ajv.compile(agentSchema),
+    'system-extension-hook': ajv.compile(systemExtensionHookSchema),
 };
 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,+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"}
+{"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;AACpD,MAAM,yBAAyB,GAAG,UAAU,CAAC,mCAAmC,CAAC,CAAC;AAElF,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;IAC5C,uBAAuB,EAAE,GAAG,CAAC,OAAO,CAAC,yBAAsC,CAAC;CAC7E,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

@@ -26,7 +26,19 @@ The user-facing state update lifecycle is:
 ## Current behavior
 
 - Projections remain temporary and reproducible by default.
-- Outfitter does not do generic post-run copy-back or JSON/YAML merge-back.
+- Outfitter does not do generic post-run copy-back or JSON/YAML merge-back. The Pi and Claude
+  adapters have narrow credential and session bridges as exceptions because the current launch flow does not
+  connect those files to durable storage through materialized declared-state symlinks. Pi declares
+  `auth.json` and `models.json` with a `symlink` default, but currently copies them from the durable
+  agent directory into the projection before launch and back from the projection afterward. Claude
+  similarly copies `.credentials.json` from `~/.claude` into the projection and copies a changed
+  file back afterward. Claude's separate `~/.claude.json` sits outside `~/.claude`, so it cannot be
+  symlinked with the rest of the config directory; Outfitter seeds a narrow whitelist into the
+  projected file and merges only `oauthAccount` back rather than copying machine-local state
+  wholesale. Claude's `CLAUDE_CONFIG_DIR` also redirects session transcripts into the projection,
+  so Outfitter seeds only the current working directory's `projects/<slug>/` before launch and
+  atomically merges projected session files from every slug back afterward. This per-file merge
+  never deletes durable history and runs after both normal and thrown launcher exits.
 - 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.
@@ -181,7 +193,7 @@ Settings may override persistence by mapping adapter-declared paths to strategy
 
 ```yaml
 state_persistence:
-  auth.json: symlink
+  auth.json: symlink # Intended policy; Pi's current launch flow uses its explicit copy bridge.
   settings.json: symlink
   plugins/: symlink
   cache/: discard
@@ -198,7 +210,7 @@ Functional examples:
 ```yaml
 # Persist logins and settings, but make caches and sessions run-local.
 state_persistence:
-  auth.json: symlink
+  auth.json: symlink # Intended policy; Pi's current launch flow uses its explicit copy bridge.
   settings.json: symlink
   cache/: discard
   sessions/: discard

package/docs/documentation/README.md

@@ -2,6 +2,19 @@
 
 Outfitter lays out conventions for iterating on and sharing agent configuration — agent profiles, skills, and loadouts. The docs follow that arc: **set up** your own, **understand** the pieces, **share** them across projects and your org, **automate** them on more surfaces, then contribute back. Each page keeps to one concept and links onward when you need the next one, so nothing here has to be read up front.
 
+Onboarding an organization? Start with
+[Onboard an organization with an SDLC report](./usecases/org-onboarding-sdlc-report.md) —
+one engineer runs the maturity assessment, then creates the org `.agents`
+repository with the baseline report as its first commit.
+
+## Climb the ramp (runbooks)
+
+One runbook per rung of [the adoption ramp](../philosophy.md#the-ramp-to-an-autonomous-lifecycle). Each starts where the previous one ended and closes with the one concrete step that begins the next rung. Their success checks are the signals an SDLC assessment reports, so "done" is something you run rather than something you judge.
+
+- [Share one catalog](../runbooks/share-one-catalog.md) — one pinned catalog the organization shares, instead of per-laptop configuration. (→ delegated)
+- [Run it without your laptop](../runbooks/run-without-your-laptop.md) — an event triggers the workflow, its output lands through review, and the session is captured. (→ automated)
+- [Give the agent a residence](../runbooks/give-the-agent-a-residence.md) — a named, assignable agent with an account and somewhere to live. (→ governed)
+
 ## Start (you)
 
 - [Getting started](./getting-started.md) — install, first run, default agent.
@@ -33,10 +46,10 @@ Outfitter lays out conventions for iterating on and sharing agent configuration
 The same composition runs on every surface; only the trigger changes.
 
 - [Running an agent in GitHub Actions](./actions.md) — headless runs on any workflow trigger.
-- [Container images](./containers.md) — run the published image persistently or add Nix-packaged tools.
+- [Container images](./containers.md) — run the published Debian-based image persistently, extend it with apt, or use the `-nix` variant.
 - [Recurring runs](./recurring-runs.md) — loops three ways: the local loop extension, Actions cron, cluster schedules.
 - [In-cluster agents](./in-cluster.md) — resident agents, CronJobs, and subagent Jobs via Link Operator.
-- [Hooks](./hooks.md) — harness hook wiring and the protocol gap.
+- [Hooks](./hooks.md) — harness hook wiring, launcher-scope system observers, and the protocol gap.
 - [Dump](./dump-and-bake.md) — deterministic, self-contained `.agents/` dumps.
 - [State persistence](./state.md)
 - [Adapter support matrix](./support-matrix.md)

package/docs/documentation/catalogs.md

@@ -83,6 +83,43 @@ Remote entries additionally accept:
 
 Resources from all sources resolve by slug behind local layers, following [layer precedence](./concepts.md#layer-precedence). Agent-local skills keep their owning-agent namespace through cache and source merging. Outfitter reports shadowed IDs so consumers can see which source supplies a selected resource.
 
+### Catalog dependencies (transitive sources)
+
+A catalog can depend on other catalogs by declaring `sources` in its own settings file
+(`settings.yml` at its payload root, or `.agents/settings.yml`). Outfitter resolves those
+declarations transitively: syncing and resolving a catalog also fetches and layers the catalogs it
+declares, so one pinned root pulls in its dependency closure.
+
+Transitive sources are deliberately the narrowest safe subset — a `github:` shorthand pinned to an
+immutable ref — while the [remote-catalog trust model](https://github.com/ai-outfitter/outfitter/issues/212)
+is defined. Anything else a catalog declares is skipped with a warning:
+
+- **`github:` shorthand only.** A transitive source must be a `github: owner/repo` shorthand. A
+  `uri:` source declared by a catalog is skipped, because a URI can name an arbitrary git transport
+  (for example a local path or a remote helper) that a dependency should not be able to choose on
+  your behalf. Keeping to `github:` also routes every transitive fetch that `outfitter sync`
+  performs through the same private-catalog gate as your own sources. (The one exception is the
+  first-party default catalog's own closure, fetched during setup — see the note below.)
+- **Whole repository only.** A transitive `github:` source may not carry a `path:` subpath, so a
+  declaration can never point outside the repository it fetches.
+- **Pinned only.** A transitive source must pin an immutable `ref:` — a full commit SHA, or a
+  version tag such as `v1.2.0`. A commit SHA is truly immutable; a version tag is a pin the
+  dependency's maintainer could later move, in which case the next `outfitter sync` fetches the
+  new commit and reports it as `updated`. Pin dependencies you rely on to a SHA when you need the
+  closure to never change underneath you.
+- **Content only.** A depended-on catalog contributes `.agents` payload resources. Nothing else in
+  its settings file — default agent, default harness, cache directory, `remote_settings` — takes
+  effect transitively.
+- **Lower precedence.** Every source you configure directly outranks every transitive source;
+  deeper dependencies rank below shallower ones.
+- Cycles and duplicates resolve once — the first occurrence wins and resolution terminates.
+
+A fresh `outfitter` install fetches this closure during setup, so a default profile whose skills
+live in a depended-on catalog works without a manual sync. Because the default catalog is the
+first-party catalog Outfitter ships (pinned in the CLI), its bootstrap fetches the declared closure
+directly; the interactive private-catalog prompt is a property of `outfitter sync`, which is where
+you add your own third-party sources.
+
 ## Organization control repositories
 
 An `owner/.outfitter` repository distributes organization-wide resources plus shared settings that Outfitter layers below each user's local settings:
@@ -104,7 +141,10 @@ Remote settings are cached locally and merged at lower precedence than your proj
 1. Local settings are validated. Remote settings repositories are cloned or updated first, then
    merged settings are reloaded.
 2. Remote sources (including any added by remote settings) are cloned or updated.
-3. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
+3. Sources declared by the synced catalogs themselves (see
+   [catalog dependencies](#catalog-dependencies-transitive-sources)) are fetched next, repeating
+   until the whole dependency closure is cached.
+4. Each synced source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
 
 All repositories live under `<cache_directory>/repos/<encoded-uri-and-ref>/` (default
 `~/.agents/cache`). Pinned (`ref:`) sources stay on their selected ref until you change it; unpinned
@@ -119,6 +159,23 @@ synchronization; run sync explicitly when you want network updates.
 
 Private GitHub catalogs are an enterprise feature. When sync detects a private GitHub repository, it asks for confirmation before use and records the decision in your user settings. Review the Outfitter Enterprise license or your enterprise agreement before enabling private catalogs. Non-GitHub `uri:` sources use whatever git credentials your environment already has; credentials embedded in URIs are redacted from sync output.
 
+### How sync authenticates
+
+Outfitter does not collect, store, or validate credentials. It delegates to `git`, so a private catalog clones with whatever credentials the surrounding environment already gives `git` — which differs by where sync runs:
+
+| Where          | Credential                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your machine   | Your existing git configuration: SSH agent, credential helper, or `.netrc`.                                                                       |
+| GitHub Actions | The workflow token, configured for git — see [token-permissions.md](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md). |
+| A cluster pod  | Supplied by the deployment: `GIT_ASKPASS` over HTTPS, or `GIT_SSH_COMMAND` for a deploy key.                                                      |
+
+Two failure modes are worth knowing before you hit them:
+
+- **Credentials belong in the environment, not the URI.** Outfitter redacts credentials from a source URI before deriving its cache path, so a URI carrying a username produces a cache entry that later runs do not read. The source URI must be byte-identical everywhere it appears.
+- **`outfitter run` does not sync.** A runtime that has never synced has an empty cache and cannot resolve a profile from it, however good its credentials are.
+
+[The forge credential model](../architecture/forge-credential-model.md) covers which credential to use where, and why.
+
 ## Trust and review
 
 Adding a catalog source means trusting its authors with your agent runtime. A catalog's resources can shape prompts and policy (agents, `agents.md`, `system-prompt.md`), add MCP servers (`mcp.json`), and ship skills whose scripts execute on your machine.
@@ -129,6 +186,8 @@ Before adding a source, review it:
 2. Read every skill you will select, including its scripts and catalog-owned `file` references (see the [trust boundary](./skills.md#trust-boundary)).
 3. Review `mcp.json` — MCP servers are code with whatever access you grant them.
 4. Check `remote_settings` targets: a settings file can add further sources you did not review.
-5. Confirm the repository's ownership and that its maintainers are who you expect.
+5. Check the catalog's own `sources`: its pinned `github:` dependencies are fetched transitively, so
+   review each one like the catalog itself.
+6. Confirm the repository's ownership and that its maintainers are who you expect.
 
 **Pin a `ref:`** — ideally a full commit SHA — for any catalog you do not maintain yourself, and always for catalogs consumed in CI (see [Running tasks in GitHub Actions](./actions.md)). A pinned ref makes updates an explicit, reviewable action — bump the ref after reviewing the diff — instead of silently pulling whatever the catalog publishes next.

package/docs/documentation/cli.md

@@ -14,13 +14,14 @@ Resolve, compose, and launch an agent. `run` is the default command, so plain `o
 | Argument / Option     | Description                                                                      |
 | --------------------- | -------------------------------------------------------------------------------- |
 | `[agent]`             | Agent slug to run. Defaults to the settings `default_agent`.                     |
-| `--harness <harness>` | Harness to launch in: `pi` or `claude`. Defaults to `default_harness`.           |
+| `--harness <harness>` | Harness to launch in: `pi`, `claude`, or `codex`. Defaults to `default_harness`. |
 | `--strict`            | Fail instead of warning when the adapter cannot project part of the composition. |
 
 Any other arguments and unrecognized options are passed through to the launched harness:
 
 ```bash
 outfitter run engineer --harness claude
+outfitter run engineer --harness codex -- exec "review this repo"
 outfitter run persona-reviewer -- --print "summarize this repo"
 ```
 

package/docs/documentation/concepts.md

@@ -12,7 +12,7 @@ flowchart LR
   adapter --> harness[Harness]
 ```
 
-Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi or Claude Code).
+Settings tell Outfitter where `.agents` resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi, Claude Code, or Codex CLI).
 
 ## The `.agents` protocol
 
@@ -80,7 +80,7 @@ Listing, validation, running, and dumping all share one resolver. What `outfitte
 
 ## Adapters
 
-An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; a Claude Code adapter is supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
+An adapter projects composed resources into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; Claude Code and Codex CLI adapters are supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md).
 
 ## State persistence
 

package/docs/documentation/containers.md

@@ -6,10 +6,15 @@ The published image is a generic Outfitter runtime:
 ghcr.io/ai-outfitter/outfitter:<version>
 ```
 
-It uses `outfitter` as its entrypoint and includes the Nix CLI, Bash, core
-utilities, Git, SSH, and CA certificates. It does not include agent profiles,
-credentials, channels, MCP servers, or other use-case behavior. The default
-runtime user and group are both `1000`, with `/tmp` as the home directory.
+It is Debian-based (`node:24-slim`), uses `outfitter` as its entrypoint, and
+includes Node.js, npm, Git, SSH, and CA certificates at their conventional
+Debian paths. It does not include agent profiles, credentials, channels, MCP
+servers, or other use-case behavior. The default runtime user and group are
+both `1000` (named `outfitter`), with `/tmp` as the home directory and
+`/workspace` as the working directory.
+
+A Nix closure variant of the image is also published under the `-nix` suffix;
+see [the `-nix` variant](#the--nix-variant) below.
 
 ## Run a resident agent
 
@@ -42,6 +47,7 @@ spec:
         fsGroup: 1000
       containers:
         - name: agent
+          # The primary Debian-based image; append -nix for the Nix variant.
           image: ghcr.io/ai-outfitter/outfitter:<version>
           stdin: true
           workingDir: /workspace
@@ -75,16 +81,58 @@ resources or impose image, profile, or extension policy.
 
 ## Build a derivative image
 
-Being built with Nix does not normally imply that an image contains the Nix
-CLI. The published Outfitter image includes it intentionally, and the flake also
-exports `lib.mkContainer` for reproducible derivative images:
+The image is a normal Debian base: extend it with an ordinary Dockerfile.
+`apt-get` works, and so does `COPY`ing binaries. A dynamically linked binary
+runs when it matches the image — same architecture, glibc-linked, and its
+shared-library dependencies present. The standard ELF interpreter is where
+tools expect it (unlike the `-nix` variant), but the slim base ships a small
+library set: `apt-get install` a binary's runtime libraries when it needs more.
+Switch to `root` for the layers that install, then drop back to `1000`:
+
+```dockerfile
+FROM ghcr.io/ai-outfitter/outfitter:<version>
+
+USER root
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends jq ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+COPY --chmod=0755 my-tool /usr/local/bin/my-tool
+USER 1000
+```
+
+Build and exercise the exact image:
+
+```sh
+docker build -t example-agent .
+docker run --rm example-agent --version
+docker run --rm --entrypoint /bin/sh example-agent \
+  -c 'jq --version && rg --version && my-tool --version'
+```
+
+The entrypoint stays `outfitter`; override `ENTRYPOINT` only when the derived
+image wraps the launch itself.
+
+## The `-nix` variant
+
+The Nix closure image that was previously the primary tag remains published
+for `lib.mkContainer` consumers:
+
+```text
+ghcr.io/ai-outfitter/outfitter:<version>-nix
+```
+
+It is built by the flake, includes the Nix CLI, Bash, core utilities, Git,
+SSH, and CA certificates, and its entrypoint is an absolute `/nix/store` path.
+It is not conventionally extensible — there is no apt, and foreign dynamic
+binaries do not run — so extend it through Nix instead: the flake exports
+`lib.mkContainer` for reproducible derivative images:
 
 ```nix
 {
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     outfitter = {
-      url = "github:ai-outfitter/outfitter/v1.2.0";
+      url = "github:ai-outfitter/outfitter/v1.4.0";
       inputs.nixpkgs.follows = "nixpkgs";
     };
   };
@@ -122,13 +170,14 @@ docker run --rm --entrypoint /bin/sh example-agent:latest \
 Prefer adding known runtime packages through `extraPackages`. The resulting
 image stays reproducible, and it avoids the trap below.
 
-**Do not mount an empty volume over `/nix`.** The image _is_ its Nix store: the
-entrypoint is an absolute store path and every binary in `/bin` is a symlink
-into `/nix/store`. Mounting a fresh volume there hides all of it, so the
-container cannot start — it fails before it could initialize the very store you
-mounted the volume to populate.
+**Do not mount an empty volume over `/nix` of the `-nix` variant.** That image
+_is_ its Nix store: the entrypoint is an absolute store path and every binary
+in `/bin` is a symlink into `/nix/store`. Mounting a fresh volume there hides
+all of it, so the container cannot start — it fails before it could initialize
+the very store you mounted the volume to populate. (The primary Debian image
+has no `/nix` and is not affected.)
 
-Runtime installation therefore needs one of:
+Runtime installation in the `-nix` variant therefore needs one of:
 
 - a volume **pre-populated** with the image's closure, seeded from the image
   before the agent starts (an init container copying `/nix` into the volume);

package/docs/documentation/hooks.md

@@ -15,6 +15,39 @@ See the [Claude Code hooks documentation](https://code.claude.com/docs/en/hooks)
 
 Pi supports a bootstrap hook via its extension mechanism: an extension passed with `--extension` runs at session start and can register tools, providers, and runtime behavior. Outfitter's own onboarding flow uses this channel. For recurring per-event behavior, Pi extensions are the native surface.
 
+## System extension hooks
+
+An organization can make a local Pi observer load by default on every `outfitter run` by installing a system extension hook. Outfitter reads hook documents in lexical filename order from:
+
+1. `$OUTFITTER_SYSTEM_DIR/*.yml` when the variable is set (the test/development seam), or
+2. `/etc/outfitter/system.d/*.yml` on Linux, or
+3. `/Library/Application Support/Outfitter/system.d/*.yml` on macOS.
+
+Each file contributes extensions and environment additively; files do not override each other. Reusing the same environment key for the same harness in two files is an error rather than an implicit precedence rule. An absent directory is a no-op. An unreadable or malformed document, including one naming an extension path that does not exist, aborts the run whether or not `--strict` is set.
+
+```yaml
+name: pensieve
+harnesses:
+  pi:
+    extensions:
+      - /nix/store/example-pensieve/lib/pensieve/collectors/pi
+    env:
+      PENSIEVE_SINK: https://pensieve.example.com
+      PENSIEVE_INSTALL_SCOPE: launcher
+```
+
+Extension entries must be absolute paths that already exist. Outfitter resolves source-directory, hook-document, and extension symlinks to physical paths before loading them; a dangling link is fatal, and `OUTFITTER_SYSTEM_HOOK_SOURCE` records the physical source directory. Package and Git specifiers are rejected, so a launch never installs a system extension from the network. Only `name` and `harnesses` are accepted at the document root, and each harness entry can contain only `extensions` and `env`; a system hook cannot select an agent, harness, model, tool, skill, or prompt.
+
+For Pi, Outfitter prepends the configured `--extension <path>` arguments after projection on every launch, including `--mode rpc`, print, and other non-interactive launches. Hook documents cannot name the Outfitter-controlled `PI_CODING_AGENT_DIR` or `PI_CODING_AGENT_SESSION_DIR` variables. They also reject `NODE_OPTIONS`, `NODE_REPL_EXTERNAL_MODULE`, `OPENSSL_CONF`, `LD_PRELOAD`, `LD_AUDIT`, `LD_LIBRARY_PATH`, and every `DYLD_*` variable because those can change process loading before Pi starts. Other hook environment is below the launch plan's own environment but above the parent process environment at spawn. `harnesses.claude` and `harnesses.codex` documents validate but are ignored with a warning; Outfitter has no equivalent extension argument for those adapters. Their native managed configuration is the stronger policy surface.
+
+### Launcher scope, not managed scope
+
+This mechanism changes who owns the file that names an extension. It does not change Pi's configuration resolution because Pi never reads the system hook document. The accurate guarantee is **collection is on by default and the organization owns the configuration**, not that the session cannot turn collection off.
+
+The `--no-extensions` option does not disable explicitly passed `--extension` paths, so it does not bypass a system hook. A session can still execute Outfitter's bundled Pi binary directly, never going through the Outfitter launcher, or set `OUTFITTER_SYSTEM_DIR` to an empty directory. Every launch whose platform resolves a hook directory records that choice in `OUTFITTER_SYSTEM_HOOK_SOURCE`: the normal value is the resolved physical system path, while an override is stamped as `env-override:<resolved-physical-path>`. Downstream evidence can therefore distinguish the normal system source from the session-settable bypass.
+
+The normal Linux and macOS directories are root-owned. Outfitter deliberately fails closed on their operator errors: a malformed file should fail on a canary boot, while failing open could silently produce fleet sessions without collection. Those sessions must be treated as unattested rather than clean.
+
 ## Roadmap
 
 > **TODO (protocol gap):** hooks are the one behavioral surface the pinned protocol revision does not model, which means hook definitions cannot yet be expressed portably in a `.agents` tree and projected per harness. The path `agents/<agent-id>/hooks/<hook-id>/` is reserved for a future agent-local hook entity and deliberately has no resolution or projection behavior today. Outfitter may need to ship its own hooks extension that adapters translate to Claude `settings.json` hooks and Pi extensions respectively, or drive the concept into a future protocol revision. Until one of those lands, treat hooks as harness-native configuration and keep them thin: call scripts that live in the tree rather than embedding logic in hook definitions.