docs + release: the readme documents the distribution, and the pack is 0.1.0

The README grows a Distribution section - what a release archive is, the
different jobs of `START-HERE.bat` / `install.bat` / `vn-harness.exe`, and how a
cut is made; `SECURITY.md` gains "Secrets never enter this repository", and its
"what this pack does not do" list now says what is true after `keystate.rs`
(a presence check of `$DSH_HOME/.credentials.yaml`, a boolean and a layer name);
`app/README.md` documents the splash's two lines and the credentials document's
real shape.

Also repairs what the prose had wrong:

- the double-encoded characters a PowerShell round trip left in the new README
  and DISTRIBUTE sections (`—` for an em dash, `…` for an ellipsis, `→` for an
  arrow) - the same damage an earlier commit undid elsewhere in the tree;
- the test count: `cargo test` is 56/56 with `keystate.rs` at 18, not 55/55/17;
- the CI matrix in DISTRIBUTE.md still named the retired `macos-13`/`macos-14`
  runners, and the archive count disagreed with itself in three files. There are
  six legs: four required (win-x64, mac-x64, mac-arm64, linux-x64) and two
  non-blocking ARM64 ones;
- `package.json` is now `0.1.0`, the version the first release tag names, since
  the release job refuses to attach anything to a tag that disagrees with it.

The screenshots are renamed to the timestamped spelling the README links and
re-captured, and the shell's own README keeps the readme's image references and
the asset rename in the same commit so no revision links a file that is not
there.

Author: vecnode

README.md

@@ -15,7 +15,7 @@ Windows half is PowerShell, the macOS/Linux half is plain POSIX shell.
 ![print](assets/vn-harness-20260920-164101.png)
 
 <p align="center">
-  <img src="assets/vn-harness 26_09_2026 09_53_53.png" alt="The vn-harness desktop window while the pinned harness starts: a dark splash showing the mark, the name and a &quot;Starting the harness…&quot; line" width="49%">
+  <img src="assets/vn-harness-20260926-095353.png" alt="The vn-harness desktop window while the pinned harness starts: a dark splash showing the mark, the name and a &quot;Starting the harness…&quot; line" width="49%">
   <img src="assets/vn-harness-20260925-084844.png" alt="The same window once the harness is up, showing the pack's app in the light theme" width="49%">
   <br>
   <em><code>run-desktop.bat</code>: the shell's splash while <code>npx</code> works, and the same window once the harness is listening.</em>
@@ -165,6 +165,64 @@ To remove the pack, run **`uninstall.bat`** (Windows) or **`./uninstall.sh`**
 (macOS/Linux); both take the same `-Plugin` / `-DshHome` / `-ProfileName`
 switches. Removing a bundle also removes its patch layer.
 
+## Distribution
+
+A release archive **is** the app: there is no installer to run and nothing to
+compile. The only prerequisite is Node.js 22 or newer — the pinned harness
+itself is fetched by `npx` on the first run.
+
+**On a machine that has never had the pack**
+
+1. Download the archive for the platform from
+   [Releases](https://github.com/vecnode/vn-harness/releases) —
+   `vn-harness-<version>-win-x64.zip`, `…-mac-x64.zip`, `…-mac-arm64.zip`,
+   `…-linux-x64.zip` (the ARM64 archives, `…-win-arm64.zip` and
+   `…-linux-arm64.zip`, appear too once those two experimental legs are green) —
+   and **extract it somewhere permanent**. The folder is the application: the
+   profile installs every bundle as a live link into `packages/`, so keep
+   `vn-harness.exe` beside everything it arrived with.
+2. Install Node.js 22+ from [nodejs.org](https://nodejs.org) if it is not already
+   on `PATH`. Windows additionally needs the WebView2 runtime, which Windows 10
+   and 11 already have.
+3. **Windows:** double-click `START-HERE.bat`. **macOS/Linux:** `./START-HERE.sh`.
+   That one step installs every bundle into the harness web profile
+   (`~/.dsh/profiles/web`) and the bundled skills into `~/.dsh/skills`, then
+   opens the app in its native window. It is safe to run again.
+4. Every run after that is just the app: `vn-harness.exe` (`./vn-harness`), or
+   `run-desktop.bat` for the same native window from a console, or `run-web.bat`
+   for a browser tab instead. All of them take `-Help`.
+5. Optional but recommended: check the download against `SHA256SUMS.txt`;
+   `BUILD-INFO.json` names the pack version, the harness pin, the commit and the
+   toolchain it was built with.
+
+Installing a newer release over an older one is a non-event, and the startup
+window says so before the harness is even listening: it names **which harness home
+this run will use** (`~/.dsh`) and whether a **DeepSeek key** was found there —
+green when it was, naming the layer it came from, amber with a pointer to
+*Settings → Models* when it was not. Sessions, settings and the key all live in
+that home rather than in the folder that was replaced, so a new download keeps
+everything you had. The key's value itself is never read out, logged or shown —
+only which layer supplied it.
+
+Three files, three different jobs — this is the part that is easy to get wrong:
+
+- **`START-HERE.bat` installs *and* runs.** It is the file to click first on a
+  new machine.
+- **`install.bat` only installs.** It never opens the app; it is what you re-run
+  after the folder moves.
+- **`vn-harness.exe` only runs.** On a machine that never installed the pack it
+  opens the plain harness with none of the plugins in it.
+
+**Cutting a release.** The tag must name the version in `package.json`, or the
+release job refuses to attach anything to it: this cut is `v0.1.0` against
+`"version": "0.1.0"`. Publishing a GitHub Release for that tag builds all six
+matrix targets — the four required legs (win-x64, mac-x64, mac-arm64, linux-x64)
+and the two non-blocking ARM64 ones — and attaches their archives plus
+`SHA256SUMS.txt`. The same thing can be run by hand from *Actions → distribute →
+Run workflow* with **release** ticked. What a distribution contains, what it
+deliberately leaves out and how it is verified end to end is in
+[`docs/DISTRIBUTE.md`](docs/DISTRIBUTE.md).
+
 ## Security & license
 
 - MIT — see [LICENSE](LICENSE). Plugins are authored by **vecnode**.

SECURITY.md

@@ -29,9 +29,14 @@ is in the state you think it is.
 
 ## The short version
 
-- **No secrets in this repository.** API keys live in your own harness settings
-  (`Settings → Models`); no plugin or installer reads, writes, prompts for or
-  transmits them. The pack writes no token, password or credential anywhere.
+- **No secrets in this repository — and that is enforced, not promised.** API keys
+  live in your own harness settings (`Settings → Models`) or in
+  `$DSH_HOME/.credentials.yaml`, which is outside this tree; no plugin or
+  installer reads, writes, prompts for or transmits them. The pack writes no
+  token, password or credential anywhere, and
+  `scripts/checks/check-no-secrets.mjs` fails the build if a credential-shaped
+  string reaches anything `git add -A` would stage. See
+  [Secrets never enter this repository](#secrets-never-enter-this-repository).
 - **No core patching.** Every plugin is a standard dsh **bundle**
   (`dsh.bundle` + `cordis.patch.yml` + a `dsh.client` browser half). The pack owns
   its right bar by **forking** the shipped bar bundles into this repo and
@@ -397,10 +402,62 @@ cookie leaks, rotate the signing secret.
   option-injection guard on git, the screenshot write refusals, the diagram
   budget, and the terminal's refusal of an unauthenticated upgrade.
 
+## Secrets never enter this repository
+
+A secret in a commit is a secret on GitHub for as long as the repository exists —
+in every fork, every clone and every cache — even after the file is deleted. So
+this is a rule with a check behind it rather than a good intention.
+
+**Where credentials actually live.** The harness keeps them in
+`$DSH_HOME/.credentials.yaml`, and `$DSH_HOME` defaults to `~/.dsh`, which is
+**outside this tree** and never part of a distribution. The pack reads that file
+in exactly one place, and only to answer "is a key present": `keystate.rs` reports
+a boolean and the name of the layer that supplied it, never the value — pinned by
+`a_real_shaped_key_never_reaches_the_page`, which feeds a key-shaped value through
+and asserts it appears in neither the startup window's payload nor the console
+line. The launch token is held to the same rule (see
+[The launch token](#the-launch-token)).
+
+**The check.** `scripts/checks/check-no-secrets.mjs` runs in CI on every push and
+scans `git ls-files -co --exclude-standard` — which is exactly what `git add -A`
+would stage, so an unignored credentials file is caught *before* it is committed.
+It fails on:
+
+- a key-shaped string, a credential ref with a value attached, a generic
+  `apiKey`/`password`/`client_secret` assignment, a launch token pasted into a URL,
+  a GitHub/AWS/Slack/Stripe key, a private-key block or a bearer JWT;
+- a missing credential rule in `.gitignore` (`.env`, `.credentials.yaml`,
+  `*.pem`, `*.key`, `id_rsa*`, `.npmrc`, …);
+- **its own silence** — a self-test asserts the scanner fires on a synthetic key
+  and stays quiet on clean text, because a guard that has never been shown to fire
+  is decoration.
+
+It never prints what it found: a failure names the file, the line, the rule and a
+masked preview, because a scanner that echoes the secret into a CI log has moved
+the leak rather than closed it. Its allowlist is empty by design — if a fixture
+trips a rule, the fix is to make the fixture not look like a credential (the test
+values in `keystate.rs` carry a `/` for exactly that reason), not to loosen the
+rule for everyone.
+
+**Two things the check cannot do.** It skips binary files, so **committed
+screenshots are reviewed by hand** — they are whole-screen captures and can show a
+session, a path, a notification or a key. And it sees the working tree, not the
+past.
+
+**If a credential is ever committed.** Rotate it **first** — assume it is public
+the moment it is pushed, because it is. Then remove it from history
+(`git filter-repo` or the BFG) and force-push; deleting the file in a new commit
+does not remove it. GitHub's own secret scanning and push protection are worth
+enabling on this repository as a second net behind this check.
+
 ## What this pack does not do
 
-- No API keys, no credentials store access beyond the harness's own
-  browser-session record, no prompts for secrets.
+- No API keys are read, and the **only** credential file the pack itself touches
+  is `$DSH_HOME/.credentials.yaml` — through the desktop shell's `keystate.rs`,
+  and for PRESENCE only: a boolean and the name of the layer that supplied the
+  key, never its value (see
+  [Secrets never enter this repository](#secrets-never-enter-this-repository)).
+  No prompts for secrets.
 - **No way to weaken the harness's authentication.** The pack mounts every route
   it owns inside the harness's gated `/api` channel, and this repository has no
   flag, setting or environment variable that turns the session check off. The

app/README.md

@@ -43,8 +43,10 @@ Node.js 22 or newer exactly as the browser launcher does.
    remembers its own geometry* below), because it has to be known **before** the
    window is built.
 4. Opens the window **immediately**, on its own splash (`ui/index.html`), because
-   the first run of a dsh version spends a while inside `npx`. After 45 seconds
-   the splash says the wait is long and points at the console.
+   the first run of a dsh version spends a while inside `npx`. The splash says
+   which harness home this run will use and whether a DeepSeek key was found
+   there (see *The splash answers the two questions worth asking first* below).
+   After 45 seconds it says the wait is long and points at the console.
 5. Runs the pinned CLI, streaming its stdout and stderr to this console.
 6. Watches that output for `dsh web: http://127.0.0.1:<port>/?token=<token>`,
    parses the URL and navigates the window there.
@@ -112,6 +114,62 @@ beside the real `.dsh`. Unit tests in `src-tauri/src/main.rs` pin the rule
 (`chosen_home`, `default_dsh_home`, `pick_home_variable`), and the console still
 *reports* the resolved home  -  `~/.dsh` included  -  without exporting it.
 
+## The splash answers the two questions worth asking first
+
+The window opens before the server exists, on `ui/index.html`, and the two things a
+person actually wonders while it starts are *"will the harness find my key"* and
+*"is this the profile I have been using"*. So the splash says both:
+
+- **DeepSeek key loaded  -  from the credentials file** (green), or **No DeepSeek
+  key yet  -  add one in Settings → Models** (amber);
+- **Harness home: `C:\Users\you\.dsh`**, with the reminder that sessions, settings
+  and the key live *there* and not in the folder that was replaced. That is what
+  makes installing a newer distribution a non-event: the plugins come from the new
+  folder (the profile live-links them), and everything you accumulated stays put.
+
+`keystate.rs` decides, and it walks **the harness's own four layers**, highest
+first  -  precisely because `dsh-credentials-local` owns the real lookup and a splash
+that disagreed with it would be worse than no splash at all:
+
+```text
+inherited process environment   DEEPSEEK_API_KEY=… dsh          (wins)
+> $DSH_HOME/.credentials.yaml   what Settings > Models writes
+> <cwd>/.env                    the launcher's directory
+> $DSH_HOME/.env
+```
+
+The document's real shape matters and is easy to get wrong: the ref is nested one
+level inside `refs:`, **not** at the margin  - 
+
+```yaml
+version: 1
+refs:
+  DEEPSEEK_API_KEY: sk-…        <- here
+records:
+  client-connection/browser-session:
+    payload:
+      secret: …
+```
+
+  -  and the first cut of this module missed it for exactly that reason: it looked at
+column 0, its own tests agreed with it, and the built shell then reported "no key"
+on a machine whose key was present. `the_real_document_shape_is_read` pins the real
+layout now, and `a_ref_inside_a_record_is_not_a_credential` pins the half that must
+*not* count.
+
+**The value never leaves the module.** The splash is handed a boolean and the NAME
+of the layer (`the credentials file`), never the key  -  same rule as the launch
+token. `the_splash_script_never_carries_the_secret` feeds a real-looking key in and
+asserts it does not appear in the injected script or in the console line, and the
+console line is the other place people paste from.
+
+The page still has **no IPC channel and no command**: Tauri's
+`initialization_script` injects the payload after the global object exists and
+before the document is parsed, which is why the page needs neither. The script
+guards on the pathname, because it runs on *every* top-level navigation and this
+window is later navigated to the harness URL  -  the harness page must not inherit
+the global.
+
 ## The two rules that are load-bearing
 
 The ready line carries the **launch token**, a live credential for the running
@@ -136,10 +194,11 @@ browser, so a rendered document can never replace the app's only window.
 |---|---|
 | `src-tauri/src/main.rs` | The supervisor: flags, the repository/pin lookup, the port and harness-home choices, spawning npx, the window, the geometry write-back, the exit hook |
 | `src-tauri/src/readyline.rs` | The pure half - ANSI stripping, URL extraction, the loopback refusal, `redact` - and its tests |
+| `src-tauri/src/keystate.rs` | Whether the harness will find a DeepSeek key, and which of the four layers supplied it (`keystate` docs the layering, which is `dsh-credentials-local`'s own). Parses the credentials document and `.env` files; emits the read-only payload the splash reads. **The key's value never leaves this module** - one test feeds a key in and asserts it does not come out |
 | `src-tauri/src/windowstate.rs` | The window's own memory - the record's shape, the five rules that decide whether a record can be trusted, atomic save - and its tests. Refers to no `tauri` type |
 | `src-tauri/Cargo.toml` | Two dependencies: `tauri`, and `serde_json` (already in the tree behind tauri) |
 | `src-tauri/tauri.conf.json` | Identifier, the `ui/` folder as `frontendDist`, no declared window (it is built in Rust so the navigation filter can live with it), `bundle.active: false` |
-| `ui/index.html` | The splash. One file, no request of any kind |
+| `ui/index.html` | The splash. One file, no request of any kind. The key line and the harness home are **injected** before the document parses (`initialization_script`), not fetched - the page still has no IPC channel and no command; `scripts/checks/check-splash.mjs` renders it in both states |
 | `src-tauri/icons/` | **Generated** by `scripts/make-desktop-icon.mjs` from `assets/vn-harness.svg`, and committed so a clone builds without running the generator |
 
 ## Failures
@@ -156,8 +215,9 @@ screen.
 
 Measured on Windows 11 (Rust 1.94, Node 22.20, WebView2 153) rather than assumed:
 
-- `cargo test`  -  38/38 (`main.rs` 9, `readyline.rs` 14, `windowstate.rs` 15): the
-  launch-token rules below plus the home, port and window-geometry rules;
+- `cargo test`  -  56/56 (`main.rs` 9, `readyline.rs` 14, `windowstate.rs` 15,
+  `keystate.rs` 18): the launch-token rules below plus the home, port,
+  window-geometry and key-state rules;
 - the port rule: a free port is chosen whenever 3080 is taken (61203, 62066, 60927
   across the runs that were measured while the Web GUI was serving 3080), and 3080
   itself is asked for first once nothing holds it;