@open-agent-toolkit/cli 0.2.41 → 0.2.45

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

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.12
+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
@@ -131,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/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.41"
+  "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/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.

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -0,0 +1,75 @@
+---
+title: Picking Up Projects
+description: Continue a synced OAT project on another machine or from another user through its dedicated Git ref.
+---
+
+# Picking Up a Project on Another Machine or From Another User
+
+Synced projects travel through ordinary Git refs on `origin`. Their artifact
+history is independent from the implementation branch, so a teammate or a
+second machine can continue the project even before the branch carrying its
+record file merges.
+
+## Discover and adopt
+
+From any checkout with access to `origin`:
+
+```bash
+oat project list --remote
+oat project pull <project>
+```
+
+`list --remote` discovers `refs/oat/projects/*` directly. `pull` can adopt a
+remote project that has no local record yet: it writes the record and creates
+the nested checkout. When the selected project is a coordination parent, pull
+also discovers and pulls its child projects by default. Pass `--no-children`
+only when you intentionally want the selected project alone.
+
+After adoption, set or open the project through the normal lifecycle command
+you are using. Arrival-aware project skills pull before reading its artifacts.
+
+## What travels
+
+- The project ref carries the complete active artifact tree and its history.
+- The tracked JSON record travels once the branch containing it is shared or
+  merged.
+- Coordination relationships travel in the artifacts and records pulled with
+  the project.
+
+## What does not travel automatically
+
+- `local` projects never leave their original machine.
+- GitHub forks copy branches and tags, but not the `refs/oat/*` namespace. A
+  fork collaborator needs access to the upstream remote or an explicit ref
+  transfer.
+- A normal `git clone` fetches branches and tags, not custom OAT refs. OAT
+  handles remote discovery with `ls-remote` and explicitly fetches the selected
+  project ref during sync operations such as `pull`; do not expect a generic
+  clone or `git fetch` to materialize the checkout.
+
+## Why retained refs remain durable
+
+`refs/oat/projects/<project>` is a real Git ref locally and on `origin`. The
+objects reachable from it remain garbage-collection roots even when no nested
+checkout exists. Branch pruning, remote-tracking-ref pruning, and
+`git worktree prune` do not delete the project ref. Completion deliberately
+retains it so pinned PR links remain valid.
+
+Only the explicit destructive operation `oat project prune` removes the local
+and remote project refs. Treat it as permanent project-history deletion and
+review its warnings before using `--force`.
+
+## Archive contents
+
+When archive is selected, completion copies a synced project into
+`.oat/projects/archived/<project>/` without the nested checkout's `.git`
+pointer or `reviews/`. S3 snapshots also omit `pr/`, following the existing
+archive policy. When archive is disabled or declined, the active synced
+checkout remains in place. Both paths retain the project ref and commit the
+tracked record as `complete`; only the archive path records an archive snapshot.
+
+## Related
+
+- [Reviewing OAT PRs](reviewing-oat-prs.md)
+- [Project Artifacts](artifacts.md)
+- [Implementation Execution](implementation-execution.md#synced-projects-in-worktrees)

package/assets/docs/workflows/projects/pr-flow.md

@@ -34,6 +34,25 @@ GitHub PR body policy:
 - Keep YAML frontmatter in local artifact
 - Strip frontmatter from submitted PR body
 
+## Synced project links
+
+For a synced project, PR creation follows a six-step order:
+
+1. write and format the local PR artifact;
+2. run `oat project push` so the project ref contains the latest artifacts;
+3. run `oat project links --format markdown` to generate the delimited links
+   block from that exact ref commit;
+4. include the block in the submitted PR body;
+5. persist `oat_pr_status` and `oat_pr_url` in `state.md`; and
+6. push again so subsequent artifact writes can refresh the open PR body.
+
+The generated block links only `discovery.md`, `design.md`, and `summary.md`
+when present. The URLs are pinned to the project ref's exact commit SHA rather
+than a moving branch name. `plan.md`, `state.md`, `implementation.md`, and
+`reviews/` are intentionally excluded because they contain agent-facing
+execution detail rather than the reviewer-oriented project narrative. See
+[Reviewing OAT PRs](reviewing-oat-prs.md).
+
 ## Post-PR state
 
 After `oat-project-pr-final` creates the PR, `state.md` transitions to `oat_phase_status: pr_open`. This signals "awaiting human review" rather than "done."
@@ -57,7 +76,9 @@ Both completion orderings are supported:
 
 An open PR is not a completion blocker. When completion archives project
 artifacts, the archive-aware flow regenerates and synchronizes the open PR body
-so its artifact links remain valid.
+so its artifact links remain valid. Synced completion retains the project ref,
+which keeps its SHA-pinned links resolvable after the nested checkout is
+removed.
 
 ## Reference artifacts
 

package/assets/docs/workflows/projects/reviewing-oat-prs.md

@@ -0,0 +1,60 @@
+---
+title: Reviewing OAT PRs
+description: Understand synced-project records, SHA-pinned artifact links, and the reviewer-facing PR experience.
+---
+
+# Reviewing OAT PRs
+
+A PR for a synced OAT project contains the implementation diff without placing
+the agent-facing project tree on the feature branch. Reviewers get durable
+project context through a small tracked record and a generated links block in
+the PR body.
+
+## The synced record
+
+`.oat/projects/synced/<project>.json` is tracked on the feature branch. It
+names the project slug, `origin`, `refs/oat/projects/<project>`, whether the
+project is active or complete, and the archive snapshot when completion has
+created one. It is discovery and lifecycle metadata; the project artifacts
+themselves live on the project ref.
+
+## The artifact links block
+
+`oat project links` generates a delimited Markdown block for the PR body. Each
+URL points at the exact project-ref commit current when the block was rendered,
+so later pushes cannot silently change the content behind an existing link.
+`oat project push` refreshes the block when the project's `state.md` identifies
+an open PR.
+
+The block includes the reviewer-oriented artifacts that exist:
+
+- `discovery.md` for problem framing and constraints;
+- `design.md` for the selected architecture; and
+- `summary.md` for the concise outcome and durable decisions.
+
+It does not link `plan.md`, `state.md`, `implementation.md`, or `reviews/`.
+Those files are operational agent context, can be noisy or transient, and are
+not part of the stable reviewer narrative. The implementation diff and normal
+PR review remain authoritative for the code change.
+
+## Editor discovery
+
+The project checkout is a nested Git worktree. VS Code and Cursor may not show
+it in Source Control unless repository scanning includes nested repositories.
+Add the synced root to `git.scanRepositories` in workspace settings when you
+want editor Git integration for these checkouts:
+
+```json
+{
+  "git.scanRepositories": [".oat/projects/synced"]
+}
+```
+
+This setting is an editor convenience. OAT's `push`, `pull`, and `links`
+commands do not depend on editor discovery.
+
+## Related
+
+- [PR Flow](pr-flow.md)
+- [Project Artifacts](artifacts.md)
+- [Picking Up Projects](picking-up-projects.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.41",
-  "docs-config": "0.2.41",
-  "docs-theme": "0.2.41",
-  "docs-transforms": "0.2.41"
+  "cli": "0.2.45",
+  "docs-config": "0.2.45",
+  "docs-theme": "0.2.45",
+  "docs-transforms": "0.2.45"
 }