@foggy-projects/deepseek-harness-plugin 0.4.0-beta.10

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

@@ -0,0 +1,137 @@
+---
+name: foggy-deepseek-onboarding
+description: Install and operate a pinned Foggy CLI-first dev/test environment from DeepSeek Harness, including opaque datasource profiles, resumable verification, and schema discovery before semantic authoring. Use for initial Foggy setup or local Runtime onboarding; do not use for production deployment or MCP configuration.
+---
+
+# Foggy DeepSeek onboarding
+
+Set up Foggy through shell and `foggy-runtime` CLI. Do not configure Foggy MCP for this local workflow.
+
+## Native registry and installed-state gate
+
+This Skill is registered by the Foggy plugin through DeepSeek Harness's native Skill registry. Its
+resource base is the authoritative location for these scripts and references; do not search for or
+copy this Skill into the current workspace.
+
+- Resolve the global install state from the platform default component directory: on Linux use
+  `${XDG_DATA_HOME:-$HOME/.local/share}/foggy/deepseek-harness/install-state.json`; on Windows use
+  `%LOCALAPPDATA%\Foggy\DeepSeekHarness\install-state.json`.
+- Confirm the installation with this Skill's `doctor` wrapper and pass the current DSH session
+  workspace as `--project-root`. 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 global install state.
+- The plugin downloads and verifies a pinned private Python runtime before running this Skill. Do not
+  search for, install, or repair a system Python. Wrappers resolve the interpreter recorded in the
+  global install state. If private Python is missing, use the plugin's Python repair action. Only use
+  `FOGGY_PYTHON` or `FOGGY_ONBOARDING_PYTHON` when the user explicitly supplied an advanced override.
+- Do not independently download or reinstall the CLI. If the global install state, managed marker, or
+  analysis Skill is missing or invalid, ask the user to open the Foggy plugin settings and use
+  the matching component repair action. Repair restores managed components and invalidates the
+  native DSH Skill catalog. Reinstall or upgrade the plugin itself to restore this bundled Skill.
+- Treat the current DSH session workspace as the authoritative `projectRoot` for the whole onboarding
+  run. Do not redirect semantic drafts or contracts to a different repository merely because another
+  Skill or example was found there. Place non-secret contracts below
+  `<projectRoot>/.foggy/onboarding-contracts/<profile>/`, drafts below
+  `<projectRoot>/.foggy/onboarding-drafts/<profile>/`, and published files below the approved
+  project-relative `modelsDir`.
+
+## Mandatory orchestration boundary
+
+For every new-database onboarding session, this Skill is the orchestration authority until
+`onboard-status` reports `next.status=completed`:
+
+- Invoke datasource, schema, semantic, bundle, and query operations only through this Skill's
+  `scripts/onboard.ps1` or `scripts/onboard.sh`. Do not call `foggy-runtime` directly for those
+  operations, even if another loaded Skill documents equivalent CLI commands.
+- Use `foggy-ai-analysis` only to author TM/QM draft content. Its general direct-CLI workflow does not
+  supersede this Skill's state machine, approval gates, names, paths, query limit, or evidence rules.
+- Use the exact profile, datasource, namespace, bundle, model names, paths, fields, and query limit
+  supplied or confirmed by the user. Do not replace them with examples or inferred alternatives.
+- Do not use raw SQL to sample business rows during onboarding. `schema-discover` is the metadata gate;
+  any later SQL probe requires separate explicit approval and must be bounded and read-only.
+- Never use `--replace`, `--replace-bundle`, `--prune`, `--watch`, or `--execute` unless that exact
+  mutation was explicitly approved. Approval for adding a new resource is not approval to replace one.
+- Save each wrapper result as the single JSON object returned on stdout when the user requests evidence.
+  Do not claim completion when required evidence is missing or the persisted status is incomplete.
+- Never read query-execution evidence back into the conversation. Report only validation state,
+  execution state, row count, and evidence path; do not report row values or generated SQL containing
+  business literals.
+- Prefer one composite command per approval boundary. Do not inspect this Skill's Python implementation
+  or the CLI package source during a normal run; use the documented command contract and inspect code
+  only after a structured wrapper error requires troubleshooting.
+
+## Boundaries
+
+- Treat the bundled Launcher as local dev/test only. Its expected security mode is
+  `none-dev-test-only`; never expose it to a network.
+- Do not print, persist, or request secrets in chat. Use named environment variables or a private env
+  file outside the Skill and evidence directories.
+- Do not modify Foggy engine or CLI source. If setup cannot continue without such a change, stop and
+  ask the user for explicit authorization.
+- Before downloads, installs, replacement, Runtime start/stop, or removal, state the concrete action
+  and obtain any authorization required by the host.
+
+## Workflow
+
+1. Run `scripts/doctor.ps1 --project-root <current-session-workspace>` on Windows or
+   `bash scripts/doctor.sh --project-root <current-session-workspace>` on Linux.
+2. If private Python, the pinned CLI, Launcher, or global managed analysis Skill is missing, use the
+   Foggy plugin's matching Repair action. First-time Python bootstrap requires the plugin UI unless
+   the user explicitly supplies `FOGGY_ONBOARDING_PYTHON`. Use a matching install script only after
+   private Python exists and 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. If the
+   recorded Runtime is already running, `runtime-start` verifies and reuses it instead of starting a
+   second process.
+4. Load `foggy-ai-analysis` from the native DSH Skill registry. Do not require a workspace copy.
+5. For a new business database, read [references/onboarding-workflow.md](references/onboarding-workflow.md)
+   and prefer its two composite `onboard-datasource-run` / `onboard-semantic-run` commands. Require the
+   trusted operator to create the private CLI profile outside Harness. Unless the operator explicitly
+   overrides it, use the persistent profile store reported by the wrapper under the Foggy data root
+   (`<dataRoot>/cli-profiles`), never `/tmp`. Accept only the opaque profile
+   ID, exact revision, datasource name/type, and namespace; never request JDBC URL, username,
+   password, or password environment-variable name in Harness.
+   If plugin settings report a legacy temporary profile, use the explicit migration action before
+   onboarding. It moves only validated connection metadata and environment-variable references; it
+   never copies a password value and leaves a recoverable private backup below the Foggy data root.
+6. After schema discovery, use `foggy-ai-analysis` only to author TM/QM files in the standard project-local
+   draft directory. Register, validate, publish, and verify them through this Skill's wrapper using the deterministic commands in
+   [references/onboarding-workflow.md](references/onboarding-workflow.md). Do not publish, prune, replace
+   a bundle, or execute a business-data query without the matching explicit flag and user approval.
+7. Stop only the Runtime PID recorded by this package. Preserve Runtime data unless the user explicitly
+   requests purge.
+
+## Command contract
+
+All package scripts return one JSON object on stdout. Treat `success=false` or a nonzero exit code as a
+failure. Do not infer readiness from a fixed sleep; require CLI `wait-ready` and `capabilities`.
+
+Use this analysis order after setup:
+
+```text
+datasource test -> bind -> diagnostics
+tables list -> inspect -> optional bounded read-only SQL
+models validate -> bundles add/update -> models refresh -> models describe
+query validate -> query execute -> interpretation
+```
+
+In DeepSeek Harness, do not expand the composite onboarding commands back into these individual CLI
+operations. This order documents what the wrapper enforces internally and becomes a direct CLI workflow
+only after onboarding is complete.
+
+Composite commands are checkpointed and idempotent: a retry skips completed datasource, validation,
+publication, and verification phases when the approved contract and draft digest are unchanged. Fix a
+query payload in place and rerun the same semantic composite command; do not remove a successfully
+published bundle merely to recover from a later query-validation failure.
+
+An already-completed profile may be reused from another DSH workspace when the approved connection
+contract is byte-for-byte equivalent. Run the datasource composite in the new workspace first; it adds
+that workspace as a non-destructive binding and reuses datasource/schema checkpoints. Then pass the
+current workspace explicitly as `--project-root` to the semantic composite. A secondary workspace may
+reuse an identical published semantic digest and run its own bounded verification query, but it cannot
+replace the published semantic layer; changes must be published from the original workspace or a new
+profile.
+
+Keep user business data separate from the sales-drop SQLite demo. Prefer a read-only database account,
+opaque CLI profile references, and bounded query limits.

package/skills/foggy-deepseek-onboarding/assets/connection.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://foggy-projects.dev/schemas/deepseek-harness/connection.schema.json",
+  "title": "Foggy DeepSeek Harness connection plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "name", "type", "namespace"],
+  "properties": {
+    "schemaVersion": {"const": "foggy-deepseek-connection/v1"},
+    "profile": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
+    "name": {"type": "string", "minLength": 1},
+    "type": {"enum": ["sqlite", "mysql", "postgres", "postgresql"]},
+    "jdbcUrl": {"type": "string", "minLength": 1},
+    "username": {"type": "string"},
+    "passwordEnv": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"},
+    "opaqueProfileId": {"type": "string", "pattern": "^fop_[a-f0-9]{32}$"},
+    "opaqueRevision": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$"},
+    "namespace": {"type": "string", "minLength": 1},
+    "schemas": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true},
+    "modelsDir": {"type": "string", "minLength": 1, "default": "models"},
+    "evidenceDir": {"type": "string", "minLength": 1},
+    "readOnlyRecommended": {"type": "boolean", "default": true}
+  },
+  "oneOf": [
+    {
+      "required": ["opaqueProfileId", "opaqueRevision"],
+      "not": {"anyOf": [
+        {"required": ["jdbcUrl"]},
+        {"required": ["username"]},
+        {"required": ["passwordEnv"]}
+      ]}
+    },
+    {
+      "required": ["jdbcUrl"],
+      "not": {"anyOf": [
+        {"required": ["opaqueProfileId"]},
+        {"required": ["opaqueRevision"]}
+      ]}
+    }
+  ],
+  "allOf": [
+    {
+      "if": {
+        "required": ["jdbcUrl"],
+        "properties": {"type": {"not": {"const": "sqlite"}}}
+      },
+      "then": {"required": ["passwordEnv"]}
+    }
+  ]
+}

package/skills/foggy-deepseek-onboarding/assets/datasource.example.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": "foggy-deepseek-connection/v1",
+  "profile": "business",
+  "name": "business-db",
+  "type": "mysql",
+  "opaqueProfileId": "fop_0123456789abcdef0123456789abcdef",
+  "opaqueRevision": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  "namespace": "business",
+  "schemas": ["public"],
+  "modelsDir": "models",
+  "evidenceDir": ".foggy/onboarding-command-evidence/business",
+  "readOnlyRecommended": true
+}

package/skills/foggy-deepseek-onboarding/assets/env.example

@@ -0,0 +1,14 @@
+# Copy only the variables you need into a private, gitignored env file.
+# Never put provider keys or database passwords in DSH settings, Skill files, or evidence.
+
+FOGGY_RUNTIME_API_URL=http://127.0.0.1:18066
+FOGGY_NAMESPACE=default
+
+# Optional when Runtime reports securityMode=auth-code.
+# FOGGY_RUNTIME_API_AUTH_CODE=
+
+# Optional data-plane authorization value.
+# FOGGY_RUNTIME_AUTHORIZATION=
+
+# Example datasource password reference. Use a datasource-specific variable name.
+# FOGGY_DATASOURCE_PASSWORD=

package/skills/foggy-deepseek-onboarding/assets/onboarding-state.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://foggy-projects.dev/schemas/deepseek-harness/onboarding-state.schema.json",
+  "title": "Foggy DeepSeek Harness resumable onboarding state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "profile", "installRoot", "dataRoot", "projectRoot", "connection", "semantic", "steps", "artifacts"],
+  "properties": {
+    "schemaVersion": {"const": "foggy-deepseek-onboarding-state/v1"},
+    "profile": {"type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$"},
+    "createdAt": {"type": "string", "format": "date-time"},
+    "updatedAt": {"type": "string", "format": "date-time"},
+    "installRoot": {"type": "string"},
+    "dataRoot": {"type": "string"},
+    "projectRoot": {"type": "string"},
+    "workspaceBindings": {
+      "type": "array",
+      "items": {"type": "string"},
+      "uniqueItems": true
+    },
+    "workspaceVerifications": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["projectRoot", "queryModel", "queryPayloadDigest", "verifiedAt"],
+        "properties": {
+          "projectRoot": {"type": "string"},
+          "queryModel": {"type": "string"},
+          "queryPayloadDigest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "rowCount": {"type": ["integer", "null"], "minimum": 0},
+          "verifiedAt": {"type": "string", "format": "date-time"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "runtime": {"type": "object"},
+    "connection": {"$ref": "connection.schema.json"},
+    "semantic": {"type": "object"},
+    "steps": {"type": "object"},
+    "artifacts": {"type": "object"}
+  }
+}

package/skills/foggy-deepseek-onboarding/assets/semantic-plan.example.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "foggy-deepseek-semantic-plan/v1",
+  "profile": "business",
+  "draftDir": ".foggy/onboarding-drafts/business",
+  "bundleName": "business-semantic",
+  "evidenceDir": ".foggy/onboarding-command-evidence/business",
+  "queryModels": ["FactOrderQueryModel"]
+}

package/skills/foggy-deepseek-onboarding/assets/semantic-plan.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://foggy-projects.dev/schemas/deepseek-harness/semantic-plan.schema.json",
+  "title": "Foggy DeepSeek Harness semantic draft plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "draftDir", "bundleName", "queryModels"],
+  "properties": {
+    "schemaVersion": {"const": "foggy-deepseek-semantic-plan/v1"},
+    "profile": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"},
+    "draftDir": {"type": "string", "minLength": 1},
+    "bundleName": {"type": "string", "minLength": 1},
+    "evidenceDir": {"type": "string", "minLength": 1},
+    "queryModels": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"}
+    }
+  }
+}

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

@@ -0,0 +1,137 @@
+{
+  "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
+  "packageVersion": "0.4.0-beta.10",
+  "validatedAt": "2026-09-04",
+  "components": {
+    "deepseekHarness": {
+      "version": "0.1.2-rc.1",
+      "minimumNodeVersion": "22.19.0"
+    },
+    "python": {
+      "version": "3.12.13",
+      "distribution": "astral-sh/python-build-standalone",
+      "buildRelease": "20260718",
+      "license": "Python-2.0 AND MPL-2.0",
+      "assets": {
+        "win32-x64": {
+          "file": "cpython-3.12.13+20260718-x86_64-pc-windows-msvc-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-x86_64-pc-windows-msvc-install_only_stripped.tar.gz",
+          "sha256": "0d422a1439ec308e03f47df551bc30f5994727c456e414b026d202bcda9b7c1c",
+          "size": 21932298
+        },
+        "win32-arm64": {
+          "file": "cpython-3.12.13+20260718-aarch64-pc-windows-msvc-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-aarch64-pc-windows-msvc-install_only_stripped.tar.gz",
+          "sha256": "596808d2592a282c45921a324d5503ef0d4f488d104c1c1f12a1d5e7dea9d463",
+          "size": 20652311
+        },
+        "linux-x64": {
+          "file": "cpython-3.12.13+20260718-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz",
+          "sha256": "5854aa6ec71cad00334d5065633c210b2e7feb40956767a59a91791cadcf0b79",
+          "size": 34199823
+        },
+        "linux-arm64": {
+          "file": "cpython-3.12.13+20260718-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz",
+          "sha256": "f226576b91491ffa5739aa85726521e9031f4d87f80627d64ed348ac77cb31e9",
+          "size": 29195696
+        },
+        "darwin-x64": {
+          "file": "cpython-3.12.13+20260718-x86_64-apple-darwin-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-x86_64-apple-darwin-install_only_stripped.tar.gz",
+          "sha256": "8e6b7e6533bdf746287008edf91102e7bee0a6ca1d24f16c4514237cafd706c5",
+          "size": 24685843
+        },
+        "darwin-arm64": {
+          "file": "cpython-3.12.13+20260718-aarch64-apple-darwin-install_only_stripped.tar.gz",
+          "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13%2B20260718-aarch64-apple-darwin-install_only_stripped.tar.gz",
+          "sha256": "9a1e9e06175c10efd8378b904b07fa21bd791ab3345d7cdffeb4a76c9ff55903",
+          "size": 25000146
+        }
+      }
+    },
+    "cli": {
+      "version": "0.1.23",
+      "minimumPythonVersion": "3.11.0",
+      "wheel": {
+        "file": "foggy_runtime_cli-0.1.23-py3-none-any.whl",
+        "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/foggy_runtime_cli-0.1.23-py3-none-any.whl",
+        "sha256": "db428812039e5961db93b5c0dc35b53a21d5c349428e6830c96fbf3218cf8a45"
+      },
+      "checksums": {
+        "file": "SHA256SUMS",
+        "url": "https://github.com/foggy-projects/foggy-runtime-cli/releases/download/v0.1.23/SHA256SUMS",
+        "sha256": "1494d7f13af18bef321995509058a1ab43b1d0b2e9f9ea08230dd78028090221"
+      }
+    },
+    "launcher": {
+      "version": "0.1.18",
+      "minimumJavaVersion": "17.0.0",
+      "runtimeApiContract": "foggy-runtime-api/v1",
+      "assets": [
+        {
+          "file": "foggy-runtime-launcher-0.1.18.jar",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/foggy-runtime-launcher-0.1.18.jar",
+          "sha256": "2953d2fab39208b3fffefed033b34ec6f59da851920b533047a1d0909a1de049"
+        },
+        {
+          "file": "start-foggy-runtime.ps1",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/start-foggy-runtime.ps1",
+          "sha256": "b54f2f144cfdc38afcc3e9167d0700248f476c93adb3e9d95431490430f7b549"
+        },
+        {
+          "file": "start-foggy-runtime.sh",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/start-foggy-runtime.sh",
+          "sha256": "e801cc340bf0842e29045e5e24798921864114846b0e1aaff30640845c8f37d0"
+        },
+        {
+          "file": "README-foggy-runtime-launcher.md",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/README-foggy-runtime-launcher.md",
+          "sha256": "0202546c5221cbb9343cf7367ceb20bff785fd85c2ba77cd0dac5395f6362674"
+        },
+        {
+          "file": "runtime-launcher-manifest.json",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/runtime-launcher-manifest.json",
+          "sha256": "0065de9c516471b936927a0b13ed1b9380c484437352b2e589c5171932427326"
+        },
+        {
+          "file": "SHA256SUMS",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.18/SHA256SUMS",
+          "sha256": "26f65a7112c115ccd19c6f80336b4335ab7773d54841376aa81504d1c3fcd21f"
+        }
+      ]
+    },
+    "analysisSkill": {
+      "name": "foggy-ai-analysis",
+      "version": "0.1.17",
+      "minimumCliVersion": "0.1.21",
+      "assets": [
+        {
+          "role": "zip",
+          "file": "foggy-ai-analysis-skill-0.1.17.zip",
+          "url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17.zip",
+          "sha256": "2c5a10090befc38dd2cf8c3de5121d19c28682ca9c0fe72daf778d315c56c7ff"
+        },
+        {
+          "role": "manifest",
+          "file": "foggy-ai-analysis-skill-0.1.17-manifest.json",
+          "url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17-manifest.json",
+          "sha256": "094b1401ff384f011ef80446dd639d8afb2585aa01d7a7ba49d39cb2968ae8bf"
+        },
+        {
+          "role": "checksums",
+          "file": "foggy-ai-analysis-skill-0.1.17-SHA256SUMS",
+          "url": "https://github.com/foggy-projects/foggy-ai-analysis/releases/download/v0.1.17/foggy-ai-analysis-skill-0.1.17-SHA256SUMS",
+          "sha256": "18804088cd7da7af6bbf70d658cb0d6a5a31e765470ed673dfd274f1789db240"
+        }
+      ]
+    }
+  },
+  "defaults": {
+    "port": 18066,
+    "namespace": "default",
+    "readinessTimeoutSeconds": 180,
+    "securityMode": "none-dev-test-only"
+  }
+}

package/skills/foggy-deepseek-onboarding/references/onboarding-workflow.md

@@ -0,0 +1,156 @@
+# Resumable database onboarding
+
+Use the thin `scripts/onboard.ps1` or `scripts/onboard.sh` entrypoint. Every command emits one JSON
+object. Preserve the returned `next` instruction and use `onboard-status` or `onboard-resume` after an
+interruption.
+
+The wrapper is mandatory for the entire sequence below. Until `onboard-status` returns
+`next.status=completed`, do not substitute direct `foggy-runtime datasources`, `tables`, `sql`, `models`,
+`bundles`, or `query` calls. A second Skill may help write draft TM/QM files, but must not take over
+orchestration. Do not inspect sample rows to author the semantic layer; use schema metadata plus the
+business definitions confirmed by the user.
+
+## Conversation contract
+
+Collect these non-secret values before creating a plan:
+
+1. an opaque Foggy profile ID and its exact reviewed revision;
+2. datasource name, database type, and namespace from the CLI's public profile summary;
+3. optional schemas, the project-relative semantic model directory, and a project-relative evidence directory.
+
+Create the private profile in a trusted operator session outside DeepSeek Harness. Do not ask the user
+to paste a password and do not put a JDBC URL, username, password environment-variable name, or password in the JSON plan, command
+line, logs, or evidence. For non-SQLite databases, ask the user to set the named environment variable
+before Runtime starts so the Java process inherits it. Recommend a read-only database account.
+
+Use the current DSH session workspace as `projectRoot`. Store approved non-secret contracts at
+`.foggy/onboarding-contracts/<profile>/`, semantic drafts at `.foggy/onboarding-drafts/<profile>/`, and
+command evidence at `.foggy/onboarding-command-evidence/<profile>/`. Do not split these files across the
+session workspace and a separate example repository. The wrapper rejects a query payload outside the
+recorded project root before any semantic validation or publication mutation occurs.
+
+The wrapper defaults `FOGGY_RUNTIME_PROFILE_STORE` to the private persistent directory
+`<dataRoot>/cli-profiles`. An explicit operator-provided value still wins. Do not use `/tmp` for a profile
+that must survive a WSL or Harness restart.
+
+If plugin settings detect profiles in the legacy temporary store, use **Move to persistent store**.
+Migration validates the opaque profile schema, rejects embedded passwords and conflicts, writes the
+destination with private permissions, verifies it, and moves the legacy JSON to a recoverable private
+backup below the Foggy data root.
+Do not manually copy or edit opaque profile JSON.
+
+Treat every user-supplied identifier and bound as immutable input: profile, datasource, namespace,
+models directory, bundle name, TM/QM name, query fields, and limit. Do not swap in demo names, add
+fields, raise the limit, or introduce replacement flags. If one of these inputs is missing, pause for
+that input rather than inventing it.
+
+For composite Harness execution, persist `profile` and `evidenceDir` inside both approved contract
+files. The wrapper derives them from the files and rejects conflicting command-line values. Present the
+normalized contracts to the user before accepting mutation approvals; do not combine contract drafting
+and approval into an unseen one-turn mutation.
+
+Write the non-secret input using `assets/connection.schema.json`; `assets/datasource.example.json` is a
+template. Then execute the sequence below.
+
+## Deterministic sequence
+
+For Harness-driven onboarding, use the two composite commands below. Each writes the numbered JSON
+evidence internally and refuses to cross an unapproved mutation gate:
+
+```text
+onboard-datasource-run --project-root <current-session-workspace> \
+  --connection-file <approved-json> \
+  --approve-configure --approve-bind --include-indexes
+
+# After authoring the registered TM/QM draft from schema metadata:
+onboard-semantic-run --project-root <current-session-workspace> \
+  --semantic-plan <approved-json> --query-payload <approved-json> \
+  --approve-validate --approve-publish --approve-execute
+```
+
+Include an approval flag only after the user approves that exact action. Without it, the composite
+command stops after the corresponding dry-run and returns `phaseStatus=awaiting-...-approval`.
+
+Both composite commands are resumable. When the approved contract is unchanged, they skip completed
+checkpoints instead of re-adding an existing datasource, revalidating an already published draft, or
+registering the same bundle twice. If query validation fails after publication, correct the project-local
+payload and rerun `onboard-semantic-run`; it resumes at query verification and leaves the active bundle in
+place. A same-name datasource is accepted idempotently only when its public name and database type match
+the approved plan; otherwise replacement still requires explicit approval.
+
+When a completed profile already belongs to another workspace, the datasource composite may add the
+current workspace as a binding only if the approved connection contract is identical and the datasource,
+schema, and semantic publication checkpoints are complete. The semantic composite then accepts the same
+published draft digest from the bound workspace and performs a workspace-specific bounded verification
+query. It refuses semantic replacement from the secondary workspace.
+
+The granular commands below remain available for manual troubleshooting and resumption. Do not expand
+the composite commands into this list during a normal Harness turn.
+
+```text
+onboard-plan --connection-file <json> --profile <profile>
+datasource-configure --profile <profile>
+datasource-configure --profile <profile> --apply
+datasource-verify --profile <profile>
+datasource-verify --profile <profile> --bind
+schema-discover --profile <profile> --include-indexes
+semantic-draft --profile <profile> --semantic-plan <json>
+semantic-validate --profile <profile>
+semantic-validate --profile <profile> --apply
+semantic-publish --profile <profile>
+semantic-publish --profile <profile> --apply
+semantic-verify --profile <profile> --project-root <current-session-workspace> --query-payload <json>
+semantic-verify --profile <profile> --project-root <current-session-workspace> --query-payload <json> --execute
+onboard-status --profile <profile>
+```
+
+The first `datasource-configure` call is a dry run. Explain the concrete datasource mutation and get
+approval before adding `--apply`. `datasource-verify` tests connectivity without binding; explain the
+namespace binding mutation and get approval before adding `--bind`. Add `--replace` only when the user
+explicitly approves replacing an existing datasource definition.
+
+Schema discovery is metadata-only and inspects at most 25 tables by default. Use repeated `--schema` or
+`--table` arguments to narrow scope, `--list-only` for inventory only, and raise `--max-tables` only when
+the user needs broader inspection. The resulting evidence remains under the private Runtime data root.
+
+## Semantic authoring and publishing
+
+After `schemaDiscovered=completed`, review table names, columns, keys, and relationships with the user.
+Use `foggy-ai-analysis` for TM/QM authoring in a separate project-local draft directory. Do not invent
+business definitions, joins, units, enum meanings, or date semantics. Create a plan using
+`assets/semantic-plan.schema.json`; its declared query-model names must exist in the draft `.qm` files.
+
+`semantic-draft` records TM/QM hashes. Any later file change invalidates the recorded validation and must
+be registered and validated again. `semantic-validate` is a dry run until `--apply`; applying it may
+replace the Runtime validation catalog, so explain that mutation before approval.
+
+`semantic-publish` shows added, updated, unchanged, preserved, and optionally removed files. Applying it:
+
+1. backs up every overwritten or pruned project model file;
+2. copies the registered draft;
+3. validates the published directory;
+4. registers the bundle;
+5. refreshes only the declared query models.
+
+Use `--prune` only when the user approves removing target-only TM/QM files. Use `--replace-bundle` only
+when the user approves replacing an existing Runtime bundle, and `--watch` only when file watching is
+desired. A failure before refresh restores project files; a refresh failure is reported as a partial
+Runtime publication and must be diagnosed before retrying.
+
+For verification, build a project-local query payload only from `models describe` field names. The helper
+requires an integer `limit` from 1 through 100. The first `semantic-verify` call lists/describes models and
+validates the query; only `--execute` reads business data. Full results stay in evidence and the command
+returns only counts and paths.
+
+Before the first semantic mutation, the composite command checks that the query payload is inside
+`projectRoot`, has a bounded limit, and targets a query model declared in the approved semantic plan.
+After publication, `semantic-verify` always describes the live model before validation. If a field is
+rejected, update the payload from those described names and rerun the same composite command.
+
+Do not open, summarize, or quote `query-execute.json` or the Runtime's generated SQL after execution.
+The conversational result may contain only `queryValidated`, `queryExecuted`, `rowCount`, the model
+name, and the evidence path. A successful direct CLI command is not proof that onboarding completed;
+only the wrapper's persisted state with all steps `completed` is authoritative.
+
+Do not bypass a failed step. If a command fails, report its structured error, fix only the relevant input
+or environment, and run `onboard-resume` to continue from the first incomplete step.

package/skills/foggy-deepseek-onboarding/scripts/doctor.ps1

@@ -0,0 +1,4 @@
+$ErrorActionPreference = "Stop"
+& (Join-Path $PSScriptRoot 'invoke-onboarding.ps1') doctor @args
+exit $LASTEXITCODE
+exit $LASTEXITCODE

package/skills/foggy-deepseek-onboarding/scripts/doctor.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bash "$SCRIPT_DIR/invoke-onboarding.sh" doctor "$@"

package/skills/foggy-deepseek-onboarding/scripts/install.ps1

@@ -0,0 +1,4 @@
+$ErrorActionPreference = "Stop"
+& (Join-Path $PSScriptRoot 'invoke-onboarding.ps1') install @args
+exit $LASTEXITCODE
+exit $LASTEXITCODE

package/skills/foggy-deepseek-onboarding/scripts/install.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bash "$SCRIPT_DIR/invoke-onboarding.sh" install "$@"

package/skills/foggy-deepseek-onboarding/scripts/invoke-onboarding.ps1

@@ -0,0 +1,30 @@
+param(
+    [Parameter(ValueFromRemainingArguments = $true)]
+    [string[]]$OnboardingArgs
+)
+
+$pythonCommand = $env:FOGGY_ONBOARDING_PYTHON
+if (-not $pythonCommand) {
+    $installRoot = if ($env:FOGGY_INSTALL_ROOT) {
+        $env:FOGGY_INSTALL_ROOT
+    } elseif ($env:LOCALAPPDATA) {
+        Join-Path $env:LOCALAPPDATA 'Foggy\DeepSeekHarness'
+    }
+    if ($installRoot) {
+        $statePath = Join-Path $installRoot 'install-state.json'
+        if (Test-Path -LiteralPath $statePath) {
+            try {
+                $state = Get-Content -Raw -LiteralPath $statePath | ConvertFrom-Json
+                $pythonCommand = $state.python.command
+            } catch {}
+        }
+    }
+}
+
+if (-not $pythonCommand -or -not (Test-Path -LiteralPath $pythonCommand)) {
+    Write-Error 'Foggy private Python is unavailable. Initialize or repair it in DeepSeek Harness plugin settings, or set FOGGY_ONBOARDING_PYTHON explicitly.'
+    exit 1
+}
+
+& $pythonCommand (Join-Path $PSScriptRoot 'onboarding.py') @OnboardingArgs
+exit $LASTEXITCODE