@open-agent-toolkit/cli 0.1.18 → 0.1.20

package/README.md

@@ -36,7 +36,8 @@ Additional useful entry points:
 - `oat project status --json`
 - `oat project list --json`
 - `oat project complete-state /path/to/project`
-- `oat project archive sync`
+- `oat project archive /path/to/project`
+- `oat repo archive sync`
 - `oat doctor`
 
 ## Inspection Commands

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -62,7 +62,7 @@ Archive lifecycle settings live here as shared repo config:
 - `archive.awsProfile`
 - `archive.awsRegion`
 
-`archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat project archive sync`, and they override any values already set in the parent shell — the repo's archive-scoped declaration wins so users don't have to remember to unset `AWS_PROFILE` per shell. The per-invocation `oat project archive sync --profile <profile>` and `--region <region>` flags then override the config for a single run, giving precedence `flag > config > shell env`. When neither flag nor config is set, the parent shell's `AWS_PROFILE` / `AWS_REGION` pass through unchanged. Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
+`archive.awsProfile` and `archive.awsRegion` are forwarded as `AWS_PROFILE` / `AWS_REGION` env vars into every `aws` spawn that runs during `oat-project-complete` and `oat repo archive sync`, and they override any values already set in the parent shell — the repo's archive-scoped declaration wins so users don't have to remember to unset `AWS_PROFILE` per shell. The per-invocation `oat repo archive sync --profile <profile>` and `--region <region>` flags then override the config for a single run, giving precedence `flag > config > shell env`. When neither flag nor config is set, the parent shell's `AWS_PROFILE` / `AWS_REGION` pass through unchanged. Raw access keys (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`) remain a shell-environment concern — there is no config plumbing for them.
 
 Tool-pack installation state also lives here as shared repo config:
 

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

@@ -112,7 +112,7 @@ With those values configured:
 - `oat-project-complete` still archives locally into `.oat/projects/archived/<project>/`
 - completion also attempts an S3 upload when AWS CLI is available and configured, storing dated snapshots such as `<archive.s3Uri>/<repo-slug>/projects/20260401-my-project/`
 - completion also copies `summary.md` into `<archive.summaryExportPath>/20260401-my-project.md`
-- `oat project archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
+- `oat repo archive sync` can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path `.oat/projects/archived/<project>/`
 - `oat-wrap-up` can write tracked reports into `<archive.wrapUpExportPath>/YYYY-MM-DD-wrap-up-<label>.md`; if the key is unset, the skill uses `.oat/repo/reference/wrap-ups/`
 - every `aws` spawn (preflight `aws sts get-caller-identity`, `aws s3 ls`, `aws s3 sync`) runs with `AWS_PROFILE` / `AWS_REGION` set from `archive.awsProfile` / `archive.awsRegion` when configured, overriding any value already in the parent shell
 
@@ -120,7 +120,7 @@ With those values configured:
 
 Profile and region resolve with the following precedence per `aws` invocation, highest first:
 
-1. CLI flag passed to `oat project archive sync` (`--profile <profile>`, `--region <region>`)
+1. CLI flag passed to `oat repo archive sync` (`--profile <profile>`, `--region <region>`)
 2. The repo's shared `archive.awsProfile` / `archive.awsRegion` config
 3. The parent shell's existing `AWS_PROFILE` / `AWS_REGION` env vars
 
@@ -128,15 +128,15 @@ If none of the three are present for a given var, OAT does not inject it — the
 
 `archive.awsProfile` is treated as deliberate, OAT-archive-scoped intent: if the repo declares the identity it wants to archive under, that value wins over whatever profile happens to be in the calling shell. Use `--profile` for one-off overrides; clear `archive.awsProfile` (set it to an empty string) to fall back to shell `AWS_PROFILE`.
 
-The `oat project archive sync` flags only override for that single invocation:
+The `oat repo archive sync` flags only override for that single invocation:
 
 ```bash
-oat project archive sync --profile work-sso --region us-east-1
+oat repo archive sync --profile work-sso --region us-east-1
 ```
 
 `oat-project-complete` does not accept per-invocation flags. Set the shared config (or your shell env) ahead of time if completion needs a specific profile.
 
-Raw access keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and friends) remain a shell-environment concern. OAT does not expose config keys for them — set them in your shell before running `oat-project-complete` or `oat project archive sync` and they are inherited by the spawned `aws` process unchanged.
+Raw access keys (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and friends) remain a shell-environment concern. OAT does not expose config keys for them — set them in your shell before running `oat-project-complete` or `oat repo archive sync` and they are inherited by the spawned `aws` process unchanged.
 
 ## Repo-local and user state
 

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

@@ -7,7 +7,7 @@ description: Scannable reference for the current OAT CLI surface, with links to
 
 Use this page when you need a quick map of the OAT CLI rather than the full command-by-command docs. It is intentionally shallow: each section points to the owning page that documents the detailed behavior.
 
-The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, and repo-analysis commands without adopting the full project workflow.
+The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oat tools`, docs commands, repo archive sync, and repo-analysis commands without adopting the full project workflow.
 
 ## Contents
 
@@ -18,7 +18,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
 - [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
 - [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
-- [Repository Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
+- [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
 
 ## Command Groups
 
@@ -32,10 +32,10 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 | `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                             | [Config and Local State](../cli-utilities/config-and-local-state.md)           |
 | `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                               | [Docs Tooling Commands](../docs-tooling/commands.md)                           |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                         | [Provider Sync](../provider-sync/index.md)                                     |
-| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
-| `oat repo ...`                                  | Repository-level analysis workflows, currently centered on PR comments.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
+| `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands. | [Workflow & Projects](../workflows/projects/index.md)                          |
+| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                 | [Repository Analysis](../workflows/projects/repo-analysis.md)                  |
 
-Notable inspection commands introduced in the current CLI surface:
+Notable commands introduced in the current CLI surface:
 
 - `oat config dump --json` - merged config with source attribution
 - `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
@@ -44,6 +44,8 @@ Notable inspection commands introduced in the current CLI surface:
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
 - `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]` - 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.
+- `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#validating-plan-metadata).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 

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

@@ -57,7 +57,7 @@ Archive sync surfaces:
 
 - Local archive root: `.oat/projects/archived/`
 - Remote archive base: `archive.s3Uri` in `.oat/config.json`
-- Archive sync command: `oat project archive sync` or `oat project archive sync <project-name>`
+- 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
 - 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/`

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

@@ -112,7 +112,7 @@ Current schema keys:
 | `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                    |
 | `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                             |
 | `archive.wrapUpExportPath`                  | `string`   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                                                    |
-| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat project archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                        |
+| `archive.awsProfile`                        | `string`   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                           |
 | `archive.awsRegion`                         | `string`   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                               |
 
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
@@ -166,8 +166,8 @@ Archive sync behavior:
 
 - `oat-project-complete` always archives locally into `.oat/projects/archived/<project>/`.
 - 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 project archive sync` syncs all repo archived projects down from S3 into `.oat/projects/archived/`.
-- `oat project archive sync <project-name>` syncs the latest dated remote snapshot for a single project into `.oat/projects/archived/<project-name>/`.
+- `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>/`.
 - Default archive sync is non-destructive toward unrelated local-only archive data, but it does replace a local project archive when a newer dated remote snapshot is selected for that same project.
 
 Typical contents:

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

@@ -39,4 +39,4 @@ 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.
-- [Repository Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.
+- [Repository PR Comment Analysis](repo-analysis.md) - Repo-wide PR comment collection and triage workflows.

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

@@ -65,7 +65,7 @@ On completion, OAT now treats archive handling as part of the closeout lifecycle
 - 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`.
 - Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
-- `oat project archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
 
 ### Phase status: `pr_open`
 

package/assets/docs/workflows/projects/repo-analysis.md

@@ -1,11 +1,13 @@
 ---
-title: Repository Analysis
-description: 'Repository-level analysis commands for collecting and triaging PR review comments.'
+title: Repository PR Comment Analysis
+description: 'Repository-level PR comment analysis commands for collecting and triaging review feedback.'
 ---
 
-# Repository Analysis (`oat repo`)
+# Repository PR Comment Analysis (`oat repo pr-comments`)
 
-The `oat repo` command group provides repository-level analysis and insight tools. These commands operate across merged pull requests rather than on individual PRs.
+The `oat repo pr-comments` command group provides repository-level review analysis tools. These commands operate across merged pull requests rather than on individual PRs.
+
+This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often).
 
 ## Quick Look
 
@@ -100,3 +102,4 @@ Both commands accept dependency injection for testability:
 
 - Source: `packages/cli/src/commands/repo/pr-comments/`
 - Types: `packages/cli/src/commands/repo/pr-comments/collect/pr-comments.types.ts`
+- Archive sync: [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.18",
-  "docs-config": "0.1.18",
-  "docs-theme": "0.1.18",
-  "docs-transforms": "0.1.18"
+  "cli": "0.1.20",
+  "docs-config": "0.1.20",
+  "docs-theme": "0.1.20",
+  "docs-transforms": "0.1.20"
 }

package/assets/skills/oat-agent-instructions-apply/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-apply
-version: 1.6.1
+version: 1.6.2
 description: Run when you have an agent instructions analysis artifact and want to generate or update instruction files. Creates a branch, generates files from templates, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
@@ -217,6 +217,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 1. **AGENTS.md first** — the canonical, provider-agnostic file
 2. **CLAUDE.md** — if claude provider is active, ensure `@AGENTS.md` import exists
 3. **Glob-scoped rules** — author once in canonical format at `.agents/rules/{name}.md` with YAML frontmatter (`description`, `globs`, `activation`)
+   - `activation` MUST be one of `always`, `glob`, `agent-requested`, `manual` — any other value (e.g. `auto`) is rejected by `oat sync`. Use `glob` (with `globs`) for file-targeted rules; see `frontmatter/canonical-rule.md` for the full activation matrix.
    - Provider-specific rule files are generated by `oat sync --scope project`
    - Do not hand-author `.claude/rules/*.md`, `.cursor/rules/*.mdc`, or `.github/instructions/*.instructions.md`
 4. **Copilot shim** — if copilot provider is active, generate `.github/copilot-instructions.md` from `frontmatter/copilot-shim.md` template
@@ -320,7 +321,7 @@ For each approved recommendation, in the order from Step 2:
    - `Claim Corrections` replaces stale claims in updated files
 6. For glob-scoped rules:
    - Write the canonical markdown once to `.agents/rules/{name}.md`
-   - Include canonical rule frontmatter (`description`, `globs`, `activation`) instead of provider-specific wrappers
+   - Include canonical rule frontmatter (`description`, `globs`, `activation`) instead of provider-specific wrappers. `activation` must be one of `always`, `glob`, `agent-requested`, `manual` (not `auto`); use `glob` with `globs` for file-targeted rules. See `references/instruction-file-templates/frontmatter/canonical-rule.md`.
    - After writing canonical rules, run `oat sync --scope project` to generate provider-specific rule files
    - Verify the generated provider files exist for each active provider instead of maintaining them by hand
    - Verify each generated provider file is trackable with `git check-ignore`; if any generated file is ignored,
@@ -503,5 +504,6 @@ Apply complete.
 - Bundled Cursor-specific format reference: `references/docs/cursor-rules-files.md`
 - Analysis artifact: `.oat/repo/analysis/agent-instructions-*.md`
 - Templates: `references/instruction-file-templates/`
+- Canonical rule frontmatter reference: `references/instruction-file-templates/frontmatter/canonical-rule.md`
 - Apply plan template: `references/apply-plan-template.md`
 - Tracking script: `.oat/scripts/resolve-tracking.sh`

package/assets/skills/oat-agent-instructions-apply/references/instruction-file-templates/frontmatter/canonical-rule.md

@@ -0,0 +1,93 @@
+# Canonical Rule Frontmatter
+
+Canonical glob-scoped rules live at `.agents/rules/{name}.md`. This is the **single source you author** — `oat sync --scope project` reads it and generates the provider-specific rule files (`.claude/rules/*.md`, `.cursor/rules/*.mdc`, `.github/instructions/*.instructions.md`). Do not hand-author those provider files.
+
+The canonical frontmatter is provider-agnostic and uses three fields: `description`, `globs`, and `activation`.
+
+## Frontmatter Fields
+
+| Field         | Required    | Type     | Description                                                                            |
+| ------------- | ----------- | -------- | -------------------------------------------------------------------------------------- |
+| `activation`  | **Yes**     | enum     | One of `always`, `glob`, `agent-requested`, `manual`. See matrix below.                |
+| `globs`       | Conditional | string[] | Glob patterns the rule targets. **Required when `activation: glob`.**                  |
+| `description` | Conditional | string   | Short purpose. **Required when `activation: agent-requested`**; recommended otherwise. |
+
+> The `activation` value is validated. The only accepted values are
+> `always`, `glob`, `agent-requested`, and `manual`. Any other value
+> (e.g. `auto`) is rejected by `oat sync --scope project`.
+
+## Activation Matrix
+
+| `activation`      | When to use                                                      | Required companion fields |
+| ----------------- | ---------------------------------------------------------------- | ------------------------- |
+| `glob`            | Rule applies to files matching specific patterns                 | `globs`                   |
+| `always`          | Repo-wide rule that should be in every session                   | —                         |
+| `agent-requested` | Agent decides relevance from the description (no file targeting) | `description`             |
+| `manual`          | Opt-in only — user explicitly invokes the rule                   | —                         |
+
+Selection rule of thumb: if the recommendation targets file patterns, use `activation: glob` with `globs`. Use `always` only for genuinely repo-wide guidance, `agent-requested` for description-driven rules with no glob, and `manual` for opt-in references.
+
+## Examples
+
+### Glob-scoped (most common)
+
+```yaml
+---
+description: 'Firebase handler trigger/registration conventions'
+activation: glob
+globs:
+  - 'src/functions/**/*.ts'
+---
+# {Rule Title}
+
+{ Rule body — identical to glob-scoped-rule.md template body }
+```
+
+### Always-on
+
+```yaml
+---
+description: 'Repo-wide security non-negotiables'
+activation: always
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+### Agent-requested (no globs)
+
+```yaml
+---
+description: 'Patreon integration gotchas — apply when touching billing flows'
+activation: agent-requested
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+### Manual (opt-in)
+
+```yaml
+---
+description: 'One-off migration playbook'
+activation: manual
+---
+# {Rule Title}
+
+{ Rule body }
+```
+
+## How It Maps to Providers
+
+`oat sync --scope project` translates each canonical `activation` to the equivalent provider frontmatter:
+
+| Canonical         | Claude (`.claude/rules/*.md`) | Cursor (`.cursor/rules/*.mdc`)       | Copilot (`.github/instructions/*`) |
+| ----------------- | ----------------------------- | ------------------------------------ | ---------------------------------- |
+| `glob`            | `paths`                       | `alwaysApply: false` + `globs`       | `applyTo`                          |
+| `always`          | no frontmatter (always-on)    | `alwaysApply: true`                  | repo-wide `applyTo` / shim         |
+| `agent-requested` | degrades to always-on         | `alwaysApply: false` + `description` | degrades to always-on              |
+| `manual`          | omitted / opt-in              | no frontmatter                       | omitted                            |
+
+See the per-provider frontmatter docs in this directory (`claude-rule.md`, `cursor-rule.md`, `copilot-instruction.md`) for the generated output formats, and `references/docs/rules-files.md` for the full cross-provider deep dive.

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.8
+version: 1.4.9
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -340,166 +340,30 @@ Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path
 
 Archive happens after PR description generation (so artifacts are readable at tracked paths) but before commit+push (so the archive deletion is included in the commit).
 
-The archive-side effects in this step are CLI-owned. Follow the canonical behavior from `packages/cli/src/commands/project/archive/archive-utils.ts` rather than inventing separate S3 or summary-export logic inside the skill.
-
-**Anti-pattern (do NOT do this):** Running `git check-ignore` on the
-`.oat/projects/archived` directory itself to decide durability. A common
-gitignore shape for this repo is `.oat/projects/archived/**`, which leaves the
-directory visible in the tree while ignoring every file placed inside. A
-directory-level check reports "not ignored" and produces the inverse of the
-intended decision — archiving in the worktree when the archive must actually
-go to the primary repo. Always probe a representative path **inside** the
-archive directory (the project subpath or a probe filename), matching the CLI
-helper at `packages/cli/src/commands/project/archive/archive-utils.ts`.
+The archive-side effects in this step are CLI-owned. Do not reimplement local archive movement, summary export, S3 sync, AWS credential handling, or worktree durability checks in the skill.
 
 ```bash
-ARCHIVED_ROOT=".oat/projects/archived"
-# ARCHIVE_RELATIVE_PATH is the contents-level probe: a hypothetical file that
-# would live inside the archive directory. This is the same probe shape the
-# CLI helper uses — do not simplify this to the directory itself.
-ARCHIVE_RELATIVE_PATH=".oat/projects/archived/${PROJECT_NAME}"
-PRIMARY_REPO_ARCHIVE=""
-ARCHIVE_CONTENTS_TRACKED="true"
-USE_PRIMARY_REPO_ARCHIVE="false"
-
-# Will a newly-archived file at ${ARCHIVE_RELATIVE_PATH} actually be tracked in
-# this checkout? Probe a representative path INSIDE the directory, not the
-# directory itself. A `.oat/projects/archived/**` gitignore pattern leaves the
-# directory visible in the tree but ignores everything placed inside, so a
-# directory-level check reports "tracked" and gives the inverse of the
-# intended answer.
-if git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH" 2>/dev/null; then
-  ARCHIVE_CONTENTS_TRACKED="false"
-fi
-
-# Fall back to the primary checkout whenever archive contents are local-only
-# in the current worktree, regardless of whether the archive directory itself
-# happens to exist in the tree.
-if [[ "$ARCHIVE_CONTENTS_TRACKED" == "false" ]] && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null || true)
-  GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || true)
-  if [[ -n "$GIT_COMMON_DIR" && -n "$GIT_DIR" && "$GIT_COMMON_DIR" != "$GIT_DIR" ]]; then
-    PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
-    PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
-    if [[ -d "$(dirname "$PRIMARY_REPO_ARCHIVE")" ]]; then
-      USE_PRIMARY_REPO_ARCHIVE="true"
-      ARCHIVED_ROOT="$PRIMARY_REPO_ARCHIVE"
-    else
-      echo "Warning: Running in a worktree with a local-only archive path, but the primary repo archive path is unavailable: $PRIMARY_REPO_ARCHIVE"
-      echo "A worktree-local archive may be deleted when the worktree is removed and is not a durable archive."
-      echo "Require explicit confirmation before proceeding with local-only archive."
-    fi
-  fi
-fi
-
-if [[ "$USE_PRIMARY_REPO_ARCHIVE" != "true" ]]; then
-  ARCHIVED_ROOT=".oat/projects/archived"
+ARCHIVE_OUTPUT=""
+if ! ARCHIVE_OUTPUT=$(oat project archive "$PROJECT_PATH" 2>&1); then
+  printf '%s\n' "$ARCHIVE_OUTPUT" >&2
+  echo "Error: Project archive failed." >&2
+  exit 1
 fi
 
-mkdir -p "$ARCHIVED_ROOT"
-ARCHIVE_PATH="${ARCHIVED_ROOT}/${PROJECT_NAME}"
+printf '%s\n' "$ARCHIVE_OUTPUT"
 
-if [[ -e "$ARCHIVE_PATH" ]]; then
-  ARCHIVE_PATH="${ARCHIVED_ROOT}/${PROJECT_NAME}-$(date +%Y%m%d-%H%M%S)"
+ARCHIVE_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^Archived project `[^`]+` to `(.+)`\.$/\1/p' | tail -1)
+if [[ -z "$ARCHIVE_PATH" ]]; then
+  echo "Error: oat project archive did not report the archived path." >&2
+  exit 1
 fi
 
-mv "$PROJECT_PATH" "$ARCHIVE_PATH"
 PROJECT_PATH="$ARCHIVE_PATH"
-echo "Project archived to $ARCHIVE_PATH"
+ARCHIVE_S3_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^S3 archive: (.+)$/\1/p' | tail -1)
+ARCHIVE_S3_CONTEXT=$(printf '%s\n' "$ARCHIVE_OUTPUT" | grep -E '^Archive S3 sync: .*profile=.*region=' | tail -1 || true)
 ```
 
-**Canonical helper behaviors (required):**
-
-- Always archive locally first. The local archive is the authoritative completion artifact even when remote sync is also configured.
-- If `archive.summaryExportPath` is configured and `summary.md` exists after archive, copy it to `{repoRoot}/{archive.summaryExportPath}/YYYYMMDD-{PROJECT_NAME}.md`.
-- If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, sync the archived project to `{archive.s3Uri}/{repo-slug}/projects/YYYYMMDD-{PROJECT_NAME}/`. The S3 sync excludes process artifacts (`reviews/*`, `pr/*`) — only core deliverables (discovery, spec, design, plan, implementation, summary, state) are uploaded. The CLI enforces this via `S3_ARCHIVE_SYNC_EXCLUDES` in `archive-utils.ts`.
-- If AWS CLI is missing or unusable for that S3 sync, warn and continue. Completion must not fail after the local archive succeeds.
-- If `archive.s3SyncOnComplete` is false or `archive.s3Uri` is unset, skip remote sync without prompting.
-
-**AWS credential handling for archive S3 sync (required):**
-
-When `archive.s3SyncOnComplete=true` and `archive.s3Uri` is set, the agent MUST honor the repo's archive-scoped AWS credentials instead of falling back to whatever shell profile/region happens to be active. The contract mirrors `buildAwsEnv` in `packages/cli/src/commands/project/archive/archive-utils.ts`.
-
-- **Read both keys from OAT config before any AWS CLI call:**
-
-  ```bash
-  ARCHIVE_AWS_PROFILE=$(oat config get archive.awsProfile 2>/dev/null || true)
-  ARCHIVE_AWS_REGION=$(oat config get archive.awsRegion 2>/dev/null || true)
-  ```
-
-- **Apply them to every `aws` invocation tied to archive sync** — preflight checks (`aws --version`, `aws sts get-caller-identity`), bucket access probes (`aws s3 ls`), and the actual `aws s3 sync`. Do not mix configured values across some calls and ambient values across others.
-- **Configured archive values WIN over ambient shell AWS env vars.** A non-empty `archive.awsProfile` overrides any `AWS_PROFILE` or `AWS_DEFAULT_PROFILE` already exported in the shell. A non-empty `archive.awsRegion` overrides `AWS_REGION` and `AWS_DEFAULT_REGION`. Treat the repo's archive-scoped declaration as deliberate intent — users should not have to unset shell env vars to get correct archive credentials. Empty/unset config values fall through to the AWS CLI's normal resolution chain.
-- **Prefer the OAT CLI when it is available.** If you delegate archive sync to an `oat project archive ...` invocation, the CLI applies the canonical handling for you (config-resolved profile/region clobber the spawned env). Do not pass `--profile` / `--region` flags unless the user asked for a one-off override different from the repo config.
-- **Manual AWS CLI fallback** — when no OAT command wraps the operation and the agent must call `aws` directly, pass the configured profile/region explicitly. Either use flags:
-
-  ```bash
-  AWS_FLAGS=()
-  if [[ -n "$ARCHIVE_AWS_PROFILE" ]]; then
-    AWS_FLAGS+=(--profile "$ARCHIVE_AWS_PROFILE")
-  fi
-  if [[ -n "$ARCHIVE_AWS_REGION" ]]; then
-    AWS_FLAGS+=(--region "$ARCHIVE_AWS_REGION")
-  fi
-
-  aws "${AWS_FLAGS[@]}" sts get-caller-identity
-  aws "${AWS_FLAGS[@]}" s3 sync \
-    "$ARCHIVE_PATH" \
-    "${ARCHIVE_S3_URI%/}/${REPO_SLUG}/projects/${SNAPSHOT_NAME}/" \
-    --exclude 'reviews/*' --exclude 'pr/*'
-  ```
-
-  …or set the equivalent env vars for the spawned process so the same precedence applies:
-
-  ```bash
-  AWS_ENV=()
-  [[ -n "$ARCHIVE_AWS_PROFILE" ]] && AWS_ENV+=("AWS_PROFILE=$ARCHIVE_AWS_PROFILE")
-  [[ -n "$ARCHIVE_AWS_REGION" ]] && AWS_ENV+=("AWS_REGION=$ARCHIVE_AWS_REGION")
-  env "${AWS_ENV[@]}" aws s3 sync ...
-  ```
-
-  Both shapes are acceptable; the AWS CLI treats `--profile` / `--region` and `AWS_PROFILE` / `AWS_REGION` env as higher precedence than `AWS_DEFAULT_*`, so the configured values win.
-
-- **Report the resolved profile/region in the completion summary** so the user can confirm the right identity ran the sync, e.g. `Archive S3 sync used AWS profile=tkstang-artifact-sync region=us-east-1`. Do not echo raw access keys, session tokens, or any value from `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`. If `archive.awsProfile` or `archive.awsRegion` is unset, report `<unset; using shell default>` for that field.
-- **AccessDenied troubleshooting** — if `aws s3 sync` returns AccessDenied, confirm before retrying that the spawn actually used `archive.awsProfile` (not the ambient shell profile). A common pitfall is invoking `aws s3 sync` without flags from a shell where `AWS_PROFILE` points at an unrelated identity; rerun with the configured profile/region applied as above.
-
-**Worktree durability guard (required):**
-
-- If running in a worktree and the primary repo archive path is unavailable, do not silently continue with a local-only archive.
-- Ask the user explicitly: "Primary repo archive path is unavailable, so this archive may be lost when the worktree is deleted. Continue with local-only archive anyway?"
-- If the user declines, skip archiving and continue the completion flow without archive.
-- Resolve the durable repo root from `git rev-parse --git-common-dir` and `git rev-parse --git-dir`, matching the CLI helper in `packages/cli/src/commands/project/archive/archive-utils.ts`. Do not rely on a `main` checkout or default-branch naming.
-- Apply this guard only when `git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH"` reports that the archive **contents** are local-only in the current checkout. `$ARCHIVE_RELATIVE_PATH` must be a path **inside** the archive directory (the project subpath), never the directory itself — see the anti-pattern note above the bash block.
-
-**Git handling after archive:**
-
-If the archived directory is gitignored (check with `git check-ignore -q "$ARCHIVE_PATH"`), the move looks like a deletion to git — the original tracked files disappear and the archived copy is local-only. To commit:
-
-```bash
-git add -A "$PROJECTS_ROOT/$PROJECT_NAME" 2>/dev/null || true
-```
-
-This stages the deletions from the shared directory. The archived copy is preserved locally but not tracked by git.
-
-**Worktree archive target (required when available):**
-
-If running from a git worktree, prefer the primary repo archive directory whenever a newly-archived file inside `.oat/projects/archived/` would be local-only in the current checkout.
-
-Reference path:
-
-```bash
-GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
-PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
-PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
-```
-
-Guidance:
-
-- In a worktree, prefer `PRIMARY_REPO_ARCHIVE` whenever `git check-ignore --quiet --no-index "$ARCHIVE_RELATIVE_PATH"` reports the archive **contents** as ignored — regardless of whether the archive directory itself happens to exist in the tree. Only archive in the current checkout when a hypothetical file at `.oat/projects/archived/<project>/state.md` would actually be tracked here.
-- Do not check `git check-ignore` on `.oat/projects/archived` (the directory itself). A `.oat/projects/archived/**` ignore pattern leaves the directory unignored while ignoring all contents, so a directory-level check reports "tracked" and an agent can mistakenly archive in the worktree.
-- Do not treat the worktree-local archive as durable.
-- If forced to use a local-only archive, warn and require explicit user confirmation.
-- Always write the dated `archive.summaryExportPath` copy into the current checkout (`repoRoot`), even when the project archive itself is written to the primary checkout.
-- Do not hardcode user-specific absolute paths.
+Use `ARCHIVE_S3_CONTEXT` in Step 12 if the command reports profile/region details. If S3 sync ran and only `ARCHIVE_S3_PATH` is available, report the destination and note that credential context was not emitted by the command.
 
 ### Step 9: Regenerate Dashboard
 
@@ -607,7 +471,7 @@ Show user:
 
 - "Project **{PROJECT_NAME}** marked as complete."
 - If archived: "Archived location: **{PROJECT_PATH}**"
-- If S3 archive sync ran: include the resolved AWS profile and region used (e.g. `Archive S3 sync: profile=<archive.awsProfile> region=<archive.awsRegion>`). Show `<unset; using shell default>` for any field the config did not provide. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
+- If S3 archive sync ran: include `ARCHIVE_S3_CONTEXT` when the archive command reported profile/region details. If only `ARCHIVE_S3_PATH` is available, include the S3 destination and note that profile/region context was not reported by the command. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
 - Include commit hash and push result for the bookkeeping changes.
 - If PR was opened: include the PR URL.
 - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.

package/assets/skills/oat-wrap-up/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-wrap-up
-version: 1.0.0
+version: 1.0.1
 description: Use when preparing a shipping digest or weekly/biweekly wrap-up summarizing OAT projects and merged PRs over a time window. Reads local summary files and GitHub PR metadata; writes a version-controlled markdown report.
 argument-hint: '[--since YYYY-MM-DD] [--until YYYY-MM-DD] [--past-week|--past-2-weeks|--past-month] [--output <path>] [--dry-run]'
 disable-model-invocation: false
@@ -26,7 +26,7 @@ Don't use when:
 
 - You need a single specific project's summary — use `oat-project-summary` instead.
 - You want an always-current status view without a fixed window — the wrap-up is window-scoped by design.
-- Archived projects from teammates have not been hydrated locally yet — run `oat project archive sync` first so the digest reflects the full team's work. The skill warns if this looks undone but will not auto-run sync.
+- Archived projects from teammates have not been hydrated locally yet — run `oat repo archive sync` first so the digest reflects the full team's work. The skill warns if this looks undone but will not auto-run sync.
 
 ## Arguments
 
@@ -45,7 +45,7 @@ Exactly one time-range specifier is required: either a named range (`--past-week
 ## Prerequisites
 
 - Repository is an OAT project (contains `.oat/`).
-- For cross-teammate visibility: `oat project archive sync` has been run recently so teammates' archived projects are hydrated into `.oat/projects/archived/`. The skill warns if `archive.s3Uri` is configured but the local archive has no `.oat-archive-source.json` metadata files.
+- For cross-teammate visibility: `oat repo archive sync` has been run recently so teammates' archived projects are hydrated into `.oat/projects/archived/`. The skill warns if `archive.s3Uri` is configured but the local archive has no `.oat-archive-source.json` metadata files.
 - `gh` CLI authenticated for the current repository (needed for merged-PR fetching via `gh api graphql`).
 
 ## Mode Assertion
@@ -57,7 +57,7 @@ Exactly one time-range specifier is required: either a named range (`--past-week
 **BLOCKED Activities:**
 
 - No modifying OAT project summaries, plan files, or other implementation artifacts.
-- No auto-running `oat project archive sync` — it is a user-gated prerequisite, not a side effect of this skill.
+- No auto-running `oat repo archive sync` — it is a user-gated prerequisite, not a side effect of this skill.
 - No network writes of any kind. The GitHub API is read-only.
 
 **ALLOWED Activities:**
@@ -71,7 +71,7 @@ Exactly one time-range specifier is required: either a named range (`--past-week
 If you catch yourself:
 
 - About to modify a summary file → STOP, the skill is strictly read-only against summaries.
-- About to auto-run `oat project archive sync` → STOP, the skill only warns; the user runs sync themselves.
+- About to auto-run `oat repo archive sync` → STOP, the skill only warns; the user runs sync themselves.
 - About to string-concatenate summary prose verbatim → STOP, the report is a synthesis, not a concatenation.
 - About to skip the prerequisite warning when the local archive is empty and S3 is configured → STOP, emit the warning first.
 
@@ -123,12 +123,12 @@ S3_URI="$(oat config get archive.s3Uri 2>/dev/null || true)"
 if [ -n "$S3_URI" ] && [ -d "$ARCHIVE_DIR" ]; then
   if ! find "$ARCHIVE_DIR" -maxdepth 2 -name '.oat-archive-source.json' 2>/dev/null | grep -q . ; then
     printf '⚠️  archive.s3Uri is configured but no archived snapshots are hydrated locally.\n'
-    printf '    Run "oat project archive sync" first so teammates archived projects are visible to the wrap-up.\n'
+    printf '    Run "oat repo archive sync" first so teammates archived projects are visible to the wrap-up.\n'
     printf '    (Proceeding with active projects and the version-controlled summaries directory only.)\n'
   fi
 elif [ -n "$S3_URI" ]; then
   printf '⚠️  archive.s3Uri is configured but %s does not exist.\n' "$ARCHIVE_DIR"
-  printf '    Run "oat project archive sync" first so archived projects are available.\n'
+  printf '    Run "oat repo archive sync" first so archived projects are available.\n'
   printf '    (Proceeding with active projects and the version-controlled summaries directory only.)\n'
 fi
 ```
@@ -362,7 +362,7 @@ so I can review before committing it.
 
 - Report skeleton: `references/report-template.md`
 - Automation patterns (Claude Code `CronCreate`, Codex host scheduling, plain cron): `references/automation-recipes.md`
-- Prerequisite command: `oat project archive sync` at `packages/cli/src/commands/project/archive/index.ts:244`
+- Prerequisite command: `oat repo archive sync` at `packages/cli/src/commands/repo/archive/index.ts`
 - Merged-PR query pattern: `packages/cli/src/commands/repo/pr-comments/collect/collect-comments.ts:198-205`
 - Summary frontmatter schema: `.oat/templates/summary.md`
 - Config key: `archive.wrapUpExportPath` (managed via `oat config set archive.wrapUpExportPath <path>`)
@@ -377,7 +377,7 @@ so I can review before committing it.
 **Report is empty or "no summaries found":**
 
 - The window may genuinely have no activity — double-check `SINCE` and `UNTIL`.
-- Check whether teammates' archived projects are hydrated: `ls .oat/projects/archived/` should list directories. If empty and `archive.s3Uri` is configured, run `oat project archive sync` first.
+- Check whether teammates' archived projects are hydrated: `ls .oat/projects/archived/` should list directories. If empty and `archive.s3Uri` is configured, run `oat repo archive sync` first.
 - Verify that `.oat/projects/*/*/summary.md` and/or `${SUMMARY_EXPORT_PATH}/*.md` contain files whose `oat_last_updated` falls inside the window.
 
 **Report is missing PRs that clearly merged in the window:**