@ai-outfitter/outfitter 1.11.0 → 1.12.0

package/dist/setup/DefaultCatalog.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { runGit, syncRemoteRepositoryAtomically, tryReadCleanHead } from '../sources/GitRepository.js';
 import { createRemoteRepositoryCachePath, encodeRemoteSourceSelection, formatRemoteSourceDisplay, isImmutableRef, isVersionTagRef, redactEmbeddedSourceCredentials, } from '../sources/SourceCache.js';
 import { readDeclaredRemoteSources } from '../sources/TransitiveSources.js';
+import { writeSourceState } from '../sources/SourceState.js';
 export const defaultCatalogSource = {
     github: 'ai-outfitter/default-profiles',
     // TODO(release-automation): when default-profiles publishes a new Release Please tag, open a
@@ -45,10 +46,18 @@ export const bootstrapPinnedCatalog = (input) => {
     assertImmutableRef(input.source.ref);
     const hasPayload = input.requirePayload ?? hasAgentsDirectory;
     const root = createRemoteRepositoryCachePath(input.homeDirectory, input.source, input.cacheDirectory);
-    if (isPinnedCatalogCheckout(root, input.source.ref, hasPayload))
+    if (isPinnedCatalogCheckout(root, input.source.ref, hasPayload)) {
+        writeSourceState({
+            homeDirectory: input.homeDirectory,
+            cacheDirectory: input.cacheDirectory,
+            cachePath: root,
+            source: input.source,
+            commit: resolveExpectedCommit(root, input.source.ref),
+        });
         return { root, source: input.source };
+    }
     try {
-        (input.syncRepository ?? syncRemoteRepositoryAtomically)({
+        const synced = (input.syncRepository ?? syncRemoteRepositoryAtomically)({
             cachePath: root,
             fetchRef: isVersionTagRef(input.source.ref)
                 ? `refs/tags/${input.source.ref}:refs/tags/${input.source.ref}`
@@ -65,6 +74,13 @@ export const bootstrapPinnedCatalog = (input) => {
                 return 0;
             },
         });
+        writeSourceState({
+            homeDirectory: input.homeDirectory,
+            cacheDirectory: input.cacheDirectory,
+            cachePath: root,
+            source: input.source,
+            commit: synced.commit,
+        });
         return { root, source: input.source };
     }
     catch (error) {

package/dist/setup/DefaultCatalog.js.map

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

package/dist/sources/SourceCachePolicy.d.ts

@@ -0,0 +1,11 @@
+import type { SourceCachePolicy } from '../settings/Settings.js';
+export interface PrepareSourceCachesInput {
+    readonly homeDirectory: string;
+    readonly projectDirectory: string;
+    readonly policy: SourceCachePolicy;
+}
+export interface PrepareSourceCachesResult {
+    readonly messages: readonly string[];
+}
+/** Establishes every declared remote before resolution; local layers are never passed to sync. */
+export declare const prepareSourceCaches: (input: PrepareSourceCachesInput) => PrepareSourceCachesResult;

package/dist/sources/SourceCachePolicy.js

@@ -0,0 +1,48 @@
+import { mkdirSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { executeSyncCommand } from '../cli/commands/SyncCommand.js';
+import { syncRemoteRepositoryAtomically } from './GitRepository.js';
+import { inspectSourceCache, unchangedResult, withSourceLock, writeSourceState } from './SourceState.js';
+const fullCommitPattern = /^[a-f0-9]{40}$/u;
+const quarantine = (cachePath) => {
+    const destination = `${cachePath}.outfitter-quarantine-${new Date().toISOString().replace(/[:.]/gu, '-')}-${process.pid}`;
+    mkdirSync(dirname(destination), { recursive: true });
+    renameSync(cachePath, destination);
+    return destination;
+};
+const policyRepositorySync = (input) => (request) => withSourceLock(request.cachePath, () => {
+    if (input.policy === 'locked' && !fullCommitPattern.test(request.source.ref ?? '')) {
+        throw new Error('Locked source-cache policy requires a full 40-character commit pin.');
+    }
+    const state = inspectSourceCache({
+        homeDirectory: input.homeDirectory,
+        cachePath: request.cachePath,
+        source: request.source,
+    });
+    if (state.health === 'healthy' && state.commit !== undefined)
+        return unchangedResult(state.commit);
+    if (input.policy === 'offline') {
+        throw new Error(`Source cache is ${state.health}; offline policy prohibits repair.`);
+    }
+    const quarantined = state.health === 'dirty' ? quarantine(request.cachePath) : undefined;
+    const result = syncRemoteRepositoryAtomically(request);
+    writeSourceState({
+        homeDirectory: input.homeDirectory,
+        source: request.source,
+        commit: result.commit,
+        cachePath: request.cachePath,
+    });
+    return {
+        ...result,
+        warnings: result.warnings + (quarantined === undefined ? 0 : 1),
+    };
+});
+/** Establishes every declared remote before resolution; local layers are never passed to sync. */
+export const prepareSourceCaches = (input) => {
+    const result = executeSyncCommand({ homeDirectory: input.homeDirectory, projectDirectory: input.projectDirectory }, { syncRepository: policyRepositorySync(input) });
+    if (result.exitCode !== 0) {
+        throw new Error(`Source-cache ${input.policy} policy failed before composition: ${result.messages.join('; ')}`);
+    }
+    return { messages: result.messages };
+};
+//# sourceMappingURL=SourceCachePolicy.js.map

package/dist/sources/SourceCachePolicy.js.map

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

package/dist/sources/SourceState.d.ts

@@ -0,0 +1,32 @@
+import type { AtomicRepositorySyncResult } from './GitRepository.js';
+import type { RemoteSourceReference } from './SourceCache.js';
+export declare const SOURCE_STATE_VERSION = 1;
+export interface SourceStateManifest {
+    readonly version: 1;
+    readonly source: string;
+    readonly requestedRef: string | null;
+    readonly resolvedCommit: string;
+    readonly cacheKey: string;
+}
+export type SourceCacheHealth = 'healthy' | 'missing' | 'dirty' | 'legacy' | 'mismatched' | 'unverified';
+export declare const sourceStatePath: (homeDirectory: string, source: RemoteSourceReference, cacheDirectory?: string) => string;
+export declare const readSourceState: (path: string) => SourceStateManifest | undefined;
+export declare const inspectSourceCache: (input: {
+    readonly homeDirectory: string;
+    readonly cacheDirectory?: string;
+    readonly cachePath: string;
+    readonly source: RemoteSourceReference;
+}) => {
+    readonly health: SourceCacheHealth;
+    readonly commit?: string;
+    readonly manifest?: SourceStateManifest;
+};
+export declare const writeSourceState: (input: {
+    readonly homeDirectory: string;
+    readonly cacheDirectory?: string;
+    readonly source: RemoteSourceReference;
+    readonly commit: string;
+    readonly cachePath?: string;
+}) => void;
+export declare const withSourceLock: <T>(cachePath: string, action: () => T) => T;
+export declare const unchangedResult: (commit: string) => AtomicRepositorySyncResult;

package/dist/sources/SourceState.js

@@ -0,0 +1,90 @@
+import { mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tryReadCleanHead } from './GitRepository.js';
+import { encodeRemoteSource, normalizeRemoteSourceUri, redactSourceUriCredentials, resolveRemoteRepositoryCacheRoot, } from './SourceCache.js';
+export const SOURCE_STATE_VERSION = 1;
+export const sourceStatePath = (homeDirectory, source, cacheDirectory) => join(resolveRemoteRepositoryCacheRoot(homeDirectory, cacheDirectory), 'source-state', `${encodeRemoteSource(source)}.json`);
+const sourceStatePathForCache = (cachePath, source) => join(dirname(dirname(cachePath)), 'source-state', `${encodeRemoteSource(source)}.json`);
+const sourceIdentity = (source) => redactSourceUriCredentials(normalizeRemoteSourceUri(source));
+export const readSourceState = (path) => {
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (value.version !== SOURCE_STATE_VERSION ||
+            typeof value.source !== 'string' ||
+            !(typeof value.requestedRef === 'string' || value.requestedRef === null) ||
+            typeof value.resolvedCommit !== 'string' ||
+            typeof value.cacheKey !== 'string')
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const inspectSourceCache = (input) => {
+    const commit = tryReadCleanHead(input.cachePath);
+    if (commit === undefined) {
+        try {
+            readFileSync(join(input.cachePath, '.git', 'HEAD'));
+            return { health: 'dirty' };
+        }
+        catch {
+            return { health: 'missing' };
+        }
+    }
+    const manifest = readSourceState(sourceStatePathForCache(input.cachePath, input.source));
+    if (manifest === undefined)
+        return { health: 'legacy', commit };
+    if (manifest.source !== sourceIdentity(input.source) ||
+        manifest.requestedRef !== (input.source.ref ?? null) ||
+        manifest.cacheKey !== encodeRemoteSource(input.source) ||
+        manifest.resolvedCommit !== commit)
+        return { health: 'mismatched', commit, manifest };
+    return { health: 'healthy', commit, manifest };
+};
+export const writeSourceState = (input) => {
+    const path = input.cachePath === undefined
+        ? sourceStatePath(input.homeDirectory, input.source, input.cacheDirectory)
+        : sourceStatePathForCache(input.cachePath, input.source);
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    const manifest = {
+        version: SOURCE_STATE_VERSION,
+        source: sourceIdentity(input.source),
+        requestedRef: input.source.ref ?? null,
+        resolvedCommit: input.commit,
+        cacheKey: encodeRemoteSource(input.source),
+    };
+    writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+};
+export const withSourceLock = (cachePath, action) => {
+    const lock = `${cachePath}.outfitter.lock`;
+    mkdirSync(dirname(lock), { recursive: true });
+    const deadline = Date.now() + 300_000;
+    let descriptor;
+    while (descriptor === undefined) {
+        try {
+            descriptor = openSync(lock, 'wx', 0o600);
+        }
+        catch (error) {
+            /* v8 ignore next -- non-EEXIST open failures and a five-minute lock timeout are OS boundaries. */
+            if (error.code !== 'EEXIST' || Date.now() >= deadline)
+                throw error;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        closeSync(descriptor);
+        rmSync(lock, { force: true });
+    }
+};
+export const unchangedResult = (commit) => ({
+    commit,
+    status: 'unchanged',
+    warnings: 0,
+});
+//# sourceMappingURL=SourceState.js.map

package/dist/sources/SourceState.js.map

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

package/docs/documentation/README.md

@@ -1,8 +1,10 @@
 # Outfitter documentation
 
-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.
+Outfitter lays out conventions for iterating on and sharing agent configuration — agent profiles, skills, and loadouts. Start by setting up your configuration, then learn how to share it across projects and your organization and run it in CI or on a cluster. 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
+To understand AI Outfitter and how its projects fit together, read
+[How AI Outfitter fits together](./ai-outfitter.md). To assess and onboard your
+own 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.
@@ -48,7 +50,7 @@ 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.
 - [Channels](./channels.md) — add external event sources that wake a resident agent only when work arrives.
-- [Container images](./containers.md) — run the published Debian-based image persistently, extend it with apt, or use the `-nix` variant.
+- [Container images](./containers.md) — run the published Debian-based image persistently or extend it with apt.
 - [Recurring runs](./recurring-runs.md) — loops three ways: the local loop extension, Actions cron, cluster schedules.
 - [Cost estimation](./cost-estimation.md) — one workload profile and model-cost line across local, Actions, and Kubernetes runs.
 - [In-cluster agents](./in-cluster.md) — resident agents, CronJobs, and subagent Jobs via Link Operator.

package/docs/documentation/ai-outfitter.md

@@ -0,0 +1,259 @@
+# How AI Outfitter fits together
+
+Open, vendor-neutral tooling for configuring and operating agents: ramp a
+user, a team, or an organization from AI-assisted coding to an autonomous
+software development lifecycle.
+
+Everything here builds on one convention: an agent's context, tools, skills,
+and permissions are plain files in a `.agents/` directory — committed,
+reviewed, and shared like the rest of your code. The same plain-file definition
+can be shared across environments and model vendors; runtime support varies by
+harness, as shown in the
+[support matrix](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/support-matrix.md).
+The core is open source under MIT.
+
+## Why we built AI Outfitter
+
+We built AI Outfitter to give teams a shared path from local agent use to
+automated and governed workflows. Its defaults are customizable, so teams can
+begin at the rung that matches their current process.
+
+## The adoption ramp
+
+Five rungs, from AI-assisted coding to an autonomous lifecycle
+([full definition](https://github.com/ai-outfitter/outfitter/blob/main/docs/philosophy.md)).
+Each Outfitter component targets a rung, so you climb without rebuilding what
+got you here — and without adopting complexity too early. Rungs 2, 3, and 4
+each open with the **runbook** that gets you there: the concrete steps, and a
+success check you run rather than judge.
+
+1. **Assisted** — autocomplete and chat; a human's hands stay on the
+   keyboard. _You are here if_ you use autocomplete in an IDE.
+   There is nothing to govern yet — but the habit that matters starts here:
+   document what works and what doesn't in `AGENTS.md`/`CLAUDE.md`, and
+   keep it in the repo.
+   - [First-time CLI agent users](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/first-time-cli-agent-users.md#context-engineering)
+     — what belongs in a first `AGENTS.md`, and how to ask an agent to use
+     it.
+
+2. **Delegated** — a local agent does the task; you define the idea and
+   review the PR. _You are here if_ engineers run a coding agent in a
+   terminal and push the result. This is where configuration starts to
+   matter.
+   - **Runbook: [Share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md)**
+     — one pinned catalog the organization shares, instead of per-laptop
+     configuration.
+   - [outfitter](https://github.com/ai-outfitter/outfitter) — composes what
+     an agent knows and may do into a **profile**: plain files in your
+     `.agents/` folder, reviewed like code and portable across environments
+     and **harnesses** (the CLI that runs an agent: Claude Code, Pi, Codex).
+   - [deepwork](https://github.com/ai-outfitter/deepwork) — step-by-step
+     quality gates so the agent checks its own work.
+
+3. **Automated** — a workflow runs without your laptop: an issue, a message,
+   or a schedule triggers agents in CI, on a cluster, or on a remote server
+   you never sit at; adversarial review is part of the pipeline; session
+   logs are captured before merge. _You are here when_ you close your laptop
+   and the work keeps going. What promotes you is the trigger, not the
+   hardware: an agent you drive over SSH is rung 2 on a bigger machine.
+   - **Runbook: [Run it without your laptop](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/run-without-your-laptop.md)**
+     — an event triggers the workflow, its output lands through review, and
+     the session is captured.
+   - [actions](https://github.com/ai-outfitter/actions) — runs any profile
+     headless in GitHub Actions, on any trigger.
+   - [channels](https://github.com/ai-outfitter/channels) — pushes email,
+     Slack, Signal, and forge events (GitHub or GitLab activity) into an
+     agent session, so one message can start the same workflow.
+   - [agent-operator](https://github.com/ai-outfitter/agent-operator) —
+     hosts the same profiles on your own infrastructure, well before you
+     need its resident-agent story on the next rung.
+
+4. **Governed** — the organization shares one version-pinned catalog of
+   agents, skills, and policy; every agent action lands in an auditable
+   record; **[resident agents](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/in-cluster.md)**
+   — long-lived agents onboarded like teammates,
+   with their own accounts and boundaries — take on standing jobs. _You are
+   here when_ agents work across many teams, and the organization needs
+   shared policy — and proof of what every agent did.
+   - **Runbook: [Give the agent a residence](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/give-the-agent-a-residence.md)**
+     — a named, assignable agent with an account and somewhere to live.
+   - **Build your agent catalog: [Share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md)**
+     — the rung 2 runbook creates it and links to guidance on its layout,
+     version pinning, and governance. Our own
+     [.agents](https://github.com/ai-outfitter/.agents) is a worked example
+     you can read end to end.
+   - [agent-operator](https://github.com/ai-outfitter/agent-operator) —
+     provisions and supervises resident agents on your own infrastructure.
+   - [pensieve](https://github.com/ai-outfitter/pensieve) — designed to retain
+     evidence from agent sessions, including environments, agents, tools,
+     artifacts, and costs. That record can support audits, compliance reviews,
+     and evaluation workflows.
+
+5. **Self-improving** — the audit record feeds evals and improvement; humans
+   set goals and acceptance gates, agents own the middle. Rung 5 is where
+   the stack is thinnest today.
+   - [evals](https://github.com/ai-outfitter/evals) — evaluates changes to a
+     profile, model, or workflow with reproducible, attested benchmarks.
+   - [autoimprove](https://github.com/ai-outfitter/autoimprove) — improves
+     portable skills against measured outcomes.
+
+## Start with one workflow end to end
+
+One useful first workflow takes **a feature idea to a merged PR**, automated
+end to end, with every step leaving evidence. This is what rung 3 looks like
+up close.
+
+![A feature idea flows through plan, implement, and adversarial review to a merged PR, with every transition writing to the evidence record](./assets/feature-to-pr.svg)
+
+1. **Entry point.** Someone files an issue and assigns it to an agent — from
+   the forge, from chat, or from a planning session at a desk. Different
+   doors, same workflow.
+2. **Plan.** A planner profile with read-only tools turns the issue into a
+   spec artifact and posts it back to the issue, where a human can approve
+   it (we recommend an enforced spec system, like
+   [2119](https://github.com/Unsupervisedcom/2119), for more autonomous
+   workflows).
+3. **Implement.** An implementer profile picks up the approved spec in a
+   fresh container with exactly the tools the work needs — a different
+   agent, a clean context window, the same shared catalog.
+4. **Review.** An adversarial reviewer profile, which shares none of the
+   implementer's context, tries to break the change before any human reads
+   it.
+5. **Merge.** The PR arrives with its history attached: session transcripts,
+   tool calls, and diffs captured as artifacts before the environment that
+   produced them is torn down.
+
+The same shape handles other starting workflows. A vulnerability report
+instead of a feature idea turns the pipeline into governed security
+remediation: the scanner files the issue (most scanners already can), the
+planner scopes the fix, and the same steps carry it to a tested, approved
+PR. Bug reports run the same way with a triage step in front: an agent
+reproduces and prioritizes each report, and only the ones that clear triage
+enter the pipeline.
+
+Teams adopt the system through the same composition process: an engineer
+refines a skill in their own
+[`~/.agents`](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/local-development.md)
+against real work; the team mines
+[pensieve](https://github.com/ai-outfitter/pensieve) for the patterns behind
+successful and failing runs. When a change earns trust it moves by pull
+request into the org catalog, where every agent composes it by name. One
+person's improvement becomes everyone's default at the next pin bump — no
+one else reconfigures anything.
+
+## Start this afternoon
+
+You can begin with a local assessment and CLI trial before committing to an
+organization-wide rollout or additional infrastructure.
+
+### 1. See where you are
+
+The read-only assessment takes one afternoon. The
+[org-onboarding runbook](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/usecases/org-onboarding-sdlc-report.md)
+produces a baseline **SDLC report**: where your organization sits on the
+ramp, with evidence, gaps, and next-rung recommendations. Concretely: one
+engineer runs the `sdlc-report` skill from their own local agent with a
+read-only forge token. It reads through the API — never clones, never
+writes — and produces two local files you review before anyone else sees
+them. We ran it on this organization the day we wrote this page; the output
+is committed at
+[.agents/reports/sdlc](https://github.com/ai-outfitter/.agents/tree/main/reports/sdlc),
+so you can see exactly what you would get.
+
+### 2. Try the toolchain
+
+The first run takes about ten minutes.
+
+```bash
+npx @ai-outfitter/outfitter
+```
+
+This launches the Outfitter CLI with the
+[Pi](https://github.com/earendil-works/pi) harness bundled and walks you
+through composing your first agent profile from a starter catalog. You end
+in a working agent session, and everything it created is plain files under
+`~/.agents` — which you can read, edit, or delete afterward.
+
+### 3. Automate one workflow
+
+Pick feature-to-PR or bug-to-PR, keep it to
+one repository, and promote the profiles you already trust at a desk into
+[CI](https://github.com/ai-outfitter/actions). Work the runbooks in order —
+[share one catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/share-one-catalog.md),
+[run it without your laptop](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/run-without-your-laptop.md),
+then [give the agent a residence](https://github.com/ai-outfitter/outfitter/blob/main/docs/runbooks/give-the-agent-a-residence.md).
+Each ends with the one concrete step that starts the next.
+
+Every runbook closes with a **Done when** section naming the signals the report
+above checks — for this one, `triggered-agents`, `protected-landing`, and
+`session-capture`. Re-run the report and it names whichever is still unmet.
+
+## Agent configuration as code
+
+Your agent setup is already configuration: system prompts, skills, MCP
+servers, model choices, permissions. Today that configuration lives per tool
+and per laptop, gets pasted between repositories, and drifts. Every other
+kind of configuration your organization depends on graduated from that stage
+years ago — into files, in a repository, behind review.
+
+The [`.agents` convention](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/concepts.md#the-agents-protocol)
+is an open standard for doing the same for agents:
+
+```text
+.agents/
+  agents.md            # shared operating context
+  system-prompt.md     # base system prompt
+  mcp.json             # MCP servers
+  models.json          # model configuration
+  agents/<id>/agent.md # agent identities + loadouts
+  skills/<id>/...      # capability packages
+  knowledge/           # reference documents
+  commands/            # slash commands
+```
+
+Because the configuration is Markdown and JSON, you can read, review, and
+audit it with ordinary repository tools. Layers merge by name — a project's
+`.agents/` over an engineer's `~/.agents/` over the organization's
+**[catalog](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/catalogs.md)**,
+a shared collection pinned by version — so individuals keep their preferences and
+organizations keep their policy
+([conventions](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/conventions.md)).
+
+Composition beats accumulation. A profile is a selection from those files,
+and profiles stack: a personal baseline, a team convention, a project role,
+switched as the work changes. That keeps each profile tight, and tight
+profiles preserve the context headroom that turns into faster, better
+sessions.
+
+The directory is also the exit door. It is the source of truth, and it is
+useful without Outfitter. Vendor-neutral cuts in every direction — models,
+harnesses, and us. Swap model vendors freely. Run the catalog through any
+harness: Pi has the deepest runtime support today, with Claude Code tracked
+component by component in the
+[support matrix](https://github.com/ai-outfitter/outfitter/blob/main/docs/documentation/support-matrix.md)
+— a Claude Code team starts on Claude Code, and the matrix shows the gaps
+before you hit them. And if you drop Outfitter itself, the catalog you
+built is still yours — plain files, still working.
+
+## Where this is today
+
+Outfitter and several supporting projects are in active development. Actions
+and the catalogs run AI Outfitter's own workloads today; rung 5 remains the
+least developed part of the stack. Check each linked repository for its current
+implementation status.
+
+The model is open core: the convention, the toolchain, and the defaults are
+MIT — modules you can rip out and replace — while some advanced capabilities
+ship under an enterprise license. If you are evaluating this for an
+organization, [open an issue](https://github.com/ai-outfitter/outfitter/issues)
+with what you found. The gaps you hit are the roadmap we want.
+
+## As you climb
+
+Two suggestions we make strongly, and follow ourselves:
+
+1. **Automate nothing you have not first done manually.**
+2. **Hand over control one layer at a time.**
+
+You never skip a step you don't understand, and nothing you build on one
+rung is thrown away on the next.

package/docs/documentation/assets/feature-to-pr.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 980 284" font-family="-apple-system, 'Segoe UI', Helvetica, Arial, sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 1 L 8 5 L 0 9 z" fill="#57606a"/>
+    </marker>
+    <marker id="arrdim" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
+      <path d="M 0 1 L 8 5 L 0 9 z" fill="#d4a72c"/>
+    </marker>
+  </defs>
+
+  <rect x="0.5" y="0.5" width="979" height="283" rx="12" fill="#ffffff" stroke="#d0d7de"/>
+
+  <!-- step boxes -->
+  <g>
+    <rect x="28" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="112" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">1 · ENTRY POINT</text>
+    <text x="112" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Issue assigned</text>
+    <text x="112" y="96" text-anchor="middle" font-size="11" fill="#57606a">from the forge, chat,</text>
+    <text x="112" y="110" text-anchor="middle" font-size="11" fill="#57606a">or a desk session</text>
+  </g>
+  <g>
+    <rect x="217" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="301" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">2 · PLAN</text>
+    <text x="301" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Planner agent</text>
+    <text x="301" y="96" text-anchor="middle" font-size="11" fill="#57606a">read-only tools →</text>
+    <text x="301" y="110" text-anchor="middle" font-size="11" fill="#57606a">spec posted for approval</text>
+  </g>
+  <g>
+    <rect x="406" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="490" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">3 · IMPLEMENT</text>
+    <text x="490" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Implementer agent</text>
+    <text x="490" y="96" text-anchor="middle" font-size="11" fill="#57606a">fresh container,</text>
+    <text x="490" y="110" text-anchor="middle" font-size="11" fill="#57606a">scoped tools, clean context</text>
+  </g>
+  <g>
+    <rect x="595" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="679" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">4 · REVIEW</text>
+    <text x="679" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">Adversarial reviewer</text>
+    <text x="679" y="96" text-anchor="middle" font-size="11" fill="#57606a">shares no context,</text>
+    <text x="679" y="110" text-anchor="middle" font-size="11" fill="#57606a">tries to break the change</text>
+  </g>
+  <g>
+    <rect x="784" y="36" width="168" height="88" rx="8" fill="#f6f8fa" stroke="#d0d7de"/>
+    <text x="868" y="58" text-anchor="middle" font-size="10.5" fill="#0969da" font-weight="600" letter-spacing="0.5">5 · MERGE</text>
+    <text x="868" y="78" text-anchor="middle" font-size="14" fill="#1f2328" font-weight="600">PR, with history</text>
+    <text x="868" y="96" text-anchor="middle" font-size="11" fill="#57606a">transcripts &amp; diffs attached</text>
+    <text x="868" y="110" text-anchor="middle" font-size="11" fill="#57606a">before teardown</text>
+  </g>
+
+  <!-- horizontal arrows -->
+  <line x1="198" y1="80" x2="213" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="387" y1="80" x2="402" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="576" y1="80" x2="591" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="765" y1="80" x2="780" y2="80" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <!-- drop lines to the record -->
+  <line x1="112" y1="124" x2="112" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="301" y1="124" x2="301" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="490" y1="124" x2="490" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="679" y1="124" x2="679" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+  <line x1="868" y1="124" x2="868" y2="162" stroke="#d4a72c" stroke-width="1.2" stroke-dasharray="3 3" marker-end="url(#arrdim)"/>
+
+  <!-- evidence record band -->
+  <rect x="28" y="166" width="924" height="52" rx="8" fill="#fff8c5" stroke="#d4a72c" stroke-dasharray="5 4"/>
+  <text x="490" y="188" text-anchor="middle" font-size="11" fill="#7d4e00" font-weight="600" letter-spacing="1">THE RECORD</text>
+  <text x="490" y="206" text-anchor="middle" font-size="12" fill="#7d4e00">session transcripts · tool calls · diffs · approvals — written at every transition</text>
+
+  <!-- footer caption -->
+  <text x="490" y="252" text-anchor="middle" font-size="12" fill="#57606a" font-style="italic">Each step is an agent profile from a shared catalog — designed to run the same at a desk, in CI, or in a cluster.</text>
+</svg>

package/docs/documentation/cli.md

@@ -94,3 +94,11 @@ Write the composed resource tree as a self-contained `.agents/` directory for re
 | `--out <dir>`  | Destination directory (default `./.agents`).         |
 
 > **Tasks and `outfitter task bake`** — baking a task and its inputs into an immutable execution artifact — are the subject of a separate upcoming RFC and are not part of this command surface yet. See [Tasks](./tasks.md).
+
+`outfitter run` verifies these caches before composition. Use
+`--source-cache-policy <repair|locked|offline>` to override the configured startup policy.
+
+## `outfitter sources`
+
+Report local and remote source precedence, requested and resolved revisions, origins, and cache
+health. `outfitter sources --json` emits stable credential-redacted machine-readable output.