@open-agent-toolkit/cli 0.2.40 → 0.2.45

package/assets/agents/oat-codebase-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: oat-codebase-mapper
-version: 1.0.0
+version: 1.0.1
 description: Explores codebase and writes structured analysis documents. Spawned by oat-repo-knowledge-index with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
@@ -221,7 +221,19 @@ oat_warning: 'GENERATED FILE - Do not edit manually. Regenerate with oat-repo-kn
 3. If something is not found, use "Not detected" or "Not applicable"
 4. Always include file paths with backticks
 
-Use templates from `.agents/skills/oat-repo-knowledge-index/references/templates/`.
+This agent is materialized into provider-specific views, so no portable
+loaded-agent root exists. Resolve the template owner from installed scope
+instead: independently probe each required `<name>/SKILL.md` in order,
+`${HOME}/.agents/skills` then `<repo-root>/.agents/skills`. Bind the first
+match for `oat-repo-knowledge-index` to its own
+`${KNOWLEDGE_INDEX_SKILLS_ROOT}`; never ambient discovery. On a miss, name the
+skill, stop before writing any document instead of inventing a format, and give
+its intended-scope recovery command:
+`oat tools install workflows --scope <user|project>` or
+`oat tools update --pack workflows --scope <user|project>`.
+
+Use templates from
+`${KNOWLEDGE_INDEX_SKILLS_ROOT}/oat-repo-knowledge-index/references/templates/`.
 
 Use the Write tool to create each document.
 
@@ -254,7 +266,7 @@ Ready for orchestrator summary.
 
 **NO RECOMMENDATIONS.** No “recommended setup” or “consider using X” in knowledge docs. Capture gaps as current-state issues in `concerns.md` only.
 
-**USE THE TEMPLATES.** Fill in the template structure from `.agents/skills/oat-repo-knowledge-index/references/templates/`. Don't invent your own format.
+**USE THE TEMPLATES.** Fill in the template structure from `${KNOWLEDGE_INDEX_SKILLS_ROOT}/oat-repo-knowledge-index/references/templates/`. Don't invent your own format.
 
 **INCLUDE FRONTMATTER.** Every generated document must have frontmatter with oat_generated: true and both SHA fields.
 

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.11
+version: 1.1.1
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -70,16 +70,31 @@ task.
 
 Nested dispatch is optional and justified only by a clear benefit such as
 read-only reconnaissance, independent analysis lanes, safely isolated fanout,
-or genuinely specialized implementation. Before any optional child launch,
-read and follow:
-
-1. `.agents/skills/oat-project-dispatch-subagents/SKILL.md`;
-2. `.agents/skills/oat-dispatch-subagents/SKILL.md`; and
-3. `.agents/skills/subagent-orchestration/references/model-selection-principles.md`;
+or genuinely specialized implementation.
+
+This agent is materialized into provider-specific views, so no portable
+loaded-agent root exists. Resolve every required sibling skill from installed
+scope instead: independently probe each required `<name>/SKILL.md` in order,
+`${HOME}/.agents/skills` then `<repo-root>/.agents/skills`. Bind each first
+match to its own root: `${PROJECT_DISPATCH_SKILLS_ROOT}` for
+`oat-project-dispatch-subagents`, `${DISPATCH_SKILLS_ROOT}` for
+`oat-dispatch-subagents`, and `${ORCHESTRATION_SKILLS_ROOT}` for
+`subagent-orchestration`; never ambient discovery. On a miss, name the skill,
+stop the optional launch and implement the task directly, and give its
+intended-scope recovery command:
+
+- `oat-project-dispatch-subagents`: `oat tools install workflows --scope <user|project>` or `oat tools update --pack workflows --scope <user|project>`.
+- `oat-dispatch-subagents` or `subagent-orchestration`: `oat tools install utility --scope <user|project>` or `oat tools update --pack utility --scope <user|project>`.
+
+Before any optional child launch, read and follow:
+
+1. `${PROJECT_DISPATCH_SKILLS_ROOT}/oat-project-dispatch-subagents/SKILL.md`;
+2. `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md`; and
+3. `${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/model-selection-principles.md`;
 4. read exactly one active-provider selection reference from
-   `.agents/skills/subagent-orchestration/references/`; and
+   `${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/`; and
 5. read the matching mechanics reference from
-   `.agents/skills/oat-dispatch-subagents/references/`.
+   `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/references/`.
 
 Every optional launch must have a bounded objective, explicit read/write
 authority, exact target at or below the phase ceiling, verification/output
@@ -116,6 +131,16 @@ After formatting, run the repository's applicable gate set over the produced
 diff, explicitly including artifact writes. This supplements rather than
 replaces every task and phase verification command below.
 
+## Synced-Scope Bookkeeping
+
+Artifact and recovery-ledger bookkeeping commits must first resolve scope with
+`oat project scope "$PROJECT_PATH" --format value`. A `synced` project uses
+`oat project push` with the original bookkeeping message; other scopes keep the
+existing scoped `git add` and `git commit` commands. Scope resolution fails
+closed. A nonzero project-push exit stops bookkeeping until the reported
+recovery is resolved and the push is retried. Planned code task commits such as
+`feat(pNN-tNN)` are unchanged.
+
 ## Prevention and Post-Commit Recovery
 
 Prevention is the first recovery control. Before every planned task commit:

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.0
+version: 1.2.1
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -81,7 +81,7 @@ The primary reviewer must establish the authoritative scope before considering d
 When delegation is eligible:
 
 1. Use one bounded, read-only, non-recursive reconnaissance round with disjoint lane scopes. This is a one-level fan-out limit: lane workers must not spawn additional workers.
-2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md` and `.agents/skills/subagent-orchestration/references/model-selection-principles.md`. Resolve the active provider, then read exactly one matching selection reference under `.agents/skills/subagent-orchestration/references/` and one matching mechanics reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
+2. Before launching any lane, resolve the required sibling skills from installed scope: this agent is materialized into provider-specific views, so no portable loaded-agent root exists. Independently probe each required `<name>/SKILL.md` in order, `${HOME}/.agents/skills` then `<repo-root>/.agents/skills`, and bind each first match to its own root: `${DISPATCH_SKILLS_ROOT}` for `oat-dispatch-subagents` and `${ORCHESTRATION_SKILLS_ROOT}` for `subagent-orchestration`; never ambient discovery. On a miss, name the skill, stop the reconnaissance launch and review inline, and give its intended-scope recovery command: `oat tools install utility --scope <user|project>` or `oat tools update --pack utility --scope <user|project>`. Then read `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md` and `${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/model-selection-principles.md`. Resolve the active provider, then read exactly one matching selection reference under `${ORCHESTRATION_SKILLS_ROOT}/subagent-orchestration/references/` and one matching mechanics reference under `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load the `oat-project-dispatch-subagents` adapter; that adapter is reserved for project lifecycle phase/task policy.
 3. Map every lane worker to the shared `recon` role class (`role.class: recon`); role authority stays read-only and advisory. Assign the independent `task_class`, `classification_source: caller`, and non-empty `classification_reason` fields after understanding the artifacts and diff. These task-class fields are required for reviewer-local reconnaissance even though the generic dispatch contract keeps them optional for other callers.
 4. Classify each lane as `mechanical-recon`, `intelligent-recon`, `default-implementation`, `hard-reasoning`, or `consequential`. Use the stronger floor when uncertain. Classification proceeds from deterministic verification to silent-miss risk, then dispersed context, ambiguity, and consequence; file count alone never justifies escalation.
    - `mechanical-recon`: deterministic inventories, parity checks, and test/lint/format/build execution whose misses are visible and cheaply checked.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.40"
+  "oatVersion": "0.2.45"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -76,7 +76,17 @@ Earlier CLI versions returned `config.json` / `config.local.json` / `env` / `def
 
 Common keys in `.oat/config.json`:
 
-- `projects.root` — where tracked projects live
+- `projects.root` — shared-scope project root. Relative values resolve from the
+  repository root; absolute values remain absolute. OAT derives the `local`
+  and `synced` roots as sibling directories named `local` and `synced` under
+  this root's parent, so a custom value relocates all three scope roots as one
+  layout. Synced project creation requires the derived `synced` root to resolve
+  inside the repository; an external absolute root remains usable for `shared`
+  and `local` projects but is rejected before any synced checkout, ref, record,
+  active pointer, or Git index mutation.
+- `projects.defaultScope` — scope used by project creation when `--scope` is
+  omitted (`synced` by default). `OAT_PROJECTS_DEFAULT_SCOPE` overrides the
+  configured value for the current process.
 - `worktrees.root` — where OAT-managed worktrees live
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership

package/assets/docs/cli-utilities/tool-packs.md

@@ -84,6 +84,14 @@ Lifecycle skills resolve each required sibling independently from the loaded
 scope, then user scope, then project scope. This makes mixed-scope placement a
 supported execution path rather than relying on one frozen skills root.
 
+Materialized **agents** from any pack that ships them (`workflows` here,
+`research` elsewhere) use a two-step order instead — user scope, then project
+scope — because no provider exposes a stable loaded-agent source directory to
+derive a loaded scope from. They still bind each dependency independently and
+still fail closed with the owning pack's install or update command. See
+[Writing Skills → Portable sibling reads](../contributing/skills.md#portable-sibling-reads-skills-and-agents)
+for the full contract.
+
 The packs remain independently installable. If the workflows adapter is
 present without the utility contracts, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical

package/assets/docs/contributing/skills.md

@@ -24,32 +24,85 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Define a pre-work capability and authorization gate for skills that delegate to subagents, workers, or reviewers.
 - Keep output obligations explicit so downstream skills and users know what changed.
 
-## Portable sibling-skill reads
+## Portable sibling reads (skills and agents)
 
-Executable instructions must not assume the skill is running from a repository
-checkout. Before a skill or one of its operational reference files reads a
-sibling `SKILL.md`, resolve a `${SKILLS_ROOT}` in this order:
+Executable instructions must not assume the asset is running from a repository
+checkout. The rule is not skill-specific: it applies to every Markdown asset
+shipped by a pack whose `defaultScope` is `user`, which today means both
+canonical skills under `.agents/skills` and canonical agents under
+`.agents/agents`. The scanned surface is derived from `PACK_MANIFEST` rather
+than a hand-maintained list, so adding a skill or agent to a user-default pack
+puts it under the contract automatically.
+
+The contract covers a cross-asset read of a sibling `SKILL.md` and of any file
+or directory at or below a sibling's `references/`.
+
+### Loaded skills resolve in three steps
+
+Before a skill or one of its operational reference files reads a sibling,
+resolve a `${SKILLS_ROOT}` in this order:
 
 1. Derive `${SKILL_DIR}/..` from the directory containing the currently loaded
    `SKILL.md`, when the provider exposes that path.
 2. Try the user-scope root at `${HOME}/.agents/skills`.
 3. Fall back to the project-scope root at `<repo-root>/.agents/skills`.
 
-Probe each candidate for `<sibling>/SKILL.md` and use the first match. If none
+Probe each candidate for the exact target and use the first match. If none
 exists, name the missing sibling, give an actionable install or update command,
 and stop that workflow branch instead of improvising the sibling's process.
 
-When a caller needs multiple sibling skills, resolve and bind each sibling
-independently. Do not freeze one `${SKILLS_ROOT}` and assume every dependency is
-installed there: a workflows adapter may be at project scope while its utility
-contracts are at user scope. A missing-sibling recovery must name the owning
-pack and intended scope, using `oat tools install <pack> --scope <user|project>`
-or `oat tools update --pack <pack> --scope <user|project>` as appropriate.
+### Materialized agents resolve in two steps
+
+Canonical agents are materialized into provider-specific views — Codex receives
+agent content as developer instructions, while Claude and Cursor use distinct
+provider directories. No stable loaded-agent source path exists across those
+providers, so an agent must not invent a `${SKILL_DIR}`-style loaded-agent
+candidate. Agents resolve installed scope only:
+
+1. Try the user-scope root at `${HOME}/.agents/skills`.
+2. Fall back to the project-scope root at `<repo-root>/.agents/skills`.
+
+User scope comes first because the packs that own these dependencies default
+there; project scope remains a real fallback for project installations.
+
+### Bind every dependency independently
+
+When a caller needs multiple siblings, resolve and bind each one to its own
+root variable. Do not freeze a single `${SKILLS_ROOT}` and assume every
+dependency is installed there: a workflows adapter may be at project scope
+while its utility contracts are at user scope. Validate the exact target file
+before acting on it, and never substitute ambient discovery for a bound root.
+
+Follow-on reads inside an already-bound sibling root — for example a second
+reference file under a root that an earlier read established and validated —
+are local reads rather than new cross-asset reads. They are only acceptable
+when the anchoring read comes first.
+
+### Fail closed with pack-specific recovery
+
+A missing-sibling recovery must name the missing target, its owning pack, and
+the intended scope, using `oat tools install <pack> --scope <user|project>` or
+`oat tools update --pack <pack> --scope <user|project>` as appropriate. Do not
+degrade to a partially guided path, and do not continue past the missing
+dependency.
+
+### The ratchet allows only exact historical baselines
 
 Do not use a bare `.agents/skills/<sibling>/SKILL.md`, `./.agents/...`, or
-`../.agents/...` path for an executable read. Historical examples may retain
-those spellings only when they are non-executable and explicitly baselined by
-the bundled-docs contract test.
+`../.agents/...` path for an executable read in any user-default skill or
+agent. The bundled-docs contract test enforces this over the whole
+manifest-derived surface and reports each violation as exact
+`source -> target` evidence.
+
+The only exemption is a pinned historical baseline: non-executable evidence
+such as a dogfood transcript or a fixture README, recorded by exact source
+file, target skill, and target path. There is no wildcard, directory-wide, or
+skill-wide allowance, and no temporary migration allowlist — executable debt is
+fixed at the caller instead of being exempted. The same assertions run against
+the bundled CLI copies of both skills and agents, and the sync contract test
+re-checks the roles it materializes for Codex, so a canonical fix must survive
+bundling and Codex sync as well. No test yet gates the generated `.claude` or
+`.cursor` agent views, so regenerate and spot-check those by hand.
 
 ## Contract components
 

package/assets/docs/quickstart.md

@@ -9,6 +9,15 @@ Use this page to choose the OAT path that matches what you are actually trying t
 
 This page is intentionally lightweight. It is not the full command manual. Once you choose a path, continue into the owning section for the deeper operational detail.
 
+## Prerequisites
+
+- Node.js 22.17 or newer
+- Git 2.31 or newer
+
+OAT does not run an up-front Git version check. Git compatibility is evaluated
+best-effort by each command, and a missing or unsupported Git operation exits as
+a system error.
+
 ## Choose a Path
 
 ### Provider Sync

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

@@ -56,6 +56,61 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 Notable commands introduced in the current CLI surface:
 
+- `oat project new <slug> --scope shared|local|synced [--force]` - create a
+  project in an explicit scope. Without `--scope`, creation uses
+  `projects.defaultScope`, which defaults to `synced`. Project slugs are
+  unique across all scopes by default, including recorded or remotely
+  published synced projects. `--force` deliberately permits a duplicate; use
+  an explicit project path with `project open` or `project pause` whenever a
+  slug is ambiguous across scopes.
+- `oat project scope [project] --format value|json` - resolve a project's
+  storage scope without inspecting its path manually.
+- `oat project push [project] [--message <message>]` - commit pending synced
+  artifacts, reconcile with the exact project ref on `origin`, publish it, and
+  refresh an open PR's artifact-links block. Use `--no-refresh-pr` to skip the
+  PR edit. With `--json`, success returns `status` (`pushed` or `up-to-date`),
+  the full project-ref `sha`, the retained `ref`, and optional `prRefresh`;
+  conflict and rejected outcomes return their corresponding `status` and exit
+  nonzero.
+- `oat project pull [project] [--no-commit]` - fetch and materialize or update a synced
+  checkout. Resolve a rebase conflict and run `pull --continue`, or use
+  `pull --abort` to return to the pre-pull state. Coordination children are
+  pulled by default; `--no-children` limits the operation to the selected
+  project. When pull adopts a remote project with no local discovery record,
+  `--no-commit` leaves the new record uncommitted for the caller to persist.
+  With `--json`, the receipt includes `status`, `sha`, and `ref`, plus
+  `conflicts` when applicable and per-child results when coordination children
+  were requested.
+- `oat project links [project] --format markdown|json` - render SHA-pinned
+  links for the linkable artifacts on the project ref. On GitHub origins the
+  artifacts become full-SHA blob links; other hosts degrade to the retained ref
+  and short SHA without guessing a web URL. `--durable-summary <path>` accepts
+  only a path contained in the repository, normalizes it repository-relative,
+  and renders it as a code span rather than a guessed remote link.
+- `oat project pause [project]` - persist the pause state and clear the active
+  project pointer. If synced publication is declined or fails after the pause
+  commit is created, that clean commit is retained; address the publication
+  failure and rerun `pause` to publish it.
+- `oat project prune [project] [--force] [--no-commit]` - remove every
+  checkout, the local and remote project refs, and the tracked record. When the
+  project is omitted, the active project is used. This is the explicit
+  destructive operation; `--force` may discard dirty or unpushed artifacts,
+  while `--no-commit` leaves the parent-record deletion for a library caller to
+  commit. If remote deletion succeeds but local checkout removal fails, the
+  local ref, record, and checkouts are retained. Resolve the reported local
+  obstruction and retry `prune --force`; do not run `project push`, which would
+  republish the deleted remote ref.
+- `oat project migrate <path> --to synced [--no-commit]` - migrate an existing
+  shared project to synced storage while preserving its artifacts and
+  retargeting the active project pointer. `--no-commit` leaves the parent
+  record and source-tree transition uncommitted for a library caller.
+- `oat project list --scope shared|local|synced` - filter tracked projects by
+  scope. Add `--remote` to discover project refs that do not yet have a local
+  record or checkout, and `--include-coordination` to include coordination
+  parents. A malformed discovery record with no materialized checkout appears
+  as a `recorded-invalid` row. When the checkout is materialized, its existing
+  row instead carries the restore hint and `recordError` parse diagnostic in
+  `--json` output.
 - `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
 - `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
 - `oat config dump --json` - merged config with source attribution
@@ -66,7 +121,7 @@ Notable commands introduced in the current CLI surface:
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
-- `oat project archive [project-path] [--project-recap-run <project-relative-path>]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project.
+- `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately omits the lifecycle commit receipt. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).

package/assets/docs/reference/file-locations.md

@@ -52,6 +52,8 @@ Pack intent is stored per scope:
 - Local runtime config (per-developer state): `.oat/config.local.json`
 - Active idea: `activeIdea` in `.oat/config.local.json` (repo) or `~/.oat/config.json` (user)
 - Projects root config: `projects.root` in `.oat/config.json` (read via `oat config get projects.root`)
+- Default project scope: `projects.defaultScope` in `.oat/config.json`
+  (`synced` by default; override with `OAT_PROJECTS_DEFAULT_SCOPE`)
 - Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, `archive.wrapUpExportPath`, `archive.awsProfile`, and `archive.awsRegion` in `.oat/config.json`
 - Workflow gate config: `workflow.gates.skills` and `workflow.gates.execTargets` in `.oat/config.json`, `.oat/config.local.json`, or `~/.oat/config.json` (manage via `oat gate`)
 - Project sync manifest/config: `.oat/sync/`
@@ -87,16 +89,31 @@ Config ownership note:
 ## Project artifact trees
 
 - Shared: `.oat/projects/shared/<project>/`
+- Synced checkout: `.oat/projects/synced/<project>/` (gitignored nested
+  worktree)
+- Synced record: `.oat/projects/synced/<project>.json` (tracked on the parent
+  branch)
+- Synced ref: `refs/oat/projects/<project>` on `origin`
 - Local: `.oat/projects/local/<project>/`
 - Archived: `.oat/projects/archived/<project>/`
 
+The OAT-managed block in the repository root `.gitattributes` marks shared
+project artifacts as generated for repository hosting UIs. `oat init` and
+`oat tools update` own that block; preserve non-OAT entries outside its markers
+and do not hand-edit the managed entry.
+
 Archive sync surfaces:
 
 - Local archive root: `.oat/projects/archived/`
 - Remote archive base: `archive.s3Uri` in `.oat/config.json`
 - Archive sync command: `oat repo archive sync` or `oat repo archive sync <project-name>`
 - Remote archive snapshot shape: `<archive.s3Uri>/<repo-slug>/projects/YYYYMMDD-<project-name>/`
-- Summary export target: `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when configured
+- Summary export target:
+  `<repo>/<archive.summaryExportPath>/YYYYMMDD-<project-name>.md` when
+  configured. The archive report returns this absolute filesystem path, while
+  `oat project links --durable-summary` normalizes a contained path to a
+  repository-relative code span. It does not invent a GitHub-style URL for
+  non-GitHub remotes.
 - Wrap-up export target: `<repo>/<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md` when configured; otherwise `oat-wrap-up` falls back to `<repo>/.oat/repo/reference/wrap-ups/`
 
 ## Ideas — project level (gitignored)

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

@@ -24,6 +24,9 @@ Project scope is used for project workflows and repo-local sync state. User scop
   config.local.json
   projects/
     shared/
+    synced/
+      <project>.json
+      <project>/
     local/
     archived/
   ideas/
@@ -47,7 +50,7 @@ Project scope is used for project workflows and repo-local sync state. User scop
 | `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, and `documentation.*`     |
 | `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                 |
 | `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata     |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `local`, `archived` scopes                                                                    |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                         |
 | `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                        |
 | `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                       |
 | `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates. |
@@ -105,6 +108,7 @@ Current schema keys:
 | `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
 | `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
+| `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                           |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
 | `documentation.root`                                       | `string`                   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
 | `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
@@ -139,7 +143,8 @@ Example:
 {
   "version": 1,
   "projects": {
-    "root": ".oat/projects/shared"
+    "root": ".oat/projects/shared",
+    "defaultScope": "synced"
   },
   "worktrees": {
     "root": ".worktrees"
@@ -173,12 +178,23 @@ For repo-relative values (levels 3-4), paths are resolved from the repository ro
 Each OAT project lives under:
 
 - `.oat/projects/shared/<project>/`
+- `.oat/projects/synced/<project>/` for a gitignored nested worktree whose
+  history is published to `refs/oat/projects/<project>`
+- `.oat/projects/synced/<project>.json` for the tracked discovery record that
+  identifies the ref, remote, and active or complete status
 - `.oat/projects/local/<project>/`
 - `.oat/projects/archived/<project>/`
 
-Archive sync behavior:
+Completion and archive sync behavior:
 
-- `oat-project-complete` always archives locally into `.oat/projects/archived/<project>/`.
+- When archiving is selected, `oat-project-complete` archives locally into
+  `.oat/projects/archived/<project>/`. For a synced project, the snapshot omits
+  the nested checkout's `.git` pointer and `reviews/`, then completion marks
+  the tracked record complete, removes the nested worktree, and retains the
+  project ref so pinned links keep resolving.
+- When archiving is disabled or declined, completion leaves the synced
+  checkout and ref in place, pushes the finalized artifacts, and exact-path
+  commits the tracked record as complete.
 - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, completion also uploads a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
 - `oat repo archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
 - `oat repo archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.

package/assets/docs/workflows/projects/artifacts.md

@@ -5,7 +5,33 @@ description: 'Project artifact contracts: state.md, spec.md, design.md, plan.md,
 
 # Project Artifacts
 
-Project artifacts live under `.oat/projects/<scope>/<project>/`.
+Project artifacts use one of three active scopes:
+
+- `shared` artifacts live directly on the feature branch under
+  `.oat/projects/shared/<project>/`.
+- `synced` artifacts live in a gitignored nested worktree at
+  `.oat/projects/synced/<project>/`, backed by
+  `refs/oat/projects/<project>` on `origin`. The feature branch tracks only
+  `.oat/projects/synced/<project>.json`.
+- `local` artifacts stay untracked on the current machine under
+  `.oat/projects/local/<project>/`.
+
+`projects.defaultScope` controls creation when a command does not pass
+`--scope`; its default is `synced`.
+
+## Synced artifact bookkeeping
+
+Lifecycle skills write the same project files in every scope. After a synced
+write, they use `oat project push` instead of staging the artifact path on the
+parent branch. The command makes an artifact commit in the nested checkout,
+rebases it on the fetched project ref, and pushes only that ref. Arrival skills
+run `oat project pull` before reading artifacts so a record or remote ref can
+materialize the checkout first.
+
+The tracked JSON record is routing metadata, not a copy of the project. It
+identifies the slug, `origin`, ref, status, and archive snapshot when present.
+The project ref remains the source of truth for active artifact content and
+history.
 
 ## Core artifacts
 

package/assets/docs/workflows/projects/implementation-execution.md

@@ -406,6 +406,28 @@ For a plan-declared parallel group, the root:
 Containment, ownership, base, or fixture-readiness failure in smoke mode aborts
 the run. It never authorizes replacement or sequential degradation.
 
+## Synced projects in worktrees
+
+A tracked `.oat/projects/synced/<project>.json` record lets every repository
+worktree discover the same synced project without putting its artifacts on the
+feature branch. On arrival, project skills run `oat project pull` before they
+read state. Pull fetches the exact `refs/oat/projects/<project>` ref and, when
+needed, materializes a fresh nested checkout at
+`.oat/projects/synced/<project>/`.
+
+Each parent worktree gets an independent detached nested checkout. Those
+checkouts do not share an index or working tree; they reconcile artifact
+history through the project ref on `origin`. If a pull or push encounters an
+overlapping change, resolve the files in the nested checkout and run
+`oat project pull --continue`. Use `oat project pull --abort` to restore the
+pre-pull state instead.
+
+`oat local sync` skips these nested repositories, so local-path hydration does
+not copy or overwrite synced artifact checkouts. Removing a parent worktree
+also needs no special nested-checkout cleanup: the ignored nested worktree does
+not prevent parent removal, and the next `oat project pull` prunes stale Git
+worktree registrations before materializing or updating the current checkout.
+
 ## Codex Depth
 
 Default execution needs the root-to-phase-agent depth. `agents.max_depth >= 2`

package/assets/docs/workflows/projects/index.md

@@ -24,6 +24,8 @@ Projects are where the workflow layer becomes concrete: lifecycle phases, `state
 - [Programmatic Execution](programmatic-execution.md) - Per-harness headless/CLI execution surfaces and where OAT uses them.
 - [Project Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
 - [Implementation Execution](implementation-execution.md) - Phase dispatch, runtime selection, review/fix loop, and dry-run behavior.
+- [Reviewing OAT PRs](reviewing-oat-prs.md) - Read synced-project records and SHA-pinned reviewer links in a PR.
+- [Picking Up Projects](picking-up-projects.md) - Continue a synced project on another machine or from another user.
 - [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
@@ -50,6 +52,8 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - Split broad scopes into coordination parents and focused children in [Project Splitting](splitting.md).
 - Understand lifecycle and review transitions in [State Machine](state-machine.md).
 - Learn review and PR expectations in [Reviews](reviews.md) and [PR Flow](pr-flow.md).
+- Review a synced project's durable context in [Reviewing OAT PRs](reviewing-oat-prs.md).
+- Continue remote project work with [Picking Up Projects](picking-up-projects.md).
 
 ## Go Deeper
 
@@ -68,4 +72,6 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
 - [PR Flow](pr-flow.md) - Progress and final PR generation expectations.
+- [Reviewing OAT PRs](reviewing-oat-prs.md) - Record metadata, pinned links, and editor discovery for synced projects.
+- [Picking Up Projects](picking-up-projects.md) - Remote discovery, adopting pull, coordination children, and retention boundaries.
 - [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.

package/assets/docs/workflows/projects/lifecycle.md

@@ -70,13 +70,23 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - After revision tasks complete, state returns to `pr_open`
-5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and always archives the project locally
+5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
 
 ### Completion archive behavior
 
-On completion, OAT now treats archive handling as part of the closeout lifecycle:
-
-- Local archive is always written to `.oat/projects/archived/<project>/`.
+On completion, OAT treats archive handling as an explicit closeout choice:
+
+- When archiving is selected, the local archive is written to `.oat/projects/archived/<project>/`.
+- When archiving is disabled or declined, durable projects remain at their
+  active path. Synced completion still finalizes and pushes the project ref,
+  commits the discovery record as `complete`, retains the checkout and ref, and
+  attests a selected recap against the project-ref history.
+- For a synced project, closeout first finalizes the project artifacts and
+  pushes them to `refs/oat/projects/<project>`. Archive then requires a clean,
+  fully pushed checkout; copies it without the `.git` pointer or `reviews/`;
+  marks the tracked record complete; commits the record and configured durable
+  exports on the parent branch; removes the nested checkout; and retains the
+  ref. This order keeps SHA-pinned PR links valid after completion.
 - If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion also attempts an S3 upload for a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
@@ -130,7 +140,7 @@ summary, documentation, PR, or project completion.
 
 ### Retrospective completion safety net
 
-Before an interactive completion archives the project,
+Before an interactive completion closes the project,
 `oat-project-complete` checks for
 `{PROJECT_PATH}/references/project-retro.md`. If the artifact is missing, it
 offers to generate one before completion. If the artifact exists, completion
@@ -292,6 +302,10 @@ Capture lane progression:
 ## Operational rules
 
 - Keep `state.md`, `plan.md`, and `implementation.md` synchronized.
+- For a synced project, publish lifecycle artifact writes with
+  `oat project push`; do not stage `.oat/projects/synced/<project>/` on the
+  parent branch.
+- On arrival, run `oat project pull` before reading a synced project's state.
 - Stop at configured HiLL checkpoints.
 - Do not move lifecycle forward when required review gates are unresolved.
 - Project entry skills (`oat-project-new`, `oat-project-quick-start`, and `oat-project-import-plan`) surface inherited dirty git state before scaffolding. If the dirty list includes `.oat/sync/manifest.json`, `.claude/`, `.cursor/`, or `.codex/`, the skill calls out that those paths are typically sync output and offers Commit now, Proceed anyway, or Abort.