@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-docs-apply/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: oat-docs-apply
+version: 1.2.0
+description: Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
+---
+
+# Docs Apply
+
+Generate or update documentation files from a docs analysis artifact, with explicit approval and branch-based workflow.
+
+## Prerequisites
+
+- A recent docs analysis artifact in `.oat/repo/analysis/`.
+- If no analysis exists, run `oat-docs-analyze` first.
+- `jq` available in PATH for tracking updates.
+- `gh` available if a PR should be opened automatically.
+
+## Mode Assertion
+
+**OAT MODE: Docs Apply**
+
+**Purpose:** Apply approved documentation changes derived from a docs analysis artifact.
+
+**BLOCKED Activities:**
+
+- No unapproved documentation changes.
+- No branch creation before the recommendation plan is reviewed.
+- No changes outside the documentation scope except deterministic nav sync and tracking updates.
+
+**ALLOWED Activities:**
+
+- Reading analysis artifacts and the current docs surface.
+- Creating or updating docs files and `mkdocs.yml` when approved.
+- Running `oat docs nav sync` after approved structural changes.
+- Creating branches, commits, and optional PRs.
+
+## Analyze vs Apply Boundary
+
+Treat the docs analysis artifact as the source of truth for what should be changed and why.
+
+Apply may:
+
+- read the exact evidence sources cited by the artifact
+- verify that cited files still exist
+- translate approved recommendations into concrete docs changes
+
+Apply must **not**:
+
+- invent unsupported docs conventions
+- infer structure or migration rules from defaults or a tiny sample
+- create new recommendations that are not present in the artifact
+- silently fill in missing evidence gaps
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Editing docs outside approved recommendations -> STOP and remove the extra change from the work plan.
+- Applying manual nav changes when `oat docs nav sync` should be used -> STOP and switch to the CLI helper.
+
+**Recovery:**
+
+1. Return to the approved recommendation list.
+2. Re-apply only approved docs changes and deterministic nav sync.
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can tell what’s happening.
+
+- Print a phase banner once at start:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ DOCS APPLY
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Use step indicators:
+  - `[1/7] Loading analysis artifact…`
+  - `[2/7] Building recommendation plan…`
+  - `[3/7] Reviewing approvals…`
+  - `[4/7] Creating branch…`
+  - `[5/7] Applying docs changes…`
+  - `[6/7] Running nav sync + verification…`
+  - `[7/7] Committing, tracking, and summary…`
+
+## Process
+
+### Step 0: Intake - Find Analysis Artifact
+
+Locate the most recent docs analysis artifact:
+
+```bash
+ls -t .oat/repo/analysis/docs-*.md 2>/dev/null | head -1
+```
+
+If none exists, stop and instruct the user to run `oat-docs-analyze`.
+
+Validate that each recommendation in the artifact includes:
+
+- evidence
+- confidence
+- disclosure
+- link targets when disclosure is `link_only`
+
+If the artifact is missing that detail, stop and tell the user to re-run `oat-docs-analyze`.
+
+### Step 1: Build the Recommendation Plan
+
+Read the analysis artifact and build the plan from its recommendations.
+Do not rediscover conventions from scratch during this step.
+
+Common docs actions:
+
+- Create missing `index.md`
+- Add or repair `## Contents`
+- Convert `overview.md` usage to the `index.md` contract
+- Add or update `docs/contributing.md` plugin guidance
+- Scaffold an OAT docs app when no docs app exists
+- Run `oat docs nav sync` after approved structural changes
+
+Carry forward the artifact's evidence refs, confidence, disclosure mode, and link targets into the apply plan.
+
+Coverage-gap recommendations may also be:
+
+- `omit`
+- `ask_user`
+
+If evidence is missing, stale, or contradicts the current docs tree, stop and ask for a fresh analysis instead of guessing.
+
+Use `references/apply-plan-template.md` and preserve the exact presented markdown as `APPLY_PLAN_MARKDOWN` for commit/PR summary use.
+
+### Step 2: Review the Plan with the User
+
+Present the full recommendation plan first, then ask which review mode they want:
+
+- `apply all`
+- `apply interactively`
+- `discuss`
+
+For review-mode and follow-up decisions, use host-aware prompting:
+
+- Claude Code: `AskUserQuestion`
+- Codex: structured user-input tooling when available in the current host/runtime
+- Fallback: plain-text questions
+
+If the user chooses `apply all`:
+
+- confirm the full plan
+- capture any global notes that apply across the whole plan
+- treat all non-blocked recommendations as approved unless the user names exceptions
+
+If the user chooses `apply interactively`, ask for each recommendation:
+
+- `approve`
+- `modify`
+- `skip`
+
+If the user chooses `discuss`, answer questions, revise the plan if needed, and then ask again:
+
+- `apply all`
+- `apply interactively`
+- `discuss`
+
+If all recommendations are skipped, stop without changing files.
+
+Build an `APPLIED_PLAN_DETAILS` block from approved or modified recommendations with:
+
+- recommendation id
+- action
+- target path
+- disclosure
+- evidence refs
+- decision (`approved_via_apply_all` / `approved` / `modified`)
+- user notes
+
+### Step 3: Create Branch
+
+After approvals:
+
+```bash
+TIMESTAMP=$(date -u +"%Y-%m-%d-%H%M")
+BRANCH="oat/docs-${TIMESTAMP}"
+git checkout -b "$BRANCH"
+```
+
+If branch creation fails because of unrelated local changes, ask the user to resolve that state before continuing.
+
+### Step 4: Apply Approved Changes
+
+For each approved recommendation:
+
+1. Read only the affected docs files and the evidence sources cited by the artifact.
+2. Make targeted edits that satisfy the approved fix.
+3. Preserve existing prose and only change the necessary sections.
+4. Honor the disclosure mode from the artifact:
+   - `inline` -> keep the essential guidance in the target page
+   - `link_only` -> add a concise pointer to the canonical doc/config/example
+   - `omit` -> do not encode the item in the docs change
+   - `ask_user` -> require explicit user confirmation before writing
+
+When approved actions involve docs app creation or nav updates:
+
+- Use `oat docs init` for scaffolding when appropriate.
+- Use `oat docs nav sync` instead of manually editing nav when the CLI helper can generate it.
+
+Negative rules:
+
+- Do not invent docs structure rules, migration rules, or plugin guidance not backed by the artifact's cited evidence.
+- Do not inline large setup/config details when the artifact says `link_only`.
+- Do not create replacement link targets if the artifact omitted them; stop and ask for a fresh analysis or user guidance.
+- If a cited source no longer exists, stop that recommendation and ask for a fresh analysis or user guidance.
+
+### Step 5: Verify and Sync Navigation
+
+Run the smallest relevant verification set based on what changed:
+
+- `oat docs nav sync`
+- `pnpm --dir <docs-app> docs:lint` (no-op when no linter is configured)
+- `pnpm --dir <docs-app> docs:format:check`
+- `pnpm --dir <docs-app> docs:build`
+
+If no docs app exists yet, use file-level verification and confirm the structural contract manually in the summary.
+
+### Step 6: Commit and PR
+
+Commit the approved changes:
+
+```bash
+git add {approved-files}
+git commit -m "docs: apply approved docs recommendations"
+```
+
+**Offer to open a PR:**
+
+After committing, proactively ask the user if they'd like to open a pull request. Frame this as the recommended next step:
+
+```
+Changes committed. Would you like me to push and open a pull request?
+The PR will include the applied plan summary and the full analysis artifact for reference.
+```
+
+For the PR-choice prompt, use host-aware prompting:
+
+- Claude Code: `AskUserQuestion`
+- Codex: structured user-input tooling when available in the current host/runtime
+- Fallback: plain-text questions
+
+**If creating PR:**
+
+1. Push the branch.
+2. Create a PR with the structure below.
+3. The PR body must include the full analysis artifact in a collapsible section at the bottom so reviewers can see the evidence behind every change.
+
+```bash
+git push -u origin "$(git rev-parse --abbrev-ref HEAD)"
+gh pr create --base main \
+  --title "docs: apply approved docs recommendations" \
+  --body "$(cat <<'PRBODY'
+## Summary
+
+- Applied docs recommendations from analysis artifact
+- Source: {analysis-artifact-path}
+- Result: {N} created, {N} updated, {N} skipped
+
+## Applied Plan
+
+{APPLY_PLAN_MARKDOWN}
+
+## Verification
+
+- {commands run and results}
+
+---
+
+## Full Analysis Artifact
+
+The complete analysis that produced these recommendations is included below for reviewer reference.
+
+<details>
+<summary>Click to expand full analysis</summary>
+
+{full contents of the analysis artifact markdown file}
+
+</details>
+PRBODY
+)"
+```
+
+**If `gh` is not available or fails:**
+
+```
+PR creation failed. To create manually:
+1. Push: git push -u origin {branch}
+2. Open PR at your repository's web interface
+3. Use the structure above in the PR body, including the full analysis in a collapsible section
+```
+
+### Step 7: Update Tracking and Output Summary
+
+Update shared tracking:
+
+```bash
+TRACKING_SCRIPT=".oat/scripts/resolve-tracking.sh"
+ROOT_TARGET=$(bash "$TRACKING_SCRIPT" root)
+ROOT_HASH=$(echo "$ROOT_TARGET" | jq -r '.commitHash')
+ROOT_BRANCH=$(echo "$ROOT_TARGET" | jq -r '.baseBranch')
+
+bash "$TRACKING_SCRIPT" write \
+  docsApply \
+  "$ROOT_HASH" \
+  "$ROOT_BRANCH" \
+  "apply"
+```
+
+Output:
+
+```text
+Apply complete.
+
+  Files created:   {N}
+  Files updated:   {N}
+  Files skipped:   {N}
+  Docs target:     {path}
+  Verification:    {commands run}
+
+Next step: Re-run oat-docs-analyze if you want a post-apply verification artifact.
+```
+
+## Deferred from v1
+
+- Automatic content synthesis for missing topic pages
+- Multi-docs-app fanout in one apply session
+- Bulk conversion of legacy docs trees without user review
+
+## References
+
+- Apply plan template: `references/apply-plan-template.md`
+- Shared tracking helper: `.oat/scripts/resolve-tracking.sh`

package/assets/skills/oat-docs-apply/references/apply-plan-template.md

@@ -0,0 +1,69 @@
+---
+oat_generated: true
+oat_generated_at: { YYYY-MM-DD }
+oat_apply_type: docs
+oat_source_analysis: { analysis-artifact-path }
+oat_docs_target: { docs-target-path }
+---
+
+# Docs Apply Plan
+
+**Date:** {YYYY-MM-DD}
+**Source Analysis:** `{analysis-artifact-path}`
+**Docs Target:** `{docs-target-path}`
+
+## Instructions
+
+Review the full recommendation set first, then choose a review mode:
+
+- **apply all** — approve the full set as presented
+- **apply interactively** — review recommendation by recommendation
+- **discuss** — pause to talk through the plan before approving
+
+Recommendations should already carry evidence, confidence, disclosure guidance, and link
+targets when `link_only` is used. If a recommendation lacks that detail, it should be
+blocked pending a fresh analysis rather than guessed.
+
+## Review Mode
+
+**Selected Mode:** {apply all / apply interactively / discuss / pending}
+
+**Global Notes:** {Any notes that apply to the whole plan, or "None"}
+
+## Recommendations
+
+### {N}. {Action}: `{target-path}`
+
+| Field        | Value                                                             |
+| ------------ | ----------------------------------------------------------------- |
+| Action       | {create / update / move / scaffold / sync-nav}                    |
+| Target       | `{target-path}`                                                   |
+| Rationale    | {why this recommendation exists}                                  |
+| Source       | {finding # / contract gap / nav issue}                            |
+| Evidence     | {exact file refs / config / docs that justify the recommendation} |
+| Confidence   | {high / medium / low}                                             |
+| Disclosure   | {inline / link_only / omit / ask_user}                            |
+| Link Targets | {path or URL when link_only; otherwise N/A}                       |
+| Helper       | `oat docs nav sync` / `oat docs init` / `manual edit`             |
+
+**Context:** {1-2 sentences}
+
+**Decision:** {approve / modify / skip | deferred until interactive review}
+**Notes:** {user notes if modifying}
+
+---
+
+{Repeat for each recommendation}
+
+## Summary of Actions
+
+| #   | Action                                 | Target   | Disclosure                       | Decision                                                 |
+| --- | -------------------------------------- | -------- | -------------------------------- | -------------------------------------------------------- |
+| {N} | {create/update/move/scaffold/sync-nav} | `{path}` | {inline/link_only/omit/ask_user} | {approved_via_apply_all/approved/modified/skip/deferred} |
+| ... |                                        |          |                                  |                                                          |
+
+**Total:** {N} approved, {N} modified, {N} skipped
+
+## Proceed?
+
+Confirm to begin applying the approved documentation changes.

package/assets/skills/oat-doctor/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: oat-doctor
+version: 1.0.0
+description: Use when you need to diagnose your OAT setup, check for outdated skills, identify misconfigurations, or get a summary of installed tools and config. Runs health checks and recommends corrective actions.
+argument-hint: '[--summary]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+---
+
+# OAT Doctor
+
+Diagnose your OAT setup at both project and user levels. Checks for skill updates, identifies misconfigurations, summarizes what's installed, and recommends corrective actions.
+
+## Prerequisites
+
+- OAT CLI installed and available as `oat` in PATH.
+- At least one `oat init` has been run (project or user level).
+
+## Mode Assertion
+
+**OAT MODE: Doctor (Diagnostic)**
+
+**Purpose:** Inspect OAT setup and report findings with actionable fix commands. Never modify files or configuration.
+
+**BLOCKED Activities:**
+
+- No editing configuration files, skills, or templates.
+- No running `oat init`, `oat sync`, `oat tools update`, or any mutating commands.
+- No creating, modifying, or deleting any files.
+
+**ALLOWED Activities:**
+
+- Running `oat` CLI commands with `--json` flag for read-only data gathering.
+- Reading files to inspect configuration state.
+- Reading `~/.oat/docs/` for config key explanations.
+- Presenting diagnostic findings and recommendations to the user.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- About to run a mutating command → STOP and present it as a recommendation instead.
+- Editing a file to fix a problem → STOP and tell the user the fix command.
+
+**Recovery:**
+
+1. Return to read-only diagnostic mode.
+2. Present the needed fix as an actionable recommendation.
+
+## Progress Indicators (User-Facing)
+
+Print a phase banner once at start:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ DOCTOR
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Check Mode (default)
+
+- `[1/4] Gathering installed tools…`
+- `[2/4] Checking for outdated skills…`
+- `[3/4] Inspecting configuration…`
+- `[4/4] Reporting findings…`
+
+### Summary Mode (`--summary`)
+
+- `[1/6] Gathering installed tools…`
+- `[2/6] Checking for outdated skills…`
+- `[3/6] Inspecting configuration…`
+- `[4/6] Discovering available packs…`
+- `[5/6] Checking sync status…`
+- `[6/6] Building dashboard…`
+
+## Process
+
+### Step 0: Determine Mode
+
+Read `$ARGUMENTS`:
+
+- If `$ARGUMENTS` contains `--summary` → **summary mode**
+- Otherwise → **check mode** (default)
+
+### Step 1: Gather Installed Tools
+
+```bash
+TOOLS_JSON=$(oat tools list --json --scope all 2>/dev/null || echo '{"tools":[]}')
+```
+
+Parse the JSON output. Each tool has: `name`, `type` (skill/agent), `scope` (project/user), `version`, `bundledVersion`, `pack` (core/docs/ideas/workflows/utility/project-management/research/custom), `status` (current/outdated/newer/not-bundled).
+
+### Step 2: Check for Outdated Skills
+
+```bash
+OUTDATED_JSON=$(oat tools outdated --json --scope all 2>/dev/null || echo '{"tools":[]}')
+```
+
+Parse the JSON output. Each entry has `name`, `version` (installed), `bundledVersion` (available), `pack`, `scope`.
+
+### Step 3: Inspect Configuration
+
+```bash
+CONFIG_JSON=$(oat config list --json 2>/dev/null || echo '{"configs":[]}')
+```
+
+Check for issues:
+
+- **Stale `activeProject` pointer:** If `activeProject` is set, verify the directory exists. If not, warn.
+- **Stale `activeIdea` pointer:** If `activeIdea` is set, verify the directory exists. If not, warn.
+- **Missing `projects.root`:** If not configured and no default exists, warn.
+
+For config key explanations, read from the bundled docs at `~/.oat/docs/`. Check `reference/file-locations.md` and `guide/cli-reference.md` for authoritative descriptions.
+
+### Step 4: Check Mode — Report Findings
+
+If in **check mode**, output a terse, `brew doctor`-style checklist.
+
+**Format:**
+
+```
+Your OAT setup has {N} warning(s).
+
+⚠  {N} outdated skill(s)
+   Run: oat tools update --scope {scope}
+
+⚠  Stale activeProject pointer: {path} does not exist
+   Run: oat config set activeProject ""
+
+⚠  Stale activeIdea pointer: {path} does not exist
+   Run: oat config set activeIdea ""
+
+⚠  {pack} pack not installed at {scope} scope
+   Run: oat init tools
+```
+
+If no warnings:
+
+```
+Your OAT setup looks good. No issues found.
+```
+
+Stop here for check mode.
+
+### Step 5: Summary Mode — Discover Available Packs
+
+For summary mode, compare installed skills against the full manifest to identify available-but-uninstalled packs and skills.
+
+**Bundled skill manifest (source of truth):**
+
+Core pack skills:
+
+- oat-docs, oat-doctor
+
+Workflow pack skills:
+
+- oat-project-capture, oat-project-clear-active, oat-project-complete
+- oat-project-design, oat-project-discover, oat-project-document
+- oat-project-implement, oat-project-import-plan, oat-project-new
+- oat-project-open, oat-project-plan, oat-project-plan-writing
+- oat-project-pr-final, oat-project-pr-progress, oat-project-progress
+- oat-project-promote-spec-driven, oat-project-quick-start
+- oat-project-reconcile, oat-project-revise, oat-project-review-provide
+- oat-project-review-receive, oat-project-review-receive-remote
+- oat-project-spec, oat-project-subagent-implement, oat-project-summary
+- oat-repo-knowledge-index, oat-worktree-bootstrap, oat-worktree-bootstrap-auto
+
+Ideas pack skills:
+
+- oat-idea-new, oat-idea-ideate, oat-idea-summarize, oat-idea-scratchpad
+
+Docs pack skills:
+
+- oat-agent-instructions-analyze, oat-agent-instructions-apply
+- oat-docs-analyze, oat-docs-apply
+
+Utility pack skills:
+
+- create-agnostic-skill
+- oat-repo-maintainability-review, oat-review-provide
+- oat-review-receive, oat-review-receive-remote
+
+Project management pack skills:
+
+- oat-pjm-add-backlog-item, oat-pjm-update-repo-reference
+- oat-pjm-review-backlog
+
+Research pack skills:
+
+- analyze, compare, deep-research
+- skeptic, synthesize
+
+For each pack, determine:
+
+- **Installed:** all pack skills found in installed tools list
+- **Partially installed:** some but not all pack skills found
+- **Not installed:** no pack skills found
+- **Missing skills:** specific skills in the manifest but not in installed list (highlights newly-added skills after CLI upgrades)
+
+### Step 6: Summary Mode — Check Sync Status
+
+If in a project directory (`.oat/` exists):
+
+```bash
+SYNC_STATUS=$(oat sync --dry-run --json --scope project 2>/dev/null || echo '{}')
+```
+
+Report whether provider views are in sync or have pending changes.
+
+### Step 7: Summary Mode — Build Dashboard
+
+Output a full dashboard:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ DOCTOR SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Installed Packs
+
+| Pack      | Scope   | Skills | Status   |
+| --------- | ------- | ------ | -------- |
+| core      | user    | 2/2    | current  |
+| docs      | project | 4/4    | current  |
+| workflows | project | 26/26  | current  |
+| ideas     | user    | 4/4    | current  |
+| project-management | project | 3/3 | current |
+| research  | project | 5/5    | current  |
+| utility   | project | 5/5    | outdated |
+
+## Outdated Skills
+
+| Skill                   | Installed | Available | Scope   |
+| ----------------------- | --------- | --------- | ------- |
+| oat-project-implement   | 1.1.0     | 1.2.0     | project |
+
+## Available But Not Installed
+
+- **docs** pack: oat-docs-analyze, oat-docs-apply, oat-agent-instructions-analyze, oat-agent-instructions-apply (4 skills available)
+  → Run: oat tools install docs --scope {scope}
+- **project-management** pack: oat-pjm-add-backlog-item, oat-pjm-update-repo-reference, oat-pjm-review-backlog (3 skills available)
+  → Run: oat tools install project-management --scope {scope}
+- **research** pack: analyze, compare, deep-research, skeptic, synthesize (5 skills available)
+  → Run: oat tools install research --scope {scope}
+
+## Configuration
+
+| Key                  | Value                     | Source  |
+| -------------------- | ------------------------- | ------- |
+| activeProject        | .oat/projects/shared/foo  | local   |
+| activeIdea           | (not set)                 | -       |
+| projects.root        | .oat/projects/shared      | default |
+| documentation.root   | (not set)                 | -       |
+| worktrees.root       | (not set)                 | -       |
+
+### Config Key Explanations
+
+Read config key descriptions from `~/.oat/docs/reference/file-locations.md` and `~/.oat/docs/guide/cli-reference.md`. If docs are not available, use these fallback descriptions:
+
+- **activeProject:** Path to the currently active OAT project. Set automatically by project skills.
+- **activeIdea:** Path to the currently active idea. Set by oat-idea-new.
+- **lastPausedProject:** Path to the last paused project for quick resume.
+- **projects.root:** Base directory for all OAT projects. Default: `.oat/projects/shared`.
+- **documentation.root:** Root directory for documentation. Used by docs skills.
+- **documentation.config:** Path to docs config file (e.g., mkdocs.yml).
+- **documentation.tooling:** Docs tooling in use (e.g., mkdocs, fumadocs).
+- **documentation.requireForProjectCompletion:** Whether docs update is required before project completion.
+- **autoReviewAtCheckpoints:** When true, completing a plan phase checkpoint auto-triggers a subagent code review. Default false. Can be overridden per-project via `oat_auto_review_at_checkpoints` in plan.md frontmatter.
+- **worktrees.root:** Base directory for git worktrees. Used by worktree-bootstrap skills.
+
+## Sync Status
+
+{In sync / N pending changes across M providers}
+
+## Warnings
+
+{Same warnings as check mode, if any}
+
+## Recommendations
+
+- Run `oat tools update` to update outdated skills.
+- Run `oat init tools` to install newly available packs.
+- Run `oat sync --scope project` to sync provider views.
+```
+
+Adapt the dashboard to show only sections with relevant data. Omit empty sections.
+
+## Success Criteria
+
+- ✅ Check mode reports all warnings with actionable fix commands.
+- ✅ Summary mode shows a complete dashboard of installed packs, config, and available skills.
+- ✅ Outdated skills are detected and update commands are provided.
+- ✅ Stale config pointers are identified.
+- ✅ Available-but-uninstalled packs/skills are surfaced (discovery gap closed).
+- ✅ No files are modified — purely diagnostic output.