@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -1,74 +0,0 @@
----
-title: CLI Utilities
-description: Standalone adoption lane for general OAT CLI surfaces outside provider sync, docs tooling, and tracked workflows.
----
-
-# CLI Utilities
-
-CLI Utilities is the OAT lane for the useful command surface that does not primarily belong to Provider Sync, Docs Tooling, or tracked workflow lifecycle execution.
-
-Use this section when you want bootstrap guidance, tool-pack lifecycle details, configuration help, and general-purpose command references. It covers general-purpose setup, configuration, pack-management, and diagnostic utilities that support the rest of the toolkit without being specific to provider sync, docs tooling, or tracked workflow execution.
-
-## Contents
-
-- [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`.
-- [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
-
-## What Lives Here
-
-This section collects the command groups that help you initialize OAT, manage installed packs, inspect local or config state, and use the wider CLI without implying that you are adopting provider sync or tracked workflows.
-
-Examples include:
-
-- bootstrap and setup flows such as `oat init`
-- bundled pack management through `oat tools`
-- general configuration guidance
-- workflow gate commands for per-skill final checks and cross-runtime review dispatch
-- utility command groups for config, local state, diagnostics, and related inspection flows
-- a guided health check, the `/oat-doctor` skill, that sweeps config, project management, agent instructions, docs, and installed tools, then explains and offers fixes for what it finds (described in [Config and Local State](config-and-local-state.md))
-
-## Who It's For
-
-- Users getting OAT set up in a repo
-- Teams managing installed tool packs and local config
-- People who need a general command map without diving into workflow lifecycle docs
-
-## When To Use This Section
-
-Use CLI Utilities when:
-
-- you are first setting up OAT in a repo
-- you need to install or update OAT packs
-- you are looking for configuration or local-state inspection help
-- you need the general CLI surface without committing to one of the deeper lanes yet
-
-## Start Here
-
-- 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
-
-- Bootstrap OAT in a repo with [CLI Bootstrap](bootstrap.md).
-- Manage installed packs in [Tool Packs](tool-packs.md).
-- Adjust settings in [Configuration](configuration.md).
-- Use [Config and Local State](config-and-local-state.md) for the utility command groups that support inspection and diagnostics.
-- Configure cross-runtime review gates in [Workflow Gates](workflow-gates.md).
-
-## Go Deeper
-
-- [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/meta.json

@@ -1,13 +0,0 @@
-{
-  "title": "CLI Utilities",
-  "pages": [
-    "bootstrap",
-    "tool-packs",
-    "configuration",
-    "remote-project-management",
-    "config-and-local-state",
-    "project-log",
-    "backlog-lifecycle",
-    "workflow-gates"
-  ]
-}

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

@@ -1,191 +0,0 @@
----
-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/guide/concepts.md

@@ -1,88 +0,0 @@
----
-title: Core Concepts
-description: Mental model for canonical assets, provider views, scopes, skills, and the optional workflow layer.
----
-
-# Core Concepts
-
-OAT combines a provider-sync layer, reusable skills and CLI tooling, and an optional workflow system. This page gives the high-level mental model so the detailed docs are easier to navigate.
-
-## Capability Stack
-
-```mermaid
-flowchart TD
-  BASE["Provider sync + CLI\ncanonical assets, status, sync, docs commands"] --> MIDDLE["Reusable skills + tooling\nideas, docs workflows, repo helpers"]
-  MIDDLE --> TOP["Optional workflow layer\ntracked projects, reviews, PR flow, HiLL"]
-```
-
-## Canonical Assets and Provider Views
-
-OAT keeps canonical assets in repo-controlled locations and projects provider-specific views from that source of truth. The canonical form is what you edit and review directly; provider views are synchronized outputs that let Claude Code, Cursor, Copilot, Gemini, and Codex consume the same intent in their native layouts.
-
-```mermaid
-flowchart LR
-  SKILLS[".agents/skills/"] --> OAT["oat sync"]
-  AGENTS[".agents/agents/"] --> OAT
-  RULES[".agents/rules/"] --> OAT
-  OAT --> CLAUDE[".claude/"]
-  OAT --> CURSOR[".cursor/"]
-  OAT --> COPILOT[".github/"]
-  OAT --> GEMINI[".gemini/"]
-  OAT --> CODEX[".codex/"]
-```
-
-Use these docs next:
-
-- [Provider Sync](../provider-sync/index.md)
-- [Reference](../reference/index.md)
-
-## Sync, Drift, and Adoption
-
-`oat sync` applies canonical content to provider views, while `oat status` reports whether a provider is in sync, drifted, or missing content. Drift is expected when provider-side files diverge from canonical content; OAT now also covers canonical rule sync and stray adoption so you can bring unmanaged files back under the canonical model deliberately.
-
-Use these docs next:
-
-- [Provider Sync Commands](../provider-sync/commands.md)
-- [Manifest and Drift](../provider-sync/manifest-and-drift.md)
-
-## Scopes
-
-Most OAT operations run in one of three scopes: `project`, `user`, or `all`. Project scope targets the current repository, user scope targets user-level installations, and `all` evaluates both. The same scope model appears across sync, status, and provider configuration commands, so it is worth learning early.
-
-Use these docs next:
-
-- [Scope and Surface](../provider-sync/scope-and-surface.md)
-- [CLI Reference](../reference/cli-reference.md)
-
-## Skills and CLI Commands
-
-Skills are structured workflow instructions stored in `.agents/skills`, while CLI commands provide direct operational entry points like `oat init`, `oat sync`, or `oat docs init`. Some capabilities are primarily CLI-driven, some are primarily skill-driven, and some combine both. As a rule: use the CLI for direct system actions and use skills when you want guided lifecycle execution.
-
-Use these docs next:
-
-- [Skills](../workflows/skills/index.md)
-- [Contributing Skills](../contributing/skills.md)
-
-## The Three Usage Modes
-
-OAT can be adopted in three layers:
-
-1. Provider sync and CLI interop only
-2. Provider-agnostic tooling and reusable skills
-3. Optional workflow/project lifecycle
-
-These layers stack. You can stay at the interop layer, use only the tooling layer, or adopt the full lifecycle when you need tracked discovery, planning, implementation, review, and PR flow.
-
-Use these docs next:
-
-- [Quickstart](../quickstart.md)
-- [Workflow & Projects](../workflows/projects/index.md)
-
-## Human-in-the-Loop Lifecycle
-
-The workflow system supports explicit checkpoints so a project can pause at selected moments for approval or direction. At the workflow level, HiLL gates control lifecycle routing across discovery, spec, design, plan, and implementation. During implementation, plan-phase checkpoints control where execution pauses between plan phases.
-
-Use these docs next:
-
-- [Workflow & Projects](../workflows/projects/index.md)
-- [Hill Checkpoints](../workflows/projects/hill-checkpoints.md)

package/assets/docs/guide/index.md

@@ -1,31 +0,0 @@
----
-title: User Guide
-description: User-facing guide for operating OAT across provider sync, docs tooling, workflow execution, skills, and ideas.
----
-
-# User Guide
-
-This page is now a compatibility router.
-
-The old catch-all User Guide is being split into clearer adoption lanes so new users can choose the part of OAT that matches what they actually need.
-
-## Contents
-
-- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
-
-## Status
-
-This guide bucket remains visible so older links have a stable landing page. New docs should go into the canonical top-level sections below instead of adding more pages under `guide/`.
-
-## Canonical Sections
-
-- [Provider Sync](../provider-sync/index.md) - Provider interoperability, drift, sync, and config behavior.
-- [Agentic Workflows](../workflows/index.md) - Tracked projects, ideas, workflow skills, and lifecycle execution.
-- [Docs Tooling](../docs-tooling/index.md) - Docs app setup, docs commands, and docs workflow entry points.
-- [CLI Utilities](../cli-utilities/index.md) - Bootstrap, tool packs, configuration, and general CLI surfaces.
-- [Reference](../reference/index.md) - Durable contracts and reference material.
-
-## Legacy Pages Still Under Guide
-
-- [Core Concepts](concepts.md) - High-level mental model while concept material is being redistributed.
-- This guide bucket is being retired. Use the canonical top-level sections above for active documentation.

package/assets/docs/guide/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "User Guide",
-  "pages": ["concepts"]
-}

package/assets/docs/quickstart.md

@@ -1,88 +0,0 @@
----
-title: Quickstart
-description: 'Start-here guide for choosing the right OAT adoption path.'
----
-
-# Quickstart
-
-Use this page to choose the OAT path that matches what you are actually trying to do.
-
-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
-
-Use this path when you want canonical skills, agents, and rules to stay aligned across provider surfaces such as Claude, Cursor, Copilot, Gemini, or Codex.
-
-Best fit:
-
-- you want cross-provider sync and drift checks
-- you care about canonical-to-provider asset management
-- you do not necessarily need tracked project workflows
-
-Continue here:
-
-- [Provider Sync](provider-sync/index.md)
-
-### Agentic Workflows
-
-Use this path when you want tracked, resumable implementation work with explicit lifecycle artifacts, reviews, and handoff-friendly state.
-
-Best fit:
-
-- you want structured project execution
-- you want lifecycle artifacts like `state.md`, `plan.md`, and `implementation.md`
-- you want a workflow layer on top of the base CLI/tooling
-
-Continue here:
-
-- [Agentic Workflows](workflows/index.md)
-
-### Docs Tooling
-
-Use this path when you are bootstrapping or maintaining a documentation surface with OAT.
-
-Best fit:
-
-- you need docs app setup or maintenance workflows
-- you care about docs navigation, docs commands, and docs-specific analysis/apply flows
-- you want the docs-system contract rather than the broader workflow layer
-
-Continue here:
-
-- [Docs Tooling](docs-tooling/index.md)
-
-### CLI Utilities
-
-Use this path when you want general OAT CLI help outside the dedicated provider-sync, workflows, and docs-tooling lanes.
-
-Best fit:
-
-- you want bootstrap/setup guidance
-- you want tool-pack, configuration, local-state, or utility command guidance
-- you want a general CLI surface map rather than one specific product lane
-
-Continue here:
-
-- [CLI Utilities](cli-utilities/index.md)
-
-## If You Are Unsure
-
-Start with the path that best matches the primary thing you need right now.
-
-- If you are trying to sync canonical assets across tools, choose Provider Sync.
-- If you are trying to run a tracked implementation workflow, choose Agentic Workflows.
-- If you are working on the docs system itself, choose Docs Tooling.
-- If you mainly need command-line setup or utility guidance, choose CLI Utilities.
-
-You can adopt more than one lane over time. OAT is designed so these sections can be used together or independently.