From 8f0e4862c500aaccf2a02ca6aede891793a8b6fd Mon Sep 17 00:00:00 2001 From: uipreliga Date: Mon, 14 Sep 2026 14:37:53 -0700 Subject: [PATCH] docs: one pitch across every surface, and a shorter first screen Eight surfaces described the project eight different ways, and four of them were over the 155-character budget where Google and GitHub truncate. Repo traffic showed the cost: ~75% of all page views are the README, and the Sep 4-5 Hacker News wave converted 179 unique visitors into 2 stars (~1%). One pitch, layered, so each surface takes as many layers as it has room for: 1. Hook Playwright for coding agents. 2. Promise Test that your skills, MCP servers, and CLIs actually work when an agent uses them. 3. Mechanism Sandboxed YAML suites, weighted scoring, A/B, CI gates. 4. Roster Claude Code, Codex, Gemini, OpenCode, Pi. Layer 2 previously existed on exactly one surface (the plugin manifest) and is the only layer that answers "why do I care?". - README: the H1 now carries layers 1+2; the centred tagline says where a run happens; the intro is 249 -> 128 words; the duplicate "What you can do with it" section is merged into the feature bullets. Quick Start moves 76 -> 63. - pyproject: the roster leaves `description` because CE047 checks it together with `keywords`, which already names all five harnesses (~50 chars freed on the visible PyPI subtitle). - mkdocs: 242 -> 145 chars, now inside the SERP budget. This is the one surface where layer 2 does not fit: CE047 checks `site_description` in isolation, so it must spend ~48 chars naming the roster. - docs/index: 311 -> 143 chars. The H1 stays keyword-shaped; unlike the README, that page ranks on its own H1. - llms.txt: layers 1+2 lead the blockquote, so an LLM quoting one sentence quotes the right one. - action.yml / pages stub: same voice; `plugin.json` is left alone, having got this right first. Also: - New social preview card (.github/social-preview/), with its HTML source and a regenerate + upload runbook. The old card named three of five harnesses and carried the weaker headline. It needs a manual upload - GitHub has no API for the social preview image. - Delete the stray root comparison.md: a design note about the grading-material leak (PR #88), unrelated to docs/comparison.md, linked from nowhere. - Move ADOPTERS.md to .github/. With one entry - the maintainer - a root-level adopters file is negative social proof, and nothing linked to it. Applied outside the tree, so not visible in this diff: the repo description (164 chars, was 249 and missing Pi), the wiki turned off, and topics reworked so all five harnesses appear - long-horizon-agents -> mcp, then regression-testing + claude-agent-sdk -> opencode + pi-coding-agent. Not `pi`: that topic is ~50/50 Raspberry Pi. Note nothing enforces the topic roster the way CE047 enforces the seven prose surfaces. Rationale and the open items are recorded in c/2026-09-14-*.md (gitignored). Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_016BPXB3v34yHtVV4PFYYLQC --- ADOPTERS.md => .github/ADOPTERS.md | 0 .github/pages-stub/index.html | 2 +- .github/social-preview/README.md | 55 +++++++ .github/social-preview/social-preview.html | 149 ++++++++++++++++++ .github/social-preview/social-preview.png | Bin 0 -> 230584 bytes README.md | 83 +++++----- action.yml | 2 +- comparison.md | 171 --------------------- docs/index.md | 6 +- docs/llms.txt | 4 +- mkdocs.yml | 6 +- pyproject.toml | 2 +- 12 files changed, 251 insertions(+), 229 deletions(-) rename ADOPTERS.md => .github/ADOPTERS.md (100%) create mode 100644 .github/social-preview/README.md create mode 100644 .github/social-preview/social-preview.html create mode 100644 .github/social-preview/social-preview.png delete mode 100644 comparison.md diff --git a/ADOPTERS.md b/.github/ADOPTERS.md similarity index 100% rename from ADOPTERS.md rename to .github/ADOPTERS.md diff --git a/.github/pages-stub/index.html b/.github/pages-stub/index.html index 39deba000..7bf034d1c 100644 --- a/.github/pages-stub/index.html +++ b/.github/pages-stub/index.html @@ -12,7 +12,7 @@ -->