@scoutmesh/viewer 0.2.0

package/README.md

@@ -0,0 +1,534 @@
+# Scout Mesh local viewer
+
+A standalone candidate viewer for agents with a terminal and a browser. The
+agent sends JSON over HTTP; the viewer handles cards, profile details,
+shortlisting, reversible removal, and live updates. It does not use the Scout Mesh
+portal, Convex, provider credentials, or paid searches.
+
+## Install the packaged preview
+
+This is an unpublished preview for agents with a local terminal and browser.
+The bootstrap handles Node.js and npm installation for the user. macOS has been
+tested with Node/npm absent from PATH; Windows installer and browser-launch code
+are included but still need a trial on a Windows machine.
+
+### npm delivery (preferred)
+
+The package is prepared for publication but is not live on npm yet. After a
+release is confirmed, the agent uses the exact version supplied by ScoutMesh:
+
+```bash
+npx --yes --ignore-scripts --registry=https://registry.npmjs.org @scoutmesh/viewer@0.2.0 launch
+```
+
+`launch` copies the package out of npm's cache into the workspace's `.viewer`
+directory, then starts it on a free port. It returns `node` and `launcher`
+absolute paths alongside `url`, `stateFile`, `version`, and `update`. Invoke the
+returned paths as `"<node>" "<launcher>" request GET /api/views` (in PowerShell,
+`& '<node>' '<launcher>' request GET /api/views`). Use that launcher for token,
+status, stop, and requests throughout the session. Clearing npm's cache does not
+remove the running installation or its rollback copies.
+
+At the next session, ScoutMesh supplies the approved version again and the agent
+runs the versioned npm command. A newer version uses the same backup, health
+check, and rollback implementation as the bootstrap launcher. Equal versions
+reuse the process; older versions do not downgrade. `current` compares against
+the requested npm version, not a fresh registry check. A cached/offline launch
+does not prove that the version is the newest published release. The saved local
+launcher's `start` works offline but does not check npm for updates.
+
+State defaults to `~/.scoutmesh/workspaces/state.json` on both platforms for the
+npm route. Set `SCOUTMESH_VIEWER_HOME` consistently for a different workspace;
+`launch` rejects `VIEWER_STATE_FILE` to prevent ambiguous ownership. Existing
+bootstrap users should keep their managed launcher; switching delivery methods
+requires stopping the old viewer and explicitly retaining its state directory.
+Node.js 24+ and npm must be available. If absent, use the verified bootstrap below.
+Neither route changes execution policy or promises to bypass host permissions.
+
+### Publish the npm pilot
+
+From the repository root, run the checks and pack the artifact:
+
+```bash
+npm run check
+npm run check-types
+npm run viewer:test
+npm run viewer:package-test
+npm run viewer:update-test
+npm publish /tmp/scoutmesh-viewer-0.2.0.tgz --dry-run --access public --ignore-scripts
+```
+
+Inspect the tarball file list before publication: it must contain only the
+package manifest, README, compiled code, public assets, and bundled skill. Local
+candidate state, runtime credentials, fixtures, and repository files are excluded
+by the package's `files` allowlist. Authenticate using `npm login` in a user
+terminal with permission to publish under `@scoutmesh`; never put a token in chat.
+Publish the reviewed artifact, not a rebuild:
+
+```bash
+npm publish /tmp/scoutmesh-viewer-0.2.0.tgz --access public --tag next --ignore-scripts --registry=https://registry.npmjs.org
+```
+
+Use the `next` tag for this pilot while Windows validation is pending. Exact
+version commands work independently of that tag. Read back the registry version
+and integrity and test a clean registry install before marking publication done.
+Promoting a tested release to `latest` and deploying the gateway instructions are
+separate rollout steps. Each later release needs a new version. No npm login,
+publication, or production gateway deployment is implied by building locally.
+
+### Bootstrap without Node or npm
+
+From the repository root on macOS, run `npm run viewer:bootstrap-pack`. It builds
+`/tmp/scoutmesh-viewer-bootstrap-0.2.0.zip` and a `.zip.sha256` checksum file.
+The ZIP contains both installers, a pinned Node runtime manifest, the viewer
+package, and its checksum. The pack command also prints the extracted bundle path.
+Build tooling needs Node and `zip`; the recruiter's machine does not.
+
+After verifying and extracting the release ZIP, the agent runs:
+
+```bash
+/bin/bash /absolute/path/to/bootstrap.sh
+~/.scoutmesh/viewer/viewer status
+```
+
+On Windows, using the bundled PowerShell:
+
+```powershell
+powershell.exe -NoProfile -File C:\absolute\path\bootstrap.ps1
+& "$env:LOCALAPPDATA\ScoutMesh\viewer\viewer.ps1" status
+```
+
+The installer checks the included package checksum, reuses compatible Node.js 24+
+with npm when present, or downloads the exact official Node archive pinned in
+`bootstrap/runtime.json`. It verifies that archive before extracting or executing
+it. npm installs the included zero-dependency package offline with install scripts
+disabled. The runtime and npm cache stay inside the installation directory; nothing
+changes the global runtime, PATH, or npm cache. The launcher remembers the paths.
+
+Defaults are `~/.scoutmesh/viewer` and `~/.scoutmesh/workspaces` on macOS, or
+`%LOCALAPPDATA%\ScoutMesh\viewer` and `...\workspaces` on Windows. Candidate JSON
+stays in the workspaces directory, separate from replaceable package files.
+The bootstrap chooses a free port; use the returned URL after every start.
+
+For an isolated trial, use `--install-dir` and `--state-dir` (absolute paths),
+`--force-runtime`, and optionally `--port` or `--no-start`. PowerShell equivalents
+are `-InstallDir`, `-StateDir`, `-ForceRuntime`, `-Port`, and `-NoStart`.
+Repeat installation reuses verified downloads and the same running workspace.
+Managed startup handles viewer upgrades. An interrupted install may leave `.bootstrap.lock`; verify
+no installer is running before removing that lock and retrying. Keep saved state.
+
+Downloads and localhost access still depend on the agent host's permissions.
+Use normal approval flows; do not change PowerShell execution policy or bypass a
+rejected token read. An existing but unreachable viewer produces an explicit
+connectivity/permission error instead of silently launching a duplicate.
+
+### Automatic updates (0.2.0 onward)
+
+The stable launcher reads `launcher.json` on every invocation, so its active package
+can change without changing the command the agent remembers. Every managed `start`
+fetches the configured release manifest and compares semantic versions. `status`
+and the authenticated health endpoint report the running package version.
+
+The release manifest has four required fields: `version` (for example `0.2.0`),
+`nodeMajor` (currently `24`), `archiveUrl`, and `sha256` (the npm tarball checksum).
+The manifest and tarball must share one HTTPS origin; redirects are rejected.
+HTTP `127.0.0.1` is accepted only to support isolated local release tests.
+The updater sends no candidate data to that origin. This relies on the configured
+HTTPS publisher plus the manifest checksum; it is not a signed release system.
+
+To package an official channel, set `SCOUTMESH_VIEWER_RELEASE_URL` to its stable
+manifest URL and `SCOUTMESH_VIEWER_ARCHIVE_URL` to the immutable tarball URL for this
+version, then run `npm run viewer:bootstrap-pack`. Both URLs are operator-supplied.
+The ZIP embeds the channel URL and the packer writes a sibling `.zip.release.json`
+for publishing at the manifest URL. Upload the tarball and ZIP first, then publish
+the manifest last. Use a new package version for every release; never replace an
+existing version's tarball. Serve the channel manifest with revalidation/no-cache.
+The ZIP's checksum should be distributed through ScoutMesh's release instructions.
+
+For a supplied channel, the installer also accepts `--release-url` / `-ReleaseUrl`.
+Rerunning with that option updates the saved channel while retaining the active
+package and state directory. Ordinary local builds have no channel and report
+`update: "not-configured"`; there is no assumed live ScoutMesh download endpoint.
+
+On a newer release, the launcher verifies and installs it in a separate directory
+with npm lifecycle scripts disabled. It then stops the current writer, backs up
+JSON and installation settings under `<stateDir>/backups`, starts the new package,
+checks its authenticated health/version, and atomically changes the active pointer.
+If startup fails, it first confirms the attempted server has stopped, preserves
+its state as `failed.json`, restores `before.json`, and restarts the previous
+package. A failed/ambiguous stop leaves recovery files and reports an error rather
+than restoring over a live writer. Backups and previous packages are retained.
+
+Startup returns `update` as `current`, `updated`, `newer-installed` (no downgrade),
+`unavailable` (download, manifest, checksum or installation failed), `rolled-back`,
+or `not-configured`. `unavailable` keeps the installed version usable and prints
+the reason; it never claims the release is current. `updated`/`rolled-back` include
+a backup directory. Always reopen the returned URL and unlock again after a restart.
+Node runtime upgrades are separate from package updates; unsupported runtime
+requirements are reported rather than installed automatically.
+
+Managed commands serialize through `.update.lock`. An interrupted updater may
+leave that lock or a partially completed transition. Confirm all relevant processes
+have stopped before manual recovery, retain both state snapshots, restore the
+appropriate installation pointer and matching JSON, and remove only stale locks.
+Recovery after a process/laptop crash during the transition is not automatic yet.
+
+The older unpublished 0.1.0 bootstrap needs to be run once with the new bundle;
+subsequent package updates use the managed launcher. The npm `launch` command uses the requested package version and managed rollback;
+plain `start` does not configure a channel or upgrade another running version. A direct CLI refuses to
+reuse a running server whose version differs from its own.
+
+### Release verification
+
+`npm run viewer:update-test` serves local test releases, upgrades a running older
+package, preserves Yes/Maybe/No decisions, rejects a bad checksum, tests unavailable
+releases and downgrade avoidance, and rolls back a failed migration.
+`npm run viewer:bootstrap-test` exercises the Mac installer with Node/npm absent
+from PATH. Neither test alters the real candidate workspace.
+
+The manual [Local viewer release checks](../../.github/workflows/viewer-smoke.yml)
+workflow runs upgrade tests on macOS and Windows, then each platform's bootstrap
+checks. The Windows smoke test uses stock Windows PowerShell 5.1, a private Node
+download, paths containing spaces, repeated startup, and saved-state recovery.
+It can also run directly with `bootstrap/windows-smoke.ps1 -BundleDir <extracted-bundle>`.
+Windows execution, Intel Mac installation, and external-browser opening still need
+platform validation before release. The workflow has not been dispatched by this
+local implementation.
+
+### Direct npm installation for development
+
+Build and pack from the ScoutMesh repository root:
+
+```bash
+npm run viewer:pack
+```
+
+This produces `/tmp/scoutmesh-viewer-0.2.0.tgz`. Install that artifact into a
+user-writable tools directory (the example uses a directory in the current folder):
+
+```bash
+npm install --ignore-scripts --no-audit --no-fund --cache ./scoutmesh-tools/npm-cache --prefix ./scoutmesh-tools /tmp/scoutmesh-viewer-0.2.0.tgz
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer start
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer status
+```
+
+Check `node --version` before installation. If your default Node is older than 24,
+use an already installed Node 24+ and keep its bin directory on PATH for npm and
+all viewer commands. The dedicated npm cache in the installation command avoids
+permission problems with an existing global cache; no global runtime or cache
+permissions need changing.
+
+Use the returned URL. `start` runs a background process and reuses an authenticated
+server already owning the same state file. `stop` stops that process without
+clearing data. Run `start` after reboot; no login service is installed. Set
+`VIEWER_PORT=4318` if the prototype is already using 4317. Keep the same
+`SCOUTMESH_VIEWER_HOME` or `VIEWER_STATE_FILE` on subsequent commands.
+
+The packaged CLI saves to `~/.scoutmesh/workspaces/state.json`, outside npm's
+installation/cache directories. `SCOUTMESH_VIEWER_HOME` changes its directory;
+`VIEWER_STATE_FILE` specifies an exact path. It contains all local workspaces.
+The sibling runtime file contains the local token and endpoint; both files are
+created with owner-only permissions on macOS; Windows uses the user directory's
+inherited ACLs. The token is not an account login and is
+never sent to ScoutMesh. `request` reads it automatically:
+
+```bash
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer request GET /api/views
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer request POST /api/views ./candidates.json
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer request PATCH /api/views/search-1 ./batch.json
+./scoutmesh-tools/node_modules/.bin/scoutmesh-viewer skill
+```
+
+The browser has an Unlock form. The agent reads `scoutmesh-viewer token` locally
+and fills it using browser tools; users need not copy the token. Never put it in
+a URL or conversation. Successful unlock creates an HttpOnly, SameSite=Strict
+cookie. The token rotates on restart; reload the page and unlock again. API calls
+require `Authorization: Bearer <local-token>` or the browser cookie. Origin/Host
+checks still apply. Shutdown requires the CLI's bearer token. Local software
+running as the same OS user can read the token file; this is not isolation from
+that user's own processes.
+
+For a direct npm installation, stop before upgrading the package, then start again. To migrate the existing
+prototype, stop it first, then copy `.data/state.json` to the chosen permanent
+state path before starting the package. Do not overwrite an existing destination
+or run the prototype and packaged server against the same state file. The
+prototype's data is deliberately not migrated or cleared automatically.
+
+The CLI prevents concurrent writers with a state-file lock and recovers locks
+whose owner process no longer exists. It refuses an ambiguous/incomplete lock or
+a live PID. For manual recovery, first verify no viewer owns this file, then
+remove only stale `.lock`, `.lock.recovery`, and `.runtime.json` metadata. Keep
+`state.json`. A damaged state file fails startup without being overwritten. The
+CLI reports the local diagnostic log path on startup failure.
+
+### Agent skill and gateway discovery
+
+The package includes [local-candidate-viewer](skills/local-candidate-viewer/SKILL.md).
+Its canonical source is this folder. The gateway has a release copy in
+`skills/local-candidate-viewer.md`; `load_skill` discovers that file automatically,
+and the overview/presentation guidance points agents to it. After changing the
+skill, run `npm run viewer:sync-skill -- /absolute/path/to/sourcing-gateway` and
+review both repository diffs. Deploying that gateway change is a separate step.
+The remote MCP service supplies instructions only; the agent performs local
+installation and HTTP requests. Cloud-only chat clients still use chat results.
+
+Publish the npm pilot using the procedure above, then put the confirmed package
+version in the gateway release instructions. The Node-missing fallback still needs
+a tested bootstrap ZIP at an official immutable URL with its SHA-256. Test Windows
+and Intel macOS before general release. Sync the skill and deploy the gateway as a
+separate rollout step. No artifact has been published and no production gateway
+has been changed by this local work.
+
+## Run the repository prototype
+
+Use Node.js 24 or newer. From the repository root:
+
+```bash
+npm run viewer
+```
+
+In a second terminal:
+
+```bash
+npm run viewer:demo
+```
+
+Open the returned URL. Shortlist or remove a candidate, then send another
+batch from the terminal:
+
+```bash
+npm run viewer:demo -- --next
+```
+
+This adds two fictional candidates and enriches one existing record. The page
+updates automatically. All demo names, employers, and evidence are fictional;
+the demo email is unverified. The initial demo command creates its view once;
+use `--next` afterward or delete the view to start again.
+
+Set `VIEWER_PORT` on both commands to use a port other than 4317.
+
+## Large-list demo
+
+Run `node prototypes/local-viewer/scale-demo.ts` to create a separate view with
+100 fictional candidates. Open its URL, move to another page, then run
+`node prototypes/local-viewer/scale-demo.ts --next` to append 20 more. Repeat
+`--next` for another unique batch; rerunning the initial command keeps the view.
+No real photos, contact information, or paid sourcing are used for this demo.
+
+Cards are paginated in groups of 20, with Previous/Next above and below the list.
+Each review list retains its page while the tab is open. New IDs arriving over
+SSE produce a View new notice; enrichment of existing IDs does not. View new
+opens that group, with Back to candidates returning to the prior candidate page
+and scroll position. Additional arrivals remain separate until opened. The notice
+and page position are browser-session state; a reload shows all records from page
+one. Stable candidate IDs retain shortlist/removal decisions across pages and batches.
+The full dataset still transfers to the browser; pagination limits rendered cards,
+not API payload size. `batchId` is optional source metadata on each record; current
+notifications detect newly added IDs, so agents need no special batch endpoint.
+
+## Agent contract
+
+1. Start `npm run viewer` and keep the process running. If it is already running,
+   inspect `GET /api/views` and reuse the intended view.
+2. Create a view with `POST /api/views`. Open the `url` returned by the server.
+3. Send the next batch to the existing view with `PATCH`. Never make a new page
+   just to append a batch. Use the same stable candidate ID for enrichment.
+4. Read `GET /api/views/:id/state` before acting on the shortlist. `selectedIds` contains the shortlist;
+   `removedIds` contains candidates set aside by the user.
+5. Reuse the same `updateId` and identical body for an HTTP retry. Generate a new
+   ID for genuinely new work. Optionally send `expectedRevision` to reject stale
+   updates; on HTTP 409, read the current view before deciding what to change.
+
+Example creation:
+
+```bash
+curl http://127.0.0.1:4317/api/views \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"search-1","title":"Engineering leads","records":[{"id":"source:42","name":"Anna","role":"Engineering lead","company":"Example"}],"layout":{"type":"table","columns":["name","role","company"]}}'
+```
+
+Example enrichment and next batch:
+
+```bash
+curl -X PATCH http://127.0.0.1:4317/api/views/search-1 \
+  -H 'Content-Type: application/json' \
+  --data '{"updateId":"batch-2","expectedRevision":1,"operation":"upsert","records":[{"id":"source:42","location":"Amsterdam"},{"id":"source:43","name":"Noah","company":"Example"}]}'
+```
+
+| Endpoint                    | Purpose                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| `GET /api/views`            | List local views and record counts.                                                     |
+| `POST /api/views`           | Create with `title`, `records`, optional `id` and `layout`.                             |
+| `GET /api/views/:id`        | Read current records, layout, revision, and UI state.                                   |
+| `PATCH /api/views/:id`      | Apply `upsert`, `replace`, `remove`, or `set_layout`. Requires `updateId`.              |
+| `GET /api/views/:id/state`  | Read selected IDs, filter, sorting, revision, record count, and connected browsers.     |
+| `PUT /api/views/:id/state`  | Save `selectedIds` (shortlist), `maybeIds`, `removedIds`, and legacy filter/sort state. |
+| `DELETE /api/views/:id`     | Remove this view and its records from the saved session.                                |
+| `GET /api/views/:id/events` | Browser SSE subscription; refetch on notifications and reconnect.                       |
+
+`upsert` merges fields by ID. New records require `id` and `name`; enrichment
+can omit the name. `replace` replaces the record set; `remove` takes `ids`.
+`set_layout` takes `layout: {type: "table" | "cards", columns: [...]}`. A PATCH
+can also include `title` and `layout` alongside a data update.
+
+Candidate fields accept strings, finite numbers, booleans, null, or string
+arrays. Preserve source links and evidence as explicit fields. The viewer does
+not verify claims, compute fit scores, or merge identities across providers.
+Profile details expose all supplied fields. Candidate text renders as text,
+never HTML; only HTTP(S) values become external links.
+
+On macOS and Windows, clicking a profile or source link (including a middle-click or
+modified click) opens it in the system's default browser. The viewer sends a
+JSON POST to `/api/open-external`; the local server validates an HTTP(S) URL
+without embedded credentials and invokes `/usr/bin/open` with an argument
+array, without a shell. The endpoint uses the same Host/Origin checks as the
+rest of the API. Failure displays an error instead of opening an in-app tab.
+Windows uses a constant PowerShell `Start-Process` command with the validated URL
+supplied in an environment variable, never interpolated into code. Other operating
+systems return an unsupported-platform error. Windows execution remains unverified.
+Email addresses continue to use the default mail application through `mailto:`.
+
+## Candidate cards
+
+The UI labels positive and negative review decisions **Yes** and **No**, with
+Maybe unchanged. Yes uses the existing `selectedIds` field; No uses `removedIds`.
+Saved decisions and the API schema are unchanged. Undo No returns a candidate to
+Unreviewed. References to shortlisting or removal below describe those same states.
+
+Review lists show All, Unreviewed (the default), Yes, Maybe, and No
+with counts. All includes removed candidates, who have a Restore action. Shortlist
+and Maybe are mutually exclusive toggles; pressing an active choice returns the
+candidate to Unreviewed. Removing a candidate clears the other decisions. Undo
+restores the prior decision; Restore returns them to Unreviewed.
+
+Profiles keep identity, section navigation, and review actions visible while the
+content scrolls. Overview prioritizes supplied `fitSummary` and `unconfirmed`,
+with the full assessment under a disclosure. Career appears only with career,
+education, skills, or experience evidence. Contact appears only with supplied
+contact/profile links or drafts. Empty tabs are omitted; Previous/Next opens each
+person on Overview. Profile tabs support arrow keys, Home, and End.
+
+The open profile has Previous and Next buttons with a position count. Navigation
+follows the current All, Unreviewed, Yes, Maybe, No, or new-batch list across page
+boundaries. The buttons stop at the first and last person. Moving resets profile
+scroll; Close or Escape returns focus to the original card without changing the
+list page. Live updates refresh both the profile and navigation.
+
+Cards show the candidate's photo, name, role, company, location, and two assessment rows: Why they may fit and Needs confirmation.
+Send an optional `photoUrl` containing an HTTPS image URL returned by the
+candidate's source (for example, GitHub's `avatar_url`). Keep attribution in
+`photoSource` and `photoSourceUrl`; these appear under More information. The same photo appears in the open profile. Missing, invalid, or
+failed images fall back to initials. Images load directly from the provider
+without sending a referrer; the viewer does not download or store image files.
+Source URLs can expire; refresh `photoUrl` through the normal upsert API.
+Send `fitSummary` with a concise, role-specific reason to consider the person,
+and `unconfirmed` with the main missing requirements or uncertainties. Keep
+source qualifiers such as "reported" or "public repository"; a title or code
+sample does not prove proficiency. These rows are fully visible, without text
+clamping. The viewer renders the agent's assessment; it does not calculate fit.
+Without these fields it uses existing `justification`/`summary` and `gaps`.
+Missing uncertainty is shown as "Not assessed yet", never as all requirements met.
+
+View details opens a separate profile card on Overview. Sources shows named
+profile and repository links, deduplicating a repeated `evidenceLink`. Other
+supplied fields remain under More information. A valid `linkedin` URL adds a
+direct card link. A valid `email` address adds a card Email action with supplied
+verification status and Copy email. Missing contacts do not produce inactive buttons.
+
+The viewer preserves the agent's record order. Search, sorting, table controls,
+and selection checkboxes are not shown. Decisions can be changed from either a
+card or the fixed profile footer; deciding does not close the profile.
+
+Review actions use `PUT /api/views/:id/state`. `selectedIds` remains the API name
+for shortlisted IDs; `maybeIds` tracks candidates needing further review and
+`removedIds` tracks removals. All three survive upsert batches
+and page reloads in the local state file. Decisions do not change candidate records.
+An agent should exclude `removedIds` when proposing more actions on the batch.
+A permanent API remove prunes all three lists.
+Legacy filter/sort/layout fields remain accepted by the API but do not control
+the card interface. Older state writes may omit `removedIds` or `maybeIds` to preserve them.
+The three lists are mutually exclusive. Existing JSON files without `maybeIds`
+load with an empty Maybe list and retain their previous decisions.
+
+The profile card has an always-visible Close button and supports Escape.
+Closing it returns focus to the original result. Shortlist, Maybe, and Remove stay
+available in the profile footer. Revealed emails and source disclosures are
+browser-only and reset on reload; shortlist/removal state is saved to disk.
+
+## State and delivery
+
+The repository prototype automatically saves candidate records, shortlist/removal decisions,
+record batch IDs, revisions, and retry history to
+`prototypes/local-viewer/.data/state.json`. This is plain, readable JSON, not
+SQL. It stays on this laptop, is excluded from Git, and is not served as a web
+asset or sent to the portal. Arrays and nested state make JSON a better session
+format than CSV. Images remain provider URLs, not downloaded image files.
+
+Every successful mutation writes a temporary file, flushes it, then atomically
+replaces the state file. A failed save rejects the change without updating memory.
+An unreadable, invalid, or unsupported state file stops startup rather than
+silently clearing saved work. The file is created with owner-only permissions.
+Run only one viewer process per state file. To use a different path:
+
+```bash
+VIEWER_STATE_FILE=/absolute/path/viewer-state.json npm run viewer
+```
+
+After a laptop restart, run `npm run viewer` and reopen the same URL; this does
+not install an automatic startup service. Saved views and decisions are restored.
+Active tabs, pages, open profiles, Undo, and new-batch notices remain temporary
+browser state and reset on reload. To back up the session, copy the JSON file.
+Stop the server before manually editing or restoring it. DELETE a view to remove
+it from the saved session; stopping the process no longer clears data.
+The `createViewerServer` factory uses an in-memory store by default for tests;
+the `npm run viewer` entry point explicitly uses the file-backed store.
+
+HTTP success confirms the mutation was saved by the running store, not browser rendering.
+SSE tells connected pages to refetch. `connectedBrowsers` describes active
+subscriptions, not proof that a person saw the update. Reconnecting pages fetch
+the latest complete snapshot, so missed notifications do not lose batches.
+
+Review decisions and legacy filter/sort state survive data updates, page
+refreshes, and server restarts. They are shared by tabs viewing the same view; the last UI state
+write wins. The server prunes selections when records are removed. This is a
+single-user prototype, not a collaborative editing protocol.
+
+The process binds only to `127.0.0.1`. Host and browser-origin checks reject
+cross-site access, mutations require JSON, and responses disable caching. No
+request bodies are logged. Other local programs are trusted. Do not expose the
+port publicly or forward it without adding authentication. A remote agent needs
+its browser on the same host or an authenticated preview mechanism.
+
+Limits: 20 views, 2,000 candidates per view, 2 MB per request, 12 visible columns,
+and retry deduplication for the last 500 update IDs per view. Components are
+shared by the repository prototype and the packaged CLI. The package is not
+yet published; gateway integration distributes instructions, not a remote UI. It uses browser DOM components instead of the
+portal's React components to keep the prototype free of bundling and auth setup.
+
+## Verify
+
+```bash
+npm run viewer:check
+npm run viewer:test
+npm run viewer:package-test
+npm run viewer:update-test
+npm run viewer:bootstrap-test # macOS; downloads the pinned runtime
+npm run check
+npm run check-types
+```
+
+The automated tests cover batch merging, enrichment, retries, stale revisions,
+atomic validation, selection preservation, removal/replacement, layout changes,
+HTTP boundaries, SSE delivery, and deletion. Browser validation must additionally
+check that an external PATCH updates the open page and preserves UI state.
+
+The package test installs the real tarball into a temporary directory, starts two
+clients concurrently, adds 100 + 20 records, saves decisions and an email draft,
+reinstalls the package, restarts, retries the update, and checks that corrupt state
+is left intact. It also verifies token rotation and private file permissions.
+
+The bootstrap test removes Node and npm from PATH, downloads and verifies the
+pinned runtime, installs in paths containing spaces, checks repeat installation,
+restarts with saved decisions, and rejects a corrupt package. It uses temporary
+fictional data and stops its server on completion. Windows needs a separate real
+machine trial before release.