@skillcap/gdh 0.24.0 → 0.25.0

package/node_modules/@gdh/docs/dist/template-assets.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export function renderDocsTemplate(relativePath, values) {
+    return renderStringTemplate(readDocsTemplate(relativePath), values);
+}
+function readDocsTemplate(relativePath) {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const templatePath = path.join(moduleDir, "templates", relativePath);
+    return fs.readFileSync(templatePath, "utf8");
+}
+function renderStringTemplate(template, values) {
+    const rendered = template.replace(/\{\{([a-zA-Z0-9_]+)\}\}/gu, (match, key) => {
+        const value = values[key];
+        if (value === undefined) {
+            throw new Error(`Missing template value for ${match}.`);
+        }
+        return value;
+    });
+    const unresolved = rendered.match(/\{\{[a-zA-Z0-9_]+\}\}/u);
+    if (unresolved) {
+        throw new Error(`Unresolved template placeholder ${unresolved[0]}.`);
+    }
+    return rendered;
+}
+//# sourceMappingURL=template-assets.js.map

package/node_modules/@gdh/docs/dist/template-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-assets.js","sourceRoot":"","sources":["../src/template-assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,kBAAkB,CAChC,YAAoB,EACpB,MAAwC;IAExC,OAAO,oBAAoB,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,gBAAgB,CAAC,YAAoB;IAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,oBAAoB,CAC3B,QAAgB,EAChB,MAAwC;IAExC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,2BAA2B,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QACpF,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,GAAG,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5D,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,mCAAmC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/node_modules/@gdh/docs/dist/templates/guidance/authoring-and-validation.md.tpl

@@ -0,0 +1,111 @@
+# {{projectName}}: Authoring And Validation
+
+If GDH was just set up or repaired, start with `/gdh-onboard` before editing files or choosing validation manually.
+
+Use GDH's authoring-facing surfaces before trusting ad hoc Godot state:
+
+- `gdh status` to confirm readiness and capability availability
+- if `gdh status` shows migration or degraded compatibility, load `.gdh/guidance/project-migration.md` before treating the target as ready for normal authoring work
+- `gdh target prepare --dry-run` before assuming a fresh target is hydrated and import-ready
+- `gdh lsp status` to inspect managed LSP lifecycle state only; this is lifecycle visibility, not diagnostic evidence
+- `gdh authoring diagnostics current` to read the current known diagnostics snapshot without triggering a new LSP refresh
+- `gdh authoring diagnostics refresh --changed <path>` to refresh broker diagnostics for specific files after edits; use this before checking current known problems when files were just modified
+- `gdh authoring diagnostics doctor` to explain stale, missing, incompatible, or unavailable broker states with actionable recovery steps
+- `gdh authoring check --mode final` to collect full validator evidence, diagnostics, import-state visibility, editor-side caveats, and an authoring-only blocking summary; use for task handoff, commit, or broad validation evidence
+- `gdh authoring check --mode post-edit --changed <path> --format compact` for fast agent-hook feedback after focused edits; when broker diagnostics are fresh, this uses the existing snapshot for speed
+- use GDH's LSP manager instead of hand-managing Godot LSP processes; use `gdh lsp status` for lifecycle visibility and `gdh lsp prune` or `gdh lsp stop` for bounded cleanup when stale instances are suspected
+- `gdh imports refresh` when the target already has generated state but needs an explicit Godot import/update pass
+- `gdh target prepare --source-target <path>` to hydrate a cold worktree by copying `.godot/` from the main checkout — use this when `gdh imports refresh` fails because headless import cannot handle editor-only plugins (e.g., aseprite importers)
+- if `gdh target prepare` or `gdh imports refresh` blocks after an exit-`0` Godot import pass, inspect `importRefresh.processOutput.stderr`; GDH now treats fatal Godot stderr as blocking evidence even when the engine exits cleanly
+- if direct editor/import-sensitive work is blocked by `godot_editor_not_configured`, explain that GDH checked `GDH_GODOT_EDITOR_BIN`, target-local `.gdh-state/local-paths.json`, `~/.gdh/config.json`, and safe common editor locations; ask for the machine-local editor path and explicit permission before recording it only after those fail, prefer reusable `~/.gdh/config.json` `godotEditorBinPath` when the path should apply across targets, and never write this path into committed project config
+
+Validator-family split:
+
+- `.gd` changes require GDScript LSP validator evidence (`gdscript_lsp`) from `gdh authoring check`
+- `.tscn` and `.tres` changes require Godot scene/resource validator evidence (`godot_scene_resource`) from `gdh authoring check`
+- `project.godot` and unsupported authoring-facing files are not covered by GDScript LSP diagnostics; treat them as explicit manual validation until GDH ships a dedicated validator
+- a ready `authoring.lsp` lifecycle or available capability is not diagnostic evidence; unavailable, degraded, or missing `gdh authoring check` evidence blocks code-validity claims
+- default authoring blocking policy is error-only: warnings are reported but do not block unless the command is run with `--severity-policy all` or project guidance explicitly requires warning-clean output
+
+Agent-hook use:
+
+- Codex and Claude managed adapter installs include GDH post-edit authoring hooks for touched `.gd`, `.tscn`, `.tres`, or `project.godot` files inside the configured Godot target
+- Post-edit hooks call `gdh authoring diagnostics refresh --changed <path>` to warm the diagnostics broker, then run `gdh authoring check --mode post-edit --changed <path> --format compact` to evaluate blocking state; when the broker is unavailable, the check falls back to direct LSP collection
+- Managed hooks do not persist dirty-file state and do not run final validation from Stop hooks; use `gdh authoring check --mode final` explicitly for task handoff, commit, or broad validation evidence
+- Cursor does not currently have a GDH-managed hook surface; Cursor agents must use `gdh authoring diagnostics refresh` plus `gdh authoring check --mode final` explicitly
+- Hooks and skills must call `gdh authoring check` and `gdh authoring diagnostics` commands; they must not talk to the raw Godot LSP or hand-manage Godot editor/LSP processes
+
+When `EditorPlugin`, `@tool`, plugin configuration, or import-sensitive work is involved, treat editor-side validation as a distinct requirement instead of assuming runtime checks are enough.
+
+When runtime verification is part of proving a Godot fix, keep the runtime bridge vocabulary and evidence boundary explicit:
+
+- `player_reachable` means a bounded action that a normal player could do through ordinary game input
+- `internal_route` means bounded direct control used only when no practical player path exists
+- `waiter` is the bounded wait primitive for runtime verification; prefer explicit waits for property, node, or signal conditions instead of open-ended sleeps
+- `artifact_policy.screenshots: "rendered"` requests one supporting rendered screenshot artifact for a verification run; legacy `"fallback"` remains accepted as a compatibility alias, but scenario truth should still come from source-backed project-owned signals instead of image interpretation
+
+Broker-backed bridge recovery:
+
+- GDH bridge sessions are owned by a target-local broker, not by the MCP stdio process; if MCP transport is stale, closed, or restarted, inspect recovery with `gdh bridge session doctor` before trying fallback launch workarounds
+- use `gdh bridge session list`, `gdh bridge session get <sessionId>`, `gdh bridge session entries <sessionId>`, and `gdh bridge session invoke <sessionId> <entryId>` when MCP bridge access is unavailable but the broker is healthy
+- use `gdh bridge session prune` only for GDH-owned stale broker metadata or compatible broker-owned sessions; do not manually kill editor, Godot, or unrelated user processes
+- pre-broker active bridge sessions lived in MCP process memory and cannot be recovered after update or MCP restart; new broker-backed sessions are reconnectable through CLI and MCP clients
+- host-side broker recovery does not require `gdh bridge repair`; use repair only when GDH reports project-side runtime bridge surface drift
+- broker metadata, heartbeat, and token files live under `.gdh-state/`; do not copy tokens into chat, logs, or committed files
+
+Bridge entry reference (all built-in `core` entries shipped in the GDH runtime bridge surface). All entries are invoked through MCP `bridge.entry.invoke` while a bridge session is active. Every response is `{state, result, error}` where `state` is one of `ok`, `failed`, `unavailable`, or `blocked`. `failed` means the call was malformed (missing or wrong-typed input). `unavailable` means the call shape was valid but the runtime cannot satisfy it right now (node missing, action not in InputMap, observation never started, viewport empty, etc.).
+
+Probes (read-only, safe to call repeatedly):
+
+- `bridge.session.get` — input: `{}`. Returns the active bridge session snapshot.
+- `scene.active.get` and `scene.current.get` — input: `{}`. Both return the same active-scene snapshot (`scene.current.get` is an alias).
+- `scene.nodes.find` — input: `{nameContains?: string, className?: string, limit?: int}`. Searches the active scene only. `nameContains` is a substring match on `node.name`, lowercased on both sides before comparison; pass `"player"` to match `Player` and `MainPlayerCharacter` alike. `className` filters via Godot's `Node.is_class()`, which only matches **built-in Godot classes** (e.g., `Node`, `Node2D`, `Control`, `BaseButton`); a `class_name`-declared GDScript class will NOT match — use `nameContains` for those. `limit` is clamped to `1..50` (default `20`). Returns `Array<{name, path, className, sceneFilePath, groups}>`. Empty array means no matches.
+- `scene.tree.nodes.find` — same input shape as `scene.nodes.find`, but searches the whole SceneTree (including autoload roots), not just the active scene.
+- `scene.node.nodes.find` — input: `{rootNodePath: string, nameContains?: string, className?: string, limit?: int}`. Same filter semantics as above, scoped to the subtree under `rootNodePath` (an exact node path). `failed` reason `"requires rootNodePath"` if missing. `unavailable` reason `"could not find rootNodePath %s"` when the path resolves to no node.
+- `scene.snapshot.get` — input: same filter shape as `scene.nodes.find`. Returns `{activeScene, nodes}` in one round trip — the composite is for cases where you need both at the same instant.
+- `state.node_presence.get` — input: `{nodePath: string}`. Returns `{nodePath, present: bool, name?, className?}`. Returns `present: false` (with `state: ok`) when the node is missing, not an error.
+- `state.signal_observation.get` — input: `{nodePath: string, signalName: string}`. Returns `{nodePath, signalName, count, lastObservedAt, lastPayload}`. `unavailable` when `state.signal_observation.start` was not called for this `(nodePath, signalName)` pair earlier in the same session.
+- `state.node_property.get` — input: `{nodePath: string, property: string}`. The input key is **`property`**, not `propertyPath` or `propertyName`. `property` is a Godot `NodePath`-style indexed property path using `:` as the separator (e.g., `"position"`, `"position:x"`, `"transform:origin:y"`). Dotted JS-style paths (`"position.x"`) will not work. Returns `{nodePath, property, value}` where `value` is serialized via `to_bridge_value` (primitives stay primitive; `Vector2`/`Vector3`/`Color` become `{_type, ...components}`; `Node`/`Resource` references become `{_type, name?, path?, resourcePath?}`). `failed` when `nodePath` or `property` is missing. `unavailable` when the node does not exist or the property's first segment is not declared on the node.
+
+Waiters (Node-side synthetic entries; intercepted by the runtime manager and expanded into bounded polling against probe entries; emit `waiterEvidence` in run records):
+
+- `state.node_property.await` — input: `{nodePath: string, property: string, expected: any, timeoutMs?: int (100..5000, default 1500), pollIntervalMs?: int (25..250, default 50)}`. Polls `state.node_property.get` until the returned value deep-equals `expected`. `expected` is required (not optional). `failed` when `nodePath`, `property`, or `expected` is missing. Returns `state: ok` with `{...target, value, attempts, elapsedMs}` when satisfied; returns `state: unavailable` with the same shape plus `error: "Timed out…"` on timeout. Same `:` indexed-path semantics as `state.node_property.get`.
+- `state.node_presence.await` — input: `{nodePath: string, expected: "present" | "absent", timeoutMs?: int, pollIntervalMs?: int}`. Polls `state.node_presence.get` until presence matches `expected`. `failed` if `expected` is anything other than `"present"` or `"absent"`.
+- `state.signal.await` — input: `{nodePath: string, signalName: string, afterCount?: int (default 0), timeoutMs?: int, pollIntervalMs?: int}`. Calls `state.signal_observation.start` once, then polls `state.signal_observation.get` until `count > afterCount`. Use `afterCount` to wait for a signal emission that happens AFTER a known baseline.
+
+Actions — input (`InputMap`-driven, `player_reachable`):
+
+- `input.action.press` and `input.action.release` — input: `{action: string}` (an action ID registered in Godot's `InputMap`). Returns `{action, pressed: bool}`. `failed` when `action` is missing. `unavailable` when `action` is not in `InputMap`.
+- `input.action.hold` — input: `{action: string, durationMs?: int (1..5000), physicsFrames?: int (1..300)}`. Pass exactly one of `durationMs` or `physicsFrames`; passing both or neither returns `failed`. `durationMs` waits wall-clock; `physicsFrames` waits physics frames advancing in the live game. This is NOT manual ticking and NOT deterministic time-control: the engine continues at its real rate while the action is held, so other physics, animation, and signal work also progresses. The runtime bridge handles this entry directly through an awaiting dispatch path — calling `BridgeRegistry.invoke()` from non-WS code paths returns `unavailable` by design.
+- `input.event.send` — input: `{event: {kind: "key", keycode: int, pressed?: bool, physicalKeycode?: int, unicode?: int, echo?: bool, alt?: bool, ctrl?: bool, meta?: bool, shift?: bool}}`. Only `kind: "key"` is supported in the current core entry; missing or unsupported `kind` returns `failed`. `keycode` is required; the others are optional and default to false / 0. Use this for `_input(event)` or `_unhandled_input(event)` paths that inspect the raw `InputEventKey`, not `Input.is_action_pressed`.
+- `input.sequence.run` — input: `{steps: Array<{entryId: string, input?: object} | {delayMs: int}>, stopOnFailure?: bool (default true)}`. `steps` length must be 1..20. Cannot recursively invoke itself (`failed`). Each step is either an `action`-kind bridge invocation or a bounded delay. Use this when separate MCP round trips would make the timing fragile.
+
+Actions — UI (`internal_route`, controlled fallback only when no `player_reachable` route exists):
+
+- `ui.button.press` — input: `{nodePath: string}`. Emits the `pressed` signal on a `BaseButton`. `unavailable` if the node is missing, not a `BaseButton`, or `disabled`.
+- `ui.line_edit.text.set` — input: `{nodePath: string, text: string, caretColumn?: int}`. Sets `LineEdit.text`, clamps `caret_column` to `0..text.length()`, emits `text_changed`. `unavailable` if the node is missing or not a `LineEdit`.
+- `ui.range.value.set` — input: `{nodePath: string, value: number}`. Sets `Range.value` clamped to `Range.min_value..Range.max_value`, emits `value_changed`. `unavailable` if the node is missing or not a `Range`-derived control.
+
+Actions — runtime control:
+
+- `state.signal_observation.start` — input: `{nodePath: string, signalName: string}`. Starts observing one signal on one node for the rest of the session; idempotent for the same `(nodePath, signalName)` key. `unavailable` when the node is missing, the signal is missing, or the connection failed.
+- `screenshot.capture` — input: `{imagePath: string, metadataPath: string}`. Both paths must be absolute or resolvable from Godot's working directory; GDH creates parent directories as needed. Writes a PNG to `imagePath` and a JSON metadata file to `metadataPath`. The metadata file is always written (even on failure) and includes `state` (`captured` / `unavailable` / `failed`), `summary`, `reason` (machine-readable hint such as `active_scene_missing`, `viewport_texture_missing`, `viewport_image_empty`, `save_png_failed`), `capturedAt`, `imagePath`, `metadataPath`, `activeScene`, and (on success) `viewportSize`. Start a bridge session, navigate or wait to the needed moment, then invoke this — do not predict the right frame at launch time.
+- `scene.tree.pause.set` — input: `{paused: bool}`. Sets `SceneTree.paused`. `failed` when `paused` is missing. Returns `{paused: bool}` reflecting the resulting tree state.
+
+Project-owned bridge entries:
+
+- prefer GDH core bridge entries first; use shipped probes, actions, and waiters when they can express the needed truth
+- create a bounded project-owned bridge entry under `.gdh/bridge/entries/` only when GDH core entries cannot express source-backed project-specific semantics
+- Do not edit `addons/gdh_bridge/` for project-specific custom entries; that tree is GDH-managed generated bridge addon output
+- every custom entry must keep explicit `kind`, `shape`, `source`, `executionRoute`, and `safetyLevel` metadata, with entry kinds limited to `probe`, `action`, and `waiter`
+
+Runtime reachability knowledge:
+
+- store scene-scoped runtime reachability knowledge under `.gdh/runtime-knowledge/`, not under `addons/gdh_bridge/` or `.gdh-state/`
+- use `.gdh/runtime-knowledge/scenes/*.yaml` for reusable scene records with `scene_path`, `waypoints`, `routes`, `transitions`, `dynamic_blockers`, `trust`, and stale-status notes
+- restrict this surface to Godot runtime reachability: routes, waypoint knowledge, transition behavior, dynamic-blocker caveats, and evidence notes; do not dump generic project knowledge there
+- when runtime reachability knowledge is missing or incomplete, ask the user for known route, waypoint, transition, or dynamic-blocker details if that project-specific knowledge may already exist
+- if the user has no route knowledge or asks you to investigate, explore with bounded bridge probes and persist only evidence-backed results
+- update runtime knowledge or mark it `stale` when scene layout, dynamic blockers, or transition behavior changes
+- fixture `project.navigation.*` entries in GDH's navigation feasibility lab are evidence for experiments only; they are not generic pathfinding support
+

package/node_modules/@gdh/docs/dist/templates/guidance/gdh-glossary.md.tpl

@@ -0,0 +1,34 @@
+# {{projectName}}: GDH Operational Terms
+
+Use this unit when a GDH skill, command, or guidance file uses GDH-specific vocabulary. Do not repeat the words without understanding the operational meaning.
+
+- `target`: the Godot project root GDH should inspect, prepare, validate, or manage.
+- `authoring`: editing or validating Godot-facing files such as `.gd`, `.tscn`, `.tres`, and `project.godot`.
+- `authoring check`: `gdh authoring check`, the command that collects validator diagnostics and blocking summaries.
+- `diagnostics broker`: GDH's persistent diagnostics snapshot service backed by the managed LSP; exposes `current`, `refresh`, `status`, `doctor`, and `prune` operations under `gdh authoring diagnostics`.
+- `diagnostics snapshot`: the last set of normalized diagnostics GDH collected from the managed LSP, scoped to files that were opened or refreshed; not whole-project coverage.
+- `validation evidence`: concrete diagnostics from validators; capability availability or LSP lifecycle health alone is not validation evidence.
+- `LSP lifecycle`: whether GDH can launch, reuse, inspect, restart, prune, or stop the editor-backed Godot LSP service for this target.
+- `readiness`: GDH's structured status for whether the target is detected, onboarded, authorable, blocked, degraded, or unavailable.
+- `capability`: an available GDH feature surface, such as scan, authoring readiness, authoring LSP lifecycle, or runtime bridge support.
+- `inventory`: discovered Godot projects, addons, scenes, tests, and related filesystem evidence.
+- `inventory cache`: `.gdh-state/inventory.json`, derived machine-local project discovery data used by onboarded targets.
+- `.gdh/`: durable project truth owned by the repository, including GDH config, rules, run configurations, scenarios, project-owned bridge entries, and runtime knowledge.
+- `.gdh-state/`: ignored machine-local operational state, such as inventory cache, readiness snapshots, local paths, hook state, and logs.
+- `.godot/ generated state`: Godot's editor/import cache; useful for validation and import readiness, but not durable project truth.
+- `cold worktree`: a checkout/worktree whose generated Godot editor/import state is missing, stale, or incomplete.
+- `hydration`: copying reusable `.godot/` generated state from another local checkout to make this worktree ready faster.
+- `source target`: a sibling checkout used as the source for `.godot/` hydration.
+- `import refresh`: running Godot to rebuild or update generated import state for the target.
+- `machine-local path`: a path valid only on this computer, such as the Godot editor binary path; keep it in `.gdh-state/`, not committed project config.
+- `managed surface`: a GDH-owned or GDH-merge-managed file that must match the selected GDH version, such as guidance, rules, agent adapters, MCP config, or runtime bridge output.
+- `terminal.state`: the structured lifecycle outcome from migration or update flows; use it instead of prose, stderr, or action count guesses.
+- `manual review`: project-owned judgment GDH cannot safely automate; stop for the user after surfaced commands and validations.
+- `validationCommands`: exact GDH-surfaced commands to run after apply or follow-up work.
+- `runtime reachability knowledge`: scene-scoped route, waypoint, transition, dynamic-blocker, trust, and stale-status notes under `.gdh/runtime-knowledge/`.
+- `player_reachable`: a bounded action that a normal player could do through ordinary game input.
+- `internal_route`: bounded direct control used only when no practical player path exists.
+- `waiter`: a bounded runtime polling primitive for property, node, or signal conditions.
+
+If a shipped skill uses a GDH term not defined locally, load this glossary before acting. If the term is still ambiguous, ask for clarification rather than guessing.
+

package/node_modules/@gdh/docs/dist/templates/guidance/persistence-semantics.md.tpl

@@ -0,0 +1,24 @@
+# {{projectName}}: Persistence Semantics
+
+Use this unit when the task touches `gdh scan`, `gdh onboard`, `gdh status`, or any reasoning about whether a command warms `.gdh-state/` cache or not.
+
+Anchor on the command → effect table:
+
+| Command | Reads from disk | Writes to disk | Precondition | Session event |
+|---------|-----------------|----------------|--------------|---------------|
+| scan | `.gdh-state/inventory.json` (cache-first on onboarded targets) | `.gdh-state/inventory.json` (onboarded targets only) | Any filesystem path | `kind: "scan"` on onboarded branch only |
+| onboard | `.gdh/project.yaml` (if exists, for migration check), `.gitignore` | `.gitignore` (GDH-managed `.gdh-state/` section only), `.gdh/project.yaml`, `.gdh-state/inventory.json`, skill files | No precondition | `kind: "onboard"` |
+| status | `.gdh-state/inventory.json` (cache-first when onboarded) | None | Any filesystem path | None |
+
+Key facts agents keep getting wrong:
+
+- The inventory cache is `.gdh-state/inventory.json`: derived, machine-local project inventory used to avoid rescanning unchanged onboarded targets.
+- `gdh scan` on a target with no ancestor `.gdh/project.yaml` writes nothing — it is stdout-only and `persisted` is `null`. It does not "warm the cache" because there is no cache to warm.
+- `gdh scan` on an onboarded target writes `.gdh-state/inventory.json` atomically and emits `persisted.mode` of `create`, `unchanged`, or `overwrite`.
+- `gdh status` never writes to disk. It reads the cached inventory when present and live-scans when it is missing, corrupt, or schema-mismatched (degraded path).
+- `gdh onboard` may update `.gitignore`, but only for the GDH-managed `.gdh-state/` ignore section. It does not take ownership of `.godot/` ignore policy.
+- `gdh onboard` writes durable project truth (`.gdh/project.yaml`), derived state (`.gdh-state/inventory.json`), and skill files. It is not a synonym for scan.
+- Run `gdh scan` when you need fresh filesystem discovery: before first setup/onboard, after project structure changed, when the user asks what Godot projects/addons/scenes/tests were detected, or when cache freshness is explicitly in doubt. For normal readiness, migration, or validation questions, start with `gdh status` or `gdh authoring check` instead.
+
+Do not infer behavior from command names. Read the table, run the command, and check the envelope.
+

package/node_modules/@gdh/docs/dist/templates/guidance/project-migration.md.tpl

@@ -0,0 +1,19 @@
+# {{projectName}}: Project Migration
+
+Use this unit when `gdh status` or `gdh migrate` says the managed target needs migration, repair, or follow-up before normal implementation work.
+
+Follow this order:
+
+- run `gdh status` first and name the exact migration or degraded-compatibility reasons GDH reports
+- run `gdh migrate` before proposing manual edits so GDH can preview the supported repair or migration actions
+- only run `gdh migrate --apply` after explaining the planned changes and confirming the target path is correct
+- after apply, read `terminal.state` in the stdout JSON instead of guessing from prose summaries
+- if `terminal.state` is `healthy`, stop — no further migration action is required
+- if `terminal.state` is `follow_up_required`, run the surfaced `terminal.commands`, then run the surfaced `terminal.validationCommands` before treating the target as healthy
+- if `terminal.state` is `manual_review_required`, complete the surfaced `terminal.manualSteps`, then run the surfaced `terminal.validationCommands`; do not collapse review-gated work into an automatic repair
+- if runtime bridge compatibility remains degraded, enable the `GDH Runtime Bridge` plugin in the Godot editor so the addon can register `GDHBridge` itself
+- read `brokerTransition` when present: old pre-broker active sessions are unrecoverable, new broker-backed sessions are reconnectable, `.gdh-state/` remains untracked runtime state, and host-side broker migration alone does not require `gdh bridge repair`
+- if `terminal.state` is `blocked`, stop and review the surfaced reasons before making repo-local changes
+
+Do not hand-edit `project.godot` to register `GDHBridge`, and do not treat a migrated target as healthy until GDH's structured surfaces agree. GDH does not yet back up or reapply customized managed-surface patches automatically.
+

package/node_modules/@gdh/docs/dist/templates/guidance/project-surfaces.md.tpl

@@ -0,0 +1,14 @@
+# {{projectName}}: Project Surfaces
+
+Keep the repo-visible GDH surface small and explicit:
+
+- `.gdh/` is durable project truth, including project config, rules, run configurations, and verification scenarios; in a monorepo it may live at the integration root above this Godot target
+- `.gdh/bridge/entries/` is durable project truth for bounded project-owned bridge entries
+- `.gdh/runtime-knowledge/` is durable project truth for Godot scene-scoped reachability knowledge such as scene waypoints, routes, transitions, dynamic blockers, trust, and stale caveats
+- target-local `.gdh/guidance/` holds richer Godot-specific operational guidance for progressive disclosure
+- `.gdh-state/` is ignored operational state for inventories, readiness snapshots, and other worktree-local artifacts
+- GDH may ensure `.gitignore` ignores `.gdh-state/`, because that path is GDH-owned machine-local state
+- `.godot/` is generated editor/import state and should not be treated as durable project truth, even when GDH hydrates or refreshes it during target preparation
+- GDH does not manage `.godot/` ignore policy; whether a project commits or ignores `.godot/` remains Godot/project-owned policy
+- project-local env files such as `.env.local` are not part of default GDH target preparation unless project-specific guidance explicitly says otherwise
+

package/node_modules/@gdh/docs/package.json

@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@gdh/core": "0.24.0",
+    "@gdh/core": "0.25.0",
     "yaml": "^2.8.3"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/mcp/package.json

@@ -11,14 +11,14 @@
     }
   },
   "dependencies": {
-    "@gdh/adapters": "0.24.0",
-    "@gdh/authoring": "0.24.0",
-    "@gdh/core": "0.24.0",
-    "@gdh/docs": "0.24.0",
-    "@gdh/observability": "0.24.0",
-    "@gdh/scan": "0.24.0",
-    "@gdh/verify": "0.24.0",
+    "@gdh/adapters": "0.25.0",
+    "@gdh/authoring": "0.25.0",
+    "@gdh/core": "0.25.0",
+    "@gdh/docs": "0.25.0",
+    "@gdh/observability": "0.25.0",
+    "@gdh/scan": "0.25.0",
+    "@gdh/verify": "0.25.0",
     "@modelcontextprotocol/sdk": "1.29.0"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/observability/package.json

@@ -11,7 +11,7 @@
     }
   },
   "dependencies": {
-    "@gdh/core": "0.24.0"
+    "@gdh/core": "0.25.0"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/runtime/package.json

@@ -11,9 +11,9 @@
     }
   },
   "dependencies": {
-    "@gdh/core": "0.24.0",
+    "@gdh/core": "0.25.0",
     "ws": "^8.18.3",
     "yaml": "^2.8.3"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/scan/package.json

@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@gdh/core": "0.24.0",
-    "@gdh/docs": "0.24.0"
+    "@gdh/core": "0.25.0",
+    "@gdh/docs": "0.25.0"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/node_modules/@gdh/verify/package.json

@@ -11,13 +11,13 @@
     }
   },
   "dependencies": {
-    "@gdh/authoring": "0.24.0",
-    "@gdh/core": "0.24.0",
-    "@gdh/docs": "0.24.0",
-    "@gdh/observability": "0.24.0",
-    "@gdh/runtime": "0.24.0",
-    "@gdh/scan": "0.24.0",
+    "@gdh/authoring": "0.25.0",
+    "@gdh/core": "0.25.0",
+    "@gdh/docs": "0.25.0",
+    "@gdh/observability": "0.25.0",
+    "@gdh/runtime": "0.25.0",
+    "@gdh/scan": "0.25.0",
     "yaml": "^2.8.3"
   },
-  "version": "0.24.0"
+  "version": "0.25.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillcap/gdh",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Godot-specific authoring and validation harness for agentic development.",
   "license": "MIT",
   "type": "module",
@@ -31,17 +31,17 @@
     "releaseStage": "broader_internal_release"
   },
   "dependencies": {
-    "@gdh/cli": "0.24.0",
+    "@gdh/cli": "0.25.0",
     "@clack/prompts": "^1.2.0",
-    "@gdh/adapters": "0.24.0",
-    "@gdh/authoring": "0.24.0",
-    "@gdh/core": "0.24.0",
-    "@gdh/docs": "0.24.0",
-    "@gdh/mcp": "0.24.0",
-    "@gdh/observability": "0.24.0",
-    "@gdh/runtime": "0.24.0",
-    "@gdh/scan": "0.24.0",
-    "@gdh/verify": "0.24.0",
+    "@gdh/adapters": "0.25.0",
+    "@gdh/authoring": "0.25.0",
+    "@gdh/core": "0.25.0",
+    "@gdh/docs": "0.25.0",
+    "@gdh/mcp": "0.25.0",
+    "@gdh/observability": "0.25.0",
+    "@gdh/runtime": "0.25.0",
+    "@gdh/scan": "0.25.0",
+    "@gdh/verify": "0.25.0",
     "picocolors": "^1.1.1"
   },
   "bundledDependencies": [