David/HERMES-GIELIE
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
HERMES-GIELIE/AGENTS.md

127 lines
6.5 KiB
Markdown
Raw Permalink Normal View History

docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
# Agent instructions for Hermes WebUI
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
This file is the shared entry point for AI assistants working in this
repository. Keep it project-specific and safe to publish. Do not put personal
machine setup, private network details, credentials, tokens, or local-only
workflow notes here.
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
## Read first
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
Before making changes, read:
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
1. `README.md`
2. `CONTRIBUTING.md`
3. `docs/CONTRACTS.md`
4. `CHANGELOG.md`
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
For architecture, testing, or setup work, also read the matching reference:
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
- `ARCHITECTURE.md` for design constraints and current module layout
- `TESTING.md` for local verification commands and manual test guidance
- `docs/onboarding.md` for first-run onboarding behavior
- `docs/troubleshooting.md` for diagnostic flows
- `docs/rfcs/README.md` for larger RFCs and state/durability contracts
Stage 382: PR #2503
2026-05-18 03:45:42 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before
changing layout, interaction flow, themes, chat rendering, or composer chrome.
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
## Onboarding and reinstall support
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
If the task involves install, reinstall, bootstrap, first-run onboarding,
provider setup, local model server setup, Docker onboarding, WSL onboarding, or
support for a failed first run, read `docs/onboarding-agent-checklist.md`
before running commands or inspecting logs.
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
Follow that checklist's safety rules:
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
- use isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` for trials unless the
human explicitly asks to use real state
- do not delete or overwrite a real `~/.hermes` directory without explicit
approval
- do not print API keys, OAuth tokens, cookies, full `.env` files, full
`auth.json` files, or password hashes
- collect non-secret status and log evidence before recommending a fix
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
## Contribution style
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
Stage 382: PR #2503
2026-05-18 03:45:42 +00:00
- Keep one logical change per PR; split unrelated refactors or cleanup.
- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched
subsystem before editing.
Release OV (v0.51.435): supported local pytest runner (#3908) (#4252) * stage-3908: supported local pytest runner + symlink-guard on venv create/clear (Codex CORE fix) Rebased rodboev/franksong2702 #3908 onto v0.51.434. Adds scripts/test.sh dev runner + requirements-dev.txt + test_ci_hygiene.py + conftest version guard. Defensive fix on the authoritative gate: create_or_rebuild_venv refuses a symlinked .venv so 'python -m venv --clear' can't wipe the symlink target (same symlink-hardening class as #4217/#4234/#4240). Locked by a hygiene test. * Release OV: supported local pytest runner (#3908) scripts/test.sh + requirements-dev.txt + conftest version guard + hygiene tests. Self-rebased franksong2702's #3908 onto v0.51.434; full Codex+Opus+suite gate. Codex CORE fix applied: refuse to create/--clear a virtualenv through a symlinked .venv (symlink-hardening class, #4217/#4234/#4240), locked by a hygiene assertion. Co-authored-by: franksong2702 <franksong2702@users.noreply.github.com> --------- Co-authored-by: nesquena-hermes <agent@nesquena-hermes> Co-authored-by: franksong2702 <franksong2702@users.noreply.github.com>
2026-06-15 17:25:32 +00:00
- For local pytest runs, use `./scripts/test.sh` instead of bare `python3`,
`python -m pytest`, or `pytest`. The script creates/uses the repo `.venv`,
pins execution to Python 3.11-3.13, and installs missing dev test dependencies.
`HERMES_WEBUI_TEST_PYTHON` selects the supported base interpreter used to
create or rebuild `.venv`; it must not install test dependencies into a
system/Homebrew interpreter directly.
If a direct pytest invocation reports an unsupported interpreter, rerun through
`./scripts/test.sh` before debugging product code.
Stage 382: PR #2503
2026-05-18 03:45:42 +00:00
- Prefer the existing Python + vanilla JavaScript structure. Do not add
dependencies, build tools, frameworks, or long-lived processes without clear
justification and a rollback story.
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
- Update docs when changing setup, onboarding, runtime behavior, architecture,
Stage 382: PR #2503
2026-05-18 03:45:42 +00:00
testing guidance, or user-facing workflows.
docs: clarify changelog release ownership
2026-06-28 02:20:55 +00:00
- Do not edit `CHANGELOG.md` in ordinary contributor PRs. The release workflow
owns changelog updates through release commits. If a change is release-note
worthy, include concise release-note wording in the PR body instead.
Stage 382: PR #2503
2026-05-18 03:45:42 +00:00
- For UI or UX changes, include before/after evidence and test relevant
desktop, narrow, and mobile states.
- For behavior changes, add or update automated tests where practical and list
the manual verification performed.
- For runtime, streaming, recovery, replay, compression, or sidebar metadata
changes, name the state layer being mutated and prove the relevant invariant.
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
- For Docker build changes in `docker_init.bash`, mirror directory exclusions
in both the `rsync` and `cp -a` paths — `/opt/hermes` may contain subdirectories
with restricted permissions (e.g. `.playwright/`).
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
docs: add change guidelines (GUIDELINES.md) + wire into AGENTS.md and CONTRIBUTING.md Distilled habits that get a PR merged in one review round instead of several: four root causes + ten rules + show-your-work PR-description contract. Full doc in docs/GUIDELINES.md, compressed 10-point form in AGENTS.md (agent entry point), pointer added to CONTRIBUTING.md reading list.
2026-07-14 22:40:52 +00:00
## Before you open a PR — the change guidelines
Read [`docs/GUIDELINES.md`](docs/GUIDELINES.md) in full before non-trivial work. It is the
distilled set of habits that get a change merged in one review round instead of several. The
compressed form:
1. **Fix the class, not the instance.** A bug usually has siblings — other call sites, backends,
companion endpoints, layouts, exit paths. Find them all and fix the shared chokepoint, or name
the ones you left out of scope.
2. **Trace one authoritative value end-to-end** (`input → normalize → decision → action → persist →
cleanup`); the code that *decides* and the code that *acts* must use the same resolved value.
3. **When you can't confirm something, fail closed and say so.** Never take the permissive branch on
uncertainty; never report a failure as success. "Unknown" is not "allowed."
4. **Enumerate the state-space before editing** — entry point, backend, item count (0/1/many), every
lifecycle exit (success/error/cancel/replace/teardown), auth on/off, concurrency, hostile input —
and cover each or mark it out of scope. Most redo rounds are one un-considered dimension.
5. **Assume inputs and check-then-use gaps are adversarial** — validate at the point of use (hold a
handle, don't re-resolve a path), scope caches by complete identity, handle crafted input.
6. **A test must fail before your fix and pass after it.** Assert observable behavior, not a source
string or a mock of the thing under test; use multiple items if selection is what's being tested.
7. **Name the owner of every piece of state and prove it's released on every exit** (success, error,
cancel, replace, shrink, teardown) — not just the happy path.
8. **Fallbacks/defaults are contracts — extend the mechanism, don't copy it.** Editing N parallel
blocks identically means you missed a chokepoint (e.g. new copy goes in the `en` locale only).
9. **The diff is the task and nothing else.** Extras go in the PR description, not the diff; run the
affected + neighboring tests before opening.
10. **A visible control costs attention on every visit** — place it by frequency of use and by where
mainstream chat apps put the equivalent, not by where your diff already is; verify with
before/after images at desktop and narrow widths.
Show the work in the PR body: the siblings you found, proof the test failed before the fix, the
verification run, before/after images for visible changes, and an explicit list of what you could
not verify.
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
## Local state and secrets
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
Hermes WebUI can read and write real agent state, sessions, workspaces,
credentials, and cron data. Treat local validation as potentially destructive
unless you have confirmed the active state directories.
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
Prefer isolated trial state for experiments:
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
```bash
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
HERMES_HOME=/tmp/hermes-webui-agent-home \
HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
docs: add agent onboarding entrypoint
2026-05-13 05:38:47 +00:00
HERMES_WEBUI_PORT=8789 \
python3 bootstrap.py
```
fix(docker): exclude .playwright from rsync staging to avoid error 23 The agent source at /opt/hermes inside the container may contain a .playwright/ directory with browser dependency files that have restricted permissions. rsync fails with exit code 23 when attempting to read them, which kills the container build ("Failed to stage hermes-agent source"). - Add --exclude=.playwright to rsync in docker_init.bash - Add rm -rf .playwright to cp -a fallback path for symmetry - Update test_docker_init_excludes_egg_info_during_staging to assert both the rsync --exclude and a broad .playwright presence check - Add a brief note in AGENTS.md Contribution style about mirroring directory exclusions in both rsync and cp paths Fixes #5315
2026-07-01 05:00:15 +00:00
Do not include private machine instructions in this tracked file. Use a
git-ignored local note for personal workflow details.
Reference in a new issue Copy permalink