initialize Electron desktop app and remove unused files

docs/harness/README.md

@@ -0,0 +1,42 @@
+# Harness Overview
+
+This harness turns recurring project knowledge into files and checks that an
+agent can discover without chat history.
+
+## Goals
+
+- Make repository context legible through short maps and deeper docs.
+- Keep architecture constraints close to the code they protect.
+- Give agents a deterministic validation path before opening or updating a PR.
+- Prefer mechanical checks over reminder text when a rule can be verified.
+
+## Entry Points
+
+- `AGENTS.md` is the root map for coding agents.
+- `ARCHITECTURE.md` documents package boundaries and state ownership.
+- `DEVELOPMENT.md` remains the contributor rules and command reference.
+- `docs/harness/validation.md` maps change types to checks.
+- `docs/harness/worktree-runbook.md` explains isolated worktree development.
+- `docs/harness/pr-review.md` provides a PR self-review checklist.
+- `scripts/harness-check.mjs` enforces baseline repository invariants.
+- `npm run check:orphans` checks source reachability from application and test
+  entrypoints; see `docs/harness/orphan-audit.md` for the audit and exceptions.
+
+## Operating Model
+
+1. Read the root map and the specific doc for the task.
+2. Make the smallest scoped change.
+3. Add or update focused tests when behavior changes.
+4. Run `npm run harness:check` and the relevant validation commands.
+5. If a failure pattern repeats, improve this harness with docs, tests, scripts,
+   or CI instead of relying on a longer prompt.
+
+## What Belongs In The Harness
+
+- Facts that future agents must know to work safely.
+- Checklists that prevent repeated PR review comments.
+- Scripts that fail fast on repository-wide invariants.
+- Runbooks for local, CI, and release flows.
+
+Do not put long implementation notes in `AGENTS.md`. Add them under `docs/` and
+link to them from the map.

docs/harness/orphan-audit.md

@@ -0,0 +1,73 @@
+# Orphan-file audit — 2026-10-25
+
+The audit followed static imports, re-exports, literal `import()` and `require()`
+from Electron, Vue, server, CLI and test entrypoints, then checked candidate paths
+and exported names against source, scripts, tests and documentation. Public
+assets were checked separately against HTML, Vue, CSS/SCSS, manifest and source
+references. No unresolved local imports were found during the audit.
+
+## Removed
+
+Seven source files had no application or test callers:
+
+- `packages/server/src/services/windows-command.ts`: unused Windows shim helpers;
+  active command launchers have their own implementations.
+- `packages/server/src/services/credentials.ts`: unused file-based credential
+  store; active login uses the users database and profile credential services.
+- `packages/server/src/services/hermes/context-engine/index.ts`: unused barrel;
+  compression code imports implementation modules directly.
+- `packages/client/src/api/hermes/runtime-versions.ts`: unused browser API wrapper;
+  the server's runtime/version endpoints remain in use and were retained.
+- `packages/client/src/api/hermes/global-agent.ts`: unused browser socket wrapper;
+  the active chat store owns its global-agent connection.
+- `packages/client/src/components/hermes/kanban/KanbanColumn.vue`: unused column
+  component; the current Kanban view builds its active columns directly.
+- `packages/client/src/components/hermes/chat/DrawerPanel.vue`: unused old drawer;
+  active file and terminal panels remain.
+
+Nine unreferenced assets were removed: `public/logo-original.png`,
+`src/assets/image.gif` and all seven TTF files in `public/fonts/` under
+`packages/client/`. Total source/asset reduction: 16 files, 16,571,452 bytes.
+The current logo, favicon, thinking animation and external KaTeX fonts remain.
+
+## Retained deliberately
+
+- `api/hermes/stt.contract.ts` is compiled by `vue-tsc` for request-shape assertions.
+- `styles/arco-theme.ts` is the documented token reference and a style-test input.
+- `composables/useNotification.ts` belongs to the documented frozen Arco adapter
+  API, alongside the message and dialog adapters.
+- Modules imported only by regression tests remain test dependencies, including
+  summary-cache, read-only conversation helpers, response-stream parsing and the
+  disabled session-import guard. Removing these would change test coverage and
+  safety checks, which is outside this cleanup.
+- `prototype_reference/` is referenced by the current theme documentation and
+  style comments. Historical documents, vendor provenance and vendored Python
+  bridge files were preserved.
+- `dist/`, `release/`, dependencies, coverage and browser-test reports are ignored
+  generated output, not source orphans. Existing tested installers are retained
+  locally and excluded from Git.
+
+## Ongoing check
+
+Run `npm run check:orphans`. The checker follows application and test module
+imports and explicitly lists the two documented non-runtime entrypoints above
+(STT contract and notification adapter). Declaration files and vendored code are
+excluded. Dynamically constructed paths and public assets still need manual
+review; the checker is not proof that an individual export is unused.
+
+Component tests now enable Vue Test Utils automatic unmount in the JSDOM setup.
+This disposes watchers and animation work that could otherwise outlive the test
+document and intermittently fail coverage runs during environment teardown.
+
+## Validation
+
+- `npm run harness:check` and `npm run check:orphans`: passed.
+- `npm run test:coverage -- --maxWorkers=4`: 289 files passed; 2,141 tests passed,
+  2 skipped, no unhandled errors after the component cleanup fix.
+- `npm run test:e2e -- --workers=2`: all 69 browser tests passed.
+- `npm run build`: passed.
+- `npm run test:electron`: all three real Electron tests passed.
+
+This checkout had no initial Git commit. The initial source snapshot excludes
+dependencies, installers, build output, local state and test reports. A scan of
+the candidate files found no private-key or provider-key patterns.

docs/harness/pr-review.md

@@ -0,0 +1,42 @@
+# PR Self-Review
+
+Use this checklist before pushing or updating a pull request.
+
+## Scope
+
+- The PR title states the behavior being changed.
+- The diff is limited to the requested task and required harness updates.
+- Unrelated formatting or refactors are not bundled into the change.
+- User-facing text has locale coverage.
+
+## Architecture
+
+- Client code uses shared API helpers and existing UI patterns.
+- Server routes stay thin and delegate reusable behavior to controllers/services.
+- Web UI state uses `config.appHome` or documented helpers.
+- Hermes Agent state and Web UI state remain separate.
+- Subprocess calls use argument arrays instead of shell string construction.
+
+## Tests And Validation
+
+- A focused test was added or updated for behavior changes.
+- Browser-visible flows have e2e coverage when the risk justifies it.
+- `npm run harness:check` passes.
+- The PR body lists validation commands that actually ran.
+- Known limitations or follow-ups are called out.
+
+## Release And CI
+
+- Workflow changes were checked with `npm run harness:check`.
+- Release artifact lists stay platform-specific where a matrix target has its
+  own expected output.
+- `fail_on_unmatched_files: true` is preserved when each matrix target has its
+  own expected artifact list.
+- Package manifest changes have matching lockfile changes when dependencies
+  change.
+
+## Before Merge
+
+- CI is green or failures are explained as unrelated.
+- The branch is mergeable.
+- The PR does not depend on hidden local state, credentials, or uncommitted files.

docs/harness/validation.md

@@ -0,0 +1,67 @@
+# Validation Guide
+
+Run the smallest relevant checks while iterating. Escalate to the broad checks
+when touching shared behavior, release automation, auth, persistence, or chat.
+
+## Always Run For PRs
+
+```bash
+npm run harness:check
+npm run check:orphans
+```
+
+For broad or shared changes, also run:
+
+```bash
+npm run test:coverage
+npm run test:e2e
+npm run build
+```
+
+## Change-Type Matrix
+
+| Change | Minimum local validation |
+| --- | --- |
+| Docs only | `npm run harness:check` |
+| Client component/store/API | focused `npm run test -- <pattern>`, then `npm run build` |
+| User-visible browser flow | focused Vitest plus `npm run test:e2e` |
+| Server controller/service/db | focused `npm run test -- tests/server/<file>` |
+| Auth, profile, or credential behavior | focused server tests plus relevant e2e auth tests |
+| Chat, Socket.IO, group chat | focused server tests plus relevant e2e chat tests |
+| Chat session chain, Agent Bridge, compression, or Group Chat | Add one `docs/chat-chain-changes/*.md` fragment with date, PR/commit, touched feature, and behavior impact; then run `npm run harness:check` plus focused chat/bridge/group-chat tests |
+| Electron lifecycle, preload, native packaging | `npm run build`, `npm run electron:setup`, `npm run test:electron`, `npm run pack` |
+| Docker image | `npm run harness:check` and `npm run build` |
+| GitHub workflow | `npm run harness:check` and `actionlint` when available |
+| Package manifests | `npm ci --ignore-scripts` and lockfile workflow expectations |
+
+## CI Mapping
+
+- Build workflow: installs dependencies, runs coverage, and builds production
+  assets on pushes and pull requests.
+- Playwright workflow: runs browser e2e tests.
+- NPM lockfile workflow: verifies `package-lock.json` is synchronized.
+- Electron packages workflow: manually builds native installers on macOS, Windows
+  and Linux, then uploads platform-specific artifacts without publishing.
+- Electron smoke tests: run after the browser suite on Linux, and in the manual
+  macOS verification workflow.
+
+## Release Workflow Guardrail
+
+Published GitHub Releases should still trigger Web UI artifact packaging and
+Docker image publishing, but those workflows must keep the GitHub Release out
+of latest.
+
+Web UI release jobs must upload only the artifacts their build can produce. Keep
+artifact globs in matrix data and keep `fail_on_unmatched_files: true` so a
+missing expected file still fails.
+
+## Failure Handling
+
+When a command fails:
+
+1. Read the first actionable error, not just the final stack trace.
+2. Check whether the failure indicates missing context, missing test coverage,
+   or a missing mechanical rule.
+3. Fix the product bug when there is one.
+4. Update docs or `scripts/harness-check.mjs` when the same class of mistake
+   should be prevented next time.

docs/harness/worktree-runbook.md

@@ -0,0 +1,62 @@
+# Worktree Runbook
+
+Use a separate git worktree for agent changes so local user work remains
+untouched.
+
+## Create A Worktree
+
+```bash
+git fetch origin --prune
+git worktree add -b codex/<short-topic> ../worktrees/hermes-ui-<short-topic> origin/main
+cd ../worktrees/hermes-ui-<short-topic>
+```
+
+If the repository uses a fork remote, push to the remote requested by the task.
+Do not rewrite or reset unrelated branches.
+
+## Install
+
+```bash
+npm ci --ignore-scripts
+npm rebuild node-pty
+```
+
+## Isolated Runtime
+
+Use per-worktree state and ports to avoid colliding with a running local app:
+
+```bash
+export PORT=18648
+export HERMES_WEB_UI_HOME="$PWD/.tmp/hermes-ui"
+export HERMES_WEBUI_STATE_DIR="$HERMES_WEB_UI_HOME"
+export UPLOAD_DIR="$PWD/.tmp/uploads"
+npm run dev:web
+```
+
+Do not point `HERMES_WEB_UI_HOME` at a user's real `~/.hermes-web-ui` when a task
+only needs local verification.
+
+For Electron development, first run `npm run electron:setup`, then launch with
+`HERMES_ELECTRON_USER_DATA="$PWD/.tmp/chromium" npm run dev` while keeping the
+service home overrides above. Electron selects its own loopback service port.
+
+## Browser Checks
+
+For browser-visible changes:
+
+```bash
+npm run test:e2e
+```
+
+Prefer existing Playwright fixtures and mocked backend services. Add real-service
+requirements only when the behavior cannot be represented with mocks.
+
+## Cleanup
+
+After a PR is pushed and no more local work is needed:
+
+```bash
+git worktree remove ../worktrees/hermes-ui-<short-topic>
+```
+
+Only remove the worktree you created.