@open-agent-toolkit/cli 0.2.64 → 0.2.66

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.64"
+  "oatVersion": "0.2.66"
 }

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

@@ -15,6 +15,7 @@ For the deep file-by-file reference, see:
 - [File Locations](../reference/file-locations.md)
 - [`.oat` Directory Structure](../reference/oat-directory-structure.md)
 - [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
+- [Remote Project Management](remote-project-management.md)
 
 ## The five config surfaces
 
@@ -51,7 +52,7 @@ What each command is for:
 - `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
 - `oat config get <key>` reads one supported key value.
 - `oat config set <key> <value>` updates supported shared or repo-local keys.
-- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, the `workflow.dispatchCeiling` aggregate read views, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
+- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, aggregate read views, read-only remote-policy structure, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
 - `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
 
@@ -101,10 +102,27 @@ Common keys in `.oat/config.json`:
 - `archive.awsProfile` — optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
 - `tools.<pack>` — project-scope intent for a bundled tool pack (`true` or absent)
+- `pjm.remote.storage.state` — `local` by default; `shared` requires an
+  explicit preview and fresh approval and is unavailable to local projects
+- `pjm.remote.policy.description` — `none`, `managed-section`, or `replace`;
+  the default is `none`
+- `pjm.remote.policy.authority.*` — repository defaults and operation-specific
+  authority for remote creates, field updates, transitions, annotations,
+  deletion, relink, detach, and recreate; the default is `read-only`
+- `pjm.remote.policy.providers.<provider>.*` — optional GitHub, Linear, or Jira
+  replacement policy; its operation override or default may broaden the
+  repository result before later restrictions apply
 - `pjm.initialized` / `pjm.schemaVersion` — explicit repository PJM adoption written by `oat pjm init`
 - `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — default review budgets in milliseconds
 
+Remote authority resolves the repository operation override, repository
+default, or built-in read-only fallback first. Matching provider policy replaces
+that result. Binding defaults and operation restrictions then clamp authority,
+and purpose field grants intersect to narrow outbound fields. No configured
+layer bypasses hard approval floors or current caller-owned authority evidence;
+missing, stale, or mismatched evidence fails closed.
+
 Tool-pack intent example:
 
 ```bash

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

@@ -14,6 +14,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
 - [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
+- [Remote Project Management](remote-project-management.md) - Provider-neutral remote bindings, policy, previews, approvals, storage, and recovery.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [Project Log](project-log.md) - Append-only project observations, synthesis, inspection, and durable roll-up.
 - [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
@@ -51,6 +52,7 @@ Use CLI Utilities when:
 - Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
 - Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
 - Read [Configuration](configuration.md) for config semantics, or [Config and Local State](config-and-local-state.md) for inspection and diagnostic command groups.
+- Read [Remote Project Management](remote-project-management.md) before binding local planning records to GitHub, Linear, or Jira.
 - Use [Workflow Gates](workflow-gates.md) when you want a skill to run a configured final command before it is considered done.
 
 ## Common Tasks
@@ -66,5 +68,6 @@ Use CLI Utilities when:
 - [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
 - [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance.
+- [Remote Project Management](remote-project-management.md) - Safely operate explicit remote planning-record bindings.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch.

package/assets/docs/cli-utilities/remote-project-management.md

@@ -0,0 +1,191 @@
+---
+title: Remote Project Management
+description: Safely bind OAT planning records to GitHub, Linear, or Jira through provider-neutral host capabilities.
+---
+
+# Remote Project Management
+
+Remote project management connects an OAT backlog item or project to a remote
+GitHub, Linear, or Jira record. OAT owns policy, previews, approvals, durable
+operation state, and authoritative read-back verification. The host agent owns
+live execution capability discovery.
+
+Remote management is deliberately explicit. It does not turn every plan task
+into a remote issue, run background synchronization, or treat a provider result
+as proof of success.
+
+## Prerequisite
+
+Confirm that file-backed project management is adopted before using a remote
+command:
+
+```bash
+oat pjm doctor --json
+```
+
+Continue only when `adoption.state` is `declared` or `inferred-legacy`. Run
+`oat pjm init` first when adoption is absent or only partially initialized.
+
+## Lifecycle operations
+
+The command family is `oat pjm remote`:
+
+```bash
+oat pjm remote intake github:example/repository#123 --to-backlog BL-123 --capability-evidence-stdin --json
+oat pjm remote publish --binding rb_example --capability-evidence-stdin --json
+oat pjm remote refresh --binding rb_example --capability-evidence-stdin --json
+oat pjm remote reconcile --binding rb_example --capability-evidence-stdin --json
+oat pjm remote closeout --project .oat/projects/shared/example --capability-evidence-stdin --json
+oat pjm remote discussion --binding rb_example --limit 20 --capability-evidence-stdin --json
+oat pjm remote resolve relink --binding rb_example github:example/repository#456 --capability-evidence-stdin --json
+oat pjm remote resolve detach --binding rb_example --json
+oat pjm remote resolve recreate --binding rb_example --capability-evidence-stdin --json
+oat pjm remote doctor --json
+oat pjm remote migrate --check --json
+```
+
+Before each provider-contacting example, the host discovers live capability and
+supplies only its bounded provider-neutral evidence on standard input. Mutation
+commands also require the current caller-owned authority evidence requested by
+their live help.
+
+- `intake` reads one remote record into a selected local backlog target and
+  creates the binding.
+- `publish` creates or updates one explicitly selected binding.
+- `refresh` updates retained snapshots without writing remotely.
+- `reconcile` classifies local, remote, and baseline changes before proposing
+  any write.
+- `closeout` prepares a reviewed batch while preserving independent per-binding
+  outcomes.
+- `discussion` returns one bounded, sanitized page as non-persisted evidence.
+- `resolve relink`, `detach`, and `recreate` handle anomalous bindings without
+  discarding identity history or retrying an uncertain create blindly.
+- `doctor` and `migrate` diagnose or repair local records without contacting a
+  provider.
+
+Use `--help` on the live command for current options. JSON output uses one
+versioned envelope and may return a nonzero shell exit for a safely persisted
+`pending`, `needs-review`, `partial`, `uncertain`, or `blocked` outcome.
+
+## Repository-owned policy
+
+Remote policy lives only in the shared repository config at `.oat/config.json`.
+The safe defaults are local operational state, no description publication, and
+read-only authority:
+
+```json
+{
+  "pjm": {
+    "remote": {
+      "schemaVersion": 1,
+      "storage": { "state": "local" },
+      "policy": {
+        "description": "none",
+        "authority": { "default": "read-only" }
+      }
+    }
+  }
+}
+```
+
+Use the config command instead of editing nested values by hand:
+
+```bash
+oat config set pjm.remote.policy.description managed-section --shared
+oat config set pjm.remote.policy.authority.operations.update-fields user-approved --shared
+oat config set pjm.remote.policy.providers.github.authority.operations.create user-approved --shared
+```
+
+Description modes are `none`, `managed-section`, and `replace`. Authority modes
+are `read-only`, `user-approved`, `user-authorized`, and `autonomous`.
+For each operation, OAT resolves the repository operation override, then its
+repository default, then the built-in read-only fallback. A matching provider
+operation override or provider default replaces that repository result and may
+broaden it. Binding defaults and operation restrictions then clamp authority,
+while purpose field grants intersect to narrow the outbound fields. Provider
+configuration never bypasses hard approval floors or the requirement for
+current caller-owned authority evidence; missing, stale, or mismatched evidence
+fails closed. Autonomous configuration is not a background grant.
+
+## Live host capability boundary
+
+At operation time, the host agent inspects currently granted MCP or connector
+descriptions for the requested semantic operation and exact account, workspace,
+site, or repository context. If no capable connector is available, it may
+inspect the live help of an already configured provider CLI before the first
+provider-contacting command.
+
+OAT does not store provider tool names, native schemas, captured catalogs,
+executable names, flags, or CLI dialects. The host returns only bounded,
+sanitized capability evidence through `--capability-evidence-stdin`. It must not
+install tools, request credential values, or switch execution surfaces after an
+attempt begins. The CLI may then emit one provider-neutral `externalAction`.
+The host executes that exact action at most once and returns one bounded
+observation with `oat pjm remote operation continue`.
+
+## Content and outbound safety
+
+Inbound provider text is retained only through an allowlist of core fields and
+adapter-approved extensions. If a retained text field triggers a conservative
+sensitive-content signal, OAT suppresses that whole field and marks the
+snapshot incomplete. This is a bounded field-safety rule, not general DLP or
+credential-value parsing.
+
+Every remote create or update consumes only an explicit normalized projection.
+The universal provider-neutral pre-write gate evaluates that projection before
+preview, approval, action, and authoritative read-back. It never scans the
+repository, worktree, Git history, or arbitrary files for secrets. Missing,
+stale, failed, or blocked safety evidence prevents execution.
+
+## Previews, approval floors, and uncertainty
+
+Mutation-capable commands persist and return a preview before execution. The
+preview digest binds the target, normalized fields, remote revision,
+capability, safety result, and effective policy. If any load-bearing input
+changes, the approval is stale.
+
+Fresh approval is always required for complete description replacement,
+relink, detach, recreate, destructive operations, and promotion to shared
+operational storage. `user-approved` authority also requires applying the exact
+persisted preview. Higher configured authority cannot bypass those floors.
+
+The host submits a bounded observation with `oat pjm remote operation continue`.
+Only an OAT `ok` envelope after authoritative read-back means success. A
+connector response, process exit, or visible remote change is evidence rather
+than a verdict. If a create or update is uncertain, do not retry it blindly;
+use the recovery guidance in the envelope so OAT can search, relink, recreate,
+or reconcile without producing duplicates.
+
+## Storage and worktrees
+
+Portable binding metadata follows its backlog or project owner. Shared backlog
+metadata lives under `.oat/repo/pjm/remote/bindings`; project metadata lives
+under that project's `remote/bindings` directory. Local projects keep their
+portable metadata in the local operational store.
+
+Operational snapshots, journals, batches, and receipts default to a
+repository-fingerprinted directory under the Git common directory:
+`.git/oat/pjm-remote/<repository-fingerprint>/`. All linked worktrees for one
+repository therefore share the same local operational state, while another
+clone gets its own store.
+
+Shared operational storage is opt-in and may expose remote planning content to
+everyone with repository access. It requires a persisted preview and fresh
+approval, and it is rejected for local projects. Preview the exact proposed
+paths through `oat pjm remote storage shared --help` before applying them.
+
+## Offline behavior
+
+OAT can inspect portable bindings, the bounded local snapshot, journals,
+receipts, and pending recovery instructions while offline. `remote doctor` and
+`migrate` are local-only. Provider refresh, publication, reconciliation writes,
+and authoritative verification remain pending or blocked until matching live
+capability evidence is available; offline state never fabricates remote
+freshness or success.
+
+## Related references
+
+- [Configuration](configuration.md)
+- [CLI Reference](../reference/cli-reference.md)
+- [File Locations](../reference/file-locations.md)
+- [Troubleshooting](../reference/troubleshooting.md)

package/assets/docs/contributing/skills.md

@@ -204,9 +204,14 @@ resolution. `resolveSkillVersion` in
 runtime helper and the validators cannot disagree.
 
 The top-level `version` field remains supported as a deprecated alias. Every
-bundled skill still uses it today, so `pnpm oat:validate-skills` reports each
-one as a non-blocking warning; the value is still read, and nothing breaks.
-Migrating the bundled skills is tracked separately.
+bundled skill now declares `metadata.version` and carries no top-level
+`version`, so `pnpm oat:validate-skills` reports no alias warnings on the
+bundled tree. The alias is retained for third-party skills installed from
+packs, which may still carry it; it retires on the schedule recorded in
+`DR-260908-bundled-skills-declare` — the warning becomes an error in the first
+release after 0.2.65 that changes the validator, and the resolver's top-level
+read is removed one release after that error has produced no findings on the
+bundled tree.
 
 A skill that carries both fields with different values is a conflict. The
 resolver reports the `metadata.version` value together with the conflict, and
@@ -214,7 +219,12 @@ the callers that must not guess act on it: validation reports an error rather
 than silently picking one, and canonical role resolution treats the identity as
 invalid. The runtime version readers still return the `metadata.version` value,
 so an installed-versus-bundled comparison keeps working while the conflict is
-being fixed. Carrying both with the _same_ value is accepted.
+being fixed. Carrying both with the _same_ value resolves without a conflict and
+without an alias warning, because `metadata.version` wins. A bundled skill must
+still carry `metadata.version` alone: the corpus sweep in
+`packages/cli/src/validation/skills.test.ts` fails on any column-0 `version:`
+line under `.agents/skills`, which is the only check that catches the
+same-value case.
 
 ### The version is gated
 
@@ -227,7 +237,7 @@ resolved version, so it enforces the bump whether the skill declares
 of Done) and in CI; a changed skill whose version matches `origin/main` fails
 the gate. The deprecation warning above is deliberately not part of that gate:
 `check:skill-bumps` fails on any finding it receives, so an alias warning
-routed through it would fail every changed skill until the migration lands.
+routed through it would fail every changed skill that still carried one.
 
 ## Practical Authoring Flow
 

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

@@ -14,6 +14,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
 - [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
 - [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
+- [Remote Project Management](../cli-utilities/remote-project-management.md) - Explicit remote bindings, policy, host handoffs, and recovery.
 - [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
 - [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
@@ -43,6 +44,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                                        | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                     |
 | `oat tools ...`                                 | Install, inspect, update, remove, and migrate bundled OAT tool packs and assets across project and user scope.                                                                                                             | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
 | `oat pjm ...`                                   | Adopt PJM for a repository and record it (`init`), run read-only adoption and reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`). Adoption is separate from pack placement. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
+| `oat pjm remote ...`                            | Intake, publish, refresh, reconcile, close out, inspect discussion, resolve anomalies, diagnose, migrate, and continue durable host actions for explicit remote bindings.                                                  | [Remote Project Management](../cli-utilities/remote-project-management.md)         |
 | `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
 | `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
@@ -134,6 +136,12 @@ Notable commands introduced in the current CLI surface:
   never converted into a `recorded-absent` row or pull guidance.
 - `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 pjm remote ... --json` - operate one explicit provider-neutral binding.
+  The family includes `intake`, `publish`, `refresh`, `reconcile`, `closeout`,
+  `discussion`, `resolve`, `doctor`, `migrate`, `storage`, and
+  `operation continue`. An `ok` envelope exits 0, a system `failed` envelope exits 2, and
+  every safely persisted nonterminal or blocked status exits 1. A `pending`
+  envelope with `externalAction` is a durable host handoff, not remote success.
 - `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.
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
@@ -171,12 +179,15 @@ Per-key restrictions apply identically to `set` and `unset`: structural keys can
 
 `oat config unset <key>` removes the key from the selected surface and prunes any parent object it empties, so the resolved value falls back through the remaining surfaces to the built-in default. Removing a key the surface does not hold is not an error: it reports an already-unset outcome and exits 0. With `--json` the envelope adds a `removed` boolean, which is the machine-readable way to tell a real removal from an already-unset no-op, since both exit 0. A stored value that fails validation is still removed, matching `oat config set`, which repairs the same file.
 
-`unset` refuses five classes of key, each with exit code 1:
+Remote settings under `pjm.remote.*` remain shared-only. Removing a mutable leaf preserves sibling settings and the required empty `policy` object, if necessary, so the remaining remote configuration stays readable. Explicit defaults are removed from disk rather than silently written back by normalization; effective values still use fail-closed defaults. Remote policy must pass strict validation before removal.
+
+`unset` refuses six classes of key, each with exit code 1:
 
 - **Unknown keys**, including keys OAT reads but does not expose in the `oat config` catalog (`documentation.index`). These are not removable by any `oat config` command.
 - **Lifecycle state** (`activeProject`, `lastPausedProject`) — cleared with `oat config set <key> ''` instead.
 - **Pack intent** (`tools.*`) — removed with `oat tools remove --pack <pack> --scope project`, which also removes the installed pack files. Clearing the intent alone would leave them behind.
 - **Aggregate read views** (`workflow.dispatchCeiling`, `workflow.dispatchCeiling.providers`) — these are assembled for `get` from the leaf keys and are not stored as such. Unset `workflow.dispatchCeiling.preset` or `workflow.dispatchCeiling.providers.<provider>` instead.
+- **Read-only remote-policy structure** (`pjm.remote`, `pjm.remote.policy`, `pjm.remote.schemaVersion`) — unset a documented mutable child key instead; removing the complete policy or its schema discriminator is not supported.
 - **Environment-shadowed keys with nothing stored on the target surface** — when `OAT_PROJECTS_ROOT`, `OAT_PROJECTS_DEFAULT_SCOPE`, or `OAT_WORKTREES_ROOT` supplies the effective value and the surface holds nothing to remove, clear the environment variable in your shell. When the surface _does_ hold a stored value, `unset` removes it (as `set` would rewrite it) and warns that the override still supplies the effective value.
 
 ## `workflow.*` preference keys

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

@@ -82,10 +82,32 @@ Config ownership note:
 - Runtime sync state: `.oat/sync/`
 - Repo knowledge: `.oat/repo/knowledge/`
 - Active PJM operational layer: `.oat/repo/pjm/` (`current-state.md`, `roadmap.md`, `backlog/`)
+- Shared backlog remote-binding metadata: `.oat/repo/pjm/remote/bindings/`
 - Durable repo references: `.oat/repo/reference/` (file-per-record decisions under `decisions/`)
 - Repo reviews: `.oat/repo/reviews/`
 - Repo archive: `.oat/repo/archive/`
 
+### Remote PJM binding and operation state
+
+Remote binding metadata follows the local owner:
+
+- shared backlog bindings: `.oat/repo/pjm/remote/bindings/`
+- shared or synced project bindings: `<project>/remote/bindings/`
+- local project bindings: the local operational store's `metadata/bindings/`
+
+Operational snapshots, journals, batches, and receipts default to
+`<git-common-dir>/oat/pjm-remote/<repository-fingerprint>/`. Git linked
+worktrees resolve the same common directory and therefore share this local
+state. A separate clone has a different Git directory and begins without the
+first clone's operational snapshot; run `oat pjm remote refresh` through a live
+host capability before relying on remote freshness.
+
+When shared state is explicitly previewed and approved,
+`.oat/repo/pjm/remote/state/` or `<project>/remote/state/` replaces the local
+operational root. Shared state can contain remote planning content and is not
+available for local projects. See
+[Remote Project Management](../cli-utilities/remote-project-management.md).
+
 ## Project artifact trees
 
 - Shared: `.oat/projects/shared/<project>/`

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

@@ -38,6 +38,9 @@ Project scope is used for project workflows and repo-local sync state. User scop
   repo/
     knowledge/
     pjm/
+      remote/
+        bindings/
+        state/
     reference/
     reviews/
     archive/
@@ -45,16 +48,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                             | Notes                                                                                                   |
-| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `.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`, `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. |
-| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`              |
+| Path                     | Purpose                                             | Notes                                                                                                               |
+| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, and `pjm.remote.*` |
+| `.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`, `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.             |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                          |
 
 ## `.oat/sync/` details
 
@@ -283,8 +286,17 @@ Typical contents:
   reviews/
   pr/
   references/
+  remote/
+    bindings/
+    state/
 ```
 
+The `remote/bindings/` directory is portable metadata for shared and synced
+projects. `remote/state/` exists only after approved shared-storage promotion.
+With the default local storage policy, operational state instead lives under
+`<git-common-dir>/oat/pjm-remote/<repository-fingerprint>/`, outside `.oat/`.
+Linked worktrees share that location; independent clones do not.
+
 ### Core artifact roles
 
 | File                    | Purpose                                                                                                                                                                                                                        |
@@ -310,13 +322,14 @@ Not all workflow modes require every artifact:
 
 ## `.oat/repo/` structure
 
-| Path                   | Purpose                                                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `.oat/repo/knowledge/` | Generated codebase knowledge indexes                                                     |
-| `.oat/repo/pjm/`       | Active operational PJM layer (`current-state.md`, `roadmap.md`, and `backlog/`)          |
-| `.oat/repo/reference/` | Durable append-mostly references, including file-per-record decisions under `decisions/` |
-| `.oat/repo/reviews/`   | Repo-scoped review artifacts (ad-hoc/non-project)                                        |
-| `.oat/repo/archive/`   | Archived repo-level artifacts                                                            |
+| Path                    | Purpose                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| `.oat/repo/knowledge/`  | Generated codebase knowledge indexes                                                     |
+| `.oat/repo/pjm/`        | Active operational PJM layer (`current-state.md`, `roadmap.md`, and `backlog/`)          |
+| `.oat/repo/pjm/remote/` | Portable backlog binding metadata and, only when approved, shared operational state      |
+| `.oat/repo/reference/`  | Durable append-mostly references, including file-per-record decisions under `decisions/` |
+| `.oat/repo/reviews/`    | Repo-scoped review artifacts (ad-hoc/non-project)                                        |
+| `.oat/repo/archive/`    | Archived repo-level artifacts                                                            |
 
 Canonical project-management repo-reference surface splits the active
 operational layer (`pjm/`) from durable references (`reference/`):

package/assets/docs/reference/troubleshooting.md

@@ -264,6 +264,50 @@ managed default itself:
 oat tools update --pack project-management --scope user
 ```
 
+## A remote PJM command is pending, uncertain, or blocked
+
+Read the JSON envelope before retrying:
+
+```bash
+oat pjm remote doctor --json
+```
+
+Before the first provider-contacting command, discover a matching live
+connector. If no capable connector exists, inspect an already configured
+provider CLI's live help. Construct only bounded provider-neutral capability
+evidence and supply it through `--capability-evidence-stdin`.
+
+- `pending` with `externalAction` means OAT durably prepared one exact semantic
+  host action. Confirm the previously selected capability remains granted,
+  execute that exact action at most once, then submit one bounded observation
+  through `oat pjm remote operation continue`.
+- `uncertain` means an effect may have occurred. Follow the envelope's recovery
+  instructions; never repeat a create or update blindly.
+- `needs-review` requires an explicit reconciliation choice.
+- `blocked` means policy, approval, capability, lifecycle state, or outbound
+  safety prevented the action. Do not bypass the gate or broaden the field
+  projection.
+
+Only an `ok` envelope after authoritative read-back is remote success. Native
+provider output, a zero process exit, or a visible remote change is not.
+
+## A clone or worktree has unexpected remote PJM state
+
+Linked worktrees share default local operational state through the Git common
+directory. If one worktree has a pending operation, inspect or continue it
+instead of starting a competing action elsewhere.
+
+Independent clones do not share that local store. In a fresh clone, use
+portable binding metadata plus `oat pjm remote refresh` through a matching live
+host capability before treating snapshots as current. Offline, doctor and
+migration remain available, but commands requiring remote freshness stay
+pending or blocked.
+
+If the repository opted into `.oat/repo/pjm/remote/state/` or
+`<project>/remote/state/`, remember that shared operational storage may contain
+remote planning content visible to repository readers. Promotion requires an
+exact persisted preview and fresh approval; local projects cannot use it.
+
 ## `--scope all` fails outside a Git repository
 
 It should not. `oat status --scope all` and `oat doctor --scope all` complete

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

@@ -31,6 +31,10 @@ Use this section when you want to choose the right OAT skill for a task. If you
   [Project Retrospectives](../projects/retro.md).
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Operate an explicit GitHub, Linear, or Jira planning-record binding through a
+  live host capability: `oat-pjm-remote`. The OAT CLI retains policy, preview,
+  approval, journal, and verification authority; the skill discovers and
+  invokes only the exact host action emitted for one durable operation.
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
 - Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
@@ -46,6 +50,34 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Capture or refine ideas: `oat-idea-new` (capture a new idea), `oat-idea-ideate` (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use `oat-brainstorm` for those), `oat-idea-scratchpad`, `oat-idea-summarize`
 - Run a project-independent brainstorming conversation: `oat-brainstorm` — entry point with an explicit activation contract. Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See [Tool Packs](../../cli-utilities/tool-packs.md) for the brainstorm pack details.
 
+## Remote host execution loop
+
+Use `oat-pjm-remote` only for an explicit remote lifecycle request. Its loop is
+deliberately narrow:
+
+1. Before the first provider-contacting command, inspect currently granted MCP
+   or connector descriptions for a semantic and exact-context match.
+2. If no capable connector is available, inspect an already configured
+   provider CLI's live help before the first attempt. Do not install a tool,
+   retain its dialect, or switch execution surfaces mid-attempt.
+3. Construct only bounded provider-neutral capability evidence and pass it to
+   the requested command with `--capability-evidence-stdin`. Treat the CLI's
+   policy, preview, approval, safety, and durable state as authoritative.
+4. When the CLI returns `pending` with `externalAction`, execute that exact
+   semantic action at most once and submit one bounded,
+   sanitized observation with `oat pjm remote operation continue`.
+5. Continue only when the CLI emits another exact action for the same durable
+   operation. Stop on its terminal envelope.
+
+The skill cannot broaden the normalized projection, bypass effective policy,
+binding clamps, purpose field grants, hard approval floors, or caller-owned
+authority evidence, read credential values, persist native provider data, or
+declare remote success. A connector result, process exit, or visible remote
+change is only evidence. Success requires an OAT `ok` envelope after
+authoritative read-back.
+See [Remote Project Management](../../cli-utilities/remote-project-management.md)
+for policy, storage, approval, and recovery details.
+
 ## If You Are Trying To...
 
 - choose the right skill for a task, stay in this guide page
@@ -122,6 +154,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-pjm-add-backlog-item`
     - `oat-pjm-update-repo-reference`
     - `oat-pjm-review-backlog`
+    - `oat-pjm-remote`
     - `docs-completed-projects-gap-review`
 
 === "Research"

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.64",
-  "docs-config": "0.2.64",
-  "docs-theme": "0.2.64",
-  "docs-transforms": "0.2.64"
+  "cli": "0.2.66",
+  "docs-config": "0.2.66",
+  "docs-theme": "0.2.66",
+  "docs-transforms": "0.2.66"
 }

package/assets/skills/analyze/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: analyze
-version: 0.2.0
 description: Multi-angle analysis of existing artifacts, codebases, documents, or systems. Examines what you have from six analysis angles and produces structured findings with prioritized recommendations.
 argument-hint: 'target [--context path]'
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+metadata:
+  version: 0.2.1
 ---
 
 # /analyze

package/assets/skills/authoring-docs/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: authoring-docs
-version: 1.0.0
 description: Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
+metadata:
+  version: 1.0.1
 ---
 
 # Authoring Docs

package/assets/skills/compare/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: compare
-version: 0.1.1
 description: Domain-aware comparative analysis with clear recommendations. Compares options across auto-detected or user-specified dimensions and produces a qualitative assessment with a clear winner.
 argument-hint: 'item1 item2 [item3...] [--save] [--context path] [--dimensions "dim1, dim2, ..."]'
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, WebSearch, WebFetch, AskUserQuestion, Agent, mcp__*
+metadata:
+  version: 0.1.2
 ---
 
 # /compare