Finding
Hermes configuration reliability is weak when YAML or JSON edits are treated as text changes instead of validated operational changes.
Current
A real Hermes installation often depends on structured configuration for profiles, providers, tools, cron jobs, gateway behavior, memory settings, and dashboard content. The weak point is that a tiny syntax issue, especially a colon, quote, indent, list marker, or multiline string, can silently break loading or change meaning before anyone notices. If validation only happens after a runtime failure, the installation is debugging symptoms instead of catching the config defect at the edit boundary.
Suggested
- Add mandatory syntax validation after every structured config edit. Exact change: add a “YAML/JSON validation” step to
docs/runbooks/hermes-config-change.mdrequiring the edited file to be parsed before restart or deployment, using an appropriate YAML or JSON parser rather than visual inspection. - Add a config-edit verification habit to the main operator instructions. Exact change: patch
SOUL.mdor the optimizer-agent operating prompt with: “After changing YAML, JSON, TOML, cron definitions, profile config, dashboard data, or workflow metadata, validate syntax first, then verify the affected Hermes behavior.” - Create a small regression check for public achievement and dashboard data. Exact change: add a verification item to the dashboard publish checklist: “Before publishing, parse all achievement frontmatter and structured data, confirm required keys exist, and fail the update if title, slug, rank, category, state, or source_url is missing or malformed.”
Impact
This catches configuration breakage at the cheapest possible point: immediately after the edit. It reduces downtime, avoids confusing provider or tool failures caused by malformed config, and makes dashboard publishing safer because structured page metadata is checked before it reaches users. The result is less debugging chaos and more confidence that configuration changes are deliberate, valid, and reversible.
Effort
Small — the main work is adding one validation step to the config runbook, one operator habit, and one dashboard publishing check. No new architecture is required; this is a discipline upgrade around existing Hermes files and workflows.
Public page note
Safe public content includes the operational lesson, generic YAML/JSON validation rules, required metadata fields, and the maturity recommendation to validate structured config after edits. Internal-only content includes actual private config files, raw parse errors containing sensitive paths, env values, credentials, provider details, gateway tokens, raw logs, and private chat or session content.