hermes - 💡(How to fix) Fix docs: document post_tool_call plugin hook as the integration seam for audit/receipt-chain plugins [1 participants]

Tracking issue for the proposal in PR #18151 (@nosleepcassette). Converting the +1907-line spec-as-PR into an issue so the ideas can live somewhere discussable without a standing PR.

Four threads, scoped roughly from smallest to largest:

1. Filtering and sorting on the achievements API

Add query params to GET /api/plugins/hermes-achievements/achievements:

• state — unlocked / discovered / secret / all
• category — filter by category string
• sort_by — name / tier / progress / evidence / unlocked_at
• order — asc / desc
• limit — cap results

"Evidence depth" = raw progress for tiered achievements, sum of per-requirement fulfillment % for multi-condition ones. Lets users sort by "how much of this achievement's lifecycle have I traversed." Dashboard frontend gets a filter bar above the grid.

2. CLI, slash command, and TUI panel

• hermes achievements [summary|list|show <id>|rescan|export] top-level subcommand, imports the plugin engine directly (no HTTP).
• /achievements slash command with /ach, /badges aliases.
• Ink TUI panel: category-grouped cards, keyboard navigation, evidence drill-down.

3. Export formats and agent communication

• GET /api/plugins/hermes-achievements/export?format=json|markdown|svg (optional state param)
• hermes achievements export --format json|markdown|svg [--output PATH]
• SVG = badge sheet (shields.io-style, tier-colored, embeddable in READMEs).
• Markdown = category tables with progress bars and tier badges.
• GET /achievements/summary plus ~/.hermes/plugins/hermes-achievements/agent_summary.json — compact profile (strengths, gaps, unlocked_ids, top_tier) written on every rescan, injectable into agent context without blowing the token budget.

4. hermes curator --dry-run (cross-cutting — not achievements-specific)

This is the piece that isn't coupled to the achievements plugin. Adds --dry-run to mutating curator subcommands (install, update, enable, disable, remove, rescan). Core idea: a DryRunRecorder that intercepts planned mutations (file writes, config edits, plugin state transitions) and prints a structured preview instead of executing.

Exit codes:

• 0 — no breaking changes
• 1 — breaking change detected (deletes, config removals, plugin removal)
• 2 — preview computation failed

Plugin hook: optional dry_run_preview(proposed_version, current_state) in a plugin's plugin_api.py lets the plugin report version-specific risks (e.g. achievements can report orphaned unlock IDs whose achievement definitions no longer exist).

Relates to #18373 — a dry-run / preview flag is one plausible answer to the "curator auto-archived my skills without asking" class of complaint.

Full design (endpoint specs, pseudo-code, test outlines, files-changed table) is in the closed PR #18151. Not splitting into four separate issues yet — each section is implementation-ready and a contributor can pick one up without needing to re-derive the design.

cc @nosleepcassette — thanks for writing this up.