@open-agent-toolkit/cli 0.2.75 → 0.2.77

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.75"
+  "oatVersion": "0.2.77"
 }

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

@@ -124,7 +124,7 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config
-- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key
+- `oat config describe <key>` - show file location, scope, default, mutability, and owning command for one key; a deprecated key also prints a `Deprecated: prefer …` line, and `--json` carries it as a `deprecated` object with `supersededBy` (plus `legacyValues` when only a legacy value form is deprecated), which `oat-doctor` reads
 
 Use `oat config dump --json` when you need the whole resolved config in one machine-readable response rather than a single key or a human-oriented list view.
 
@@ -281,6 +281,6 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
 - `oat internal validate-oat-skills` - validate `oat-*` skill contracts and metadata
 - `oat doctor` - run environment and setup diagnostics, including installed-vs-bundled skill version checks
 
-`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync`, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
+`oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync` <!-- oat-doctor: allow-stale-invocation -->, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
 
-The `/oat-doctor` skill (installed via the core pack) provides richer diagnostics with check and summary modes, including config explanations sourced from bundled documentation.
+The `/oat-doctor` skill (installed via the core pack) goes further: it sweeps config, project management (PJM), agent instructions, docs, and installed tools read-only, prints one report grouped by area and severity, and then dives into any area you pick, teaching from the bundled documentation and the `oat config describe` entries and offering the exact fix command or the owning skill. It applies nothing except a single fix command you approve. Unattended (`OAT_NON_INTERACTIVE=1`), the report is the whole output; `--summary` keeps the installed-tools dashboard.

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

@@ -54,7 +54,9 @@ What each command is for:
 - `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, 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.
+- `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key. A deprecated key also prints `Deprecated: prefer <successor>`, and `--json` carries the same fact as a `deprecated` object (`supersededBy`, plus `note` and `legacyValues` where they apply).
+
+For a guided pass instead of individual commands, run the `/oat-doctor` skill (core pack). It sweeps every config surface read-only, flags stale `activeProject` / `lastPausedProject` pointers, keys set on the wrong surface, and deprecated values, then walks each key group you have not set: what it does, when you would want it, and which surface owns it. It offers the exact `oat config` command for each fix and runs one only after you approve it. See [Config and Local State](config-and-local-state.md#internal-helpers-and-diagnostics) for the other areas it covers.
 
 ### Source labels
 

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

@@ -31,6 +31,7 @@ Examples include:
 - 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
 

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

@@ -850,7 +850,7 @@ packs and is retained while either pack still owns it in that scope.
 
 The `core` pack contains foundational diagnostic and documentation skills:
 
-- **oat-doctor** — Setup diagnostics with two modes: check mode (terse `brew doctor`-style warnings with fix commands) and summary mode (full dashboard of installed packs, config values, and sync status).
+- **oat-doctor** — One read-only sweep over config, PJM, agent instructions, docs, and tools; a report grouped by area and severity; then a dive into any area on request that explains findings and unset settings from the bundled docs and offers the exact fix command or the owning skill (nothing is applied without approval). `--summary` keeps the installed-tools dashboard.
 - **oat-docs** — Interactive Q&A skill backed by locally-bundled OAT documentation at `~/.oat/docs/`.
 
 Key behavior:

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

@@ -62,7 +62,7 @@ Pack intent is stored per scope:
 Config discovery via CLI:
 
 - `oat config describe` lists the supported config surfaces and keys across `.oat/config.json`, `.oat/config.local.json`, `~/.oat/config.json`, `.oat/sync/config.json`, and `~/.oat/sync/config.json`.
-- `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key.
+- `oat config describe <key>` shows file location, scope, default, mutability, and the owning command for one key, and for a deprecated key its successor.
 - `oat config list` shows the currently resolved values for the repo-local/shared command surface.
 
 Config ownership note:

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

@@ -104,7 +104,7 @@ Current config ownership:
 CLI discovery surfaces:
 
 - `oat config describe` lists the supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config.
-- `oat config describe <key>` prints scope, file, default, mutability, owning command, and description for one config key.
+- `oat config describe <key>` prints scope, file, default, mutability, owning command, and description for one config key, plus a `Deprecated: prefer …` line when the key is deprecated.
 - `oat config list` prints the resolved values for the repo-scoped/local command surface.
 
 Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files may still be present in some environments but are no longer the canonical source in migrated command paths.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.75",
-  "docs-config": "0.2.75",
-  "docs-theme": "0.2.75",
-  "docs-transforms": "0.2.75"
+  "cli": "0.2.77",
+  "docs-config": "0.2.77",
+  "docs-theme": "0.2.77",
+  "docs-transforms": "0.2.77"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -4,7 +4,7 @@ description: Use when building destination-neutral visual explainer artifacts fr
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
 metadata:
-  version: 3.0.2
+  version: 3.0.3
 ---
 
 # Explainer Kit

package/assets/skills/explainer-kit/scripts/bundle.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import {
   lstat,
   mkdir,
@@ -20,8 +21,9 @@ import {
   isAbsolute,
   join,
   relative,
+  resolve,
 } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import {
   harvestNumericTokens,
@@ -704,7 +706,29 @@ function bundleError(message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runBundle(process.argv.slice(2)).catch((error) => {
     console.error(error.message);
     process.exitCode = 1;

package/assets/skills/explainer-kit/scripts/record.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { access, readFile, readdir, rename, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { validateContract } from './lib/contracts.mjs';
 import {
@@ -327,7 +328,29 @@ function recordError(code, message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runRecord(process.argv.slice(2)).catch((error) => {
     console.error(`${error.code}: ${error.message}`);
     process.exitCode = 1;

package/assets/skills/explainer-kit/scripts/verify.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { writeFailure } from './bundle.mjs';
 import {
@@ -640,7 +641,29 @@ function verifyError(code, message) {
   return error;
 }
 
-if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+/**
+ * Direct invocation, compared as canonical paths on both sides. Comparing a raw
+ * `process.argv[1]` against `import.meta.url` makes this script a silent no-op
+ * that exits 0 whenever the skill is reached through a symlinked install root,
+ * and canonicalizing only one side has the same effect under
+ * `--preserve-symlinks-main`, which keeps the link in `import.meta.url`.
+ * A path that cannot be canonicalized is not a module Node loaded as the entry
+ * point, so a thrown `realpathSync` means "not invoked directly" and returns
+ * `false`; it never masks a direct run.
+ */
+function isDirectInvocation(invokedPath) {
+  if (!invokedPath) return false;
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) ===
+      realpathSync(resolve(invokedPath))
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(process.argv[1])) {
   runVerify(process.argv.slice(2)).catch((error) => {
     console.error(`${error.code ?? 'verify-error'}: ${error.message}`);
     process.exitCode = 1;