@ai-outfitter/outfitter 0.7.2 → 0.9.0

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.

package/doc/documentation/profiles.md

@@ -0,0 +1,183 @@
+# Profiles
+
+Profiles define the accoutrements that shape an Outfitter-managed agent launch.
+
+A profile can compose:
+
+- context and prompts
+- model and provider settings
+- Pi extensions
+- skills
+- subagents
+- DeepWork workflows
+- agent-specific CLI flags and environment variables
+
+Profiles can be local to a user or project, inherited from other profiles, or loaded from a shared profile repository. See [Profile repositories](./profile-repository.md) for shared setup sources.
+
+## Profile layouts
+
+Outfitter supports two profile layouts inside any configured `profile_sources` directory.
+
+### Flat profile layout
+
+Use the flat layout for small profile catalogs where each profile is mostly YAML and does not need its own resource folder. Each `*.yml` or `*.yaml` file directly under the profile source is a profile. If the file omits `id`, Outfitter uses the filename stem as the profile id.
+
+```text
+~/.outfitter/profiles/
+  founder.yml
+  engineer.yml
+  data-analyst.yaml
+```
+
+```yaml
+# ~/.outfitter/profiles/founder.yml
+label: Founder
+description: Founder-operator defaults for product, engineering, research, and prose.
+controls:
+  append_system_prompt: |
+    Think like a founder-operator: connect product judgment, implementation, and evidence.
+```
+
+Flat profiles are easy to scan, diff, and copy between setup repositories. Generated Pi prompt exports for flat profiles are written beside the flat file as `<profile-id>.generated-system-prompt.md` when `profile_export` is enabled.
+
+### Directory profile layout
+
+The original layout is one folder per profile with a required `profile.yml`. Use it when a profile owns prompts, skills, extensions, DeepWork jobs, or CLI-specific files that should travel with that profile.
+
+```text
+~/.outfitter/profiles/
+  home-default/
+    profile.yml
+    prompts/
+      system.md
+    skills/
+    extensions/
+    deepwork/
+      jobs/
+    cli_specific/
+      pi/
+```
+
+```yaml
+# ~/.outfitter/profiles/home-default/profile.yml
+id: home-default
+label: Home Default
+controls:
+  system_prompt: ./prompts/system.md
+  skills:
+    - ./skills/review
+```
+
+Directory profiles keep bundled resources close to the profile that references them. Generated Pi prompt exports for directory profiles are written as `generated-system-prompt.md` inside the profile directory when `profile_export` is enabled.
+
+## Home and project example
+
+A home profile SHOULD hold reusable defaults for one developer.
+A project profile SHOULD live with the repository and add only the behavior that project needs.
+The comments below name the files; each `---` starts a separate YAML document in the same example block.
+
+```yaml
+# ~/.outfitter/settings.yml
+default_profile: home-default
+default_agent: pi
+profile_sources:
+  - path: ./profiles
+
+---
+# ~/.outfitter/profiles/home-default.yml
+id: home-default
+label: Home Default
+description: Reusable personal defaults for Outfitter-managed Pi runs.
+controls:
+  provider: openai-codex
+  model: gpt-5.5
+  thinking: high
+  append_system_prompt:
+    - |
+      Use concise, evidence-backed engineering prose.
+      Prefer small, reviewable changes.
+      Keep durable decisions in repo files.
+    - file: prompts/personal-policy.md
+    - repo_file: docs/mission.md
+
+---
+# ~/repos/acme/example/.outfitter/settings.yml
+default_profile: acme-example
+profile_export: true
+profile_sources:
+  # Relative to this settings.yml; exposes ~/.outfitter/profiles to the project.
+  - path: ../../../../.outfitter/profiles
+    only:
+      - home-default
+  - path: ./profiles
+
+---
+# ~/repos/acme/example/.outfitter/profiles/acme-example/profile.yml
+id: acme-example
+label: Acme Example
+description: Checked-in project profile for ~/repos/acme/example.
+inherits:
+  - home-default
+controls:
+  thinking: xhigh
+  append_system_prompt:
+    - |
+      You are working in ~/repos/acme/example.
+      Honor the project test contract before calling work complete.
+      Prefer repository-local conventions over personal defaults.
+    - file: .outfitter/prompts/review-policy.md
+  environment:
+    ACME_PROJECT: example
+```
+
+`home-default` is the home-folder profile: it supplies personal defaults that can work across repositories.
+`acme-example` is the project profile: it inherits those defaults, then overrides the thinking level and adds project-specific prompt and environment settings.
+When a project `settings.yml` declares `profile_sources`, it SHOULD include any home profile source that project profiles inherit from.
+Because `append_system_prompt` composes instead of replacing, the higher-precedence project prompt is passed first and the inherited home prompt follows.
+Typed prompt includes read `{ file: string }` entries before launch and pass the file contents as repeated append-prompt text. Raw strings remain literal prompt text; if a raw string looks like a whole file path, Outfitter warns so the profile can be migrated to `{ file: ... }`.
+
+### Append prompt file includes
+
+`append_system_prompt` accepts a literal string, a multiline string, `{ file: string }`, `{ repo_file: string }`, or an ordered list mixing those entry types. Outfitter does not support `{ text: ... }`; use raw YAML strings for inline prompt text, `{ file: ... }` for maintained profile/catalog files, and `{ repo_file: ... }` for files that should come from the active project.
+
+Profile-owned file includes resolve from the source root of the profile layer that declares the entry, including inherited layers:
+
+| Declaring profile location                                                         | Include root               |
+| ---------------------------------------------------------------------------------- | -------------------------- |
+| `~/.outfitter/profiles/<id>/profile.yml` or `~/.outfitter/profiles/<id>.yml`       | `~/.outfitter`             |
+| `<project>/.outfitter/profiles/<id>/profile.yml`                                   | `<project>`                |
+| Catalog repo `outfitter/profiles/<id>/profile.yml`                                 | Catalog repository root    |
+| Explicit `profile_sources[].path` without `.outfitter/` or `outfitter/` convention | The configured source path |
+
+`repo_file:` resolves from the active project directory where Outfitter launches the agent. This lets a reusable catalog or home profile request project-local governance context such as `docs/mission.md` without copying those docs into the catalog.
+
+Run `outfitter profile lint` to report schema and inheritance errors, missing typed include files, and raw string append-prompt entries that look like file paths. Add `--strict` to exit non-zero for warnings, and `--json` for machine-readable diagnostics.
+
+With `profile_export: true`, the selected project directory profile can write `generated-system-prompt.md` beside `profile.yml`.
+For this example, the generated prompt fallback would show the composed prompt inputs like this:
+
+```text
+<!-- Generated by Outfitter from Pi runtime ctx.getSystemPrompt(). Safe to review or git-ignore. Do not edit by hand. -->
+# Generated Pi runtime system prompt
+
+You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+- read: Read file contents
+- bash: Execute bash commands (ls, grep, find, etc.)
+- edit: Make precise file edits with exact text replacement, including multiple disjoint edits in one call
+
+....
+
+## append_system_prompt[0]
+
+You are working in ~/repos/acme/example.
+Honor the project test contract before calling work complete.
+Prefer repository-local conventions over personal defaults.
+
+## append_system_prompt[1]
+
+Use concise, evidence-backed engineering prose.
+Prefer small, reviewable changes.
+Keep durable decisions in repo files.
+```