initial commit

1 files changed, 45 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..18e221e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# panto-herdr
+
+`panto-herdr` reports panto lifecycle state to [Herdr](https://herdr.dev/) when
+panto is running in a Herdr pane. It reports `panto` as the agent label and
+uses `thinking`, `responding`, `compacting`, and `tool:<name>` as short status
+labels.
+
+Install it through panto's rock loader:
+
+```toml
+[extensions]
+rocks = ["panto-herdr"]
+```
+
+Then run `panto update`. Start panto in Herdr, for example:
+
+```sh
+herdr agent start panto --cwd "$PWD" -- panto
+```
+
+The extension is inert outside Herdr: it only activates when `HERDR_PANE_ID`
+is set. It invokes the local `herdr` executable asynchronously and discards
+its JSON output, so reporting does not affect the panto terminal UI.
+
+## State mapping
+
+| panto event | Herdr state |
+| --- | --- |
+| `session_start` | `idle` |
+| `user_message`, `thinking`, `compaction`, `tool_details`, `assistant_text` | `working` |
+| `assistant_text_complete` | `idle` |
+
+Current panto extensions do not receive a turn-complete or interrupt event.
+`assistant_text_complete` is therefore the best available idle boundary; an
+assistant text block followed by a tool call can show `idle` briefly before
+the next lifecycle event restores `working`. Native session restore is also
+out of scope until panto exposes a stable session reference to extensions.
+
+## Check
+
+Run the module-level check with panto's Lua runtime:
+
+```sh
+panto lua _selfcheck.lua
+```