# dsh-beacons — install guide for AI agents

dsh-beacons is a **DeepSeek Harness (DSH) Web UI plugin**: a Codex/OpenChamber-style
right-edge prompt-navigator rail with scroll-spy for the conversation. If you are an
AI agent and someone handed you this repository URL, this file tells you exactly how
to install it into a DSH profile.

## One-liner

```sh
dsh plugin --profile web add github:Da-Mie/dsh-beacons
```

Run that from anywhere (needs `dsh` CLI and `pnpm` on PATH). If either is missing,
use the manual method below — it needs neither.

## Requirements

- DeepSeek Harness ≥ `0.1.0-rc.6` (Web UI profile; check with `dsh --version`)
- `$DSH_HOME` defaults to `~/.dsh`; the web profile directory is `$DSH_HOME/profiles/web`
- The package ships **prebuilt** (`lib/` is committed) — no build step needed.
  Rebuilding from source requires Node ≥ 22: `npm install && npm run build`.

## Manual install (no pnpm / no `dsh plugin`)

1. Clone this repo (or unpack `dsh-beacons-0.1.0.tgz`) to a stable path, e.g. `$P`.
2. Make the package resolvable from the profile's module fallback:

   ```sh
   mkdir -p "$DSH_HOME/profiles/node_modules"
   ln -s "$P" "$DSH_HOME/profiles/node_modules/dsh-beacons"
   # Windows (no admin needed): junction
   #   New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-beacons" -Target "$P"
   ```

3. Register the bundle in `$DSH_HOME/profiles/web/package.json`:

   - `dependencies`: add `"dsh-beacons": "link:$P"`
   - `dsh.profile.bundles`: append `"dsh-beacons"` (after `@deepseek-ai/dsh-web-app`)

4. **Restart DSH** (plugin-set changes take effect on restart), then refresh the Web UI.

## Name-consistency checklist (the #1 install breaker)

These four names MUST be identical — `dsh-beacons`:

1. `package.json` → `name`
2. the directory/junction name under `$DSH_HOME/profiles/node_modules`
3. the inserted row's `name` in `cordis.patch.yml`
4. the client bundle id in `lib/client.js` (`window.__ModuleLoader__.load({ id: "dsh-beacons", ... })`)

A mismatch in any of them (e.g. a stale row name left over from a rename) makes the
loader fail to resolve the plugin at startup — the backend exits with code 1 and the
plugin never loads. Always verify resolution BEFORE restarting:

```sh
node -e "const {createRequire}=require('node:module'); \
  const r=createRequire('$DSH_HOME/profiles/web/noop.js'); \
  console.log(r.resolve('dsh-beacons/package.json'))"
```

It must print the package's `package.json` path, not throw.

## Verification after install

- The Web UI index (`window.__DSH_BOOT__`) contains an entry with `"id":"dsh-beacons"`.
- `GET /plugins/dsh-beacons/client.js` returns the bundle (HTTP 200).
- Open a session with ≥ 2 user prompts: the right-edge rail appears; hover to preview,
  click to jump, scroll to move, `Alt+P` for keyboard navigation.

## Scope

- This plugin provides prompt navigation only; there is no configuration and no
  host-side behavior.