@deepseek-insight/dsi 0.5.19 → 0.5.22

package/.agents/skills/dsh-jump-prepare-fix/SKILL.md

@@ -0,0 +1,99 @@
+# DSH Jump Unstick — the `prepare` Scheduler-Symbol Split
+
+Every DSH edition jump that dies with `Cannot read properties of undefined
+(reading 'prepare')` on the first tool call has ONE verified cause class and ONE
+validated fix. This skill exists so the jump is never blocked twice on the same
+bug — the 2026-09-18 jump to `dsh-v0.1.6-alpha.2` lost the session to it, and
+the diagnosis had to be rebuilt from scratch on 2026-09-19.
+
+Authority: upstream [discussion 783](https://github.com/deepseek-ai/deepseek-harness/discussions/783)
+names the mechanism for global installs; the 2026-09-19 probe (below) proved the
+source-checkout variant and validated the fix end to end.
+
+## When to use
+
+- A DSH checkout just moved (pull / tag checkout / rebuild) and EVERY tool call
+  in EVERY session fails with `Cannot read properties of undefined (reading
+  'prepare')`, code `UNKNOWN`, ending the turn.
+- Or the jump aborted earlier and `~/.dsh/sessions/**/session.v3.jsonl.zstd`
+  shows a `turn/end` with that exact message.
+- Do NOT use for other `undefined` errors — the message must name `prepare`.
+
+## The mechanism, in one paragraph
+
+`packages/core/tools` exports `TOOL_RUNTIME_SCHEDULER = Symbol(...)` — a plain
+Symbol, so each loaded copy of the module mints a distinct key. The tools
+registry registers the scheduler under ONE copy's Symbol; the agent loop reads
+it through the OTHER copy's Symbol; the lookup yields `undefined` and
+`.prepare` throws. What splits the copies depends on launch mode: in a global
+install it is a profile-local `pnpm install` materializing `@deepseek-ai/*`
+under `~/.dsh/profiles/<name>/node_modules` (discussion 783); in a
+source-checkout launch (`pnpm dsh …` = `node --import tsx/esm apps/cli/src/bin.ts`)
+the 2026-09-19 probe caught the cordis plugin loader importing BOTH
+`packages/core/tools/src/index.ts` (via tsx tsconfig `paths`) AND
+`packages/core/tools/lib/index.js` (via package `exports`) in the same process.
+Any jump that changes plugin resolution can re-trigger it.
+
+## Confirm before fixing (2 minutes, optional but cheap)
+
+Instrument both copies, reproduce, read the stacks:
+
+```sh
+# in the moved checkout, add after the Symbol line in BOTH
+# packages/core/tools/src/index.ts and packages/core/tools/lib/index.js:
+if (process.env.DSH_PROBE_SYMBOL) console.error('[PROBE]', import.meta.url, new Error('stack').stack)
+
+export DSH_PROBE_SYMBOL=1
+pnpm dsh --profile headless "Use the bash tool to run: echo probe" 2>&1 | grep PROBE
+```
+
+Two `[PROBE]` lines with different URLs (one `src/`, one `lib/`, or two
+distinct trees) = this bug. One line only = something else; stop and re-diagnose.
+
+## The fix (validated 2026-09-19 against a pristine alpha.2 worktree)
+
+Make the scheduler key copy-robust with the global symbol registry, in BOTH
+copies of `packages/core/tools`:
+
+- `src/index.ts`:
+  `export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol.for('@deepseek-ai/dsh-tools.scheduler')`
+- `lib/index.js` (after the line `const TOOL_RUNTIME_SCHEDULER = …`):
+  `Symbol.for("@deepseek-ai/dsh-tools.scheduler")`
+
+Patching only one copy does NOT work — either copy may provide the registry or
+read it, and a `Symbol.for` key on one side still mismatches a plain `Symbol()`
+on the other.
+
+## Verify, then clean up
+
+1. Remove any `[PROBE]` instrumentation lines added above.
+2. Headless proof (isolated home so the running web host is untouched):
+   ```sh
+   export DSH_HOME="$(mktemp -d)" && cp ~/.dsh/settings.yaml "$DSH_HOME/"
+   export ZAI_API_KEY="$(grep -oE 'ZAI_API_KEY=?["'"'"']?[A-Za-z0-9._-]+' ~/.zshrc | head -1 | sed -E 's/^ZAI_API_KEY=?["'"'"']?//')"
+   pnpm dsh --profile headless "Use the bash tool to run: echo <tag> — then reply with exactly its output."
+   ```
+   Green = the reply is exactly the echoed tag.
+3. Web profile: boot briefly with the isolated `DSH_HOME`; plugin activation
+   must pass (an `EADDRINUSE` on the running host's port means plugins are
+   healthy). Only then restart the real `pnpm dsh web`.
+
+## Standing caveats
+
+- `lib/` is a build artifact: re-apply the lib patch after every
+  `pnpm run build`. The src patch dirties the tree across pulls — re-apply
+  after checking out a new edition, drop when upstream adopts the fix.
+- Never commit the patched files; this is a local unblock only.
+- The error also litters the session ledger with orphan `tool/call` events
+  (persisted before the throwing lookup). DeepSeek's endpoint rejects later
+  turns of such sessions with a 400 (`tool_calls` must be followed by `tool`
+  messages) — affected sessions are lost for that provider; start a new session
+  rather than resuming.
+
+## Retire this skill when
+
+Upstream ships the key as `Symbol.for` (or otherwise guarantees singleton
+resolution) in a tag this machine runs — verify with:
+`git grep -n "Symbol.for('@deepseek-ai/dsh-tools.scheduler')" <tag> -- packages/core/tools/src/index.ts`,
+then delete the repo copy and the mirror and note the retirement in the DSI
+release KB note covering that jump.

package/.agents/skills/dsi-ov-setup/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: dsi-ov-setup
+description: Use when OpenViking memory is broken or missing in DeepSeek Harness — server disconnected, server not installed, ov.conf missing, plugin not loaded, or a fresh machine needs the whole OpenViking + DSH memory integration set up (plugin, skill, server). Covers diagnosis, install, config, start, and verification.
+---
+
+# OpenViking + DSH Setup and Recovery
+
+Companion KB: `dev/kb/setup/2026-09-16 - OpenViking Server + DSH Memory Plugin — From Cold Start to Recalled Memory.md` — read it for the why behind every step. This skill is the do-path.
+
+## 0. Diagnose first — which failure is this?
+
+Run in order; stop at the first failing gate:
+
+| Gate | Command | Healthy looks like |
+|---|---|---|
+| Server process | `curl -s --max-time 3 http://127.0.0.1:1933/health` | `{"status":"ok","healthy":true,...}` |
+| Server config | `ls ~/.openviking/ov.conf` | exists |
+| Client config | `cat ~/.openviking/ovcli.conf` | `url` = `http://127.0.0.1:1933` |
+| Package | `openviking-server --version` | prints a version |
+| Plugin installed | `grep @openviking ~/.dsh/profiles/web/package.json` + `ls ~/.dsh/profiles/web/node_modules/@openviking/dsh-memory-plugin` | both the bundle entry and the package exist |
+| MCP connection | harness tool list shows `mcp__openviking__*` | tools present |
+
+- Health fails + `ov.conf` missing → **Recovery path (§2)**, the common case.
+- Health fails + `ov.conf` exists → run `openviking-server doctor`, fix what it names, go to §2 step 4.
+- Plugin missing from manifest or `node_modules` → reinstall via the sanctioned path (§2 step 6): from the running host's checkout, `pnpm dsh plugin --profile web add @openviking/dsh-memory-plugin`. This persists both the dependency and the `dsh.profile.bundles` entry, so profile rebuilds keep it. A bare `pnpm install` in the profile dir is a dead end — bundles are not `dependencies` and pnpm reports "Already up to date" while the plugin stays missing (RCA 2026-09-18 — The Vanished Plugin).
+- Health ok but MCP disconnected → the plugin reconnects on its own within a turn or two; if not after a full turn, restart the harness session. Do not reinstall anything.
+- Package missing → fresh install: do §2 steps 1–6 from scratch.
+
+## 1. Facts to keep straight (most-confused pair)
+
+- `~/.openviking/ovcli.conf` — **client** pointer: `{"url": "http://127.0.0.1:1933", "api_key": ""}`. Missing it breaks CLI commands only.
+- `~/.openviking/ov.conf` — **server** model config (embedding + VLM). Missing it means the server process cannot start at all. This is the usual blocker.
+- The DSH plugin (`@openviking/dsh-memory-plugin`, in the profile bundles at `~/.dsh/profiles/web/package.json`) is a **client only** — it never starts the server, and it reconnects automatically once the server is healthy. Never "fix" a disconnected MCP by touching the plugin.
+- `openviking`/`ov` = CLI/SDK; `openviking-server` = the daemon. Same pip package.
+
+## 2. Recovery / install path
+
+### Step 1 — Install the package (skip if `openviking-server --version` works)
+
+```sh
+pip install openviking --upgrade --force-reinstall
+```
+
+Entry points land in `~/.local/bin`: `ov`, `openviking`, `openviking-server`, `vikingbot`.
+
+### Step 2 — CLI housekeeping
+
+```sh
+ov language en        # v0.3.23+ refuses most commands without this; writes ovcli.settings.conf
+ov config add custom --name local --url http://127.0.0.1:1933 --activate -o json   # only if ovcli.conf missing
+```
+
+Note: both write under `~/.openviking/` — they fail under a workspace-only file sandbox; run with full file access.
+
+### Step 3 — Create the server config: `openviking-server init`
+
+Preferred: run it interactively and let the human answer. If driving it with piped answers, the wizard's prompt order is exact and hidden prompts exist — the tested sequence for the recommended local setup:
+
+```
+1     # mode: step-by-step
+3     # embedding: lightweight CPU (llama.cpp, bge-small-zh-v1.5-f16, no key)
+1     # embedding model: (only option — EASY TO MISS; missing this shifts every later answer)
+6     # VLM: GLM (subscription API key)
+2     # GLM plan: coding
+<key> # API key — pass via stdin from an env var; NEVER in the command line or logs
+N     # query planner via Ollama: no
+1     # bind 127.0.0.1 (dev, no auth)
+1933  # port
+Y     # save
+```
+
+After saving the wizard echoes the resolved API key in its summary — **redact any captured log** before storing it.
+
+Decision guardrails (from the KB §4): embedding `[3]` CPU is the default because it is keyless and tiny; offer `[1]` cloud embedding only when the user cares about retrieval quality and has a key; VLM is the piece worth a strong model — GLM via an existing subscription beats skipping it. `[9]` skip-VLM gives a server that stores but extracts poorly.
+
+### Step 4 — Wait out the build
+
+Choosing CPU embedding triggers `pip install "openviking[local-embed]"`, which **builds `llama-cpp-python` from source** — several minutes of silent wheel-building. It is not hung. Do not kill it; verify with `ps aux | grep "openviking-server init"`.
+
+### Step 5 — Validate and start
+
+```sh
+openviking-server doctor    # expect: all checks PASS (config, auth, disk ≥ several GB)
+openviking-server           # foreground proof; then move to a supervisor
+```
+
+Sandbox warning: server startup acquires a PID lock at
+`~/.openviking/data/.openviking.pid` — under a workspace-only file sandbox it
+dies with `PermissionError` / exit 3 at once. Start the server with full file
+access (same as step 2's CLI housekeeping).
+
+For persistence: launchd/nohup/systemd — never rely on an agent shell outliving the session. Verify:
+
+```sh
+curl -s http://127.0.0.1:1933/health   # {"status":"ok","healthy":true,...}
+ov status                              # "Connected (Healthy)", queue 0 pending / 0 errors
+```
+
+A stale `~/.openviking/pending/` queue (hundreds of files) from the downtime drains on its own — do not delete it.
+
+### Step 6 — Confirm the integration
+
+Within a turn of the server going healthy, the plugin reconnects (MCP tools answer, `<openviking-context>` appears at the next session start). If MCP tools still error after a full turn: restart the harness session once. Only then suspect the bundle (`~/.dsh/profiles/web/package.json` must list `@openviking/dsh-memory-plugin` in `dsh.profile.bundles`).
+
+If the plugin must be (re)installed, run from the **running host's checkout** (find it: `lsof -p <dsh-web-pid> | grep cwd`):
+
+```sh
+pnpm dsh plugin --profile web add @openviking/dsh-memory-plugin
+```
+
+This is the only install path that reconciles `dsh.profile.bundles` and survives profile rebuilds. With `patchReload: "live"` in the manifest the profile recomposes without a host restart and `<openviking-context>` returns mid-session.
+
+## 3. Verification checklist (all seven, in order)
+
+1. `openviking-server --version` → prints version
+2. `ls ~/.openviking/ov.conf ~/.openviking/ovcli.conf` → both exist
+3. `openviking-server doctor` → all PASS
+4. `curl -s http://127.0.0.1:1933/health` → `"healthy":true`
+5. `ov status` → Connected (Healthy), 0 errors
+6. `ov find "smoke test"` after any resource exists → ranked hits, not a connection error
+7. New session → `<openviking-context>` block present
+
+## 4. Known traps
+
+- `ov status` saying "Unreachable" while the server is fine → the language gate; run `ov language en` first.
+- Two config files, one directory (§1) — check the right one for the symptom.
+- `auth_mode: "dev"` = no auth, localhost only. Never bind `0.0.0.0` without switching to API-key auth (docs: Authentication guide).
+- Piped `init` answers are prompt-order-fragile (Step 3) — count prompts, don't trust defaults.
+- Re-examine actual prompt output on every version bump; this sequence was tested against OpenViking 0.4.20 / plugin 0.3.2 (2026-09-16) and the wizard's prompts are not a stable contract.
+
+## 5. Report the run — always, before finishing
+
+Every execution of this skill — recovery, install, or clean-bill-of-health —
+ends by writing an RCA report so the next run diffs from a written baseline.
+
+- Path: `~/.dsi/dev/ov/YYYY-MM-DD HH-MM - <Short Name> — <What Happened>.md`
+  (mkdir the directory first; date = when the analysis ran, 24h `HH-MM` to
+  keep colons out of the filename).
+- Required sections: TL;DR (+ layman glossary), symptom & diagnosis path
+  (the §0 gate table with pass/fail per gate), one RCA block per root cause
+  with file/line evidence, a mermaid **flowchart** (the journey, failed
+  branches colored) and a mermaid **sequenceDiagram** (who talks to whom),
+  fix application & testing (command → result table), corrective actions,
+  and a closing **open question**.
+- Exemplar: `~/.dsi/dev/ov/2026-09-18 09-56 - The Vanished Plugin and the
+  Sandboxed Lock — OpenViking Recovery RCA.md`.
+- If the run surfaced a new trap or fixed a gap in this skill, update this
+  SKILL.md (repo copy at `deepseek-insight/.agents/skills/dsi-ov-setup/`),
+  then re-copy to the mirror `~/.agents/skills/dsi-ov-setup/` — a skill the
+  slash menu never sees is a skill nobody invokes.

package/.agents/skills/dsi-sync/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: dsi-sync
+description: Use when the user runs /dsi-sync or says to sync/mirror DeepSeek Insight (DSI) to its GitHub mirror — re-syncs ~/agentic-ai/deepseek-insight into ~/github/deepseek-insight (excluding dev/ and .git/), then commits and pushes the mirror. Covers resync, commit, push, and no-change skip.
+---
+
+# DSI → GitHub Mirror Sync
+
+Mirror DSI into a publishable GitHub repo, then commit & push. The mirror lives at
+`~/github/deepseek-insight` and has its own `.git` (origin:
+`git@github.com:mitmplay/deepseek-insight.git`). Never touch the mirror's `.git`
+or DSI's `dev/` folder.
+
+## Source of truth
+
+- SOURCE: `~/agentic-ai/deepseek-insight/`
+- MIRROR: `~/github/deepseek-insight/`
+- EXCLUDED from sync (always): `dev/`, `.git/`
+- The mirror's own `.git` is protected because rsync excludes `.git/` — with
+  `--delete`, excluded target paths are never deleted.
+
+## 1. Re-sync
+
+```bash
+rsync -a --delete \
+  --exclude 'dev/' \
+  --exclude '.git/' \
+  ~/agentic-ai/deepseek-insight/ \
+  ~/github/deepseek-insight/
+```
+
+Trailing slashes matter: they copy CONTENTS of source into target, not the folder itself.
+
+## 2. Verify the exclusions held
+
+```bash
+test -d ~/github/deepseek-insight/dev && echo 'BAD: dev leaked' || echo 'ok: no dev'
+test -d ~/github/deepseek-insight/.git && echo 'ok: .git intact' || echo 'BAD: .git lost'
+```
+
+If either BAD line prints, stop and fix before committing — do not push a broken mirror.
+
+## 3. Commit & push (skip if nothing changed)
+
+```bash
+cd ~/github/deepseek-insight
+git add -A
+if git diff --cached --quiet; then
+  echo 'no changes to sync'
+else
+  git commit -m "sync from DSI $(date '+%Y-%m-%d %H:%M')"
+  git push origin main
+fi
+```
+
+- Always use `git add -A` then check the staged diff — never commit blind.
+- Quote the date format: `(date '+%Y-%m-%d %H:%M')` — unquoted, the space
+  word-splits the expansion and `date` errors with "illegal time format"
+  (observed 2026-09-18).
+- Report to the user: file count changed (or "no changes"), commit hash, push result.
+- If push is rejected (non-fast-forward), STOP and ask the user — never force-push
+  without explicit approval.
+
+## Failure handling
+
+- `rsync` errors: report the failing path; do not commit a partial sync.
+- Remote unreachable (SSH): report the error verbatim; the sync itself is still
+  complete and committed locally.
+- Mirror `.git` missing entirely: ask the user before re-initializing — do not
+  invent a remote URL.

package/README.md

@@ -1,48 +1,42 @@
 # DeepSeek Insight
 
-- `DSH web` shows you a conversation. 
-- [DeepSeek Insight](https://gitlab.com/wharsojo.dev/deepseek-insight) (DSI) shows you the **whole floor**
+> [DeepSeek Insight](https://github.com/mitmplay/deepseek-insight) (**DSI**) **See your multiple agents run on the floor (agent, sub-agent, etc)**, each **conversation on the floor are updated instantly**. 
 
-> `DSI` as a `Control room` built on your harness's own records: every session, past and running, side by side on one page; lineage tree of sub-agents pinned under the parent that spawned them; every tool call with its pass/fail receipt; history you can search; prompts worth keeping filed for reuse. It speaks the same wire as the `DSH` you already run — nothing new to configure.
+> A `Control room` built on [Deepseek Harness's](https://github.com/deepseek-ai/deepseek-harness) (**DSH**) **records**: any (running) session, show side by side on the floor; **Lineage tree** of **parent to sub-agents**; Clean conversation with **tool-call(s) chips** with status **+** auto-expand **thingking chips**. 
 
-## Run
+> A `Prompt Input` with **Slash-command(/)**, **Macros(!)** and **Auto-complete(?)**. Prompt-manager you can search it and to manage macros & autocomplete; user-prompts worth keeping is one-click-away tobe reuse.
 
-The whole DX loop lives in the home page: pick a preset + workspace, press **+ New chat** and watch your agent work.
-> tool chips pass/fail with durations and receipts, reasoning folds open, older turns load as you scroll up, and when a turn needs permission the approval card answers it with one click.
+> Included skills for:
+> - Spec and Tasks execution, 
+> - Integration helper for [OpenViking](https://openviking.ai/)  
 
-### What you'll see
+> **Your language.** The interface speaks English, Chinese, Indonesian & Spanish.
 
-Everything on the page is **real harness activity**, not a mock — every chip, diff, and reply is read straight from the running harness.
+<details>
+  <summary>Deepseek-insight-panels</summary>
+  <img src="docs/images/deepseek-insight-panels.png"/>
+</details>
 
-- **Conversation, with receipts.** Each tool the agent runs shows as a chip that passes or fails, with its duration and its receipt; open it to see exactly what ran. Reasoning folds away until you want it, and long sessions load older turns as you scroll up.
-- **The workspace explorer, with git diff.** A side panel shows the files your agent is touching. Changed files are flagged and pulsing while the agent works; click one and you get a **real git diff** — additions in green, removals in red — rendered from the file's live buffer, so it updates as the agent edits and refreshes if you (or anything else) change the file underneath.
-- **Presets and workspaces.** Start each chat with the right agent for the job — a coder, a researcher, a generalist — pointed at the right folder.
-- **Many conversations, one page.** Conversations live in panels you can open side by side; compare two runs, or keep a scratch chat next to the main one.
-- **A family tree under every chat.** When your agent spawns sub-agents, they appear as their own panels **below the parent that made them** — a ghost-tinted panel that stays put on refresh, so you always know who was working for whom. And when one conversation is worth a second try, **fork it**: one click clones the loaded context into a fresh session that starts exactly where the original stood — same history, new task.
-- **A prompt library that files itself.** Save any bubble into the library and give it short filing words (tags) at save time; filter the prompt manager by tag chips or `+tag` words in the search box, and narrow the suggestion strip with its own tag chips — filters survive a reload. Tune the offered tags in `~/.dsi/settings.yaml` under `prompts.tags`.
-- **Your language.** The interface speaks English, Chinese, and Indonesian.
+---
 
-### Run from npm
+## Quick Start
 
-Install [Node.js](https://nodejs.org) (>= 22.19), open a terminal, and run the **recommended one-liner**:
-
-```sh
+```bash
 npx @deepseek-insight/dsi@latest dsh --sync --zai
+# Open http://localhost:5174
 ```
 
-What that single command does, in plain words:
+- **`npx @deepseek-insight/dsi@latest`** — get latest DSI.
+- `dsh` — starts **DSH** (`dsh web`) and **DSI** together, as one pair and runs it.
+- `--sync` — copies DSH token to DSI config — **one window, one Ctrl-C stops both**.
+- `--zai` — **optional.** It bootstraps the GLM (Z.AI) provider into the harness settings (`~/.dsh/settings.yaml`). **If you do not have a GLM account, simply leave it off** — DSI will use whatever provider your harness is already configured with.
+
 
-- `npx @deepseek-insight/dsi@latest` — fetches the newest published DSI and runs it, **no install step**; nothing is added to your project, and `@latest` is what keeps it the latest.
-- `dsh` — talk to the harness side: this subcommand starts the **DSH host** (`dsh web`) and the **DSI page** together, as one pair.
-- `--sync` — copies the harness one-time launch token into DSI config (`~/.dsi/settings.yaml`) so the page can speak to the host, then serves both in the foreground — **one window, one Ctrl-C stops both**.
-- `--zai` — **optional.** It bootstraps the GLM (Z.AI) provider into the harness settings (`~/.dsh/settings.yaml`). **If you do not have a GLM account, simply leave it off** — DSI will use whatever provider your harness is already configured with:
 
-```sh
-npx @deepseek-insight/dsi@latest dsh --sync
-```
 
-When it is up, your browser opens the page by itself (default `http://127.0.0.1:5174`). Run it again later and DSI even cleans up after a lost previous run: `dsi dsh --sync-kills`.
+When it is up, your browser opens the page by itself (default `http://127.0.0.1:5174`).
 
 ## License
 
-[Apache-2.0](LICENSE) — Copyright © 2026 Widi Harsojo
+[Apache-2.0](LICENSE) — Copyright © 2026 [Widi Harsojo](https://www.linkedin.com/in/wharsojo/)
+> OPEN TO WORK (SG_PR)

package/bin/dsi.mjs

@@ -4,14 +4,19 @@
 // prepares the artifacts, this launcher only runs them. The build is resolved
 // relative to this file, not the cwd, so a globally installed or npx-run
 // package serves its own bundled build from any directory.
-// `dsi zai` bootstraps a fresh DSH install: it adds the ZAI provider and the
-// default model to ~/.dsh/settings.yaml (idempotent — existing entries win).
+// `--zai` (on `dsi web` / `dsi dsh --sync`) bootstraps a fresh DSH install:
+// it adds the ZAI provider and the default model to ~/.dsh/settings.yaml
+// (idempotent — existing entries win). The standalone `dsi zai` command was
+// decommissioned — the flag does the same work before anything boots.
 // `dsi dsh --token <token>` copies a dsh launch token into DSI's config
 // ($DSI_CONFIG_PATH or ~/.dsi/settings.yaml, key dsh.authToken — the same
 // file scripts/dsh-web-synced.sh keeps fresh). `dsi dsh --sync` runs that
 // script AND serves the dsi build — one foreground pair, one Ctrl-C.
 // `--dev` serves the Vite dev server instead of the build (sources only).
 // `dsi dsh --sync-kills` sweeps orphans a lost previous run left behind.
+// `dsi dsh --ov` (or --sync --ov, or web --ov) installs the OpenViking
+// memory plugin into
+// the active dsh profile by delegating to `dsh plugin ... add` (idempotent).
 
 import { spawn, spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -53,6 +58,9 @@ const USAGE = [
 	'               port 5175; needs a full checkout: pnpm install)',
 	'      --sync-kills',
 	'               kill orphaned dsh/dsi processes left by an earlier run',
+	'      --ov    install the OpenViking memory plugin into the active dsh',
+	'              profile (dsh plugin ... add). Client only — the memory',
+	'              server itself is set up separately (dsi-ov-setup skill)',
 	'',
 	'  Ports: `dsi dsh --sync` serves the DSI page on 5174 and opens your',
 	'  browser there. With --dev the Vite dev server takes 5175 instead',
@@ -60,16 +68,17 @@ const USAGE = [
 	'',
 	'  All commands (flags — see above):',
 	'',
-	'      dsi web [--zai] [--dev] [--token <token>]',
+	'      dsi web [--zai] [--ov] [--dev] [--token <token>]',
 	'                   serve the DSI page alone (PORT env default 5174,',
 	'                   HOST env default 127.0.0.1)',
-	'      dsi zai      add the ZAI provider + default model to',
-	'                   ~/.dsh/settings.yaml',
 	'      dsi dsh --token <token>',
 	'                   store the dsh launch token in ~/.dsi/settings.yaml',
-	'      dsi dsh --sync [--zai] [--dev]',
+	'      dsi dsh --sync [--zai] [--dev] [--ov]',
 	'                   run dsh-web-synced.sh (dsh web + token sync) AND serve',
 	'                   dsi — see the recommended command above',
+	'      dsi dsh --ov',
+	'                   install the OpenViking memory plugin into the active',
+	'                   dsh profile (idempotent; alone, without --sync)',
 	'      dsi dsh --sync-kills',
 	'                   kill orphaned dsh/dsi processes left by an earlier run'
 ].join('\n');
@@ -79,7 +88,7 @@ if (command === '--help' || command === '-h' || command === 'help') {
 	console.log(USAGE);
 	process.exit(0);
 }
-if (command !== 'web' && command !== 'zai' && command !== 'dsh') {
+if (command !== 'web' && command !== 'dsh') {
 	console.error(command === undefined ? 'dsi: missing command' : `dsi: unknown command "${command}"`);
 	console.error(USAGE);
 	process.exit(64);
@@ -87,6 +96,11 @@ if (command !== 'web' && command !== 'zai' && command !== 'dsh') {
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+/** The OpenViking memory plugin DSI's host profile wants. Client-side only:
+ *  it never starts openviking-server — it reconnects on its own once the
+ *  server is healthy (KB 2026-09-16 §2). */
+const OV_PLUGIN = '@openviking/dsh-memory-plugin';
+
 // ── dsi zai ────────────────────────────────────────────────────────────────
 
 /** The ZAI provider block, byte-for-byte the fresh-install shape. */
@@ -124,11 +138,6 @@ function isRecord(value) {
 	return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-if (command === 'zai') {
-	addZaiProvider();
-	process.exit(0);
-}
-
 // ── dsi dsh ────────────────────────────────────────────────────────────────
 
 /** One pkill -f sweep per orphan signature. The patterns match only the
@@ -156,6 +165,10 @@ if (command === 'dsh') {
 		setDshAuthToken(token);
 		process.exit(0);
 	}
+	if (flag === '--ov') {
+		runOvPlugin();
+		process.exit(0);
+	}
 	if (flag === '--sync') {
 		// --zai and --dev are dsi-side flags, stripped from the args the sync
 		// script forwards to `dsh web` (which would refuse them):
@@ -166,10 +179,12 @@ if (command === 'dsh') {
 		const rest = process.argv.slice(4);
 		const withZai = rest.includes('--zai');
 		const withDev = rest.includes('--dev');
+		const withOv = rest.includes('--ov');
 		if (withZai) addZaiProvider();
+		if (withOv) runOvPlugin();
 		runSkillsMirror();
 		runSyncedPair(
-			rest.filter((arg) => arg !== '--zai' && arg !== '--dev'),
+			rest.filter((arg) => arg !== '--zai' && arg !== '--dev' && arg !== '--ov'),
 			withDev
 		);
 	} else if (flag === '--sync-kills') {
@@ -387,6 +402,47 @@ function addZaiProvider() {
 	console.log(`dsi zai: ${settingsPath} updated — set ZAI_API_KEY in the harness env, then restart dsh web`);
 }
 
+/** Install the OpenViking memory plugin into the active dsh profile by
+ *  delegating to `dsh plugin --profile <profile> add` — the same dsh
+ *  launcher `dsi dsh --sync` uses (DSH_WEB_CMD override, else the published
+ *  pin via npx). dsh's own reconcilePlugins appends the package to
+ *  dsh.profile.bundles (it declares a dsh.bundle), so nothing is hand-edited
+ *  here. Idempotent: a profile that already has the dependency AND the bundle
+ *  entry skips the pnpm round-trip. Fail-loud: a nonzero child exit (or a
+ *  missing pnpm — dsh exits 127 for it) propagates. */
+function runOvPlugin() {
+	const profile = process.env.DSH_PROFILE ?? 'web';
+	const manifestPath = path.join(
+		homedir(), '.dsh', 'profiles', profile, 'package.json'
+	);
+	if (existsSync(manifestPath)) {
+		try {
+			const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+			const deps = manifest?.dependencies ?? {};
+			const bundles = manifest?.dsh?.profile?.bundles ?? [];
+			if (deps[OV_PLUGIN] !== undefined && bundles.includes(OV_PLUGIN)) {
+				console.log(`dsi dsh: ${OV_PLUGIN} already installed in the ${profile} profile — nothing to do`);
+				return;
+			}
+		} catch (error) {
+			console.error(`dsi dsh: cannot parse ${manifestPath}: ${error?.message ?? error}`);
+			process.exit(65);
+		}
+	}
+	const cmd = process.env.DSH_WEB_CMD
+		? `${process.env.DSH_WEB_CMD} plugin --profile ${profile} add ${OV_PLUGIN}`
+		: `npx --yes @deepseek-ai/dsh@${dshWebVersion()} plugin --profile ${profile} add ${OV_PLUGIN}`;
+	console.log(`dsi dsh: installing ${OV_PLUGIN} into the ${profile} profile (${cmd})`);
+	const result = spawnSync('/bin/sh', ['-c', cmd], { stdio: 'inherit' });
+	if (result.error !== undefined) throw result.error;
+	const code = result.status ?? 1;
+	if (code !== 0) {
+		console.error(`dsi dsh: plugin install failed (exit ${code}) — pnpm on PATH is required; fix the cause above, then re-run`);
+		process.exit(code);
+	}
+	console.log(`dsi dsh: ${OV_PLUGIN} installed — it connects on its own once openviking-server answers (see the dsi-ov-setup skill for the server side)`);
+}
+
 /** Plant the shipped skills into the operator's skill mirror
  *  (~/.agents/skills) — ADR "The Skill Mirror" 2026-09-15, D1–D5:
  *  per-skill copy-only-if-absent, every repo skill, failures warn and
@@ -465,12 +521,14 @@ function startDsiServer(defaultPort = '5174') {
 if (command === 'web') {
 	// Optional dsi-side flags, the same meanings as `dsi dsh --sync`: --zai
 	// bootstraps the ZAI provider BEFORE anything boots (so this run picks it
-	// up), --token stores the dsh launch token before the page serves, --dev
-	// swaps the built server for the Vite dev server. Everything is done
+	// up), --token stores the dsh launch token before the page serves, --ov
+	// installs the OpenViking memory plugin, --dev swaps the built server for
+	// the Vite dev server. Everything is done
 	// first, then the one child spawns and the script falls off the end.
 	const rest = process.argv.slice(3);
 	const withZai = rest.includes('--zai');
 	const withDev = rest.includes('--dev');
+	const withOv = rest.includes('--ov');
 	const tokenIdx = rest.indexOf('--token');
 	let token;
 	if (tokenIdx !== -1) {
@@ -481,7 +539,7 @@ if (command === 'web') {
 		}
 	}
 	const unknown = rest.filter((arg, i) =>
-		arg !== '--zai' && arg !== '--dev'
+		arg !== '--zai' && arg !== '--ov' && arg !== '--dev'
 		&& arg !== '--token' && !(tokenIdx !== -1 && i === tokenIdx + 1)
 	);
 	if (unknown.length > 0) {
@@ -490,9 +548,14 @@ if (command === 'web') {
 		process.exit(64);
 	}
 	if (withZai) addZaiProvider();
+	if (withOv) runOvPlugin();
 	if (token !== undefined) setDshAuthToken(token);
 	runSkillsMirror();
 	const child = withDev ? startDsiDevServer() : startDsiServer();
+	// Same browser-follows-the-UI contract as the pair (runSyncedPair): open
+	// the default browser at the serving port — --dev's Vite server takes
+	// 5175, the built server 5174; PORT/HOST overrides apply.
+	openBrowser(`http://${process.env.HOST ?? '127.0.0.1'}:${process.env.PORT ?? (withDev ? '5175' : '5174')}/`);
 
 	for (const signal of ['SIGINT', 'SIGTERM']) {
 		process.on(signal, () => {