# Technical Implementation Guide for Hermes

## Preflight commands and evidence

Use tools available in the target environment; do not invent command success. At minimum record:

- release-manifest and SHA-256 verification;
- runtime and package-manager versions;
- source tree, application entry points and current tests;
- port availability and loopback behavior;
- Hermes version/profile-safe status and capability endpoints actually supported;
- current worktree/uncommitted changes;
- operating system/architecture; and
- required dependency downloads awaiting approval.

Create a new work copy outside the immutable `source/` directory. If Git is available, use a dedicated branch or worktree and commit intentionally. Do not initialize a repository over unrelated user files.

## Expected reproducible commands

The finished application must document and implement commands equivalent to:

```text
install locked dependencies
initialize or migrate database
seed safe starter content
run development mode
build production assets/server
start production local service
run unit tests
run integration tests
run end-to-end/accessibility tests
run diagnostics/doctor
create backup
validate and restore backup
package release
```

Exact command names follow the selected package manager. No successful path may depend on undocumented source edits.

## Required configuration names

Start from the root `.env.example`. The final `.env.example` contains names and safe comments only. Populate the private `.env` outside source control. Never print values in reports. Separate the application access secret, session secret, CSRF secret and provider keys.

`APP_ACCESS_SECRET`, if the approved architecture actually needs it, is internal server entropy—not a login password, bypass account, universal credential, URL token or browser value. The user creates the local login credential interactively on first run, and only its reviewed password verifier persists. Remove an unused secret variable rather than inventing a second authentication path.

Do not assume the illustrative `HERMES_BASE_URL` from the master contract exists. Detect the installed interface, show the exact proposed local URL and obtain approval before probing it. Do not expose a local gateway publicly.

## Definition of a completed offline core

S1 can pass only when a test proves:

1. first run creates a credential and approved Mission Profile;
2. role-specific Starter missions are clearly labeled;
3. mission/project/task/note/measure/decision/risk/review CRUD works;
4. valid loop transitions and invalid transitions are enforced server-side;
5. material earlier edits reopen downstream stages and clear stale approvals;
6. archive, restore and delete behave distinctly;
7. search/filter/sort operate on real saved records;
8. restart recovers the exact durable state;
9. starter clear/restore never overwrites adopted or real records;
10. export/import/backup/restore/delete validate atomically;
11. role and data partitions reject cross-boundary access;
12. browser code contains no provider secret; and
13. AI controls show a truthful setup/offline state.

## Definition of a connected AI path

S3 can pass only when authenticated capability discovery selects a real supported endpoint and a safe request produces provider-originated streamed deltas. Verify Stop/cancel, retry/failure, session resume, selected-agent server instructions, tool-event separation, redacted diagnostics and no fake fallback. Preserve a sanitized run receipt without confidential content.

If live Hermes is unavailable, finish the adapters and test contracts but report the live path untested. Never relabel a test double as a real smoke test.

## Uniform governance enforcement

Implement one server-authoritative policy engine called by every create/update/import/AI/retrieval/memory/export/agent/tool path. The browser may provide early warnings, but server rules are controlling. Test equivalent actions through different pages and agents to prove the same EDENA, CHART and permission outcome.

## Release hygiene

Before packaging:

- scan source/builds/logs/fixtures/reports for secrets and prohibited data;
- run type/build/lint/test commands;
- verify clean install from the packaged archive in a new temporary directory;
- verify migration from the prior supported schema and rollback from failure;
- verify launchers and loopback-only binding;
- verify control matrix coverage against the rendered UI;
- create SBOM, manifest and checksums after all content is final; and
- ensure ZIP members have one safe root, no traversal, symlinks, duplicates or embedded secrets.

The final report records actual results and remaining blockers, not intentions.
