1 files changed, 69 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3bd4b57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,69 @@
+# panto-agent
+
+The `agent.*` extension suite for [pantograph](https://github.com/travisp/pantograph)'s
+`panto` CLI: coding-agent conveniences packaged as a luarocks rock.
+
+## Extensions
+
+- **`agent.rules`** — at session start, injects the contents of `AGENTS.md`
+  (or `CLAUDE.md` when no `AGENTS.md` exists — never both) into the system
+  prompt, from each of: the base layer agent dir
+  (`${XDG_DATA_HOME:-~/.local/share}/panto/agent`), the user layer dir
+  (`${XDG_CONFIG_HOME:-~/.config}/panto`), and the project root (cwd).
+  Symlinks are resolved; each file becomes one system message headed
+  `context from <path>:`.
+
+  It also hooks `std.read` results (a `tool_result` event handler using
+  the writable `output` field): reading a file (or directory) below the
+  project root appends any `AGENTS.md`/`CLAUDE.md` found between the read
+  location and the root (root excluded — the system prompt covers it) to
+  the tool result as `---`-separated `context from <path>:` sections.
+  Each real file is injected at most once per session. The transcript
+  keeps the read's own output, with a `+ rules: <path>` line per attached
+  file below it.
+
+- **`agent.skill`** — an `agent.skill` tool for loading
+  [Agent Skills](https://agentskills.io) on demand. At activation it
+  discovers skills (subdirectories containing a `SKILL.md` with YAML
+  frontmatter) from, lowest priority first:
+  `${XDG_DATA_HOME:-~/.local/share}/panto/agent/skills`,
+  `${XDG_CONFIG_HOME:-~/.config}/panto/skills`, `~/.agent/skills`,
+  `<cwd>/.panto/skills`, and `<cwd>/.agent/skills`. The frontmatter
+  `name` (not the directory name) is the skill's identity; later
+  directories shadow same-named skills from earlier ones. Surviving
+  names and descriptions are baked into the tool's description and its
+  input schema's enum. Calling the tool returns the skill's `SKILL.md`
+  instructions (frontmatter stripped) behind a preamble that tells the
+  model to resolve the skill's relative paths against its directory.
+  With no skills discovered, the tool is not registered.
+
+## Install
+
+Via the rock (once published):
+
+```toml
+[extensions]
+rocks = ["panto-agent"]
+```
+
+Or as a local checkout:
+
+```toml
+[extensions]
+paths = ["/path/to/panto-agent"]
+```
+
+Individual extensions can be toggled with the usual policy globs, e.g.
+`deny = ["agent.rules"]`.
+
+## Development
+
+Run the self-check (needs `panto` for its embedded Lua + luv):
+
+```sh
+panto lua _selfcheck.lua
+```
+
+Layout note: the sources live under `panto-agent/` (matching the installed
+module tree) so `require` works identically installed and from a checkout;
+`_selfcheck.lua` is `_`-prefixed so panto's directory scan skips it.