@ai-outfitter/outfitter 0.7.2 → 0.8.0

package/doc/documentation/cli.md

@@ -0,0 +1,74 @@
+# CLI reference
+
+Global options:
+
+| Option          | Description                  |
+| --------------- | ---------------------------- |
+| `-V, --version` | Print the Outfitter version. |
+| `-h, --help`    | Show help for a command.     |
+
+## `outfitter run [args...]`
+
+Assemble a composite profile and launch the selected agent CLI. `run` is the default command, so plain `outfitter` and `outfitter run` are equivalent.
+
+| Option                    | Description                                                                |
+| ------------------------- | -------------------------------------------------------------------------- |
+| `-p, --profile <profile>` | Outfitter profile id to run. Defaults to the settings `default_profile`.   |
+| `--agent <agent>`         | Agent adapter to launch: `pi` or `claude`. Defaults to `default_agent`.    |
+| `--strict`                | Fail instead of warning when controls cannot be translated by the adapter. |
+
+Any other arguments and unrecognized options are passed through to the launched agent CLI:
+
+```bash
+outfitter run --profile engineer --agent claude
+outfitter -p data_analyst -- --print "summarize this repo"
+```
+
+On a first interactive launch with no `~/.outfitter/settings.yml`, `outfitter` starts Pi-native onboarding instead of a normal run.
+
+## `outfitter setup [source]`
+
+Create initial Outfitter settings and a default profile. Setup launches Pi with the Outfitter onboarding extension and finishes profile selection inside the agent session (see [Getting started](./getting-started.md)).
+
+| Argument   | Description                                                                                                    |
+| ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `[source]` | Optional setup source: a local path or a git URL of a [profile repository](./profile-repository.md) to import. |
+
+## `outfitter sync`
+
+Synchronize URI-backed profile and remote settings sources into the local cache (`~/.outfitter/cache/`). Takes no options. Reports a per-source status of `updated`, `unchanged`, `skipped`, or `failed`, and validates synced profile sources.
+
+## `outfitter profile`
+
+List and manage Outfitter profiles.
+
+### `outfitter profile list`
+
+List available Outfitter profiles.
+
+| Option  | Description                                                       |
+| ------- | ----------------------------------------------------------------- |
+| `--all` | Include template profiles that are intended only for inheritance. |
+
+### `outfitter profile create <name>`
+
+Create a new Outfitter profile skeleton.
+
+| Argument / option | Description                                               |
+| ----------------- | --------------------------------------------------------- |
+| `<name>`          | Filesystem-safe profile name.                             |
+| `--scope <scope>` | Destination scope: `user`, `project`, or `project-local`. |
+| `--path <path>`   | Destination profile source directory.                     |
+
+### `outfitter profile lint`
+
+Validate profiles, inheritance, and typed prompt includes.
+
+| Option     | Description                              |
+| ---------- | ---------------------------------------- |
+| `--strict` | Exit non-zero when warnings are present. |
+| `--json`   | Print diagnostics as JSON.               |
+
+## `outfitter welcome`
+
+Run Outfitter welcome onboarding prompts in the terminal. This is a legacy compatibility command: current onboarding runs natively inside Pi (via `outfitter setup` or the first-run `outfitter` launch), and `welcome` remains for environments that need the older terminal prompt flow. Requires an interactive TTY. Takes no options.

package/doc/documentation/concepts.md

@@ -0,0 +1,54 @@
+# Concepts
+
+How an `outfitter` launch goes from configuration files to a running agent:
+
+```mermaid
+flowchart LR
+  A[Settings] --> B[Profile sources]
+  B --> C[Profile stack]
+  C --> D[Composite profile]
+  D --> E[Adapter]
+  E --> F[Agent CLI]
+```
+
+Settings tell Outfitter where profiles come from; profile sources supply profile definitions; the definitions for the selected profile form an ordered stack; the merged stack is written out as a composite profile; an adapter translates that composite profile into agent-specific files, flags, and environment variables; and the agent CLI launches with the result.
+
+## Profile
+
+A profile is a named, reusable YAML definition of how an agent should be outfitted: model and provider, thinking level, system and append prompts, skills, extensions, subagents, DeepWork jobs, CLI arguments, and environment variables. Profiles can inherit from other profiles and can live as a flat `<id>.yml` file or a directory with a `profile.yml` plus bundled resources. See [Profiles](./profiles.md).
+
+## Composite profile
+
+A composite profile is the temporary runtime configuration directory Outfitter assembles for one profile and one agent CLI run. It contains the generated files the agent needs, is created under the system temp directory, and is owned by Outfitter for the lifetime of the run — durable state is handled separately (see state persistence below).
+
+## Catalog / profile source
+
+A profile source is any place profiles are loaded from: a local directory (`path:`), a GitHub repository (`github: owner/repo`), or a git URI (`uri:`). A shared repository of profiles is called a catalog (or profile repository). Remote sources are cached under `~/.outfitter/cache/` and updated with `outfitter sync`; they support `ref` pinning and `only`/`except` filters. See [Profile repositories](./profile-repository.md).
+
+## Settings scopes
+
+Outfitter reads `settings.yml` from three local scopes — user (`~/.outfitter/settings.yml`), project (`<project>/.outfitter/settings.yml`), and project-local (`<project>/.outfitter/local/settings.yml`, for personal, uncommitted overrides) — plus cached remote settings supplied by `remote_settings` entries. Settings declare the default profile and agent, profile sources, and other launch behavior.
+
+## Controls
+
+Controls are the generic, agent-neutral knobs a profile sets: `model`, `provider`, `thinking`, `system_prompt`, `append_system_prompt`, `skills`, `extensions`, `args`, `environment`, and more. Profiles can also nest adapter-specific overrides under `controls.pi` or `controls.claude` when one agent needs different values.
+
+## Adapters
+
+An adapter translates generic controls into one agent CLI's native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; a Claude Code adapter is supported with gaps. When an adapter cannot honor a control it warns to stderr, or fails when `--strict` is set. See the [adapter support matrix](./support-matrix.md) for per-adapter coverage.
+
+## State persistence
+
+Agents write state during a run — auth, native settings, plugins, sessions. Each adapter declares the state paths it understands and how writes are handled (`symlink`, `discard`, `warn`, `error`, or `prompt`), so useful state survives future runs without Outfitter silently copying unknown files. See [State persistence](./state.md).
+
+## Layer precedence
+
+When several layers define the same profile or setting, higher layers win:
+
+1. Project-local (`.outfitter/local/`)
+2. Project (`.outfitter/`)
+3. User (`~/.outfitter/`)
+4. Cached remote sources (in configured source order)
+5. Built-in defaults
+
+For profiles, explicitly inherited profiles slot between cached remote sources and built-in defaults, in declared order.

package/doc/documentation/first-time-cli-agent-users.md

@@ -0,0 +1,137 @@
+# First-time CLI agent users
+
+This guide is for people who have never used Claude Code, Codex, Pi, or another terminal agent. Outfitter gives you a curated Pi setup; this page explains the working model so the first session feels powerful instead of mysterious.
+
+## Start with YOLO mode, then understand permissions
+
+Most people first enjoy agent CLIs when they let the agent act: read the repo, edit files, run tests, and iterate without stopping for every tiny approval. That is the “YOLO mode” feeling: the agent can move at software speed while you steer the goal.
+
+Use it intentionally:
+
+```text
+Goal: make the failing test pass.
+You may inspect files, edit code, and run project tests.
+Ask before deleting files, changing dependencies, touching credentials, or publishing anything.
+```
+
+Permissions are the safety boundary. A good session says what the agent may do, what it must ask about, and what evidence proves the job is done. Outfitter’s default profile catalog is meant to provide useful defaults, but you still own the trust decision for each project and command.
+
+Good first permission rules:
+
+- Let the agent read project files and run local tests.
+- Let it make small edits in a git branch or worktree.
+- Require approval for dependency changes, destructive shell commands, production data, credentials, publishing, releases, payments, legal filings, merges, and force-pushes.
+- Ask for a short plan before broad rewrites.
+
+## Context engineering
+
+Agent CLIs work best when you shape the context, not when you paste everything. Basic context engineering starts with `AGENTS.md`: a repository-local instruction file that tells the agent how the project works, what commands are safe, what evidence matters, and what rules must survive across sessions.
+
+A useful first `AGENTS.md` can be small:
+
+```md
+# Agent instructions
+
+- Read `README.md` and `package.json` before changing code.
+- Use `npm test -- --runInBand path/to/test` for narrow test runs when possible.
+- Ask before deleting files, changing dependencies, or editing release config.
+- Treat docs in `docs/requirements/` as product requirements.
+```
+
+Then ask the agent to use that context:
+
+```text
+Read AGENTS.md, the README, package scripts, and the failing test before editing.
+Then propose a three-step plan with acceptance criteria.
+```
+
+Outfitter profiles can store reusable personal context, while `AGENTS.md` keeps project context in the repo. Pi also supports extension-provided tools and skills; the default profile catalog may include skills that add project-governance, review, or browser/testing instructions to the session.
+
+## Planning mode
+
+Planning mode is provided by the plan Pi extension installed in the current Outfitter profile. In the default Outfitter Pi setup, use the plan-mode keybinding (`Shift+Tab`) to toggle from build mode into plan mode before broad changes. Plan mode keeps the agent in an investigation/design posture: read, inspect, and propose; do not write the implementation yet.
+
+Use the plan-mode keybinding when:
+
+- the change spans multiple files;
+- you do not know the repo conventions;
+- the task mixes product, docs, and code;
+- the cost of a wrong edit is high.
+
+Example after toggling plan mode:
+
+```text
+Goal: add a settings flag for quiet startup.
+Find the relevant command, settings schema, tests, and docs.
+Return the expected commits and validation commands.
+```
+
+A strong plan includes checkable requirements: “MUST update the schema,” “MUST preserve non-interactive behavior,” “SHOULD add a regression test.” Toggle back to build mode when you want the agent to implement the approved plan.
+
+## Subagents
+
+A subagent is another agent process given a focused task. Use subagents when one agent should keep the main plan while another does isolated research or implementation.
+
+Two common patterns:
+
+```text
+One focused agent:
+Fix this bug in the current branch. Inspect, edit, test, and report the diff.
+```
+
+```text
+One agent managing subagents:
+Create a plan. Delegate implementation to a subagent in a worktree. Review the subagent diff before committing.
+```
+
+Subagents are useful for:
+
+- independent research;
+- code review;
+- implementation in a clean worktree;
+- comparing approaches;
+- keeping risky experiments away from the main checkout.
+
+Whether subagents are available depends on the active Pi/Outfitter profile and extensions. The default profile catalog may include subagent definitions or guidance; vanilla agent CLIs differ in what they provide out of the box.
+
+## Skills
+
+A skill is packaged instruction for a recurring job. Inside Pi, active skills are invoked as slash commands, for example `/skill:generated-daily-report`. Instead of teaching the agent your report, review, or research process every time, a skill can define how to run it, what files matter, and what “done” means.
+
+Try inside Pi:
+
+```text
+/skill:generated-daily-report
+```
+
+Then provide the goal or inputs the skill asks for. Other examples might be project review, browser testing, release notes, or incident summaries, depending on what the active profile installed.
+
+Skills may come from Pi packages, from the Outfitter default profile catalog, or from a project-local `.outfitter` profile. If a skill is not active, ask Pi what skills it can see before relying on it.
+
+## Extensions and tools
+
+Extensions add tools and UI affordances to Pi. For example, an extension can expose a browser tool, a structured question UI, a GitHub helper, or an Outfitter setup command. These are not all vanilla Pi features; they appear when the active profile loads the relevant Pi package or extension.
+
+Ask:
+
+```text
+What tools and skills are active in this session? Which came from Pi, which came from Outfitter, and which came from project-local config?
+```
+
+That question teaches you the session’s actual capability boundary before you depend on a tool.
+
+## First useful session script
+
+Paste this into your first serious agent session:
+
+```text
+I am new to CLI agents.
+Goal: help me make one small, safe improvement in this repo.
+First, inspect the repo entry points and explain the project shape.
+Second, propose a plan with acceptance criteria.
+Third, wait for my approval before editing.
+You may read files and run non-destructive discovery commands.
+Ask before deleting files, changing dependencies, pushing, publishing, or touching credentials.
+```
+
+After a few sessions, move the reusable parts into an Outfitter profile so every launch starts with your preferred operating style.

package/doc/documentation/getting-started.md

@@ -0,0 +1,49 @@
+# Getting started
+
+Install Outfitter globally:
+
+```bash
+npm install -g @ai-outfitter/outfitter
+outfitter --help
+```
+
+Outfitter launches agent CLIs; install the agents you plan to use separately.
+
+## First-time setup
+
+Set up profiles from the Outfitter [default profiles repo](https://github.com/ai-outfitter/default-profiles), then launch the default profile:
+
+```bash
+outfitter setup
+outfitter
+```
+
+If you are new to Claude Code, Codex, Pi, and agent CLIs, start with [First-time CLI agent users](./first-time-cli-agent-users.md) for YOLO mode, permissions, context engineering, planning mode, subagents, skills, and extension basics. If you already have an agent workflow, use [Switching to Outfitter](./switching-to-outfitter.md) to migrate the smallest durable set of habits first.
+
+Learn how shared setup sources work in [Profile repositories](./profile-repository.md), then see [Profiles](./profiles.md) for profile composition, inheritance, and prompt examples.
+
+## Common commands
+
+```bash
+outfitter run --profile engineering-default
+outfitter run --agent claude --profile support
+outfitter sync
+outfitter profile list
+outfitter profile create regulated --scope user
+```
+
+See the [CLI reference](./cli.md) for every command and flag, and [Concepts](./concepts.md) for how settings, profiles, and adapters fit together. (`outfitter welcome` also exists as a legacy compatibility command for the older terminal onboarding prompts; current onboarding runs inside Pi via `outfitter setup`.)
+
+## Other install options
+
+Upgrade a global install:
+
+```bash
+npm update -g @ai-outfitter/outfitter
+```
+
+Try without a global install:
+
+```bash
+npx --yes @ai-outfitter/outfitter@latest --help
+```

package/doc/documentation/iterating-on-profiles.md

@@ -0,0 +1,109 @@
+# Iterating on local and worktree profiles
+
+This guide covers the edit-run-inspect loop for profiles: switching to a profile you can edit, iterating on it locally or in a git worktree of a profile catalog, and verifying the result.
+It is written for people and for Outfitter-managed agents — if you are an agent reading this, the "Improving your own profile" section describes how to modify the profile you were launched with.
+
+## Where editable profiles live
+
+Outfitter resolves profiles from every configured `profile_sources` entry.
+Three scopes are directly editable on the current machine:
+
+| Scope         | Profiles                               | Settings                                  | Use for                                   |
+| ------------- | -------------------------------------- | ----------------------------------------- | ----------------------------------------- |
+| user          | `~/.outfitter/profiles/`               | `~/.outfitter/settings.yml`               | Personal defaults shared across projects  |
+| project       | `<project>/.outfitter/profiles/`       | `<project>/.outfitter/settings.yml`       | Checked-in behavior the whole team gets   |
+| project-local | `<project>/.outfitter/local/profiles/` | `<project>/.outfitter/local/settings.yml` | Machine-private overrides and experiments |
+
+Profiles synced from a remote catalog (`github:` or `uri:` profile sources) land in the Outfitter cache.
+Do not edit the cache — `outfitter sync` overwrites it.
+To iterate on a catalog profile, work in a local checkout of the catalog instead (see the worktree section below).
+
+## Switching profiles
+
+- One launch: `outfitter run --profile <id> [-- <agent args>]`
+- Future launches: set `default_profile: <id>` in the settings scope you want it to apply to.
+- List what is resolvable right now: `outfitter profile list` (add `--all` to include inheritance-only templates).
+
+Profile changes apply on the next launch.
+A running session keeps the composite profile it started with, so after editing a profile you must restart `outfitter` to load the result.
+
+## The iteration loop
+
+1. Create or locate an editable profile:
+
+   ```sh
+   outfitter profile create my_experiment --scope project-local
+   ```
+
+To iterate on an existing profile without touching it, create a new profile that inherits from it:
+
+```yaml
+# .outfitter/local/profiles/my_experiment/profile.yml
+id: my_experiment
+label: My Experiment
+inherits:
+  - engineer
+controls:
+  append_system_prompt:
+    - |
+      <the behavior you are trying out>
+```
+
+2. Point your next launch at it, either with `outfitter run --profile my_experiment` or by setting `default_profile: my_experiment` in `.outfitter/local/settings.yml`.
+
+3. Validate before launching:
+
+   ```sh
+   outfitter profile lint --strict
+   ```
+
+This reports schema and inheritance errors, missing typed prompt include files, and raw append-prompt strings that look like file paths.
+
+4. Inspect what the agent actually received.
+   With `profile_export: true` in the active settings, Outfitter writes the composed system prompt next to the profile (`generated-system-prompt.md` in a directory profile, `<id>.generated-system-prompt.md` beside a flat profile).
+   Diff it between iterations to confirm a change landed.
+
+5. Restart and test the behavior, then fold the settled changes back into the profile the experiment inherited from.
+
+## Iterating on a catalog profile in a git worktree
+
+Shared profiles usually come from a catalog repository (see [Profile repositories](./profile-repository.md)) referenced as a `github:` source.
+To change one:
+
+1. Clone the catalog, or add a worktree to an existing clone so the iteration branch stays isolated:
+
+   ```sh
+   cd ~/repos/acme/profile-catalog/main
+   git worktree add ../worktrees/feat/sharper-review-prompts -b feat/sharper-review-prompts
+   ```
+
+2. Point a machine-private profile source at the worktree in `.outfitter/local/settings.yml` (or `~/.outfitter/settings.yml`).
+   Local `path:` sources take the same layout as the catalog:
+
+   ```yaml
+   # .outfitter/local/settings.yml
+   profile_sources:
+     - path: ~/repos/acme/profile-catalog/worktrees/feat/sharper-review-prompts/profiles
+   ```
+
+3. Iterate with the loop above: edit in the worktree, `outfitter profile lint --strict`, relaunch, inspect the prompt export.
+
+4. Commit in the worktree, push, and open a pull request against the catalog.
+   After it merges, remove the local `path:` override, run `outfitter sync` to refresh the cached catalog, and remove the worktree.
+
+Because the override lives in project-local settings, teammates and CI keep resolving the published catalog while you iterate.
+
+## Improving your own profile (for Outfitter-managed agents)
+
+If you are an agent launched by Outfitter, your instructions, tools, skills, and extensions came from a profile, and you can improve that profile the same way you improve code — but the change only takes effect for future sessions, never the current one.
+
+1. Identify your active profile.
+   The launch header and `outfitter profile list` show profile ids; your composite profile directory contains `outfitter/profile.json` with the id, label, and merged controls you were launched with.
+2. Find the editable source for that profile with the scope table above.
+   If the profile comes from a remote catalog, do not edit the cache — use the worktree flow above, or create a local profile that `inherits` from it and layer the improvement on top.
+3. Make the smallest change that captures the improvement: a new `append_system_prompt` entry for a behavior correction, a `skills` entry for a reusable procedure, or a control override (model, thinking level, environment) for launch mechanics.
+4. Validate with `outfitter profile lint --strict`, and review the `profile_export` prompt output when prompt text changed.
+5. Tell the user what you changed and why, and that the change applies when they restart `outfitter` (or launch `outfitter run --profile <id>`).
+   You cannot reload your own profile mid-session.
+
+Prefer durable, reviewable improvements: put team-relevant changes in the project or catalog profile through a pull request, and keep personal or experimental changes in user or project-local scope.

package/doc/documentation/profile-repository.md

@@ -0,0 +1,111 @@
+# Profile repositories
+
+A profile repository (also called a profile catalog) is a git repository that publishes Outfitter profiles so a team or organization can share them. You can bootstrap a machine or project from one, or add one as an ongoing profile source that Outfitter keeps synchronized.
+
+```bash
+outfitter setup https://github.com/my_account/outfitter_config
+```
+
+## Authoring a catalog repository
+
+A setup repository usually contains either root-level Outfitter files:
+
+```text
+outfitter_config/
+  settings.yml
+  profiles/
+    engineering-default/profile.yml
+```
+
+or a `.outfitter/` folder:
+
+```text
+outfitter_config/
+  .outfitter/
+    settings.yml
+    profiles/
+      engineering-default/profile.yml
+    deepwork/jobs/
+```
+
+Inside the profiles directory, both profile layouts work:
+
+- **Flat profiles** — each `*.yml` or `*.yaml` file directly under the profiles directory is one profile. Best for catalogs where profiles are mostly YAML (controls, prompts inline). Easy to scan, diff, and review.
+- **Directory profiles** — one folder per profile with a required `profile.yml`, plus bundled resources such as `prompts/`, `skills/`, `extensions/`, and `deepwork/jobs/` that travel with the profile.
+
+See [Profiles](./profiles.md) for the full layout reference, inheritance, and prompt-include rules. A catalog can also publish a shared base profile marked `template: true` that role profiles inherit from without the base itself appearing as a launchable choice.
+
+## Consuming a catalog as a profile source
+
+Add the repository to `profile_sources` in your user (`~/.outfitter/settings.yml`) or project (`.outfitter/settings.yml`) settings:
+
+```yaml
+profile_sources:
+  - github: my-org/outfitter-catalog # owner/repo shorthand
+    ref: v1.2.0 # optional: pin a tag, branch, or commit
+    path: profiles # optional: subdirectory inside the repo
+    only: # optional: allowlist of profile ids
+      - engineer
+      - platform-operator
+  - uri: git+https://git.example.com/team/catalog.git # any git URI
+    except: # optional: blocklist of profile ids
+      - experimental
+```
+
+Each source entry is one of:
+
+- `path:` — a local directory (no `ref`; read live from disk).
+- `github:` — an `owner/repo` GitHub shorthand.
+- `uri:` — any git-cloneable URI, for non-GitHub hosts.
+
+Remote entries (`github`/`uri`) additionally accept:
+
+- `ref:` — a tag, branch, or commit to pin. With a `ref`, `outfitter sync` fetches and checks out exactly that ref. Without one, sync fast-forwards the repository's default branch, so you always track the catalog's latest state.
+- `path:` — a subdirectory inside the repository that contains the profiles.
+- `only:` / `except:` — filter which profile ids from the source are exposed. `only` is an allowlist; `except` is a blocklist.
+
+## Remote settings
+
+Beyond profiles, a repository can supply a shared settings file that Outfitter layers below your local settings:
+
+```yaml
+# ~/.outfitter/settings.yml
+remote_settings:
+  - github: my-org/outfitter-catalog
+    path: settings.yml # required: file path inside the repo
+    ref: v1.2.0 # optional pin
+```
+
+Remote settings are cached locally and merged at lower precedence than your project and user settings, so anything you set locally wins. This is how an organization distributes shared `profile_sources` and defaults without controlling each user's machine.
+
+## Syncing and updating
+
+`outfitter sync` synchronizes every remote source into the local cache under `~/.outfitter/cache/`:
+
+1. Remote settings repositories are cloned or updated first, then reloaded.
+2. Remote profile sources (including any added by remote settings) are cloned or updated.
+3. Each synced profile source is validated; sync reports `updated`, `unchanged`, `skipped`, or `failed` per source.
+
+Run `outfitter sync` after changing remote settings or profile sources, and periodically to pick up catalog updates. Pinned (`ref:`) sources stay on their pinned ref until you change it; unpinned sources fast-forward to the latest default branch on every sync.
+
+## Private repositories
+
+Private GitHub catalogs are an enterprise feature. When sync detects a private GitHub repository, it asks for confirmation before use and records the decision via the `enterprise.private_profile_catalogs` setting in `~/.outfitter/settings.yml`. 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.
+
+## Trust and review
+
+Adding a catalog source means trusting its authors with your agent runtime. Profiles from a catalog can:
+
+- **Inject extensions** into your agent launch (`controls.extensions`). Extensions are code that runs inside the agent process with full access to your system — files, network, and shell.
+- **Add arbitrary CLI arguments** (`controls.args`) to the launched agent, which can change permission modes or other agent behavior.
+- **Set environment variables** (`controls.environment`) for the agent process.
+- **Shape prompts, skills, subagents, and DeepWork jobs** — steering what the agent does with the access it already has.
+
+Before adding a source, review it:
+
+1. Read every profile's `controls` — especially `extensions`, `args`, and `environment` — and any extension code the repository ships.
+2. Check `remote_settings` targets: a settings file can add further profile sources you did not review.
+3. Confirm the repository's ownership and that its maintainers are who you expect.
+4. Prefer `only:` filters so you expose just the profiles you reviewed.
+
+For organization catalogs, pin a `ref:` (a tag or commit) rather than tracking the default branch. 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. Unpinned sources are convenient for catalogs you maintain yourself, but they mean `outfitter sync` executes-by-configuration whatever landed upstream.