@skillcap/gdh 0.15.0 → 0.16.0

package/INSTALL-BUNDLE.json

@@ -1,5 +1,5 @@
 {
   "product": "GDH",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "installMode": "packaged_install"
 }

package/README.md

@@ -1,131 +1,60 @@
 # GDH
 
-> Godot authoring and validation harness for AI agents
+[![npm version](https://img.shields.io/npm/v/@skillcap/gdh.svg)](https://www.npmjs.com/package/@skillcap/gdh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-[![npm](https://img.shields.io/npm/v/@skillcap/gdh)](https://www.npmjs.com/package/@skillcap/gdh)
-[![license](https://img.shields.io/github/license/Skillcap-Studio/gdh)](LICENSE)
+GDH helps AI coding agents work inside Godot projects without guessing the project shape, commands, runtime setup, or validation evidence.
 
-GDH detects your Godot project, configures your AI agents, and gives them the context they need to author, validate, and verify Godot work with real evidence instead of guesswork.
-
-![GDH setup demo](demo.gif)
+## Quick Start
 
-## Install
+Run this from the Godot project or repo you want GDH to manage:
 
 ```sh
-npx -y @skillcap/gdh@0.15.0 setup
+npx -y @skillcap/gdh@latest setup
 ```
 
-Replace `0.15.0` with the GDH version you want to pin this project to. `gdh setup` records the pinned version in `.gdh/project.yaml`; every managed surface generated from that config invokes GDH at that exact pinned version, so future sessions stay reproducible.
-
-From `0.9.0` onward, the shipped package also carries bounded release-span update metadata in `RELEASE-SPAN-UPDATE-CONTRACTS.json` so update flows can explain release-specific migration steps without reading repo-only `docs/releases/` files at target runtime.
-
-The current update flow is preview-first and sequential on apply: `gdh self-update --dry-run` emits machine-readable release-span preview data, and approved apply runs one ordered update -> migrate -> validate path. Apply now ends in an explicit terminal class: `healthy`, `follow_up_required`, `manual_review_required`, or `blocked`.
-
-Automatic backup and patch reapply for customized managed surfaces are not shipped yet; that preservation work remains future backlog, not part of the current update contract.
-
-The full install and update contract lives in [install-and-update.md](docs/development/install-and-update.md).
-
-## Requirements
-
-- **Node.js** ≥ 20 (per `package.json` engines)
-- **Godot** 4.4 through 4.6 stable — see [runtime-support-matrix.md](docs/development/runtime-support-matrix.md) for the full bounded support contract
-- **Host OS** macOS for the currently supported development environment
-- **Yarn 4** via `corepack` (required only for contributors working on the GDH implementation repo itself; end users invoking `npx @skillcap/gdh` do not need Yarn)
-
-## Quick Start
-
-```sh
-# 1. Run setup in your Godot project
-npx -y @skillcap/gdh@0.15.0 setup
+Then open your agent in that project and run:
 
-# 2. Open your AI agent (Claude, Cursor, Codex) in the repo
-
-# 3. Run the onboarding handoff
+```text
 /gdh-onboard
 ```
 
-That's it. GDH handles detection, scaffolding, and agent configuration. The agent takes over from `/gdh-onboard`.
-
-## What GDH Does
-
-### Detects your Godot target
-
-Finds the Godot project inside your repo or monorepo automatically. Handles nested targets, worktrees, and non-obvious layouts.
-
-### Configures your AI agents
-
-Scaffolds a minimal `.gdh/` surface and wires up agent-specific guidance so Claude, Cursor, and Codex know how to work with your project from the first session — all pinned to one canonical guidance chain.
-
-### Searches Godot docs with version awareness
+GDH writes the project guidance, command surfaces, MCP config, and local state that supported agents use for future work. Setup records the resolved GDH version in the target project so later updates can migrate that project deliberately.
 
-Fetches and searches official Godot documentation through CLI and MCP surfaces, pinned to your project's engine version. Bounded machine-local cache, explicit provenance.
-
-### Validates with evidence
-
-Runs authoring and runtime checks through inspectable surfaces. Agents get structured results they can reason about, not just pass/fail.
-The current line also ships one Docker-backed rendered runtime provider for compatible run configurations, plus bounded screenshot artifacts on rendered-capable paths when verification asks for them.
-
-### Signals completion with evidence
-
-Evidence-backed "done" decisions replace confidence-based guessing. Run records capture what happened; verification scenarios define what must be true.
-
-### What GDH does not do
-
-GDH is not a general project planner, PR/release orchestrator, or generic codebase knowledge system. It does not manage non-Godot runtimes. Use it for Godot-specific authoring, validation, worktree/import handling, and evidence-backed done decisions — and hand the rest to tools built for those jobs.
-
-## Core Concepts
-
-| Concept | What it is |
-|---------|-----------|
-| **Target** | The Godot project root or subproject GDH operates on |
-| **Run configuration** | How GDH launches a target |
-| **Verification scenario** | What GDH verifies once a target is running |
-| **Run record** | Structured evidence from one execution or verification run |
-
-## Daily Usage
-
-Normal usage happens through your AI agent, not by memorizing CLI commands.
-
-1. Open your agent in the repo
-2. The agent uses GDH surfaces to check readiness, pick validation, run checks
-3. You intervene only for narrow decisions or missing environment input
-
-The CLI exists for advanced operators, debugging, and automation. Update preview now uses a structured `preview` payload instead of changelog scraping, and update apply surfaces exact terminal follow-up data in `migration` + `terminal`. See [Advanced CLI Usage](docs/development/advanced-cli-usage.md).
-
-## Documentation
-
-- [Install and Update](docs/development/install-and-update.md) — alternative install modes, updating
-- [Advanced CLI Usage](docs/development/advanced-cli-usage.md) — raw CLI reference
-- [Runtime Support Matrix](docs/development/runtime-support-matrix.md) — what's supported today
-- [Runtime Release Readiness](docs/development/runtime-release-readiness.md) — current release stage
-
-## Status
-
-GDH now ships the current `0.15.0` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.15.0` at the `broader_internal_release` stage.
-That line includes one first-class Docker-backed rendered runtime provider and bounded screenshot evidence on rendered-capable paths.
-
-The release-stage label applies only to the documented support window in [runtime-support-matrix.md](docs/development/runtime-support-matrix.md) and [runtime-release-readiness.md](docs/development/runtime-release-readiness.md). It is not a blanket claim that every Godot project shape is supported or that this implementation checkout should behave like a GDH-managed target repo.
+## Requirements
 
-This repository is the GDH implementation repo. Treat `gdh setup`, `gdh status`, and `/gdh-onboard` here as product smoke-check paths, not as the primary way to learn the state of GDH itself — authoritative product truth lives in the source, tests, release artifacts, and `.planning/` surfaces in this checkout.
+- Node.js 20 or newer.
+- A local Godot project, currently focused on Godot 4.4 through 4.6.
+- A supported AI coding agent: Codex, Claude, or Cursor.
+- Optional: `GDH_GODOT_EDITOR_BIN` for Godot import refresh or direct local runtime checks.
+- Optional: Docker for the Docker-backed rendered runtime path.
 
-### Support
+## What It Does
 
-- **Issues:** [github.com/Skillcap-Studio/gdh/issues](https://github.com/Skillcap-Studio/gdh/issues) — reproducible bugs, concrete feature requests, documentation problems
-- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and commit policy
+- Finds Godot project roots and writes `.gdh/project.yaml` plus `.gdh-state/` derived state.
+- Installs agent commands and skills such as `/gdh-status`, `/gdh-prepare`, `/gdh-check`, `/gdh-verify`, `/gdh-migrate`, and `/gdh-update`.
+- Exposes MCP tools for project status, authoring checks, docs lookup, runtime bridge operations, and verification.
+- Keeps generated target-project files inside the managed project, not in GDH's own implementation repo.
 
-This repo does not currently promise a dedicated public support channel for project-specific troubleshooting; keep issues focused and reproducible.
+## Common Commands
 
-## Development
+```sh
+npx -y @skillcap/gdh@latest setup
+gdh status
+gdh target prepare --dry-run
+gdh authoring check
+gdh verify recommend --since main
+gdh self-update --dry-run --target .
+```
 
-If you are working on the GDH implementation repo itself, use these contributor surfaces instead of treating this checkout as a freshly managed target:
+## More Docs
 
-- [docs/development/install-and-update.md](docs/development/install-and-update.md)
-- [docs/development/release-workflow.md](docs/development/release-workflow.md)
-- [docs/development/conventions.md](docs/development/conventions.md)
-- [docs/development/open-source-maintainer-contract.md](docs/development/open-source-maintainer-contract.md)
-- [fixtures/README.md](fixtures/README.md)
+- [Install and update](./docs/development/install-and-update.md)
+- [Advanced CLI usage](./docs/development/advanced-cli-usage.md)
+- [Runtime support matrix](./docs/development/runtime-support-matrix.md)
+- [Runtime release readiness](./docs/development/runtime-release-readiness.md)
+- [All docs](./docs/README.md)
 
-When cutting a GDH release in this repo with Claude, Codex, or Cursor, use `/gdh-release` so the agent loads the canonical release guidance and runs `corepack yarn check:public-release` before `release:apply`. Use `/gdh-migration-verify` for the dedicated migration-proof step before the final release gate. Use `/gdh-publish` only when you explicitly want an already-cut release published to npm.
+## License
 
-Release history lives in the generated root [CHANGELOG.md](CHANGELOG.md); curated release notes live under [docs/releases/](docs/releases/README.md).
-Each live release line also carries a machine-readable update contract in [docs/releases/migrations/](docs/releases/migrations/README.md), which is compiled into the packaged `RELEASE-SPAN-UPDATE-CONTRACTS.json` asset for runtime update guidance.
+MIT

package/RELEASE-SPAN-UPDATE-CONTRACTS.json

@@ -1091,6 +1091,184 @@
           }
         ]
       }
+    },
+    {
+      "version": "0.15.1",
+      "releaseTag": "v0.15.1",
+      "migrationStatus": "required",
+      "summary": "v0.15.1 fixes rendered bridge screenshot orientation and changes update follow-through so auto-applicable runtime bridge repair is agent-owned work instead of a user review gate. The release changes GDH_RUNTIME_BRIDGE_SURFACE_VERSION (5 -> 6), so bridge-enabled managed targets need release-specific bridge repair and plugin/autoload follow-through when required.",
+      "releaseHighlights": {
+        "summary": "v0.15.1 fixes the active bridge screenshot path shipped in v0.15.0. On-demand and startup-triggered rendered screenshots now save with the expected vertical orientation, and update/migration follow-through treats auto-applicable bridge repair as agent-owned work instead of a user review gate. Because the managed runtime bridge surface changed, bridge-enabled targets need the bounded bridge repair path.",
+        "operatorChanges": [
+          "**Rendered bridge screenshots keep the expected orientation.** The managed runtime bridge no longer flips the viewport image before saving PNG artifacts for `screenshot.capture` or startup screenshot capture.",
+          "**Bridge repair is no longer presented as a manual review prompt.** Auto-applicable runtime bridge drift now surfaces as `follow_up_required`, so agents run the surfaced `gdh bridge repair` command and validation commands instead of asking the user to approve ordinary repair.",
+          "**Update guidance owns stale MCP cleanup.** `/gdh-update` guidance now tells agents to stop stale GDH MCP server processes themselves when possible before trusting MCP follow-up output.",
+          "**The managed bridge surface moves to the next contract version.** Bridge-enabled targets repair from runtime bridge surface `5` to `6` to receive the screenshot-orientation fix."
+        ]
+      },
+      "updateContract": {
+        "summary": "Bridge-enabled managed targets need a release-specific bridge repair path for v0.15.1 because the runtime bridge surface moves from version 5 to version 6. Agents should run surfaced follow-up commands directly for auto-applicable bridge repair, then validate with bridge status and project status.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can report whether the target entered the v0.15.1 runtime bridge repair branch.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_specific_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether bridge repair is active for this target.",
+            "detail": "If `gdh status` surfaces runtime-bridge reasons, inspect `gdh bridge status` and treat the surfaced `terminal.commands` as the release-specific follow-up. If no runtime-bridge reasons appear, no release-specific bridge repair is needed.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair the managed runtime bridge files when the bridge branch is active.",
+            "detail": "Bridge-enabled `v0.15.0` targets drift from runtime bridge surface version 6. Run `gdh bridge repair` to rewrite the managed bridge files and remove the extra screenshot flip.",
+            "commands": [
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status"
+            ]
+          },
+          {
+            "id": "enable_plugin_and_finish_gdhbridge_registration",
+            "kind": "manual_review",
+            "summary": "Enable the GDH Runtime Bridge plugin so GDHBridge registers when required.",
+            "detail": "GDH does not hand-edit `project.godot` for operators. After bridge repair, if bridge status still reports plugin/autoload follow-through, open the project in the Godot editor and enable the `GDH Runtime Bridge` plugin so it can register `GDHBridge`.",
+            "commands": [],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "validate_repaired_lifecycle",
+            "kind": "mechanical",
+            "summary": "Validate the repaired bridge and project lifecycle.",
+            "detail": "After repair and any plugin follow-through, rerun `gdh bridge status` and `gdh status`. The target should return to the healthy lifecycle state for the repaired bridge surface.",
+            "commands": [
+              "gdh bridge status",
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.16.0",
+      "releaseTag": "v0.16.0",
+      "migrationStatus": "required",
+      "summary": "v0.16.0 adds project-owned bridge entries, scene-scoped runtime reachability knowledge, navigation feasibility probes, and timed/sequenced runtime input. The release changes GDH_GUIDANCE_UNIT_VERSION (4 -> 6) and GDH_RUNTIME_BRIDGE_SURFACE_VERSION (6 -> 7), so managed targets need guidance migration and bridge repair before they are treated as current.",
+      "releaseHighlights": {
+        "summary": "v0.16.0 moves bridge extension and runtime-navigation knowledge into project-owned surfaces, adds a fixture-backed navigation lab for collision and route-probing experiments, and expands bounded runtime input with timed holds plus short action sequences. Agents can now create custom bridge entries outside the managed addon tree, reuse scene-scoped waypoint knowledge, and reduce latency-sensitive input failures without treating GDH as arbitrary gameplay automation.",
+        "operatorChanges": [
+          "**Project-owned bridge entries live outside `addons/gdh_bridge/`.** GDH scaffolds `.gdh/bridge/entries/` with a tracked `.gitkeep`, loads bounded project entries from that folder, and keeps the generated addon tree as GDH-owned output.",
+          "**Runtime reachability knowledge is durable and scene-scoped.** GDH scaffolds `.gdh/runtime-knowledge/` and supports YAML scene records for waypoints, routes, transitions, dynamic blockers, trust, and stale-status notes.",
+          "**Navigation exploration has fixture-backed probes.** The runtime bridge fixture now includes controlled-node/world-collider inspection plus segment and route probes so navigation approaches can be tested before GDH commits to a broad product API.",
+          "**Timed input and bounded action sequences are supported.** The bridge exposes `input.action.hold` with `durationMs` or live `physicsFrames`, and the host exposes `input.sequence.run` for short ordered bridge action flows.",
+          "**Generated guidance teaches the new boundaries.** Agent guidance covers project-owned bridge entries, runtime reachability knowledge, timed/sequenced input, and the line between live physics-frame holds and unsupported manual time-control."
+        ]
+      },
+      "updateContract": {
+        "summary": "Managed targets need release-specific migration for v0.16.0 because generated guidance and the runtime bridge surface changed. Agents should migrate guidance/scaffolded project-owned folders, repair the runtime bridge when GDH reports drift, complete plugin/autoload follow-through when required, and validate the target lifecycle.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can report whether the target needs guidance migration, runtime bridge repair, or plugin/autoload follow-through for v0.16.0.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "apply_guidance_and_project_surface_migration",
+            "kind": "mechanical",
+            "summary": "Apply managed guidance and project-owned surface migration.",
+            "detail": "When `gdh status` or `gdh migrate` reports migration work, run `gdh migrate --apply` to refresh guidance units and scaffold `.gdh/bridge/entries/` plus `.gdh/runtime-knowledge/` without storing project extensions inside the managed addon tree.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh guidance status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_repair_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether runtime bridge repair is active for this target.",
+            "detail": "If lifecycle output surfaces runtime-bridge reasons, inspect `gdh bridge status` and treat the surfaced terminal commands as release-specific follow-up. If no runtime-bridge reasons appear, no release-specific bridge repair is needed.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair managed runtime bridge files when drift is active.",
+            "detail": "Bridge-enabled targets on the previous surface drift from runtime bridge surface version 7. Run `gdh bridge repair` to rewrite the managed bridge addon with project-owned entry loading and timed hold support.",
+            "commands": [
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status"
+            ]
+          },
+          {
+            "id": "enable_plugin_and_finish_gdhbridge_registration",
+            "kind": "manual_review",
+            "summary": "Enable the GDH Runtime Bridge plugin so GDHBridge registers when required.",
+            "detail": "GDH does not hand-edit `project.godot` for operators. After bridge repair, if bridge status still reports plugin/autoload follow-through, open the project in the Godot editor and enable the `GDH Runtime Bridge` plugin so it can register `GDHBridge`.",
+            "commands": [],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "validate_repaired_lifecycle",
+            "kind": "mechanical",
+            "summary": "Validate guidance, bridge, and project lifecycle after migration.",
+            "detail": "After migration, bridge repair, and any plugin follow-through, rerun `gdh guidance status`, `gdh bridge status`, and `gdh status`. The target should return to the current lifecycle state for the refreshed guidance and bridge surfaces.",
+            "commands": [
+              "gdh guidance status",
+              "gdh bridge status",
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh guidance status",
+              "gdh bridge status",
+              "gdh status"
+            ]
+          }
+        ]
+      }
     }
   ]
 }

package/node_modules/@gdh/adapters/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EAiBL,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,cAAc,EAGnB,KAAK,sCAAsC,EAE3C,KAAK,gCAAgC,EAIrC,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AAYnB,eAAO,MAAM,eAAe,wCAc1B,CAAC;AAEH,eAAO,MAAM,gBAAgB,wCAAgF,CAAC;AAC9G,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AAOtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,8BAA8B,oCAAoC,CAAC;AAChF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,8BAA8B,gCAAgC,CAAC;AAC5E,eAAO,MAAM,kCAAkC,uBAAuB,CAAC;AACvE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAUzC,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC,GACL,OAAO,CAAC,4BAA4B,CAAC,CA0BvC;AAED,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC9B,GACL,OAAO,CAAC,6BAA6B,CAAC,CAgFxC;AAED,wBAAsB,oCAAoC,CACxD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,sCAAsC,CAAC,CA8DjD;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C,GACL,OAAO,CAAC,cAAc,CAAC,CAqFzB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAczC;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA6CtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAmCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA2CpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAyCrE;AAID,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA8BrE;AAED,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuClE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCnE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA4CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0CtE;AA4BD,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAyCxE;AAED,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA8CrE;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA4CtE;AAID,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+BtE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuCnE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCpE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAiCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAgCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCrE;AAylDD,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAM9E;AAED,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,aAAa,EAAE,MAAM,GACpB,MAAM,CAiCR;AA6oCD,iBAAS,sCAAsC,CAC7C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,gCAAgC,EAAE,GACpD,sCAAsC,CAmCxC;AAyOD,OAAO,EACL,gBAAgB,EAChB,KAAK,sBAAsB,GAC5B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sCAAsC,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAMhF,OAAO,EAAE,sCAAsC,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EAiBL,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EACjC,KAAK,cAAc,EAGnB,KAAK,sCAAsC,EAE3C,KAAK,gCAAgC,EAIrC,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,WAAW,CAAC;AAenB,eAAO,MAAM,eAAe,wCAc1B,CAAC;AAEH,eAAO,MAAM,gBAAgB,wCAAgF,CAAC;AAC9G,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AACrD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,eAAO,MAAM,oCAAoC,oCAAoC,CAAC;AACtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,kCAAkC,wCAAwC,CAAC;AACxF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AAOtF,eAAO,MAAM,mCAAmC,mCAAmC,CAAC;AACpF,eAAO,MAAM,gCAAgC,sCAAsC,CAAC;AACpF,eAAO,MAAM,iCAAiC,uCAAuC,CAAC;AACtF,eAAO,MAAM,iCAAiC,iCAAiC,CAAC;AAChF,eAAO,MAAM,8BAA8B,oCAAoC,CAAC;AAChF,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF,eAAO,MAAM,8BAA8B,gCAAgC,CAAC;AAC5E,eAAO,MAAM,kCAAkC,uBAAuB,CAAC;AACvE,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAUzC,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC,GACL,OAAO,CAAC,4BAA4B,CAAC,CA0BvC;AAED,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC9B,GACL,OAAO,CAAC,6BAA6B,CAAC,CAgFxC;AAED,wBAAsB,oCAAoC,CACxD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,sCAAsC,CAAC,CA8DjD;AAED,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA0B1B;AAED,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IACP,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C,GACL,OAAO,CAAC,cAAc,CAAC,CAqFzB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAczC;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA6CtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAmCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA2CpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAyCrE;AAID,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA8BrE;AAED,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuClE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCnE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA4CrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA0CtE;AA4BD,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAyCxE;AAED,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA8CrE;AAED,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA4CtE;AAID,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CA+BtE;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAuCnE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAqCpE;AAID,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAiCxE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCrE;AAED,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCtE;AAID,wBAAgB,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAgCvE;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAwCpE;AAED,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAsCrE;AAylDD,wBAAgB,gCAAgC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAM9E;AAED,wBAAgB,+BAA+B,CAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,aAAa,EAAE,MAAM,GACpB,MAAM,CAiCR;AA0oCD,iBAAS,sCAAsC,CAC7C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,gCAAgC,EAAE,GACpD,sCAAsC,CAmCxC;AAyOD,OAAO,EACL,gBAAgB,EAChB,KAAK,sBAAsB,GAC5B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sCAAsC,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAMhF,OAAO,EAAE,sCAAsC,EAAE,CAAC"}

package/node_modules/@gdh/adapters/dist/index.js

@@ -12,7 +12,7 @@ import { CLAUDE_SETTINGS_RELATIVE_PATH, patchClaudeSettingsForGdhSessionStart, p
 import { GDH_AGENT_CONTRACT_VERSION, GDH_CURSOR_RULE_VERSION, GDH_GUIDANCE_INDEX_VERSION, GDH_GUIDANCE_UNIT_VERSION, GDH_PROJECT_CONFIG_VERSION, GDH_RECIPE_SCHEMA_VERSION, GDH_RULES_SCHEMA_VERSION, GDH_SCENARIO_SCHEMA_VERSION, assertProjectLifecycleCompatibilityInvariant, definePackageBoundary, resolveCurrentGdhInstall, resolveConfiguredGodotEditorBin, resolveGdhProductMetadata, } from "@gdh/core";
 import { createDefaultGuidanceUnits, getGuidanceStatus, resolveGuidanceQuery, resolveRecoveryHints, } from "@gdh/docs";
 import { inspectGuidanceAudit } from "@gdh/observability";
-import { inspectRuntimeBridgeSurface } from "@gdh/runtime";
+import { inspectRuntimeBridgeSurface, inspectRuntimeKnowledgeSurface, } from "@gdh/runtime";
 import { readInventoryCacheOrScan } from "@gdh/scan";
 import { evaluateDonePolicy, recommendValidationForChange } from "@gdh/verify";
 export const adaptersPackage = definePackageBoundary({
@@ -227,6 +227,10 @@ export async function inspectProjectLifecycleCompatibility(targetPath) {
 export async function buildGdhStatusResult(targetPath) {
     const context = await buildAuthoringContext(targetPath);
     const projectLifecycle = await inspectProjectLifecycleCompatibility(targetPath);
+    const runtimeKnowledge = await inspectRuntimeKnowledgeSurface({
+        targetPath: context.status.targetPath,
+        runtimeKnowledgePath: context.projectConfig?.runtimeKnowledge.path ?? null,
+    });
     const recoveryHints = resolveRecoveryHints(projectLifecycle.reasons);
     const capabilities = await addOperationalCapabilityStatus(context.status.capabilities, context.status.targetPath);
     const detectedProjects = summarizeDetectedProjects(context.inventory.projects, context.status.primaryProjectPath);
@@ -236,6 +240,7 @@ export async function buildGdhStatusResult(targetPath) {
         detectedProjects,
         product: resolveGdhProductMetadata(),
         projectLifecycle,
+        runtimeKnowledge,
         recoveryHints,
     };
 }
@@ -868,7 +873,7 @@ export function renderClaudeUpdateCommand(_pinnedVersion) {
         "3. When `preview.state` is `ready`, summarize the current version, target version, intervening releases, bounded release highlights, ordered steps, and which work is `mechanical`, `agent_reasoning`, or `manual_review`.",
         "4. Ask for explicit approval before apply.",
         "5. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
-        "6. If this chat or editor keeps a long-lived GDH MCP session alive, restart or reconnect that MCP session before trusting MCP follow-up output. Self-update rebakes files on disk; an already-running MCP server can still be the old process or old env snapshot until it reconnects.",
+        "6. If this chat or editor keeps a long-lived GDH MCP session alive, do the MCP cleanup yourself before trusting MCP follow-up output: stop stale `gdh mcp serve` / `@skillcap/gdh ... mcp serve` processes for this target when possible, then let the next MCP connection restart from the updated config. If the client owns reconnection and the process cannot be controlled from Bash, report that limitation after attempting cleanup.",
         "7. Verify baked pinning: run `npx -y @skillcap/gdh@latest verify drift` to confirm every managed skill/command surface matches the new pin. This does not validate runtime bridge or other lifecycle surfaces.",
         "8. Read `terminal.state` in the apply stdout JSON and treat it as the lifecycle/runtime truth.",
         "9. If `terminal.state` is `healthy`, confirm the update completed and stop.",
@@ -915,7 +920,7 @@ export function renderCodexUpdateSkill(_pinnedVersion) {
         "3. When `preview.state` is `ready`, summarize the current version, target version, intervening releases, bounded release highlights, ordered steps, and which work is `mechanical`, `agent_reasoning`, or `manual_review`.",
         "4. Ask for explicit approval before apply.",
         "5. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
-        "6. If this chat or editor keeps a long-lived GDH MCP session alive, restart or reconnect that MCP session before trusting MCP follow-up output. Self-update rebakes files on disk; an already-running MCP server can still be the old process or old env snapshot until it reconnects.",
+        "6. If this chat or editor keeps a long-lived GDH MCP session alive, do the MCP cleanup yourself before trusting MCP follow-up output: stop stale `gdh mcp serve` / `@skillcap/gdh ... mcp serve` processes for this target when possible, then let the next MCP connection restart from the updated config. If the client owns reconnection and the process cannot be controlled from Bash, report that limitation after attempting cleanup.",
         "7. Verify baked pinning: run `npx -y @skillcap/gdh@latest verify drift` to confirm every managed skill/command surface matches the new pin. This does not validate runtime bridge or other lifecycle surfaces.",
         "8. Read `terminal.state` in the apply stdout JSON and treat it as the lifecycle/runtime truth.",
         "9. If `terminal.state` is `healthy`, confirm the update completed and stop.",
@@ -960,7 +965,7 @@ export function renderCursorUpdateSkill(_pinnedVersion) {
         "3. When `preview.state` is `ready`, summarize the current version, target version, intervening releases, bounded release highlights, ordered steps, and which work is `mechanical`, `agent_reasoning`, or `manual_review`.",
         "4. Ask for explicit approval before apply.",
         "5. Apply: run `npx -y @skillcap/gdh@latest self-update [version]` (omit `[version]` to apply against npm latest; forward whatever positional the user passed to `/gdh-update`).",
-        "6. If this chat or editor keeps a long-lived GDH MCP session alive, restart or reconnect that MCP session before trusting MCP follow-up output. Self-update rebakes files on disk; an already-running MCP server can still be the old process or old env snapshot until it reconnects.",
+        "6. If this chat or editor keeps a long-lived GDH MCP session alive, do the MCP cleanup yourself before trusting MCP follow-up output: stop stale `gdh mcp serve` / `@skillcap/gdh ... mcp serve` processes for this target when possible, then let the next MCP connection restart from the updated config. If the client owns reconnection and the process cannot be controlled from Bash, report that limitation after attempting cleanup.",
         "7. Verify baked pinning: run `npx -y @skillcap/gdh@latest verify drift` to confirm every managed skill/command surface matches the new pin. This does not validate runtime bridge or other lifecycle surfaces.",
         "8. Read `terminal.state` in the apply stdout JSON and treat it as the lifecycle/runtime truth.",
         "9. If `terminal.state` is `healthy`, confirm the update completed and stop.",
@@ -3216,20 +3221,17 @@ function inspectRuntimeBridgeLifecycleSurface(targetPath, bridgeStatus) {
             surface: "runtime_bridge_surface",
             management: "managed",
             state: "compatibility_degraded",
-            summary: "Runtime bridge managed files are present but drifted from the current GDH surface and need review or repair.",
+            summary: "Runtime bridge managed files are present but drifted from the current GDH surface and can be repaired automatically.",
             reasons: bridgeStatus.reasons,
             probes,
             action: {
                 kind: "run_repair",
-                summary: "Run GDH bridge repair after reviewing the drifted runtime bridge files.",
+                summary: "Run GDH bridge repair to rewrite the drifted runtime bridge files.",
                 command: ["gdh", "bridge", "repair", targetPath],
                 validationCommands: [
                     ["gdh", "bridge", "status", targetPath],
                     ["gdh", "status", targetPath],
                 ],
-                manualSteps: [
-                    "Review the drifted runtime bridge files before running automated repair.",
-                ],
                 autoApplicable: true,
             },
         });