docs(newos4): seed a chatting-with-hermes skill (v4.6.74)

A command that exists but is undocumented might as well not exist: the agent had no way to
learn that `hermes` exists, that `chat` is taken, that replies are asynchronous, or that
the cursor is milliseconds. Skill covers the commands, the chat_hermes tool, the failure
table (401/413/429/503/507), the rules that keep it useful, and how to verify a send.

Seeded from skill-pack-core._buildSkills() so every fresh session gets it; mirrored to
skills/chatting-with-hermes.{md,json} + index.json (19 entries).

1 files changed, 72 insertions, 0 deletions

diff --git a/modules/ext/skill-pack-core.js b/modules/ext/skill-pack-core.js
index c3c643b..8cd8632 100644
--- a/modules/ext/skill-pack-core.js
+++ b/modules/ext/skill-pack-core.js
@@ -55,6 +55,78 @@ class SkillPackCoreModule {
         });
 
         return [
+            // v4.6.74: the agent could not find out how to reach Hermes. Commands that
+            // exist but are undocumented may as well not exist.
+            sk('chatting-with-hermes', 'How to message Hermes (the platform operator) from inside newOS4, and how to read the answer - commands, the chat_hermes tool, cursor and error semantics', ["hermes", "chat", "operator", "escalation", "feedback", "agent"], 'system',
+`# Talking to Hermes
+
+Hermes is the operator agent that runs the host. You can reach it from the terminal or from your
+tool loop, and its answer comes back on its own. Use it for decisions you cannot make yourself:
+policy, deploy approval, scope, "is this what you wanted".
+
+Contract: \`/_docs/chat-contract.md\`.
+
+## Say it
+
+    hermes <message>        # send (legacy alias: feedback)
+    hermes-poll             # check for new replies now (alias: feedback-inbox)
+    hermes-reset            # rotate the token, start a fresh thread
+
+**Not \`chat\`.** \`ChatStudioModule\` already registers \`chat\` (it toggles the chat overlay) and
+command dispatch walks modules in order, so a second \`chat\` is unreachable — it silently does
+nothing. If you type \`chat hello\` and nothing happens, that is why.
+
+Inside the tool loop:
+
+    chat_hermes { "action": "send", "text": "..." }   -> { "sent": true, "id": ..., "epoch": ... }
+    chat_hermes { "action": "read" }                  -> { "awaiting": bool, "messages": [...] }
+
+Replies are **asynchronous**. Send, continue working, read on a later step. Do not block on an
+answer that is minutes away.
+
+## Read it
+
+Replies print themselves: a 30 second poller shows \`🤖 <text>\` in the terminal with no command
+from you. The cursor is persisted, so a reload does not replay history.
+
+\`awaiting: true\` means the last word in the thread is yours — an answer is pending. \`false\` means
+Hermes answered.
+
+## Failures and what they mean
+
+| Status | Code | Meaning | Do |
+|---|---|---|---|
+| 401 | \`bad_token\` | token missing or malformed in localStorage | \`hermes-reset\` |
+| 413 | \`too_long\` | over 4000 **codepoints** (emoji count as one) | shorten; nothing was sent |
+| 413 | \`too_large\` | body over 32 KB | shorten |
+| 429 | \`rate_limited\` | 20/thread or 40/IP per 10 min | wait \`retry_after_ms\` |
+| 503 | — | nginx is throttling the host, HTML body | retry with backoff; **not** your mistake |
+| 507 | \`thread_limit\` | too many threads on disk | tell the operator |
+
+Only \`429\` and \`503\` are worth retrying. Everything else is permanent for that payload.
+
+## The cursor is milliseconds
+
+\`epoch\` and \`cursor\` are epoch **milliseconds**. Seconds look plausible and are wrong — two
+messages in the same second would collide. Never compute the cursor yourself; the server issues it
+on every poll, including an empty one (0).
+
+## Rules that keep this useful
+
+- One thought per message. A wall of text gets a shallow answer.
+- Never send credentials, tokens or personal data — it is stored in plain text on the host.
+- Do not poll in a loop. 30 s is already automatic; \`hermes-poll\` is for "I need it now".
+- Threads are per browser token. \`hermes-reset\` deliberately abandons the old thread, and the old
+  messages stay on disk but you will not see them again.
+- If Hermes asks a question, answer it in the same thread — the operator loses the context otherwise.
+
+## Verify your own result
+
+    hermes hello            -> "📨 Sending…" then "✅ sent id=… epoch=…"
+    hermes-poll             -> "⏳ waiting for Hermes" while the answer is pending
+
+A send that prints only \`📨 Sending…\` and never a ✅ or ❌ means the request never completed —
+report that, it is a bug, not a slow answer.`),
             // v4.6.65: merged from `command-composition-rules` and
             // `terminal-commands-silently-failing` (packet §9) — they described one bug family
             // from two angles, and both are now describing behaviour that is refused outright.