feat(integrations): generate and safely refresh host guidance

.gitattributes

@@ -4,3 +4,5 @@ e2e/bub/tasks/*.yaml text eol=lf
 integrations/dsh/plugins/powercontext/src/operations.generated.ts text eol=lf
 integrations/dsh/plugins/powercontext/lib/*.js text eol=lf
 integrations/dsh/plugins/powercontext/lib/*.d.ts text eol=lf
+# Generated guidance compares canonical bytes; keep user notes outside its markers untouched.
+integrations/**/skills/powercontext-project-context/** text eol=lf

.github/workflows/master.yml

@@ -161,11 +161,11 @@ jobs:
           mkdir -p "$TMPDIR"
           collect_diagnostics() {
             df -h . /tmp
-            # A timed-out pytest process cannot run fixture cleanup. Retain
-            # bounded native logs from its isolated data directories as well
-            # as the Python stack and SQL trace.
+            # A timed-out pytest process cannot run fixture cleanup. Preserve
+            # native startup/recovery evidence too: a tail alone can omit the
+            # transaction that acquired the lock blocking the final SQL query.
             find "$TMPDIR" -type f \( -name '*.log' -o -name '*.log.wf' \) \
-              -print -exec tail -c 8388608 {} \; > seekdb-native.log
+              -printf '%P\0' | tar -czf seekdb-native.tar.gz -C "$TMPDIR" --null -T -
           }
           trap collect_diagnostics EXIT
           df -h . /tmp
@@ -202,7 +202,7 @@ jobs:
           name: seekdb-migrations-${{ matrix.python-version }}
           path: |
             seekdb-migrations.log
-            seekdb-native.log
+            seekdb-native.tar.gz
           if-no-files-found: ignore
 
   atomic-memory-clean-seekdb:
@@ -283,6 +283,15 @@ jobs:
           tests/builtin/test_native_code_multilanguage.py
           tests/e2e/test_native_code_multilanguage.py
 
+      - name: Verify managed guidance and exact rollback bytes on Windows
+        run: >-
+          uv run --locked --no-sync pytest -q
+          tests/test_guidance_generation.py
+          tests/test_guidance_installation.py
+          tests/test_opencode_installation.py
+          tests/test_cli_zcode.py::test_zcode_upgrade_rejects_missing_packaged_reference_and_preserves_installation
+          tests/test_setup_rollback.py
+
       - name: Exercise fixtures without Windows long-path support
         shell: pwsh
         run: |

Makefile

@@ -19,7 +19,14 @@ notebooks-test: ## Execute provider-free tutorials in fresh kernels; use ARGS fo
 	@uv run --locked --group notebooks python examples/jupyter/run.py $(ARGS)
 
 .PHONY: check
-check: version-check workflow-actions-check integration-manifest-check ## Run code quality tools.
+check: version-check workflow-actions-check integration-manifest-check integration-guidance-check ## Run code quality tools.
+
+.PHONY: integration-guidance integration-guidance-check
+integration-guidance: ## Refresh the managed regions of packaged integration guidance.
+	@uv run python scripts/integration_guidance_skills.py --write
+
+integration-guidance-check: ## Reject stale generated guidance without modifying files or calling models.
+	@uv run python scripts/integration_guidance_skills.py --check-generated
 
 .PHONY: workflow-actions-check
 workflow-actions-check: ## Verify third-party GitHub Actions use immutable commit pins.

docs/en/docs/integrations/opencode.md

@@ -63,6 +63,23 @@ Set `POWERCONTEXT_OPENCODE_CAPTURE_PROMPTS=false` when prompts must not be persi
 
 ## Verify the installation
 
+### Recover a failed refresh
+
+If setup reports `recovery failed`, keep the reported backups. Setup refuses further installation writes while a
+`.powercontext-install-*` path or a `.powercontext-project-context.*.bak` path remains; a missing active Skill is
+not treated as a fresh installation in this state.
+
+Restore the failed file destinations named in the error from the installation backup directory; file backups use their
+original filenames. If `skills/powercontext-project-context` is absent, restore its retained Skill directory to that
+location. If an active Skill or multiple backups exist, compare and reconcile their contents before choosing a version;
+setup does not choose or merge them automatically. Preserve personal files and notes outside managed regions.
+
+Only after restoring or reconciling the contents, move remaining recovery paths out of the OpenCode config directory
+and rerun the setup command, then run the checks below. Removing backups just to bypass the check can discard user notes.
+These safeguards cover caught filesystem failures; they do not guarantee recovery from process crashes or concurrent setups.
+
+### Check the plugin
+
 ```bash
 powercontext doctor
 powercontext doctor opencode

docs/zh/docs/integrations/opencode.md

@@ -60,6 +60,21 @@ HTTPS 证书校验仍然启用。安装与持久化同意见[连接远程 Server
 
 ## 验证安装
 
+### 恢复失败的更新
+
+如果 setup 报告 `recovery failed`，请保留报错中列出的备份。只要配置目录中仍有 `.powercontext-install-*`
+或 `.powercontext-project-context.*.bak` 恢复路径，后续 setup 就会在安装写入前停止；此时不会把缺失的 Skill
+目录当成首次安装。
+
+按照报错列出的失败目标，从安装备份目录还原对应文件，文件备份使用原文件名。如果 `skills/powercontext-project-context`
+不存在，将保留的 Skill 备份目录恢复到该位置。如果已有当前 Skill 或多个备份，先比较并整理其中的内容；setup 不会自动
+选择或合并版本。请保留个人文件及管理区域外的笔记。
+
+恢复或核对完内容后，再将剩余恢复路径移出 OpenCode 配置目录，重新执行 setup，并运行下面的检查。仅为绕过检查而删除
+备份，可能丢弃用户笔记。以上保护针对可捕获的文件操作失败，不保证进程崩溃或并发安装时的恢复。
+
+### 检查插件
+
 ```bash
 powercontext doctor
 powercontext doctor opencode

evaluation/skills/skill-up/README.md

@@ -114,7 +114,7 @@ claim about body consumption; ordinary coding does not require a Skill invocatio
 
 ## Pinning a Skill revision
 
-`vendor/powercontext-project-context` contains the four unchanged packaged Skill files. `skill-lock.json` identifies
+`vendor/powercontext-project-context` contains the packaged Skill files and its managed-refresh metadata. `skill-lock.json` identifies
 their source commit, individual SHA-256 hashes and an aggregate hash of sorted `<sha256>  <relative-path>\n` lines.
 Vendoring reads immutable Git blobs, and `.gitattributes` keeps the vendor bytes in LF form across platforms.
 
@@ -149,10 +149,11 @@ CRLF to Git LF. CI fails if the packaged Skill drifts without updating the pin.
 - **C6 — Lifecycle.** `environment.type: none` starts no PowerContext Server. The current runner starts its mock itself.
   The unused HTTP reference is not a ready-to-run real suite: it requires a separately started Server, an authenticated
   readiness/tool-catalog check, dedicated Scopes and explicit cleanup before any real case is admitted.
-- **C7 — Plugin boundary.** The packaged Skill references `${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py`, outside its
-  Skill directory. The wrapper deliberately provides `harness/plugin-root/scripts/workspace_scope.py`, a fixture that
-  returns only the fictional Scope and rejects bind/clear operations. The Skill text is unchanged. This evaluates the
-  guidance after controlled Scope resolution; it does not qualify the actual plugin helper or standalone packaging.
+- **C7 — Plugin boundary.** The packaged Skill resolves `scripts/workspace_scope.py` from the host-provided plugin root
+  when available, with an installed-Skill fallback. The wrapper deliberately sets `CLAUDE_PLUGIN_ROOT` to
+  `harness/plugin-root`, whose fixture returns only the fictional Scope and rejects bind/clear operations. The pinned
+  Skill is unchanged by the harness. This evaluates guidance after controlled Scope resolution; it does not qualify
+  the actual plugin helper, the fallback path, or standalone packaging.
 - **C8 — Host boundary.** Only Claude Code + MCP is covered. Results do not qualify Codex, Hermes, WorkBuddy, OpenCode,
   Pi, OpenClaw, or the portable Agent Plugin.
 

evaluation/skills/skill-up/skill-lock.json

@@ -1,12 +1,13 @@
 {
   "schema_version": 1,
   "source_path": "integrations/claude-code/plugins/powercontext/skills/powercontext-project-context",
-  "source_commit": "38432c5a2acbdd03f77137c0daa26a2bb7be09d3",
+  "source_commit": "59fc8b3ca217e63fa37a2980fd0c0a04fe5e516a",
   "files": {
-    "SKILL.md": "fd6aec8d2ee4e4aa522f8ecf75138b640c3d197c02401c5d3185089d7b345ac3",
-    "references/review-publication.md": "83f3fa674d83785d06945669cbbe08b6d679665fed7e165d778dbfbcd9d10841",
-    "references/scope-memory.md": "fee4042a82841e4d16d544bfac2440f724c3f5796e47974732cd364f587e97d9",
-    "references/work-handoff.md": "76dea45b708f2155e395029afe57b31ac112d8b13d614a6ab604aa436e3d2b2e"
+    ".powercontext-guidance.json": "e4ee4acbeccb65a95ed8d6b54f518d19d77d1aa5f6b629666ff9ae62abf8b0d2",
+    "SKILL.md": "5638a6abdae13fd7ae4dad43472aaf3cbfb1e61d2cb9c945ab0d61bd9e4112f3",
+    "references/review-publication.md": "844c3b4796d3b4e961bc943785dbe3c71960424644601b661b155fa9a6f8f3fe",
+    "references/scope-memory.md": "f84c8dc933cdfe9934bc50fd23cb53f4d6a3631506700bfdfff4731fe43e6818",
+    "references/work-handoff.md": "248069bc7f69268ba90de38b2537fe9a385d4a220a35c54603d53e16df10988f"
   },
-  "content_sha256": "681a4e2edc82d75db8078963e1c661286540ddcb651dd2db4249153863de019d"
+  "content_sha256": "f7a906e9db3b705d52f7bfbb46207c99a850d17a20a68ec5b13870ce8fd077ae"
 }

evaluation/skills/skill-up/vendor/powercontext-project-context/.powercontext-guidance.json

@@ -0,0 +1,15 @@
+{
+  "legacy_sha256": {
+    "SKILL.md": "fd6aec8d2ee4e4aa522f8ecf75138b640c3d197c02401c5d3185089d7b345ac3",
+    "references/review-publication.md": "83f3fa674d83785d06945669cbbe08b6d679665fed7e165d778dbfbcd9d10841",
+    "references/scope-memory.md": "6858a67a67fe83164234c2cdce42e094def4e1821034816739be31635c8a2943",
+    "references/work-handoff.md": "76dea45b708f2155e395029afe57b31ac112d8b13d614a6ab604aa436e3d2b2e"
+  },
+  "resources": [
+    "SKILL.md",
+    "references/review-publication.md",
+    "references/scope-memory.md",
+    "references/work-handoff.md"
+  ],
+  "schema_version": 1
+}

evaluation/skills/skill-up/vendor/powercontext-project-context/SKILL.md

@@ -1,4 +1,5 @@
 ---
+# POWERCONTEXT-GUIDANCE:START
 name: powercontext-project-context
 description: PowerContext memory search/save, inventory, work handoff and candidate review (搜索记忆、记住、盘点、交接、审查候选). Use for explicit requests or missing project history; ordinary coding and current-context summaries need no Skill detour.
 ---
@@ -32,3 +33,6 @@ Automatic capture is only Source acceptance, not proof of saved Memory or succes
 Check actual returned results: empty search is normal; failed, denied, unavailable, and unknown outcomes are distinct.
 Do not claim saved, committed, approved, installed, or executed without the corresponding result. A timed-out write has
 an unknown outcome: inspect status when available before retrying. A Skill itself grants no execution authority.
+
+Semantic recall or vector indexing may use the configured embedding provider and incur external API cost; cached embeddings can be reused, and preparing context reuses the query embedding. Respect the configured budget and existing authorization before starting additional indexing.
+<!-- POWERCONTEXT-GUIDANCE:END -->

evaluation/skills/skill-up/vendor/powercontext-project-context/references/review-publication.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Review and publication
 
 ## Inspect and decide
@@ -8,3 +10,4 @@ and the host exposes the operation, use `approve_artifact_candidate`, `reject_ar
 `revise_artifact_candidate` with the exact current `candidate_id` and `expected_version`. After a version conflict,
 read the changed proposal again; authorization for an old proposal does not silently approve new content.
 Approval does not install, publish, or execute an artifact. Preserve any stricter host review policy.
+<!-- POWERCONTEXT-GUIDANCE:END -->

evaluation/skills/skill-up/vendor/powercontext-project-context/references/scope-memory.md

@@ -1,11 +1,13 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Scope and Memory
 
 ## Resolve scope
 
-Before the first memory tool call, run:
+Before the first memory tool call, set `PLUGIN_ROOT` to the host-provided `CLAUDE_PLUGIN_ROOT` when available and verify that `scripts/workspace_scope.py` exists there. Otherwise, locate this installed Skill file: its plugin root is two directories above the Skill directory. Use that absolute path; do not assume a hook-only environment variable is available in an ordinary tool shell. Then run:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" --cwd "$PWD"
+python3 "${PLUGIN_ROOT}/scripts/workspace_scope.py" --cwd "$PWD"
 ```
 
 Reuse that exact `scope_id` for the task.
@@ -15,7 +17,7 @@ bindings, and finally its default Scope. When the user explicitly asks to bind
 the current checkout to a known Scope, run:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" \
+python3 "${PLUGIN_ROOT}/scripts/workspace_scope.py" \
   --cwd "$PWD" --bind-scope "SCOPE_ID"
 ```
 
@@ -65,3 +67,4 @@ chain. Legacy `revise_memory_entry` and `retire_memory_entry` are not current MC
 
 
 Automatic hooks attempt bounded context and Source capture; neither substitutes for an explicit Memory save.
+<!-- POWERCONTEXT-GUIDANCE:END -->

evaluation/skills/skill-up/vendor/powercontext-project-context/references/work-handoff.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Work Handoff
 
 ## Current-work Handoff input
@@ -65,3 +67,4 @@ the exact Receipt SourceRef as `handoff_receipt_ref`. Preserve failed, skipped,
 timed-out, unavailable, cancelled, and unknown checks exactly.
 
 For a preview, use inspected current facts without capture, prepare, or commit. Preserve the complete returned carrier, including required nullable fields and generation receipts.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/agent-plugin/powercontext/skills/powercontext-project-context/.powercontext-guidance.json

@@ -0,0 +1,15 @@
+{
+  "legacy_sha256": {
+    "SKILL.md": "fd6aec8d2ee4e4aa522f8ecf75138b640c3d197c02401c5d3185089d7b345ac3",
+    "references/review-publication.md": "83f3fa674d83785d06945669cbbe08b6d679665fed7e165d778dbfbcd9d10841",
+    "references/scope-memory.md": "1e6310ddd4e34028eb2ad0a4e393a6ff77b552e93f568251cb7fd82f82f9bfb9",
+    "references/work-handoff.md": "cf3ef4386ead7653431c60faa53c2ac045acd8db92cea6a214332f5c3aaeff8b"
+  },
+  "resources": [
+    "SKILL.md",
+    "references/review-publication.md",
+    "references/scope-memory.md",
+    "references/work-handoff.md"
+  ],
+  "schema_version": 1
+}

integrations/agent-plugin/powercontext/skills/powercontext-project-context/SKILL.md

@@ -1,4 +1,5 @@
 ---
+# POWERCONTEXT-GUIDANCE:START
 name: powercontext-project-context
 description: PowerContext memory search/save, inventory, work handoff and candidate review (搜索记忆、记住、盘点、交接、审查候选). Use for explicit requests or missing project history; ordinary coding and current-context summaries need no Skill detour.
 ---
@@ -32,3 +33,6 @@ Automatic capture is only Source acceptance, not proof of saved Memory or succes
 Check actual returned results: empty search is normal; failed, denied, unavailable, and unknown outcomes are distinct.
 Do not claim saved, committed, approved, installed, or executed without the corresponding result. A timed-out write has
 an unknown outcome: inspect status when available before retrying. A Skill itself grants no execution authority.
+
+Semantic recall or vector indexing may use the configured embedding provider and incur external API cost; cached embeddings can be reused, and preparing context reuses the query embedding. Respect the configured budget and existing authorization before starting additional indexing.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/agent-plugin/powercontext/skills/powercontext-project-context/references/review-publication.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Review and publication
 
 ## Inspect and decide
@@ -8,3 +10,4 @@ and the host exposes the operation, use `approve_artifact_candidate`, `reject_ar
 `revise_artifact_candidate` with the exact current `candidate_id` and `expected_version`. After a version conflict,
 read the changed proposal again; authorization for an old proposal does not silently approve new content.
 Approval does not install, publish, or execute an artifact. Preserve any stricter host review policy.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/agent-plugin/powercontext/skills/powercontext-project-context/references/scope-memory.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Scope and Memory
 
 ## Resolve Scope
@@ -52,3 +54,4 @@ chain. Legacy `revise_memory_entry` and `retire_memory_entry` are not current MC
 
 
 Automatic hooks attempt bounded context and Source capture; neither substitutes for an explicit Memory save.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/agent-plugin/powercontext/skills/powercontext-project-context/references/work-handoff.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Work Handoff
 
 ## Current-work Handoff input
@@ -43,3 +45,4 @@ with the objective, exact status, observations, checks, produced Artifacts, and
 remaining work. Do not treat every session stop as task completion.
 
 For a preview, use inspected current facts without capture, prepare, or commit. Preserve the complete returned carrier, including required nullable fields and generation receipts.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/claude-code/plugins/powercontext/skills/powercontext-project-context/.powercontext-guidance.json

@@ -0,0 +1,15 @@
+{
+  "legacy_sha256": {
+    "SKILL.md": "fd6aec8d2ee4e4aa522f8ecf75138b640c3d197c02401c5d3185089d7b345ac3",
+    "references/review-publication.md": "83f3fa674d83785d06945669cbbe08b6d679665fed7e165d778dbfbcd9d10841",
+    "references/scope-memory.md": "6858a67a67fe83164234c2cdce42e094def4e1821034816739be31635c8a2943",
+    "references/work-handoff.md": "76dea45b708f2155e395029afe57b31ac112d8b13d614a6ab604aa436e3d2b2e"
+  },
+  "resources": [
+    "SKILL.md",
+    "references/review-publication.md",
+    "references/scope-memory.md",
+    "references/work-handoff.md"
+  ],
+  "schema_version": 1
+}

integrations/claude-code/plugins/powercontext/skills/powercontext-project-context/SKILL.md

@@ -1,4 +1,5 @@
 ---
+# POWERCONTEXT-GUIDANCE:START
 name: powercontext-project-context
 description: PowerContext memory search/save, inventory, work handoff and candidate review (搜索记忆、记住、盘点、交接、审查候选). Use for explicit requests or missing project history; ordinary coding and current-context summaries need no Skill detour.
 ---
@@ -32,3 +33,6 @@ Automatic capture is only Source acceptance, not proof of saved Memory or succes
 Check actual returned results: empty search is normal; failed, denied, unavailable, and unknown outcomes are distinct.
 Do not claim saved, committed, approved, installed, or executed without the corresponding result. A timed-out write has
 an unknown outcome: inspect status when available before retrying. A Skill itself grants no execution authority.
+
+Semantic recall or vector indexing may use the configured embedding provider and incur external API cost; cached embeddings can be reused, and preparing context reuses the query embedding. Respect the configured budget and existing authorization before starting additional indexing.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/claude-code/plugins/powercontext/skills/powercontext-project-context/references/review-publication.md

@@ -1,3 +1,5 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Review and publication
 
 ## Inspect and decide
@@ -8,3 +10,4 @@ and the host exposes the operation, use `approve_artifact_candidate`, `reject_ar
 `revise_artifact_candidate` with the exact current `candidate_id` and `expected_version`. After a version conflict,
 read the changed proposal again; authorization for an old proposal does not silently approve new content.
 Approval does not install, publish, or execute an artifact. Preserve any stricter host review policy.
+<!-- POWERCONTEXT-GUIDANCE:END -->

integrations/claude-code/plugins/powercontext/skills/powercontext-project-context/references/scope-memory.md

@@ -1,11 +1,13 @@
+
+<!-- POWERCONTEXT-GUIDANCE:START -->
 # Scope and Memory
 
 ## Resolve scope
 
-Before the first memory tool call, run:
+Before the first memory tool call, set `PLUGIN_ROOT` to the host-provided `CLAUDE_PLUGIN_ROOT` when available and verify that `scripts/workspace_scope.py` exists there. Otherwise, locate this installed Skill file: its plugin root is two directories above the Skill directory. Use that absolute path; do not assume a hook-only environment variable is available in an ordinary tool shell. Then run:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" --cwd "$PWD"
+python3 "${PLUGIN_ROOT}/scripts/workspace_scope.py" --cwd "$PWD"
 ```
 
 Reuse that exact `scope_id` for the task.
@@ -15,7 +17,7 @@ bindings, and finally its default Scope. When the user explicitly asks to bind
 the current checkout to a known Scope, run:
 
 ```bash
-python3 "${CLAUDE_PLUGIN_ROOT}/scripts/workspace_scope.py" \
+python3 "${PLUGIN_ROOT}/scripts/workspace_scope.py" \
   --cwd "$PWD" --bind-scope "SCOPE_ID"
 ```
 
@@ -65,3 +67,4 @@ chain. Legacy `revise_memory_entry` and `retire_memory_entry` are not current MC
 
 
 Automatic hooks attempt bounded context and Source capture; neither substitutes for an explicit Memory save.
+<!-- POWERCONTEXT-GUIDANCE:END -->