@open-agent-toolkit/cli 0.3.38 → 0.3.39

package/README.md

@@ -20,8 +20,8 @@ npx @open-agent-toolkit/cli --help
 
 ```bash
 oat init --scope project
-oat status --scope all
-oat sync --scope all
+oat status --scope project
+oat sync --scope project
 oat config describe
 ```
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.38"
+  "oatVersion": "0.3.39"
 }

package/assets/docs/getting-started/bootstrap.md

@@ -73,9 +73,8 @@ on your `PATH`. OAT adds its lines between `# >>> oat pre-commit hook >>>` and
 
 To remove the hook, run `oat init --scope project --no-hook` in the
 repository. (Without `--scope project`, `oat init` uses scope `all` and also
-writes under your home directory.) Although its
-help text reads "Skip optional pre-commit hook install", the flag also removes
-an OAT hook that is already installed. It deletes only the marked OAT block
+writes under your home directory.) As its help text says, `--no-hook` removes
+an installed optional pre-commit hook and skips installing one. It deletes only the marked OAT block
 and keeps any other hook content; if the file contained nothing but the OAT
 block, the file is deleted (or emptied, when it is a symlink). You can also
 delete the lines between the two markers by hand. To install the hook later
@@ -99,8 +98,7 @@ oat init --scope project
 
 ### Where tool packs install
 
-Guided setup uses the same per-pack defaults as `oat tools install`, with one
-difference described at the end of this section. The `--scope` option of `oat tools install` and `oat tools remove` lists `all` as
+Guided setup uses the same per-pack defaults as `oat tools install`. The `--scope` option of `oat tools install` and `oat tools remove` lists `all` as
 its default in `--help`. For `oat tools install`, that default does not mean
 both scopes:
 
@@ -114,21 +112,22 @@ both scopes:
 The `core` pack can only live under your home directory:
 
 - `oat tools install --scope project`, with no pack name, installs the other
-  seven packs in this repository and still installs `core` under your home
-  directory.
-- `oat tools install core --scope project` exits successfully and prints
-  `Installed core tool pack.`, but it writes nothing, neither in the
-  repository nor in your home directory.
+  seven packs in this repository, skips `core`, and reports that core is
+  user-scope only.
+- `oat tools install core --scope project` exits 1 with a message that core is
+  user-scope only and writes nothing.
 - `oat tools remove --all --scope project` fails with
   `Pack core does not allow project scope`, and so does
   `oat tools remove --all` with no `--scope`.
 
-The difference: guided setup does not take its pack scope from `--scope`.
-`oat init --scope project --setup`, run without an interactive terminal,
-installed all eight packs under the home directory. In an interactive
-terminal, answer **Yes** to the per-pack scope question to choose project
-scope, or install packs afterwards with `oat tools install <pack> --scope project`. See [Where packs install](tool-packs.md#where-packs-install) for
-the full rules and how to remove packs.
+Guided setup takes its pack scope from an explicit `--scope`:
+`oat init --scope project --setup` installs the selected packs in this
+repository, skips `core`, and writes nothing under your home directory, and
+`--scope user --setup` installs them at user scope only. Without an
+explicit scope, guided setup keeps the per-pack defaults above. Guided setup
+detects the default branch from `origin/HEAD`, then `main`, and does not run
+`gh`. See [Where packs install](tool-packs.md#where-packs-install) for the full
+rules and how to remove packs.
 
 Related commands:
 

package/assets/docs/getting-started/tool-packs.md

@@ -12,7 +12,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 > - A tool pack is a bundle of OAT skills (instructions your coding agent follows), agents, templates and scripts that installs as one unit.
 > - There are eight packs: `core` (setup diagnostics and a local copy of these docs), `workflows` (tracked projects), `docs` (documentation upkeep), `utility` (reviews and maintenance helpers), `research` (evidence gathering and comparison), `ideas` and `brainstorm` (exploring ideas), and `project-management` (backlog and decisions kept in the repository).
 > - Install one pack with an explicit scope: `oat tools install research --scope project` puts it in this repository, and `oat tools install research --scope user` puts it in your home directory. Leave out the pack name, as in `oat tools install --scope project`, to install every pack; in an interactive terminal it first asks which packs to include.
-> - The `core` pack only ever installs under your home directory, whatever `--scope` you pass. [Where packs install](#where-packs-install) shows what that means for each command.
+> - The `core` pack only ever installs under your home directory; `--scope project` refuses or skips it. [Where packs install](#where-packs-install) shows what that means for each command.
 > - Installing the `project-management` pack is not the same as adopting project management: the repository's planning files are created only when someone runs `oat pjm init`.
 > - Read next: [Choosing packs and their ownership](#choosing-packs-and-their-ownership), [Install vs. initialize](#install-vs-initialize), [Upgrading from an earlier CLI](#upgrading-from-an-earlier-cli), and [What OAT Writes](../reference/what-oat-writes.md) for every file each command creates.
 
@@ -54,18 +54,19 @@ mean both scopes:
   packs asks where each one should go and suggests the same answer.
 - With `--scope project`, the pack is installed in this repository
   (`.agents/` and `.oat/`). With `--scope user`, it is installed under your
-  home directory.
+  home directory. An explicit `--scope project` or `--scope user` writes only
+  that scope, with or without a pack name: a copy the pack already has at the
+  other scope is left as it is, and the summary names only the scope written.
 - With `--scope all` given explicitly for one pack, as in
   `oat tools install docs --scope all`, that pack is installed at both scopes.
 
 The `core` pack can only live under your home directory:
 
 - `oat tools install --scope project`, with no pack name, installs the other
-  seven packs in this repository and still installs `core` under your home
-  directory.
-- `oat tools install core --scope project` exits successfully and prints
-  `Installed core tool pack.`, but it writes nothing, neither in the
-  repository nor in your home directory. Run `oat tools install core` (or add
+  seven packs in this repository, skips `core`, and reports that core is
+  user-scope only; nothing is written under your home directory.
+- `oat tools install core --scope project` exits 1 with a message that core is
+  user-scope only and writes nothing. Run `oat tools install core` (or add
   `--scope user`) to install it.
 - `oat tools remove --all --scope project` fails with
   `Pack core does not allow project scope`, and so does
@@ -773,7 +774,8 @@ Key behavior:
 - Installing is **additive**: choosing a scope for a pack never removes it from another scope. A pack installed at user scope plus a project install ends up at `project + user`, not moved
 - For every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`), the interactive flow offers a per-pack end-state selector (`project`, `user`, or `both`) defaulting to the pack's current placement; leaving the default makes no changes for that pack
 - Fresh installs default to **user scope** for every pack; existing installs keep their current placement. The `--scope` default shown in `--help` is `all`, but with no `--scope` a pack that is not installed yet goes under your home directory; see [Where packs install](#where-packs-install)
-- `oat init --setup` uses this same additive scope resolver. In guided setup, choosing to customize scope reaches the per-pack selector; choosing the recommended defaults, or running non-interactively, applies additive per-pack defaults without removals
+- `oat init --setup` uses this same additive scope resolver. In guided setup, choosing to customize scope reaches the per-pack selector; choosing the recommended defaults, or running non-interactively, applies additive per-pack defaults without removals. An explicit `oat init --scope project --setup` or `--scope user --setup` installs the selected packs at that scope only (core is skipped under `--scope project`), and guided setup never runs `gh`: it detects the default branch from `origin/HEAD`, then `main`
+- An explicit `--scope project` or `--scope user` writes only that scope, for one pack or all of them; existing placements at the other scope are neither reconciled nor removed. With no `--scope` or with `--scope all`, the rules above apply
 - Every pack's fresh-install default is user scope (`defaultScope` in the release manifest); existing installs keep their current placement on re-install, so a re-install never moves a pack between scopes or creates a second copy at the other one. This applies to the per-pack subcommands too: a bare `oat tools install docs` in a repository where `docs` is already at project scope stays at project scope, and only an explicit `--scope` overrides that
 - Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
 - Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
@@ -963,7 +965,7 @@ The `core` pack contains foundational diagnostic and documentation skills:
 
 Key behavior:
 
-- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`. A conflicting explicit `--scope project` is not rejected: `oat tools install core --scope project` (and the legacy `oat init tools core --scope project`) exits successfully and prints `Installed core tool pack.` but writes nothing, while `oat tools install --scope project` with no pack name still installs core under your home directory. To install core, omit `--scope` or pass `--scope user`. Keeping core in your home directory makes its skills available in any directory. See [Where packs install](#where-packs-install).
+- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`. A conflicting explicit `--scope project` is refused: `oat tools install core --scope project` (and the legacy `oat init tools core --scope project`) exits 1 with a message that core is user-scope only and writes nothing, and `oat tools install --scope project` with no pack name skips core and says so. To install core, omit `--scope` or pass `--scope user`. Keeping core in your home directory makes its skills available in any directory. See [Where packs install](#where-packs-install).
 - `~/.oat/docs/` is a managed directory asset: its completeness and drift are compared as a whole tree, so a partially deleted docs tree is reported as a partial `core` install rather than passing silently.
 - Core is checked by default in the `oat init tools` guided setup.
 - Installation also bundles OAT documentation to `~/.oat/docs/` for the oat-docs skill.
@@ -1277,11 +1279,10 @@ created until someone runs `oat pjm init` (see [Install vs. initialize](#install
 A fresh install goes to user scope, which lets you reuse packs across
 repositories without update churn in each one; a pack that is already installed
 keeps its scope. **`core` is user-only**: `oat tools install --scope project`
-with no pack name still installs it in your home directory, and
-`oat tools install core --scope project` reports success but installs nothing
-(see [Where packs install](#where-packs-install)). `oat init --scope project --setup` does not choose
-project scope for packs; customize each pack's scope at the prompt, or install
-packs explicitly. Installing a pack at a second scope adds a second copy rather
+with no pack name skips it, and `oat tools install core --scope project` exits
+1 without installing anything (see [Where packs install](#where-packs-install)).
+`oat init --scope project --setup` installs the packs you select at project
+scope. Installing a pack at a second scope adds a second copy rather
 than moving it, so use `oat tools migrate` to move a pack between scopes.
 Templates that a project-scope install writes belong to the repository after
 that: later pack updates and `oat tools remove` leave them alone.

package/assets/docs/provider-sync/commands.md

@@ -206,11 +206,12 @@ Key behavior:
   project role file; `--scope user` writes only under `~/.codex`
 - `--agent-path` selects a specific canonical agent and `--role-name` overrides
   the generated role name
-- Managed role registration enables multi-agent support and merges an
-  `agents.max_depth` floor of `2`
-- Project writes preserve a higher existing project depth or inherited user
-  depth without mutating user configuration; user writes do not inspect or
-  mutate project configuration
+- Managed role registration adds `[features] multi_agent = true` and
+  `agents.max_depth = 2` only when those keys are absent; an explicit value is
+  kept, and each `Config:` line names a key added or a conflict
+- A project write that adds `max_depth` uses a higher inherited user depth
+  when there is one, without mutating user configuration; user writes do not
+  inspect or mutate project configuration
 - Existing unrelated Codex configuration and custom roles are preserved
 
 ## Notes

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -54,32 +54,39 @@ Diagram: canonical assets produce provider views and a manifest; status reports
 - **What re-running `oat sync` does.** It writes unless you pass `--dry-run`.
   It recreates missing views and rewrites drifted ones from canonical, so an
   edit made in a provider copy is lost, not merged. A file you placed at a
-  view's path without OAT is replaced too. When a skill or rule is deleted
-  from `.agents/`, sync removes its views. When an agent is deleted or
-  renamed, it does not; see the warning below.
+  view's path without OAT is replaced too. When a skill, rule or agent is
+  deleted from `.agents/`, sync removes its views; see the note below for
+  agents.
 - **What to do with a stray.** In an interactive `oat status` or `oat init` you
   can adopt it, which moves or converts it into `.agents/`. For a Cursor or
   Copilot skill you can keep it in place; OAT records the path under
   `knownStrays` in `.oat/sync/config.json` and leaves it out of later reports.
   You can also list a path there by hand.
 
-> [!WARNING]
-> Sync does not clean up after a deleted or renamed agent. With Cursor enabled,
-> once `.agents/agents/<name>.md` is gone, `oat sync`, `oat sync --dry-run` and
-> `oat status` exit 1 with
-> `Cursor agent definition is a symbolic link at .cursor/agents/<name>.md whose target escapes the sync scope.`
-> With Codex enabled, the agent's generated files stay behind. After deleting
-> or renaming an agent, clean up by hand:
+> [!NOTE]
+> From 0.3.39, sync cleans up after a deleted or renamed agent. Once
+> `.agents/agents/<name>.md` is gone, `oat status` reports the pending change,
+> `oat sync --dry-run` lists the removals and writes nothing, and
+> `oat sync --scope project` removes the agent's `.claude/agents/`,
+> `.cursor/agents/` and `.github/agents/` views, its
+> `.codex/agents/<name>.toml` with any generated model variants, and its
+> `[agents.<name>]` tables in `.codex/config.toml`. A rename also creates the
+> new name's views. User-authored `[agents.*]` tables stay. A dangling link
+> left in `.cursor/agents/`, `.claude/agents/` or `.codex/agents/` no longer
+> stops sync with an `escapes the sync scope` error. At an agent view path,
+> such as `.cursor/agents/<name>.md`, sync restores the managed link. Sync
+> cannot write a generated file through a dangling link: at the path of a
+> generated Cursor model variant, such as
+> `.cursor/agents/oat-reviewer-<model>-<effort>.md`, it reports a failed
+> materialization, and at a Codex role path, such as
+> `.codex/agents/<name>.toml` or one of its model variants, it reports the
+> role as `missing`. Either way sync exits 1; delete the link and rerun sync.
+> A link whose existing target lies outside the sync scope is still refused.
 >
-> 1. Delete the link `.cursor/agents/<name>.md`.
-> 2. Delete the link `.claude/agents/<name>.md`; until it is gone, the same
->    error names that path instead.
-> 3. Delete `.codex/agents/<name>.toml`.
-> 4. In `.codex/config.toml`, delete the `[agents.<name>]` table.
-> 5. Run `oat sync --scope project`; it should now succeed.
->
-> Skills and rules are not affected: sync removes their views when the
-> canonical file is deleted.
+> Codex roles written by versions before 0.3.39 carry no owner header until
+> the next sync rewrites them. If such an agent was deleted before you first
+> synced with 0.3.39, delete its `.codex/agents/<name>.toml` and its
+> `[agents.<name>]` table by hand once.
 
 ## Manifest locations
 

package/assets/docs/provider-sync/pilot-with-a-team.md

@@ -144,23 +144,23 @@ checkouts handle committed links was not tested.
 
 Run `oat sync --scope project`, and commit its output in the same change, when
 you add, rename, or delete a skill, agent, or rule, or change an agent or rule.
-Deleting or renaming an agent also needs the manual cleanup described below.
 Rules, Codex agent files and Cursor's per-model agent variants are generated
 copies, so they only change when sync runs. An edit inside an existing linked
 skill reaches Claude Code at once, because the view is a link.
 
 Make every change in `.agents/`, never in the provider folders. Re-running sync
 overwrites edits made to generated copies, replaces an untracked file sitting
-at a view path, and removes the view of a deleted skill or rule. Editing
-through a link changes the canonical file itself, which is easy to miss in
-review.
-
-Agents are the exception. After you delete or rename an agent, delete its old
-links in `.cursor/agents/` and `.claude/agents/` yourself: with Cursor enabled,
-`oat sync` and `oat status` stop with an error saying the link's target
-`escapes the sync scope` until both links are gone. Also delete its
-`.codex/agents/<name>.toml` file and the `[agents.<name>]` table in
-`.codex/config.toml`, which sync leaves behind.
+at a view path, and removes the views of a deleted skill, rule, or agent.
+Editing through a link changes the canonical file itself, which is easy to miss
+in review.
+
+From 0.3.39, deleting or renaming an agent needs no manual cleanup: sync
+removes its old links in `.cursor/agents/`, `.claude/agents/` and
+`.github/agents/`, its `.codex/agents/<name>.toml` file and its
+`[agents.<name>]` table in `.codex/config.toml`. A Codex role that a version
+before 0.3.39 generated for an agent deleted before the upgrade has no owner
+header, so delete that file and its table by hand once (see
+[Manifest and Drift](manifest-and-drift.md#quick-look)).
 
 Before committing, run `oat status --scope project`. It exits 1 when any view
 is missing or drifted, or when a stray file sits in a provider folder. For a
@@ -177,12 +177,12 @@ inside the working tree. Remove it with `oat init --scope project --no-hook`.
 
 ## Mixed tools
 
-| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                                        |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                                           |
-| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                                           |
-| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, turns on `multi_agent` and raises `max_depth` to at least 2, and keeps your other settings and comments |
-| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                                |
+| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                                                                                                                     |
+| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                                                                                                                     |
+| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, adds `multi_agent` and `max_depth` only when they are missing, keeps the values you set (reporting a conflict when OAT needs another), and keeps your other settings and comments |
+| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                                                                                                          |
 
 If OAT's own implementer and reviewer agents are installed in the repository,
 sync also generates one file per supported model for each of them, in

package/assets/docs/provider-sync/providers.md

@@ -57,13 +57,13 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Agents are native-read from `.agents/agents` for canonical source-of-truth workflows
     - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
       - `.codex/agents/<role>.toml`
-      - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
-    - Sync and direct materialization edit `config.toml` in place. They change only `features.multi_agent`, `agents.max_depth`, and the `description` and `config_file` keys of managed `[agents.<role>]` tables, and remove stale managed role tables. Comments (including other tools' ownership markers), blank lines, table order, and other keys stay byte for byte, and the file is not rewritten when nothing managed changed. Removing a stale role deletes its whole table, including comments inside it; comments above or after the table stay. Dotted keys and inline tables are edited where they are defined. New keys and tables are never added between another tool's `# BEGIN <label>` and `# END <label>` comments: a key goes before the block, and a table that cannot sit next to its related tables outside the block goes at the end of the file. If `features`, `agents`, or a managed role is not a table, or a key can only be added inside such a block, sync stops with an error instead of rewriting the file.
+      - `.codex/config.toml` (`[features] multi_agent = true` when absent, `[agents.<role>]` upserts)
+    - Sync and direct materialization edit `config.toml` in place. They change only the `description` and `config_file` keys of managed `[agents.<role>]` tables, add `features.multi_agent` and `agents.max_depth` only when those keys are absent, and remove stale managed role tables. An explicit `multi_agent` or `max_depth` value is never rewritten. The output (human and `--json`, including when nothing else changes) names each key added, reports a conflict for `multi_agent` other than `true` or a `max_depth` below `1`, and notes that `max_depth = 1` disables only optional nested work. Comments (including other tools' ownership markers), blank lines, table order, and other keys stay byte for byte, and the file is not rewritten when nothing managed changed. Removing a stale role deletes its whole table, including comments inside it; comments above or after the table stay. Dotted keys and inline tables are edited where they are defined. New keys and tables are never added between another tool's `# BEGIN <label>` and `# END <label>` comments: a key goes before the block, and a table that cannot sit next to its related tables outside the block goes at the end of the file. If `features`, `agents`, or a managed role is not a table, or a key can only be added inside such a block, sync stops with an error instead of rewriting the file.
     - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
     - Project sync writes and maintains the version-controlled supported catalogue: GPT-6.1 Sol and GPT-6 Luna, Sol, and Astra at `low`, `medium`, `high`, `xhigh`, and `max`; GPT-5.6 Luna and Terra through `xhigh`; and GPT-5.6 Sol through `max`. Both `oat-phase-implementer` and `oat-reviewer` receive each supported pair (66 pinned variants). Sync writes files; it does not create a Git commit.
     - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
     - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
-    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
+    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership, and from 0.3.39 each canonical agent's base role carries the scope's owner (`project-config` or `user-config`). Cleanup removes stale entries only for the owner being reconciled (`supported-catalogue` and `project-config` at project scope, `user-config` at user scope) and preserves other scopes plus unrelated Codex entries. A deleted or renamed agent's role files, variants, and tables are removed by full sync and by pack removal. Roles an older CLI wrote without an owner header are left in place. A stale `[agents.<role>]` table is removed only while its `config_file` still names the stale OAT-owned role file; a table you re-pointed at another file stays, and only the leftover OAT file is removed. Cleanup never deletes a role file whose real path, after resolving symlinks (including a symlinked `.codex/agents` directory), is outside the sync scope.
     - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
     - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
@@ -71,7 +71,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Codex `max` is a first-class dispatch effort. It is supported for GPT-6.1 Sol, GPT-6 Luna, Sol, and Astra, plus GPT-5.6 Sol, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
-    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.
+    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; when the key is absent, sync and direct materialization add `2` (or a higher inherited value), and they never change an explicit value.
     - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
     - Missing depth and explicit depth `1` are sufficient for default phase execution. Invalid values or values below `1` block managed implementation preflight. `oat doctor` explains when depth `2` optional nesting is available.
     - The phase implementer directly executes its planned tasks from one Phase Scope, preserves one bounded commit per task, and returns phase-wide verification. It does not dispatch the phase reviewer.

package/assets/docs/provider-sync/scope-and-surface.md

@@ -25,7 +25,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 
 - Mutate by default; `--dry-run` to preview
 - Explicit `--dry-run` for safe preview of mutations
-- Deletions are limited to manifest-tracked entries: sync removes a skill or rule view only when the manifest records it and its canonical source is gone. Deleted agents are not cleaned up this way: with Cursor enabled, sync and status stop with an `escapes the sync scope` error until you delete the agent's dangling links in `.cursor/agents/` and `.claude/agents/`, and Codex's `.codex/agents/<name>.toml` and `[agents.<name>]` table are never removed (see [Manifest and Drift](manifest-and-drift.md#quick-look)). A provider file with no canonical source and no manifest entry is reported as a stray by `oat status`, not deleted. Writing a view is not limited this way: sync replaces whatever sits at a view's expected path, including an untracked file (see the warning under [Choosing sync scope](#choosing-sync-scope))
+- Deletions are limited to managed entries: sync removes a skill, rule or agent view only when the manifest records it and its canonical source is gone. A deleted or renamed agent's generated Codex role and `[agents.<name>]` table are removed through their owner header instead (0.3.39 and later; see [Manifest and Drift](manifest-and-drift.md#quick-look)). A provider file with no canonical source and no manifest entry is reported as a stray by `oat status`, not deleted. Writing a view is not limited this way: sync replaces whatever sits at a view's expected path, including an untracked file (see the warning under [Choosing sync scope](#choosing-sync-scope))
 - Cross-provider compatibility via adapters
 - Native-read assets stay canonical while provider-local adoption sources remain discoverable independently
 - Obsolete managed mappings are deleted only when their provider paths are verified clean; changed or unverified paths are preserved and detached from manifest ownership
@@ -64,7 +64,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Cursor provider enablement still controls agents, rules, migration discovery, and legacy cleanup even though Cursor reads canonical skills without a generated skill view.
 - Copilot provider enablement still controls agents, project rules, migration discovery, and legacy cleanup even though Copilot reads canonical skills without a generated skill view.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
-- Default Codex execution requires `root (0) → phase implementer (1)`. Sync and direct materialization continue to apply an `agents.max_depth` floor of `2` as optional nested-work capability without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
+- Default Codex execution requires `root (0) → phase implementer (1)`. When `agents.max_depth` is absent, sync and direct materialization add `2` (or a higher inherited value) as optional nested-work capability; they keep an explicit value and report it as a conflict when it is below `1`. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
 - Missing depth or depth `1` does not block default phase execution. Invalid values or explicit values below `1` fail managed implementation preflight. `oat doctor` reports whether optional depth-two nesting is available and gives a scope-specific repair when the configured value is unusable.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
@@ -154,9 +154,9 @@ the provider views, because sync overwrites changes made in the views.
 > A bare `oat sync` uses scope `all`, so it also writes under your home
 > directory. Every sync also overwrites edits made directly in provider folders,
 > replaces an untracked file sitting at a view path, and removes the view of a
-> deleted skill or rule. It does not clean up after a deleted or renamed agent;
-> see [Manifest and Drift](manifest-and-drift.md#quick-look) for the manual
-> steps. Pass `--scope` explicitly, and preview with `--dry-run` when you are
+> deleted skill or rule. From 0.3.39 it also removes a deleted or renamed
+> agent's views, Codex role and `[agents.<name>]` table; see
+> [Manifest and Drift](manifest-and-drift.md#quick-look). Pass `--scope` explicitly, and preview with `--dry-run` when you are
 > unsure.
 
 - If the run is in CI or a script, always pass `--scope project`, and preview

package/assets/docs/reference/cli-reference.md

@@ -41,8 +41,11 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 `oat internal commit-paths --identity <operation> --message <message> -- <files...>`
 commits an explicit list of owned files with enabled Git hooks. Include tracked
-removals and both names of a rename. Directories, untracked missing paths,
-unmerged entries and paths outside the repository are rejected; the command
+removals and both names of a rename. A file `HEAD` already tracks is
+committed even when an ignore rule matches it or its directory (for example
+`packages/cli/assets/templates/` under `packages/cli/assets/*`); an untracked
+path that an ignore rule matches is rejected. Directories, untracked missing
+paths, unmerged entries and paths outside the repository are rejected; the command
 does not discover ownership or expand directory/glob pathspecs. Unrelated staged
 entries and worktree bytes remain preserved, including partially staged files.
 On success, owned index/worktree bytes match the hook-final commit.

package/assets/docs/reference/oat-directory-structure.md

@@ -127,7 +127,7 @@ Current schema keys:
 | `documentation.nonReaderPaths`                             | `string[]`                 | -                        | Shared-only content-root-relative bounded globs omitted from nav inventory/Contents/check/manifest and, with OAT source config, Fumadocs rendering. MkDocs 1.4.2 still renders routes. See [Non-reader paths](#non-reader-paths).                                                                                                                                                                                                                                                                   |
 | `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                                                                                                                                                                                                                 |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                                                                                                                                                                                                  |
+| `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init --setup` from `origin/HEAD`, falling back to `main`. Used by `oat-project-pr-final`, `oat-project-pr-progress`, and `oat-project-complete`.                                                                                                                                                                                                                                                                                          |
 | `instructions.claude.shims`                                | `string`                   | `"none"`                 | CLAUDE.md shim strategy for `oat instructions sync`/`validate`: `none` (no shims; sync removes OAT-managed ones, all or nothing: none while any `CLAUDE.md` has content; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. `--strategy` overrides it for one run; any other value is rejected with exit code `2`. See [Instruction Sync](../provider-sync/instruction-sync.md#choosing-a-strategy).                                      |
 | `instructions.claude.excludes`                             | `string[]`                 | -                        | Repo-relative directories `oat instructions sync`/`validate` must not treat as pointer sites, additive to the documentation content root they skip by default. Normalized and de-duplicated; a malformed value (non-array, or an empty or non-string entry) is rejected with exit code `2`. Set as one comma-separated value with `oat config set`; absolute paths and paths escaping the repository are refused. See [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees). |
 | `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback.                                                                                                                                                                                             |

package/assets/docs/reference/troubleshooting.md

@@ -95,9 +95,8 @@ link or copy that OAT creates in the tool's own folder, such as
 - If you are working in the OAT source repository: run
   `pnpm run worktree:init`. This command copies local-only files from the main
   worktree, installs dependencies, configures Git hooks, builds the workspace,
-  and runs `oat sync` with no scope flag. A bare `oat sync` uses
-  `--scope all`, so it refreshes user-scope provider views in your home
-  directory as well as the project's.
+  and runs `oat sync --scope project`, which refreshes only the project's
+  provider views and leaves user-scope views in your home directory alone.
 
 ## Codex appears detected but no skill sync actions are listed
 
@@ -328,8 +327,8 @@ npm install --global @open-agent-toolkit/cli
 oat status # or: oat doctor
 ```
 
-The diagnostic's own recovery line says to run `pnpm build`. That applies only
-when you run the CLI from a checkout of the OAT source repository.
+The diagnostic's own recovery line names the same two remedies and mentions
+`pnpm build` only for a checkout of the OAT source repository.
 
 If you are working in the OAT source repository: rebuild the CLI workspace,
 then rerun the command named in the diagnostic: