@foggy-projects/deepseek-harness-plugin 0.4.0-beta.3 → 0.4.0-beta.4

package/README.md

@@ -8,7 +8,7 @@ only when the user selects **Initialize Foggy**.
 ## Local beta installation
 
 ```powershell
-dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.3.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.0-beta.4.tgz
 ```
 
 Restart `dsh web`, open Settings → Plugins → Foggy Data Analysis, and initialize
@@ -27,6 +27,21 @@ asset-cache directories. Neither variable is required for a normal install.
 Database credentials are deliberately outside the ordinary DSH settings
 document. The database and semantic-layer wizard is the next Bundle milestone.
 
+## Managed workspace contract
+
+Initialization writes a non-secret discovery document at
+`.foggy/deepseek-harness/context.json` in the selected project. It points agents
+to the authoritative global install state, the managed CLI's absolute command,
+the Runtime state, and the two workspace Skills. The managed CLI is intentionally
+isolated and does not need to be on `PATH`.
+
+Both `foggy-deepseek-onboarding` and `foggy-ai-analysis` carry a
+`.foggy-managed-skill.json` marker. **Re-download / Repair** verifies their
+managed content, backs up a modified or outdated Skill under
+`.foggy/onboarding-backups`, restores missing content, and regenerates the
+project context. If a Skill is restored while Harness is already running, start
+a new task or restart Harness so its Skill registry can reload it.
+
 ## Linux and WSL2 experience
 
 Ubuntu and WSL2 users can use the checked-in preflighted installer under

package/experience/linux/prepare.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 DSH_VERSION="0.1.1-rc.2"
 PNPM_VERSION="11.7.0"
-PLUGIN_VERSION="0.4.0-beta.3"
+PLUGIN_VERSION="0.4.0-beta.4"
 PLUGIN_REF="v${PLUGIN_VERSION}"
 PLUGIN_REPOSITORY="https://github.com/foggy-projects/foggy-deepseek-harness-plugin.git"
 

package/lib/client.js

@@ -41,6 +41,8 @@ window.__ModuleLoader__.load({
       cli: 'CLI',
       launcher: 'Launcher',
       analysisSkill: '分析 Skill',
+      onboardingSkill: '引导 Skill',
+      projectContext: '项目安装上下文',
       python: 'Python',
       java: 'Java',
       installed: '已安装',
@@ -68,8 +70,9 @@ window.__ModuleLoader__.load({
       dataRoot: '数据目录',
       runtimeUrl: 'Runtime 地址',
       projectRoot: 'Skill 目标工作区',
+      contextPath: '对话发现文件',
       nextTitle: '后续配置',
-      nextCopy: 'Runtime 启动成功后，将继续进入数据库连接与语义层向导。数据库密码不会写入 DSH 普通设置。',
+      nextCopy: '对话会从项目内固定的 context.json 读取 CLI、Runtime 与 Skill 安装状态，不再依赖 PATH 猜测。Runtime 启动成功后，将继续进入数据库连接与语义层向导。',
       beta: 'Beta',
     }
 
@@ -88,6 +91,8 @@ window.__ModuleLoader__.load({
       cli: 'CLI',
       launcher: 'Launcher',
       analysisSkill: 'Analysis Skill',
+      onboardingSkill: 'Onboarding Skill',
+      projectContext: 'Project install context',
       python: 'Python',
       java: 'Java',
       installed: 'Installed',
@@ -115,8 +120,9 @@ window.__ModuleLoader__.load({
       dataRoot: 'Data',
       runtimeUrl: 'Runtime URL',
       projectRoot: 'Skill target workspace',
+      contextPath: 'Conversation discovery file',
       nextTitle: 'Next configuration',
-      nextCopy: 'After the Runtime starts, the database connection and semantic-layer wizard comes next. Database passwords are never stored in ordinary DSH settings.',
+      nextCopy: 'Conversations discover the installed CLI, Runtime, and Skills from the fixed project context.json instead of guessing from PATH. After Runtime starts, the database connection and semantic-layer wizard comes next.',
       beta: 'Beta',
     }
 
@@ -264,8 +270,8 @@ window.__ModuleLoader__.load({
           jsxs('div', { className: 'foggy-state', children: [jsx('span', { className: 'foggy-dot', 'data-state': status.state }), jsx('span', { children: t(stateLabels[status.state] || 'notInstalled') })] }),
           jsxs('div', { className: 'foggy-actions', children: [
             jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: refresh, children: t('refresh') }),
-            !status.installed ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('initialize'), children: t('initialize') }) : null,
-            status.installed ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repair'), children: t('repair') }) : null,
+            status.state === 'not-installed' ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('initialize'), children: t('initialize') }) : null,
+            status.state !== 'not-installed' ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('repair'), children: t('repair') }) : null,
             status.installed && !status.running && status.components.java.available ? jsx('button', { className: 'foggy-button foggy-button-primary', type: 'button', disabled: busy, onClick: () => run('runtimeStart'), children: t('start') }) : null,
             status.running ? jsx('button', { className: 'foggy-button', type: 'button', disabled: busy, onClick: () => run('runtimeStop'), children: t('stop') }) : null,
           ] }),
@@ -278,6 +284,8 @@ window.__ModuleLoader__.load({
           componentCard(t('cli'), status.components.cli, 'runtime', t),
           componentCard(t('launcher'), status.components.launcher, 'runtime', t),
           componentCard(t('analysisSkill'), status.components.analysisSkill, 'runtime', t),
+          componentCard(t('onboardingSkill'), status.components.onboardingSkill, 'runtime', t),
+          componentCard(t('projectContext'), status.components.projectContext, 'runtime', t),
         ] }),
         jsxs('div', { className: 'foggy-paths', children: [
           jsx('h4', { children: t('roots') }),
@@ -285,6 +293,7 @@ window.__ModuleLoader__.load({
             jsx('dt', { children: t('installRoot') }), jsx('dd', { children: status.roots.installRoot }),
             jsx('dt', { children: t('dataRoot') }), jsx('dd', { children: status.roots.dataRoot }),
             jsx('dt', { children: t('projectRoot') }), jsx('dd', { children: status.projectRoot }),
+            jsx('dt', { children: t('contextPath') }), jsx('dd', { children: status.contextPath }),
             status.runtimeUrl ? jsx('dt', { children: t('runtimeUrl') }) : null,
             status.runtimeUrl ? jsx('dd', { children: status.runtimeUrl }) : null,
           ] }),

package/lib/index.js

@@ -129,9 +129,11 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 
   async status() {
     const roots = defaultRoots()
+    const projectRoot = process.env.FOGGY_PROJECT_ROOT || process.cwd()
     const statePath = join(roots.installRoot, 'install-state.json')
     const runtimeStatePath = join(roots.dataRoot, 'runtime-state.json')
     const progressPath = join(roots.dataRoot, 'operation-progress.json')
+    const contextPath = join(projectRoot, '.foggy', 'deepseek-harness', 'context.json')
     const manifest = await readJson(versionsFile)
     let pythonProbe
     try {
@@ -143,10 +145,16 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
     let state = null
     let runtime = null
+    let context = null
     try { state = await readJson(statePath) } catch {}
     try { runtime = await readJson(runtimeStatePath) } catch {}
+    try { context = await readJson(contextPath) } catch {}
     const cliPath = state?.cli?.command
     const launcherPath = state?.launcher?.path
+    const analysisSkillPath = state?.skills?.analysis?.path || join(projectRoot, '.agents', 'skills', 'foggy-ai-analysis')
+    const onboardingSkillPath = state?.skills?.onboarding?.path || join(projectRoot, '.agents', 'skills', 'foggy-deepseek-onboarding')
+    const analysisMarker = await readOptionalJson(join(analysisSkillPath, '.foggy-managed-skill.json'))
+    const onboardingMarker = await readOptionalJson(join(onboardingSkillPath, '.foggy-managed-skill.json'))
     const components = {
       python,
       java,
@@ -159,11 +167,36 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         version: state?.launcher?.version ?? manifest.components.launcher.version,
       },
       analysisSkill: {
-        installed: Boolean(state?.skills?.analysis?.path && await exists(state.skills.analysis.path)),
+        installed: Boolean(
+          await exists(join(analysisSkillPath, 'SKILL.md'))
+          && analysisMarker?.schemaVersion === 'foggy-managed-skill/v1'
+          && analysisMarker?.componentVersion === manifest.components.analysisSkill.version
+        ),
         version: state?.skills?.analysis?.version ?? manifest.components.analysisSkill.version,
       },
+      onboardingSkill: {
+        installed: Boolean(
+          await exists(join(onboardingSkillPath, 'SKILL.md'))
+          && onboardingMarker?.schemaVersion === 'foggy-managed-skill/v1'
+          && onboardingMarker?.packageVersion === manifest.packageVersion
+        ),
+        version: state?.skills?.onboarding?.version ?? state?.packageVersion ?? manifest.packageVersion,
+      },
+      projectContext: {
+        installed: Boolean(
+          context?.schemaVersion === 'foggy-deepseek-harness-context/v1'
+          && context?.packageVersion === manifest.packageVersion
+          && context?.projectRoot === projectRoot
+          && context?.installStatePath === statePath
+        ),
+        version: context?.schemaVersion ?? 'foggy-deepseek-harness-context/v1',
+      },
     }
-    const installed = components.cli.installed && components.launcher.installed && components.analysisSkill.installed
+    const installed = components.cli.installed
+      && components.launcher.installed
+      && components.analysisSkill.installed
+      && components.onboardingSkill.installed
+      && components.projectContext.installed
     const running = Boolean(runtime && processRunning(Number(runtime.pid)))
     const progress = await readOptionalJson(progressPath)
     let operation = operationView(this.operation)
@@ -189,7 +222,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       running,
       runtimeUrl: running ? runtime.runtimeUrl ?? null : null,
       roots,
-      projectRoot: process.env.FOGGY_PROJECT_ROOT || process.cwd(),
+      projectRoot,
+      contextPath,
       components,
       operation,
       next: installed ? (running ? 'configure-database' : 'start-runtime') : 'initialize',
@@ -208,7 +242,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         'create isolated Python environment',
         'download and verify pinned CLI and Launcher assets',
         'install Foggy analysis and onboarding Skills into the workspace',
-        'write local install state',
+        'write global install state and project-relative discovery context',
       ],
       secretsInDshSettings: false,
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0-beta.4",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",

package/skills/foggy-deepseek-onboarding/SKILL.md

@@ -7,6 +7,23 @@ description: Install and operate a pinned Foggy CLI-first dev/test environment f
 
 Set up Foggy through shell and `foggy-runtime` CLI. Do not configure Foggy MCP for this local workflow.
 
+## Installed-context gate
+
+Before deciding that Foggy, its CLI, or either Skill is missing, look for the project-relative file
+`.foggy/deepseek-harness/context.json` from the current workspace root:
+
+- Treat a valid `foggy-deepseek-harness-context/v1` document as the discovery pointer to the global
+  install state, absolute managed CLI command, Runtime state, and both installed Skills.
+- Confirm the installation with this Skill's `doctor` wrapper. The absence of `foggy-runtime` from
+  `PATH` is not evidence that the managed CLI is missing; the plugin intentionally installs it in an
+  isolated environment and records its absolute command in the context and install-state files.
+- Do not independently download or reinstall the CLI when valid project context exists. If the
+  context, a managed marker, or a Skill is missing or invalid, ask the user to open the Foggy plugin
+  settings and use **Re-download / Repair**. That operation regenerates context and restores managed
+  Skills, preserving a backup of modified or outdated Skill directories.
+- If the plugin reports ready but this Skill was restored during the current Harness task, tell the
+  user that a new task or Harness restart may be needed for the Skill registry to reload.
+
 ## Mandatory orchestration boundary
 
 For every new-database onboarding session, this Skill is the orchestration authority until
@@ -42,10 +59,11 @@ For every new-database onboarding session, this Skill is the orchestration autho
 
 ## Workflow
 
-1. Run `scripts/doctor.ps1 --project-root <root>` on Windows or
+1. Read `.foggy/deepseek-harness/context.json`, then run `scripts/doctor.ps1 --project-root <root>` on Windows or
    `bash scripts/doctor.sh --project-root <root>` on Linux.
-2. If the pinned CLI, Launcher, or analysis Skill is missing, run the matching `install` script. Use
-   `--dry-run` first when paths or permissions are uncertain.
+2. If the pinned CLI, Launcher, project context, or either managed Skill is missing, use the Foggy
+   plugin's Repair action. Use the matching install script only when the plugin UI is unavailable;
+   use `--dry-run` first when paths or permissions are uncertain.
 3. Run `runtime-start` and require successful `wait-ready` plus `capabilities`. Record engine,
    Runtime API version, schema version, security mode, URL, namespace, PID, and evidence path.
 4. Confirm the project contains `.agents/skills/foggy-ai-analysis/SKILL.md`.

package/skills/foggy-deepseek-onboarding/assets/versions.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
-  "packageVersion": "0.4.0-beta.3",
+  "packageVersion": "0.4.0-beta.4",
   "validatedAt": "2026-08-28",
   "components": {
     "deepseekHarness": {

package/skills/foggy-deepseek-onboarding/scripts/onboarding.py

@@ -25,6 +25,10 @@ import zipfile
 STATE_SCHEMA = "foggy-deepseek-onboarding-install/v1"
 RUNTIME_STATE_SCHEMA = "foggy-deepseek-onboarding-runtime/v1"
 ONBOARDING_STATE_SCHEMA = "foggy-deepseek-onboarding-state/v1"
+CONTEXT_SCHEMA = "foggy-deepseek-harness-context/v1"
+MANAGED_SKILL_SCHEMA = "foggy-managed-skill/v1"
+MANAGED_SKILL_MARKER = ".foggy-managed-skill.json"
+LEGACY_SKILL_MARKER = ".foggy-onboarding-install.json"
 CONNECTION_SCHEMA = "foggy-deepseek-connection/v1"
 SEMANTIC_PLAN_SCHEMA = "foggy-deepseek-semantic-plan/v1"
 PROFILE_PATTERN = re.compile(r"^[a-z0-9][a-z0-9._-]{0,62}$")
@@ -331,6 +335,145 @@ def atomic_json(path: Path, payload: dict) -> None:
     os.replace(temporary, path)
 
 
+def skill_tree_digest(root: Path) -> str:
+    """Hash managed Skill content while ignoring generated and management files."""
+    digest = hashlib.sha256()
+    ignored_names = {MANAGED_SKILL_MARKER, LEGACY_SKILL_MARKER}
+    files = sorted(
+        path for path in root.rglob("*")
+        if path.is_file()
+        and path.name not in ignored_names
+        and "__pycache__" not in path.parts
+        and path.suffix != ".pyc"
+    )
+    for path in files:
+        relative = path.relative_to(root).as_posix().encode("utf-8")
+        digest.update(len(relative).to_bytes(4, "big"))
+        digest.update(relative)
+        with path.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+    return digest.hexdigest()
+
+
+def read_skill_marker(destination: Path) -> dict | None:
+    for name in (MANAGED_SKILL_MARKER, LEGACY_SKILL_MARKER):
+        marker = destination / name
+        if marker.is_file():
+            try:
+                payload = json.loads(marker.read_text(encoding="utf-8"))
+                if isinstance(payload, dict):
+                    return payload
+            except (OSError, json.JSONDecodeError):
+                return None
+    return None
+
+
+def managed_skill_status(destination: Path, kind: str, expected_version: str) -> dict:
+    marker = read_skill_marker(destination)
+    present = (destination / "SKILL.md").is_file()
+    actual_digest = skill_tree_digest(destination) if destination.is_dir() else None
+    marker_digest = marker.get("installedDigest") if marker else None
+    managed = bool(
+        marker
+        and marker.get("schemaVersion") == MANAGED_SKILL_SCHEMA
+        and marker.get("kind") == kind
+    )
+    version = marker.get("componentVersion") if marker else None
+    return {
+        "path": str(destination),
+        "present": present,
+        "markerPresent": bool(marker),
+        "managed": managed,
+        "version": version,
+        "versionMatches": version == expected_version,
+        "integrityValid": bool(marker_digest and actual_digest == marker_digest),
+        "valid": bool(present and managed and version == expected_version and marker_digest and actual_digest == marker_digest),
+    }
+
+
+def write_skill_marker(
+    destination: Path,
+    *,
+    kind: str,
+    package_version: str,
+    component_version: str,
+    source_digest: str,
+    archive_sha256: str | None = None,
+) -> dict:
+    marker = {
+        "schemaVersion": MANAGED_SKILL_SCHEMA,
+        "kind": kind,
+        "managedBy": "@foggy-projects/deepseek-harness-plugin",
+        "packageVersion": package_version,
+        "componentVersion": component_version,
+        "sourceDigest": source_digest,
+        "installedDigest": skill_tree_digest(destination),
+        "installedAt": now_utc(),
+    }
+    if archive_sha256:
+        marker["archiveSha256"] = archive_sha256
+    atomic_json(destination / MANAGED_SKILL_MARKER, marker)
+    legacy = destination / LEGACY_SKILL_MARKER
+    if legacy.is_file():
+        legacy.unlink()
+    return marker
+
+
+def backup_skill(destination: Path, project_root: Path) -> Path:
+    backup_root = project_root / ".foggy" / "onboarding-backups"
+    backup_root.mkdir(parents=True, exist_ok=True)
+    backup = backup_root / f"{destination.name}-{dt.datetime.now().strftime('%Y%m%d-%H%M%S-%f')}"
+    shutil.move(str(destination), str(backup))
+    return backup
+
+
+def project_context_path(project_root: Path) -> Path:
+    return project_root / ".foggy" / "deepseek-harness" / "context.json"
+
+
+def project_relative(path: Path, project_root: Path) -> str:
+    try:
+        return path.resolve(strict=False).relative_to(project_root.resolve(strict=False)).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def write_project_context(state: dict) -> Path:
+    project_root = normalized(state["projectRoot"])
+    install_root = normalized(state["installRoot"])
+    data_root = normalized(state["dataRoot"])
+    context_path = project_context_path(project_root)
+    skills = {}
+    for kind in ("onboarding", "analysis"):
+        item = state["skills"][kind]
+        skill_path = normalized(item["path"])
+        skills[kind] = {
+            "version": item.get("version"),
+            "path": project_relative(skill_path, project_root),
+            "absolutePath": str(skill_path),
+            "markerPath": project_relative(skill_path / MANAGED_SKILL_MARKER, project_root),
+            "managed": bool(item.get("managed")),
+        }
+    payload = {
+        "schemaVersion": CONTEXT_SCHEMA,
+        "managedBy": "@foggy-projects/deepseek-harness-plugin",
+        "packageVersion": state["packageVersion"],
+        "generatedAt": now_utc(),
+        "projectRoot": str(project_root),
+        "installStatePath": str(install_root / "install-state.json"),
+        "runtimeStatePath": str(data_root / "runtime-state.json"),
+        "operationProgressPath": str(data_root / "operation-progress.json"),
+        "cli": state["cli"],
+        "launcher": state["launcher"],
+        "skills": skills,
+        "securityMode": state["securityMode"],
+        "productionReady": False,
+    }
+    atomic_json(context_path, payload)
+    return context_path
+
+
 def read_json_object(path: Path, label: str) -> dict:
     if not path.is_file():
         raise OnboardingError(f"{label} not found: {path}")
@@ -621,22 +764,16 @@ def safe_extract(zip_path: Path, destination: Path) -> None:
         archive.extractall(destination)
 
 
-def install_analysis_skill(zip_path: Path, project_root: Path, version: str, expected_hash: str, replace: bool) -> dict:
+def install_analysis_skill(
+    zip_path: Path,
+    project_root: Path,
+    version: str,
+    expected_hash: str,
+    package_version: str,
+    replace: bool,
+) -> dict:
     skills_root = project_root / ".agents" / "skills"
     destination = skills_root / "foggy-ai-analysis"
-    marker = destination / ".foggy-onboarding-install.json"
-    if destination.exists():
-        if marker.is_file():
-            installed = json.loads(marker.read_text(encoding="utf-8"))
-            if installed.get("archiveSha256") == expected_hash:
-                return {"path": str(destination), "version": version, "action": "kept-matching"}
-        if not replace:
-            raise OnboardingError(f"Analysis Skill already exists and is not managed at {destination}; rerun with --replace-skill to back it up")
-        backup_root = project_root / ".foggy" / "onboarding-backups"
-        backup_root.mkdir(parents=True, exist_ok=True)
-        backup = backup_root / f"foggy-ai-analysis-{dt.datetime.now().strftime('%Y%m%d-%H%M%S')}"
-        shutil.move(str(destination), str(backup))
-    skills_root.mkdir(parents=True, exist_ok=True)
     with tempfile.TemporaryDirectory(prefix="foggy-skill-") as temporary:
         extract_root = Path(temporary)
         safe_extract(zip_path, extract_root)
@@ -644,21 +781,81 @@ def install_analysis_skill(zip_path: Path, project_root: Path, version: str, exp
         if len(candidates) != 1:
             raise OnboardingError(f"Expected exactly one SKILL.md in analysis Skill archive, found {len(candidates)}")
         source = candidates[0].parent
+        source_digest = skill_tree_digest(source)
+        if destination.exists():
+            installed = read_skill_marker(destination)
+            actual_digest = skill_tree_digest(destination)
+            marker_matches = bool(
+                installed
+                and installed.get("schemaVersion") in (MANAGED_SKILL_SCHEMA, "foggy-installed-skill/v1")
+                and installed.get("archiveSha256") == expected_hash
+                and (installed.get("sourceDigest") or installed.get("installedDigest") or actual_digest) == source_digest
+                and actual_digest == source_digest
+            )
+            if marker_matches:
+                marker = write_skill_marker(
+                    destination,
+                    kind="analysis",
+                    package_version=package_version,
+                    component_version=version,
+                    source_digest=source_digest,
+                    archive_sha256=expected_hash,
+                )
+                return {"path": str(destination), "version": version, "digest": marker["installedDigest"], "managed": True, "action": "kept-matching"}
+            if not replace:
+                raise OnboardingError(f"Analysis Skill is missing, modified, or outdated at {destination}; use the plugin Repair action to back it up and restore it")
+            backup_skill(destination, project_root)
+        skills_root.mkdir(parents=True, exist_ok=True)
         shutil.copytree(source, destination)
-    atomic_json(marker, {"schemaVersion": "foggy-installed-skill/v1", "version": version, "archiveSha256": expected_hash})
-    return {"path": str(destination), "version": version, "action": "installed"}
+    marker = write_skill_marker(
+        destination,
+        kind="analysis",
+        package_version=package_version,
+        component_version=version,
+        source_digest=source_digest,
+        archive_sha256=expected_hash,
+    )
+    return {"path": str(destination), "version": version, "digest": marker["installedDigest"], "managed": True, "action": "installed"}
 
 
-def install_onboarding_skill(project_root: Path) -> dict:
+def install_onboarding_skill(project_root: Path, package_version: str, replace: bool) -> dict:
     destination = project_root / ".agents" / "skills" / "foggy-deepseek-onboarding"
     source = skill_root()
+    source_digest = skill_tree_digest(source)
     if source.resolve() == destination.resolve(strict=False):
-        return {"path": str(destination), "action": "already-running-from-target"}
+        return {"path": str(destination), "version": package_version, "digest": source_digest, "managed": True, "action": "already-running-from-target"}
     if destination.exists():
-        return {"path": str(destination), "action": "kept-existing"}
+        marker = read_skill_marker(destination)
+        actual_digest = skill_tree_digest(destination)
+        if (
+            marker
+            and marker.get("schemaVersion") == MANAGED_SKILL_SCHEMA
+            and marker.get("kind") == "onboarding"
+            and actual_digest == source_digest
+            and marker.get("sourceDigest") in (None, source_digest)
+            and marker.get("installedDigest") in (None, source_digest)
+        ):
+            written = write_skill_marker(
+                destination,
+                kind="onboarding",
+                package_version=package_version,
+                component_version=package_version,
+                source_digest=source_digest,
+            )
+            return {"path": str(destination), "version": package_version, "digest": written["installedDigest"], "managed": True, "action": "kept-matching"}
+        if not replace:
+            raise OnboardingError(f"Onboarding Skill is missing, modified, or outdated at {destination}; use the plugin Repair action to back it up and restore it")
+        backup_skill(destination, project_root)
     destination.parent.mkdir(parents=True, exist_ok=True)
     shutil.copytree(source, destination)
-    return {"path": str(destination), "action": "installed"}
+    marker = write_skill_marker(
+        destination,
+        kind="onboarding",
+        package_version=package_version,
+        component_version=package_version,
+        source_digest=source_digest,
+    )
+    return {"path": str(destination), "version": package_version, "digest": marker["installedDigest"], "managed": True, "action": "installed"}
 
 
 def read_install_state(install_root: Path, required: bool = True) -> dict | None:
@@ -820,11 +1017,12 @@ def install_command(args: argparse.Namespace) -> dict:
     zip_asset = next(item for item in analysis_assets if item["role"] == "zip")
     progress.update("analysis-skill", 3, "Installing analysis Skill", fraction=0.9, current_file=zip_asset["file"])
     analysis_skill = install_analysis_skill(
-        downloads / "skill" / zip_asset["file"], project_root, components["analysisSkill"]["version"], zip_asset["sha256"], args.replace_skill
+        downloads / "skill" / zip_asset["file"], project_root, components["analysisSkill"]["version"],
+        zip_asset["sha256"], versions["packageVersion"], args.replace_skill,
     )
     progress.update("analysis-skill", 3, "Analysis Skill ready", fraction=1.0)
     progress.update("workspace-skills", 4, "Installing onboarding Skill", fraction=0.1)
-    onboarding_skill = install_onboarding_skill(project_root)
+    onboarding_skill = install_onboarding_skill(project_root, versions["packageVersion"], args.replace_skill)
     progress.update("workspace-skills", 4, "Workspace Skills ready", fraction=1.0)
     state = {
         "schemaVersion": STATE_SCHEMA,
@@ -833,6 +1031,7 @@ def install_command(args: argparse.Namespace) -> dict:
         "installRoot": str(install_root),
         "dataRoot": str(data_root),
         "projectRoot": str(project_root),
+        "contextPath": str(project_context_path(project_root)),
         "cli": {"version": cli_component["version"], "command": str(cli_command), "mode": cli_mode},
         "launcher": {"version": components["launcher"]["version"], "path": str(launcher_dir)},
         "skills": {"onboarding": onboarding_skill, "analysis": analysis_skill},
@@ -842,6 +1041,8 @@ def install_command(args: argparse.Namespace) -> dict:
     }
     progress.update("state", 5, "Writing install state", fraction=0.2, current_file="install-state.json")
     atomic_json(install_root / "install-state.json", state)
+    progress.update("state", 5, "Writing project context", fraction=0.7, current_file=".foggy/deepseek-harness/context.json")
+    context_path = write_project_context(state)
     progress.finish()
     ACTIVE_PROGRESS = None
     return {
@@ -851,6 +1052,7 @@ def install_command(args: argparse.Namespace) -> dict:
         "installRoot": str(install_root),
         "dataRoot": str(data_root),
         "projectRoot": str(project_root),
+        "contextPath": str(context_path),
         "cliVersion": cli_component["version"],
         "launcherVersion": components["launcher"]["version"],
         "analysisSkill": analysis_skill,
@@ -2032,8 +2234,24 @@ def doctor_command(args: argparse.Namespace) -> dict:
             path = launcher_dir / asset["file"]
             launcher_checks.append({"file": asset["file"], "present": path.is_file(), "sha256Valid": path.is_file() and sha256(path) == asset["sha256"]})
     launcher_ok = bool(launcher_checks) and all(item["present"] and item["sha256Valid"] for item in launcher_checks)
-    analysis_skill = project_root / ".agents" / "skills" / "foggy-ai-analysis" / "SKILL.md"
-    onboarding_skill = project_root / ".agents" / "skills" / "foggy-deepseek-onboarding" / "SKILL.md"
+    analysis_skill_root = project_root / ".agents" / "skills" / "foggy-ai-analysis"
+    onboarding_skill_root = project_root / ".agents" / "skills" / "foggy-deepseek-onboarding"
+    analysis_skill = managed_skill_status(analysis_skill_root, "analysis", versions["components"]["analysisSkill"]["version"])
+    onboarding_skill = managed_skill_status(onboarding_skill_root, "onboarding", versions["packageVersion"])
+    context_path = project_context_path(project_root)
+    context = None
+    if context_path.is_file():
+        try:
+            context = json.loads(context_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            context = None
+    context_ok = bool(
+        context
+        and context.get("schemaVersion") == CONTEXT_SCHEMA
+        and context.get("packageVersion") == versions["packageVersion"]
+        and normalized(context.get("projectRoot", "")) == project_root
+        and normalized(context.get("installStatePath", "")) == install_root / "install-state.json"
+    )
     runtime = {"status": "stopped"}
     if state:
         data_root = normalized(state["dataRoot"])
@@ -2047,7 +2265,9 @@ def doctor_command(args: argparse.Namespace) -> dict:
         "java": java_ok,
         "cli": cli_ok,
         "launcher": launcher_ok,
-        "analysisSkill": analysis_skill.is_file(),
+        "analysisSkill": analysis_skill["valid"],
+        "onboardingSkill": onboarding_skill["valid"],
+        "projectContext": context_ok,
     }
     if args.strict_runtime:
         required["runtime"] = runtime["status"] == "running"
@@ -2061,7 +2281,8 @@ def doctor_command(args: argparse.Namespace) -> dict:
         "java": java,
         "cli": cli,
         "launcherAssets": launcher_checks,
-        "skills": {"analysis": str(analysis_skill), "onboarding": str(onboarding_skill), "onboardingPresent": onboarding_skill.is_file()},
+        "skills": {"analysis": analysis_skill, "onboarding": onboarding_skill},
+        "projectContext": {"path": str(context_path), "valid": context_ok},
         "runtime": runtime,
         "environmentPresence": {name: bool(os.environ.get(name)) for name in ("DEEPSEEK_API_KEY", "ALIYUN_TOKEN_PLAN_API_KEY", "FOGGY_RUNTIME_API_AUTH_CODE", "FOGGY_RUNTIME_AUTHORIZATION")},
         "productionReady": False,