Merge pull request #123 from open-coder-ai/docs/readme-landing

docs: README that leads with the matrix, and a GIF that tells the truth

Author: jothimani-rajendran

.github/workflows/ci.yml

@@ -148,6 +148,28 @@ jobs:
           agentseam matrix | head -3
           agentseam doctor --repo .
 
+  # The README's own Quick start is a claim like any other -- extract the real bash
+  # fence with tools/quickstart_block.py and run it, rather than trusting that a code
+  # sample still works. `pip install .` first so the block's own `pip install agentseam`
+  # is satisfied by the tree being tested instead of fetching a different release.
+  quickstart:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+      - run: pip install .
+      - name: Run the README's Quick start block
+        run: |
+          set -euo pipefail
+          workdir=$(mktemp -d)
+          python3 tools/quickstart_block.py > "$workdir/quickstart.sh"
+          cd "$workdir"
+          bash -euo pipefail quickstart.sh
+
   # The runtime path must stay importable with no third-party packages: adapters are
   # copied verbatim into other projects, so an accidental dependency breaks exactly
   # the consumers this library exists for. Cheaper to assert than to discover.

.github/workflows/render-demo.yml

@@ -0,0 +1,42 @@
+# Renders docs/assets/demo.tape -> demo.gif with VHS, on demand.
+#
+# Manual-only (workflow_dispatch): rendering is an authoring step, not a build step,
+# so it never spends CI minutes on its own. Run it from the Actions tab, download the
+# `demo-gif` artifact, review it, and commit the GIF alongside the README change that
+# points at it. Linux rendering is canonical -- the tape is authored against a Unix
+# shell, and VHS is at its flakiest on Windows.
+name: Render demo
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  vhs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7
+        with:
+          python-version: "3.12"
+
+      # The tape drives the real CLI; install the tree being rendered.
+      - name: Install agentseam
+        run: pip install .
+
+      - name: Render tape
+        uses: charmbracelet/vhs-action@f6d7db07a432fcd3b06772628d36a57f96d95dcf  # v2
+        with:
+          path: docs/assets/demo.tape
+
+      - name: Upload GIF
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: demo-gif
+          path: docs/assets/demo.gif
+          if-no-files-found: error

CHANGELOG.md

@@ -6,6 +6,17 @@ versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Docs
+- **README rewritten to lead with the hero demo GIF and the honest capability matrix**,
+  ahead of the pitch copy. Adds a hero GIF (`docs/assets/demo.tape`, rendered by the new
+  manual `render-demo` workflow) showing the real `agentseam install all` output; a
+  Supported agents table now covers all 16 agents with a `Verified` column (basis and
+  date from `agentseam matrix --evidence`); and a one-sentence count of how many
+  `pre_tool` claims are live-run witnessed versus doc-derived (4 of 12). The Quick start
+  block is now run for real in CI (`tools/quickstart_block.py` + the new `quickstart`
+  job) instead of trusted on faith. Bundles, Design and the per-vendor example-page
+  generator sections moved to `docs/` verbatim.
+
 ### Added
 - **`claude_code`'s `prompt_submit` and `stop` cells are now witnessed at 2.1.263**, the
   way W53 did `pre_tool`. Both gates were re-run against the real CLI with the fixed

README.md

@@ -0,0 +1,39 @@
+# agentseam — hero demo GIF
+#
+# Renders the real loop: a six-line handler, wired into every coding agent's own hook
+# system with one command. The end frame is `agentseam install all`'s real output --
+# one line per agent, ending in the enforcement level agentseam actually verified for
+# it. No level shown here is claimed beyond what the matrix grades that agent today.
+#
+# Prerequisites: `agentseam` on PATH (pip install -e .) and VHS
+#   (https://github.com/charmbracelet/vhs)
+# Render:
+#   vhs docs/assets/demo.tape        # writes docs/assets/demo.gif
+
+Output docs/assets/demo.gif
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 640
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 40ms
+Set Padding 24
+
+# --- hidden setup: throwaway repo, throwaway HOME (junie/kimi_code write under $HOME) ---
+Hide
+Type "cd $(mktemp -d) && git init -q && export HOME=$(mktemp -d) && clear"
+Enter
+Type "echo ZnJvbSBhZ2VudHNlYW0gaW1wb3J0IHJ1biwgRGVjaXNpb24KCmRlZiBoYW5kbGVyKGV2ZW50KToKICAgIGlmIGV2ZW50LmV2ZW50ID09ICJwcmVfdG9vbCIgYW5kICJBS0lBIiBpbiAoZXZlbnQuY29udGVudCBvciAiIik6CiAgICAgICAgcmV0dXJuIERlY2lzaW9uLmRlbnkoIm5vIEFXUyBrZXlzIGluIG1lbW9yeSBmaWxlcyIpCiAgICByZXR1cm4gRGVjaXNpb24uYWxsb3coKQoKcnVuKGhhbmRsZXIpCg== | base64 -d > my_handler.py && clear"
+Enter
+Show
+
+# --- 1. the handler is six lines ---
+Type "cat my_handler.py"
+Enter
+Sleep 2500ms
+
+# --- 2. wire it into every agent at once; end frame holds the real per-agent levels ---
+Type 'agentseam install all "python3 my_handler.py" --events pre_tool --repo .'
+Enter
+Sleep 4000ms

docs/assets/demo.gif

@@ -0,0 +1,31 @@
+# Bundles: mostly the same directory, twice
+
+A Claude Code plugin and a Gemini CLI extension turn out to be nearly the same thing
+underneath two different manifests:
+
+| part | Claude Code plugin | Gemini CLI extension | |
+|---|---|---|---|
+| skill | `skills/<name>/SKILL.md` | `skills/<name>/SKILL.md` | identical |
+| subagent | `agents/<name>.md` | `agents/<name>.md` | identical |
+| hooks | `hooks/hooks.json` | `hooks/hooks.json` | identical |
+| command | `commands/<name>.md` | `commands/<name>.toml` | same folder, different format |
+| manifest | `.claude-plugin/plugin.json` | `gemini-extension.json` | different |
+
+So one directory serves both, and the real work is the second manifest and writing the
+commands twice. VS Code has no bundle format at all — parts are found by location, so
+committing the file *is* the install — and it reads several of Claude Code's own folders
+natively: `.claude/skills`, `.claude/agents`, `.claude/rules`, and hooks straight out of
+`.claude/settings.json`.
+
+```bash
+agentseam packaging
+```
+
+...prints each layout, the templates shared by more than one agent, and which folders an
+agent reads that belong to somebody else. That last line matters in both directions: a
+repo shipping `.claude/skills` is already shipping skills to VS Code, intended or not.
+
+`plan(agent, bundle)` renders a bundle into the exact files an agent expects, and — as
+with permissions — hands back what the format cannot hold, with a reason specific to that
+agent. Gemini can't take a `.mcp.json`, but not because it lacks MCP: it declares servers
+in the manifest instead, and saying "no MCP support" would be as wrong as saying nothing.

docs/assets/demo.tape

@@ -0,0 +1,13 @@
+# Design
+
+- **stdlib only.** No dependencies, ever, in the adapter path — adapters must stay
+  copy-portable into other projects that vendor single files.
+- **Adapters own all vendor knowledge.** Adding an agent in an existing family is a
+  config entry plus a matrix row; no consumer changes.
+- **Ownership-marked wiring.** Install is idempotent and uninstall is surgical: your own
+  hooks in the same config are never touched.
+- **The matrix carries provenance.** Every row records the version and date it was
+  verified, and how.
+
+[ARCHITECTURE.md](../ARCHITECTURE.md) explains why those choices, what they cost, and the bug
+classes they exist to prevent.

docs/bundles.md

@@ -0,0 +1,25 @@
+# See it per vendor before you install anything
+
+[`examples/generated/`](../examples/generated/) has a page for every agent agentseam can hook,
+each showing the **same situation** — an agent about to write a secret into a file it will
+read back later — in that vendor's own dialect: the config `install` writes, the normalized
+event a handler sees, and what `allow` / `deny` / `escalate` / `transform` / `warn` / `vouch`
+each turn into on the way back (aliases: `ask` for `escalate`, `rewrite` for `transform`),
+including the ones that get reduced because the agent cannot express them.
+
+There is a section for **every hook each agent supports**, in lifecycle order. Every block
+is generated by running the library, and CI fails if the pages drift from what it actually
+produces — an example nobody regenerates is a claim nobody checks.
+
+What the pages cannot do is verify the vendors. Each row records what its claims rest on —
+`live-run`, `live-run-partial`, `vendor-source`, `vendor-docs`, `third-party-install`,
+`inherited` — and most are vendor documentation, which is a claim about what a vendor *says*
+rather than an observation of what their build does. Claude Code's row rests on a full live
+run; Codex CLI, Cursor, and VS Code Copilot each rest on a partial one, with the observed
+events listed on the row. Vendors change hook surfaces without notice, so **verify against
+your own installation before relying on any of it**, and open an issue if a page is wrong.
+
+```bash
+python3 examples/generate.py           # rewrite the pages
+python3 examples/generate.py --check   # what CI runs
+```

docs/design.md

@@ -0,0 +1,30 @@
+"""The extractor CI runs the README's Quick start block through."""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "tools"))
+
+from quickstart_block import extract  # noqa: E402
+
+
+def test_extracts_the_real_readme_block():
+    text = (ROOT / "README.md").read_text(encoding="utf-8")
+    block = extract(text)
+    assert block is not None
+    assert "agentseam install all" in block
+    assert "pip install agentseam" in block
+
+
+def test_none_when_no_quick_start_heading():
+    assert extract("# agentseam\n\n```bash\necho hi\n```\n") is None
+
+
+def test_none_when_quick_start_has_no_bash_fence():
+    assert extract("## Quick start\n\n```python\nprint('hi')\n```\n") is None
+
+
+def test_stops_at_the_first_fence():
+    text = "## Quick start\n\n```bash\none\n```\n\n```bash\ntwo\n```\n"
+    assert extract(text) == "one\n"