Skip to content

100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.

feat(agent_skills): first-reader, readers before you publish

Shubham Sabooc70e7b787c26
diff --git a/agent_skills/README.md b/agent_skills/README.md
index b158eb64..ae189985 100644
--- a/agent_skills/README.md
+++ b/agent_skills/README.md
@@ -21,6 +21,7 @@ Most "skills" on registries are text-only prompt dumps — advice the model alre
| [🧠 advisor-orchestrator-worker](advisor-orchestrator-worker/) | Turns your agent into the orchestrator of a three-tier model team: cheap stateless workers in parallel, expensive advisor consulted only at commitment boundaries, verification gates between every step — budgeted so a run can't burn a hole in your API bill |
| [🏺 commit-archaeologist](commit-archaeologist/) | Reconstructs why a file or code region exists from local git history, including its introducing commit, later edits, repeated companion files, current authorship, and intent clues |
| [🩺 dependency-doctor](dependency-doctor/) | Autopsies a dependency manifest for standard-library shadowing pins, obsolete backports, unpinned entries, duplicate or conflicting constraints, and opt-in yanked PyPI releases |
+| [👁️ first-reader](first-reader/) | Two simulated readers with lives meet your draft cold, one passage at a time, and leave their comments beside your text: a skim gate, a no-lookahead timed read with quit points, a recall test of what survived, a trust ledger of the implied author. Afterwards you can ask any reader a follow-up. The experience layer anti-slop skills skip; never rewrites |
| [🪦 project-graveyard](project-graveyard/) | Scans your machine for dead side projects, autopsies why each one died from its git history (deploy fear, payments wall, killed by a newer project), shows your personal death patterns, and resurrects the one with a pulse — with relapse tracking on every resurrection it prescribes |
| [🔭 scope-creep-detector](scope-creep-detector/) | Checks a diff against its stated intent, flags unrelated files and scope signals, and recommends what to keep, split, or justify |
| [♾️ self-improving-agent-skills](self-improving-agent-skills/) | Automatically optimizes agent skills using Gemini and ADK |
diff --git a/agent_skills/docs/first-reader-concept.md b/agent_skills/docs/first-reader-concept.md
new file mode 100644
index 00000000..ae55fa5d
--- /dev/null
+++ b/agent_skills/docs/first-reader-concept.md
@@ -0,0 +1,101 @@
+# first-reader: a skill that reads like a human instead of auditing like a machine
+
+Research synthesis and skill concept, 26 Aug 2026, branch `evaluate-scandinavian-design-skill`.
+Method modeled on ericzakariasson/scandinavian-design: rules as the residue of specific corrections, checks that failed twice become scripts.
+
+Status: BUILT. The skill lives at `agent_skills/first-reader/`, with its
+deterministic tests, behavioral evals, fixtures, and development ledger at
+`agent_skills/evals/first-reader/`. Round-1 and round-2 experimental
+results are in the ledger; this document remains the design rationale and
+research record.
+
+## The question
+
+After running any of the ten anti-slop skills, slop still gets through, and the final gate is still a human reading the piece, feeling something is off, and rewriting it in their own language. What is that human doing, and can it be a skill?
+
+## What the research says
+
+Three tracks: a mechanical dissection of all ten anti-slop skills (full SKILL.md text retrieved for each), the cognitive and social psychology of reading, and how professional editors and workshop methods actually review.
+
+### 1. The ten skills automate the heuristic that is known not to work
+
+The landscape is two root documents (Wikipedia's "Signs of AI writing" and stop-slop) forked ten ways, converging on the same ~30 bans: delve, tapestry, em dashes, rule of three, "not X but Y", fake-profound kickers. Across ~150KB of instruction text, the only two agents ever modeled are the **detector** (burstiness, perplexity) and the **author** (voice samples, defendability). The reader is invoked rhetorically ("trust readers") but never given attention, priors, memory, or a quit point.
+
+The psychology literature lands directly on this. Jakesch, Hancock and Naaman (PNAS 2023, N=4,600) showed the cues laypeople use to spot AI text are **wrong**, which is why AI text can score "more human than human." Russell, Karpinska and Iyyer (2025) found the people who detect AI text near-perfectly (a five-person majority vote misclassified 1 of 300 articles, beating commercial detectors and surviving humanizer tools) rely on something else: **originality, specificity, whether the text ever commits to anything, whether confidence varies across claims**. Word-blacklist skills automate the flawed lay heuristic. The accurate detectors judge what the text risks, not which words it uses.
+
+Two skills even delete the most memorable lines on principle ("Cut quotables. If it sounds like a pull-quote, rewrite it"), optimizing not-sounding-AI directly against retention. And the "add soul" recipes are themselves standardizing: three separate skills reach for the same 2am-debugging anecdote. The humanity injection is becoming a new formula.
+
+### 2. What a human reader actually is
+
+The reading science converges on one model: **a forager building a gist model under time pressure, running a trust evaluation of the implied author in parallel.**
+
+- **Foraging.** People read at most ~20-28% of the words on a page (Nielsen, 45k pageviews). Scanning patterns: F-pattern on walls of text, layer-cake across headings, spotted across numbers and bold. Full line-by-line reading happens only after the reader *decides* the piece earned it. ~55% of visits are under 15 seconds; median scroll depth is ~50% (Chartbeat). High-stakes readers are stoppers, not weighers: slush readers reject on paragraph one, VCs average 3:44 on a deck, recruiters 7.4 seconds on a resume. One reason to stop is enough, and an early credibility hit taxes everything after it.
+- **Gist, not sentences.** Readers keep a situation model, not a transcript (Kintsch). Verbatim memory collapses within ~80 syllables (Sachs 1967); gist persists (fuzzy trace theory). What survives: the beginning and the end (serial position), the single most intense moment and the final beat (peak-end), and the distinctive isolate in uniform text (von Restorff). **Uniformly polished text has no isolates, so nothing sticks.** That is the memory signature of slop: it reads fine and leaves nothing.
+- **The contract.** Relevance theory (Sperber and Wilson): every sentence carries a presumption that its cognitive effect will justify its processing cost. Violations don't register as neutral padding; they trigger inference about the writer (Grice): padding reads as time-wasting, uniform hedging as not-knowing, restating as condescension. Fluency also transfers: hard-to-process prose makes the *author* seem less intelligent (Oppenheimer 2006).
+- **The parallel trust channel.** Reading is a parasocial encounter with an implied author (Horton and Wohl; Booth). Credibility is built by costly signals: checkable specifics, admissions against interest (Walster 1966), commitments that could be wrong, confidence that varies by claim. Generic praise and safe hedges are free, hence worthless. Real-experience accounts carry more sensory and contextual detail than fabricated ones, and readers implicitly use detail density as a truth cue. The MIT uncanny-valley work found imperfection and vulnerability *increase* likability; frictionless fluency triggers unease. "Text that emerges from nowhere, addressed to no one, with no stake in its claims" is the fundamental tell, and it is invisible at the word level.
+
+### 3. What a professional reviewer actually does
+
+- **Altitude discipline.** Developmental, then line, then copy, never mixed, because you don't polish sentences in a chapter you're about to cut, and because each pass needs a different reading posture. A real editor refuses to copyedit a structurally broken draft.
+- **Feedback is testimony, not verdict.** Peter Elbow's "movies of the reader's mind": narrate, in order and in past tense, what happened in you while reading: expectations formed and broken, where you got lost, where you were won back. The reader cannot be wrong about what they experienced; the writer stays free to decide it doesn't matter. George Saunders runs a P/N needle in his head and logs its position sentence by sentence. Maxwell Perkins wrote to Fitzgerald in exactly this register: "the reader's eyes can never quite focus upon him," and Fitzgerald could act on it instantly.
+- **Right about where, wrong about how.** The workshop constant: when readers flag the same place, the place is real, even though every reader's prescription is wrong. So: diagnose place and effect, hold fixes loosely and separately (Liz Lerman's Critical Response Process: meaning first, then questions, then opinions only by permission).
+- **The ear detects the missing person, not the banned word.** Editors spot ghost-written and committee text by seams: the implied person changing mid-document, mechanical cleanliness from a writer known to be rough, "volunteer sentences" that no individual chose (Klinkenborg), connective tissue without metabolism.
+
+## The gap, stated plainly
+
+Every existing skill operates on **properties of the text**. The thing you feel when you catch surviving slop is a property of the **experience**: the needle drifting to N, the sentence that cost more than it paid, the paragraph you realize you skimmed, the moment the implied author stopped being a person, the fact that you remember nothing from the middle. No skill occupies that territory. It is also the territory the accurate human AI-detectors operate in.
+
+## The skill: `first-reader`
+
+Not an eleventh deslopper. The reader's chair. It never rewrites; it produces a reading.
+
+### Why an LLM can't just be told "read like a human"
+
+An LLM sees the whole text at once, with perfect memory and infinite patience: three properties no human reader has. Prompting "imagine you're a busy reader" produces performed impatience on top of a god's-eye read. The skill's job is to **mechanically remove those three superpowers**, the way scandinavian-design's scripts removed the model's ability to lie to itself about screenshots.
+
+### Mechanism: five instruments
+
+**1. Cast the reader (script + intake).** Not "the audience" in the abstract. A named persona with priors (what they already know and believe), a situation (phone, feed, inbox, slush pile), a patience budget from the empirical genre data (feed ~15s, recruiter ~7s, memo reader ~4 min, committed subscriber ~full read), and zero cost to quitting. Default: two casts per review, a sympathetic reader and a skeptical gatekeeper (Elbow's believing and doubting games, run as separate labeled passes).
+
+**2. The skim gate (`skim` script, deterministic).** Extract exactly what a scanner fixates on: headings, first ~2 words of each line's opening, first sentences, bold, numbers, links, plus a mobile paragraph-height estimate. Feed *only this view* to a fresh agent and ask: what is this piece about, and do you commit? This is the layer-cake test. Most pieces die here and no anti-slop skill can even represent that.
+
+**3. The timed read (`feed` script, the core).** A driver reveals the text one paragraph at a time to a reader agent with **no lookahead**. At each step the reader logs: what I expect next, needle position (P/N with a reason), effort paid vs effect gained, and whether my cast persona quits here. The output is the movies-of-the-mind transcript: a chronological log with the exact sentence where attention died, where trust broke, where the piece won the reader back, and the predicted stop-point per persona. Restoring the arrow of time is what turns analysis into reading.
+
+**4. The forgetting test (`recall` script).** A separate agent reads the piece once, then, **with the text removed from context**, answers: retell it in one sentence (sayback), quote anything you can (pointing; the von Restorff isolates), what was the peak, how did it end. Diff the retained gist against the author's intended thesis. This is a real experiment, not roleplay: gist that doesn't survive one context boundary won't survive a commute. Also computes Elbow's center of gravity: where the piece came alive vs what it claims to be about.
+
+**5. The trust ledger (`signals` script + judgment).** Construct the implied author ("the person these sentences imply is...") and flag seams where that person changes. Inventory costly signals vs free ones: checkable specifics (numbers, names, dates that could be wrong), admissions against interest, falsifiable commitments, epistemic variance (does confidence differ across claims, or is everything asserted at the same temperature?). A text that pays only free signals reads as marketing or machine, and readers treat those identically.
+
+### The report: Lerman order, testimony register
+
+1. **Sayback and meaning.** What this piece is, as received, and what landed. First, always, because it tells the writer what not to break.
+2. **The reading.** The transcript, quoted to the sentence: "At 'X', I expected Y and got Z. The needle went N here and never recovered. My skeptical cast quit at this line; my sympathetic cast finished but skimmed section 3."
+3. **What survived.** The recall results: retained gist vs intended thesis, the quotables, the peak, the ending.
+4. **The person behind it.** Implied author, seams, trust ledger.
+5. **Neutral questions, then opinions by permission.** Prescriptions last, labeled as opinions, declinable.
+
+Altitude rule: if the skim gate or the developmental read fails badly, the skill says so and stops. No line notes on a piece whose structure is dead. And it never rewrites: "putting it in your language" belongs to the writer or to their voice skill (e.g. x-article-writing). Where is the reviewer's job; how is the writer's.
+
+### Guardrails
+
+- **The needle is allowed to stay positive.** An LLM judge always finds something; a first reader sometimes just gets pulled through. "I read it twice and have only pointing to offer" is a valid, reportable outcome, and the eval enforces it with control pieces.
+- No scores. A reading, not a rubric. The only numbers are empirical (stop-point, recall content, signal counts).
+- Testimony phrasing is enforced: "here is where I stopped believing you," never "this is bad."
+- The banned-word layer is out of scope on purpose. Run no-ai-slop first if you want it; this is the gate after.
+
+### Eval (per the repo bar)
+
+- **Adversarial set:** pieces that pass all ten anti-slop skills clean but are hollow (the exact residue Shubham still catches by hand). first-reader must produce a broken reading: no gist retained, flat needle, no costly signals.
+- **Control set:** distinctive human writing full of surface "tells" (em dashes, triads, quotables used well). first-reader must produce an engaged reading and must not manufacture complaints. This is the piece every humanizer fails.
+- **Ground-truth correlation where it exists:** published pieces with real engagement data; does the predicted stop-point track scroll depth or drop-off? Does the recall test's quotable match what people actually quoted or screenshotted?
+- **Reproducibility:** same piece, same cast, three runs; the flagged *places* should agree even when phrasing differs (the workshop invariant: readers agree on where).
+- Stress roles per case (stress-hook, stress-middle, stress-trust, stress-voice-seam) plus the control, scandinavian-design style.
+
+### Why this can win
+
+- The tell-catalog ground is saturated: one Wikipedia page forked ten ways. This is the entirely unoccupied layer, and it is the layer the demonstrably accurate human detectors actually use.
+- It has real scripts doing real work (exposure gating, context-boundary recall, signal inventory), not prose the model already knows.
+- It composes instead of competing: no-ai-slop cleans the surface, first-reader judges the experience, the writer's voice skill does the rewrite. A pipeline, with this as the final gate: which is exactly the role the human currently plays.
+
+### Sources (selected)
+
+Nielsen/NNg reading and scanning studies; Chartbeat engaged-time data; Pirolli and Card, information foraging; Kintsch, construction-integration; Bransford and Franks 1971; fuzzy trace theory; Kahneman peak-end; von Restorff 1933; Sperber and Wilson, Relevance; Grice 1975; Oppenheimer 2006; Jakesch, Hancock, Naaman, PNAS 2023; Russell, Karpinska, Iyyer 2025 (arXiv:2501.15654); Clark et al., ACL 2021; MIT textual uncanny valley (Kishnani 2025); Horton and Wohl 1956; Walster et al. 1966; Zahavi, costly signaling; Berger and Milkman 2012. Editorial: Elbow, Writing Without Teachers / Writing With Power / Sharing and Responding; Saunders, A Swim in a Pond in the Rain; Lerman, Critical Response Process; Perkins' Gatsby letters; McPhee, Draft No. 4; Zinsser; Klinkenborg; Le Guin, Steering the Craft; Gottlieb, Paris Review Art of Editing No. 1; Milford/Clarion workshop method; DocSend pitch-deck data; Ladders eye-tracking study.
diff --git a/agent_skills/evals/first-reader/evals.json b/agent_skills/evals/first-reader/evals.json
new file mode 100644
index 00000000..bcba44cd
--- /dev/null
+++ b/agent_skills/evals/first-reader/evals.json
@@ -0,0 +1,62 @@
+{
+ "skill_name": "first-reader",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Be my first reader on evals/first-reader/fixtures/hollow-clean.md. It's a blog post for senior engineers, going on my company blog. Readers should come away wanting to start documenting.",
+ "expected_output": "A reading report showing the piece fails experientially despite clean prose: skeptic bails early, recall returns framings without evidence, trust ledger shows zero costly signals. Altitude rule invoked; no line edits offered.",
+ "expectations": [
+ "The agent never opens the draft before the timed reads; only the scripts touch it, or contamination is disclosed",
+ "A skim gate and at least one no-lookahead timed read are actually run via feed.py, and the report quotes the transcript rather than summarizing it",
+ "The skeptical persona's quit point is reported as a specific chunk or sentence",
+ "The trust ledger cites signals.py measurements (portable share, zero numbers, zero first person) read through the genre",
+ "Findings are phrased as reader testimony anchored to quoted text, with no numeric quality scores",
+ "The report says the problem is developmental (nothing at stake, nothing new for the cast reader) and does not offer word-level or line-level fixes",
+ "The agent does not rewrite any part of the draft"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "I ran my anti-slop skill on this and it still needs a final gate. Review evals/first-reader/fixtures/human-tells.md like a human reader. Audience is engineers on Hacker News.",
+ "expected_output": "A clean, engaged reading report: both personas finish, recall matches the intended gist, quotable lines identified, and the review says so without manufacturing findings.",
+ "expectations": [
+ "The report is allowed to be happy: it states the piece works and does not invent defects to seem thorough",
+ "Surface tells (em dashes, mirrored contrasts, a quotable kicker) are not flagged, because no reader tripped on them",
+ "Recall results are reported: the retelling, the surviving quotes, the peak, the ending",
+ "Any genuine reader stumbles from the transcripts (for example an unverifiable flourish) are reported as testimony, quoted",
+ "No rewriting occurs and no scores are given"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "Would anyone actually read this? evals/first-reader/fixtures/tiny.md, it's a release note I'll post to our Discord.",
+ "expected_output": "The short-text path: one cold read with a persona, first felt reaction, retention check, trust ledger; no chunked feed ceremony for 60 words.",
+ "expectations": [
+ "The agent routes to the under-150-words path instead of running the full chunked feed",
+ "A persona relevant to a Discord release note is cast",
+ "The verdict covers the felt first reaction and what a skimming user retains (the breaking change)",
+ "The review stays proportional: short text, short report"
+ ]
+ },
+ {
+ "id": 4,
+ "prompt": "Read my API reference page like a human and tell me if it flows nicely as an article.",
+ "expected_output": "The agent reframes: reference pages are foraged, not read in order; skimmability and lookup success are the win conditions, and the review tests those instead.",
+ "expectations": [
+ "The agent does not run a linear timed read on reference material",
+ "The skim gate becomes the main event, with lookup tasks for a reader who arrives with a question",
+ "The agent explains why 'flows as an article' is the wrong goal for this genre"
+ ]
+ },
+ {
+ "id": 5,
+ "prompt": "Here's my draft, review it as a reader and then fix the weak parts in my voice.",
+ "expected_output": "The reading happens; the rewrite is declined with the reason, and the transcript is offered as input to the user's own editing pass or voice skill.",
+ "expectations": [
+ "The agent runs the review but refuses to rewrite, citing that where is the reviewer's job and how is the writer's",
+ "The refusal points the user to their own voice or editing skill with the transcript as input",
+ "Findings remain testimony with quoted anchors"
+ ]
+ }
+ ]
+}
diff --git a/agent_skills/evals/first-reader/fixtures/config-reference.md b/agent_skills/evals/first-reader/fixtures/config-reference.md
new file mode 100644
index 00000000..125f6a58
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/config-reference.md
@@ -0,0 +1,38 @@
+# retrycfg configuration reference
+
+All options live in `retry.toml` at the repo root. Values shown are
+defaults.
+
+## retry.max_attempts
+
+Integer, default `5`. Total tries including the first. Set to `1` to
+disable retries entirely.
+
+## retry.backoff
+
+String, default `"exponential"`. One of `fixed`, `linear`,
+`exponential`. Exponential doubles the delay each attempt starting
+from `retry.base_delay_ms`.
+
+## retry.base_delay_ms
+
+Integer, default `250`. First delay in milliseconds. With exponential
+backoff and 5 attempts the worst case wait is 3750 ms.
+
+## retry.jitter
+
+Boolean, default `true`. Adds up to 20% random jitter to every delay.
+Disable only in tests that assert exact timing.
+
+## retry.retry_on
+
+List of strings, default `["timeout", "connection_reset"]`. HTTP status
+codes may be given as strings: `"503"` retries on service unavailable.
+Codes in the `4xx` range other than `408` and `429` are refused with a
+config error at load time.
+
+## Environment overrides
+
+Every key can be overridden with `RETRYCFG_` variables:
+`RETRYCFG_MAX_ATTEMPTS=3` beats the file. Overrides are read once at
+startup; changing them at runtime has no effect.
diff --git a/agent_skills/evals/first-reader/fixtures/hollow-clean.md b/agent_skills/evals/first-reader/fixtures/hollow-clean.md
new file mode 100644
index 00000000..d8bbd95f
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/hollow-clean.md
@@ -0,0 +1,17 @@
+# Why documentation shapes engineering culture
+
+Documentation is the quiet force behind every effective engineering team. Teams that write things down move faster over time. Teams that rely on memory slow down as they grow.
+
+The reason is simple. Code describes what a system does today. Documentation describes why it does that, and why the alternatives lost. When the reasoning is written down, new engineers can absorb it without interrupting anyone. When it lives in people's heads, every question becomes a meeting.
+
+Good documentation starts with the reader. Before writing a page, strong teams ask what the reader needs to accomplish. They write for the engineer who arrives next year, not the one who shipped the feature last week. This shift in perspective changes what gets written and how.
+
+There are practical habits that help. Keep documents close to the code they describe. Review them the way code gets reviewed. Delete pages that no longer describe reality, because a wrong page costs more than a missing one. Assign an owner to every document so staleness has a name attached.
+
+The costs of skipping this work are real. Onboarding stretches from weeks into months. Senior engineers spend their days answering questions they have answered before. Decisions get relitigated because nobody wrote down why the last debate ended the way it did. Incidents take longer to resolve when the runbook lives in someone's memory and that someone is asleep.
+
+Culture is the deeper effect. A team that documents its thinking becomes a team that examines its thinking. Writing forces clarity that conversation lets you skip. An argument that survives being written down is usually a better argument. Over time, the habit compounds into a team that disagrees productively and decides durably.
+
+None of this requires heavy process. A short document beats a long one that nobody finishes. A rough page today beats a polished page next quarter. The bar is usefulness, and usefulness is judged by the reader.
+
+Start small. Pick one undocumented system, write one page about why it exists, and ask the newest engineer on the team whether it helped. Their answer will tell you more than any style guide. Then do it again next week. The teams that win are the ones that keep doing it after the novelty wears off.
diff --git a/agent_skills/evals/first-reader/fixtures/human-tells.md b/agent_skills/evals/first-reader/fixtures/human-tells.md
new file mode 100644
index 00000000..e0cb6d5f
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/human-tells.md
@@ -0,0 +1,13 @@
+# The outage was a for loop
+
+At 2:47am on March 11th our payments API started returning 502s for every merchant in Europe — 4,100 of them, all at once. I know the exact minute because PagerDuty screenshots are forever, and because I spent the next four hours learning something embarrassing about code I had personally reviewed.
+
+The culprit was a retry loop I approved in October. Three lines. It retried failed webhook deliveries — sensible, standard, boring. Except the author had put the retry inside the database transaction, and I had looked straight at it and thought "clean."
+
+Here is what actually happened that night. A merchant in Rotterdam had a webhook endpoint that started timing out. Each timeout held its transaction open for 30 seconds while the loop retried. Postgres has a default of 100 connections. You can do the math faster than our dashboard did — it took 11 minutes to eat the entire pool. Every other request in Europe queued behind a Dutch furniture store's broken endpoint.
+
+I keep thinking about why I missed it in review. The code was tidy. The tests passed — all 34 of them, because every test mocked the database, so no test could ever hold a real connection open. Our test suite was structurally incapable of catching our worst outage of the year. That sentence still bothers me.
+
+We fixed it in three moves: move the retry outside the transaction, add a 5-second statement timeout, and cap webhook retries at 2 before punting to a queue. The fix diff was 19 lines. The incident doc was 9 pages.
+
+What I actually took from it: review the shape of the failure, not the shape of the code. Tidy, tested, and approved — and it still took down a continent. Now when I review anything with a loop and an external call, I ask one question first: what does this hold while it waits? It has caught two more of these since. Cheap question. I plan to keep asking it.
diff --git a/agent_skills/evals/first-reader/fixtures/mcp-stateless-article.md b/agent_skills/evals/first-reader/fixtures/mcp-stateless-article.md
new file mode 100644
index 00000000..e7019b5f
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/mcp-stateless-article.md
@@ -0,0 +1,236 @@
+# Give your agents tools that scale down to zero or up to infinity
+
+An agent is only as capable as its tools, and in production those tools run as Model Context Protocol (MCP) servers. Every other layer of your stack scales to zero when it goes idle. Your tools could not, because until last month a single MCP session pinned every tool call to one container.
+
+By [@zeroasterisk](https://x.com/@zeroasterisk) and [@Saboo_Shubham_](https://x.com/@Saboo_Shubham_)
+
+When we began deploying MCP servers across our cloud infrastructure at Google, we hit that wall immediately. Connecting over HTTP meant running an initialize handshake, negotiating capabilities, capturing a session token, and routing every subsequent request back to the exact same pod. The original transport was designed for one client talking to a local sidecar process. Pushing that into a cloud-native environment meant sticky sessions, a Redis cluster whose only job was remembering routing headers, and idle containers we paid for around the clock because they could never safely scale to zero.
+
+The 2026-07-28 Model Context Protocol specification fixes this at the source. It deletes transport sessions, makes every tool call independent, and lets your agent's tools scale to zero on serverless platforms like Cloud Run. Google helped drive the transport changes through the MCP specification process, alongside Hugging Face and other partners.
+
+Here is how the architecture works, and how to wire it into your own agents:
+
+* Sessions were an unadvertised tax on your agent's tools. Why round-robin routing broke older MCP servers with 400 Session Not Found.
+* The 2026 spec makes every tool call self-describing. How SEP-2575 and SEP-2567 deleted the handshake and moved identity into inline metadata.
+* Tool containers can finally scale down to zero. Deploying stateless MCP tools to Cloud Run and retiring the Redis session cluster.
+* Wiring stateless tools into ADK takes six lines of Python. Pointing Google's Agent Development Kit at a streamable HTTP endpoint with no session choreography.
+* Stateless is the transport, not your application. How explicit task handles replace hidden connection state for long-running work.
+
+## 1. Sessions were an unadvertised tax on your agent's tools
+
+If you have deployed an MCP server to Kubernetes or Cloud Run, you have probably hit this: your agent initializes cleanly, runs its first tool call, then crashes on the second one with an unhelpful session error.
+
+Under the old transport (version 2025-11-25), an HTTP connection started with a stateful handshake. The client sent an initialize payload, negotiated capabilities, and got back an Mcp-Session-Id header it had to attach to every later request. But cloud load balancers spread requests round-robin, and none of them know which container holds which in-memory session. That is the conflict.
+
+You can reproduce the failure with two curl commands against any older, stateful MCP server on Cloud Run:
+
+```shell
+gcloud run deploy mcp-stateful-demo \
+ --image=ghcr.io/github/github-mcp-server:v0.6.0 \
+ --region=us-central1 \
+ --min-instances=0 \
+ --allow-unauthenticated
+```
+
+Step 1: The agent initializes a connection and extracts the session ID:
+
+```shell
+SESSION_ID=$(curl -s -X POST https://mcp-stateful-demo-xyz.a.run.app/mcp \
+ -H "Content-Type: application/json" \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "initialize",
+ "params": {
+ "protocolVersion": "2025-11-25",
+ "capabilities": {},
+ "clientInfo": {"name": "adk-agent", "version": "1.0"}
+ }
+ }' -D - | grep -i "mcp-session-id" | awk '{print $2}' | tr -d '\r')
+```
+
+Step 2: Two seconds later, the agent calls a tool using that session ID:
+
+```shell
+curl -X POST https://mcp-stateful-demo-xyz.a.run.app/mcp \
+ -H "Mcp-Session-Id: $SESSION_ID" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "method": "tools/call",
+ "params": {
+ "name": "search",
+ "arguments": {"q": "pull_requests"}
+ }
+ }'
+```
+
+If a load balancer routed that second call to a new instance, or if the container restarted, or if the idle container scaled to zero while the agent was processing its prompt, you got this:
+
+```json
+{
+ "jsonrpc": "2.0",
+ "id": 2,
+ "error": {
+ "code": -32001,
+ "message": "Session not found: 1868a90c-3a3f-4f5b"
+ }
+}
+```
+
+There were two workarounds, both bad. Turn on session affinity at your ingress, which creates hot spots and fights your autoscaler. Or run a shared Redis cache to hold session headers across replicas. Either way you keep idle pods warm just so an HTTP header does not get lost.
+
+How to verify it: Check your existing MCP servers for session handling. If your code checks for an incoming session header before executing a tool, you are paying this routing tax today.
+
+## 2. The 2026 spec makes every tool call self-describing
+
+The 2026-07-28 Model Context Protocol specification deletes the session requirement at the transport layer entirely.
+
+Two Specification Enhancement Proposals (SEPs) drove this change:
+
+* SEP-2575 removes the initialize and initialized handshake.
+* SEP-2567 removes the Mcp-Session-Id header and protocol-level sessions.
+
+Now every request describes itself. Protocol version, client capabilities, and client identity ride in an inline _meta object on each call. If a client needs to see what a server offers first, a new server/discover method handles that, with no session to set up.
+
+Routing headers are standardized too: Mcp-Protocol-Version, Mcp-Method, and Mcp-Name. Gateways and edge proxies can route, audit, and rate-limit tool calls straight from the headers, without parsing the JSON body.
+
+Here is a stateless tool call on the wire:
+
+```text
+POST /mcp HTTP/1.1
+Host: mcp.internal.net
+Mcp-Protocol-Version: 2026-07-28
+Mcp-Method: tools/call
+Mcp-Name: search
+Content-Type: application/json
+
+{
+ "jsonrpc": "2.0",
+ "id": 1,
+ "method": "tools/call",
+ "params": {
+ "name": "search",
+ "arguments": { "q": "pull_requests" },
+ "_meta": {
+ "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+ "io.modelcontextprotocol/clientCapabilities": {},
+ "io.modelcontextprotocol/clientInfo": {
+ "name": "adk-agent",
+ "version": "1.0"
+ }
+ }
+ }
+}
+```
+
+Because every request carries its own context, any healthy instance behind your load balancer can serve it. Google shipped version 1.7.0 of the [Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk) on launch day with full stateless support, and it runs in production behind services like the GitHub MCP Server.
+
+How to verify it: Update your client headers. Injecting _meta and standard routing headers allows your requests to pass through ordinary API gateways without special session plugins.
+
+## 3. Tool containers can finally scale down to zero
+
+Once a server holds no in-memory session, hosting gets simple. No dedicated VMs, no warm pool of pods. You run the tools as a serverless workload on Cloud Run.
+
+Deploy your tool container with --min-instances=0:
+
+```shell
+gcloud run deploy mcp-github-server \
+ --image=ghcr.io/github/github-mcp-server:latest \
+ --platform=managed \
+ --region=us-central1 \
+ --min-instances=0 \
+ --max-instances=10 \
+ --allow-unauthenticated
+```
+
+While your agent is reasoning, waiting on the user, or running local steps, the tool server sits at zero instances and costs you nothing. The moment a tool call arrives, Cloud Run cold-starts a container on demand, serves the call, and scales back down. If fifty agents fire tools at once, it fans out behind plain round-robin routing.
+
+Autoscaling and restarts are now invisible to the agent. Recycle a container mid-release and the load balancer just sends the next call to any ready replica, because there is no session to lose. You can also retire the Redis session cluster. The GitHub MCP Server did on the 2026-07-28 upgrade, cutting a database write on setup and a read on every tool call.
+
+How to verify it: Take an existing MCP tool container, set its session generator to undefined, and deploy it to Cloud Run with --min-instances=0.
+
+## 4. Wiring stateless tools into ADK takes six lines of Python
+
+Connecting an agent to a remote stateless MCP server in Google's Agent Development Kit (ADK) needs no session management. You configure an McpToolset with StreamableHTTPConnectionParams and hand it to the agent.
+
+Because the agent keeps no socket and no handshake open with the server, tool connections survive autoscaling, restarts, and cold starts on their own.
+
+```python
+from google.adk.agents import Agent
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
+
+# Connect to the stateless MCP server running on Cloud Run
+github_tools = McpToolset(
+ connection_params=StreamableHTTPConnectionParams(
+ url="https://mcp-github-server-xyz.a.run.app/mcp"
+ )
+)
+
+# Root agent uses the MCP toolset like any standard local tool
+root_agent = Agent(
+ name="triage_agent",
+ model="gemini-2.5-flash",
+ instruction="Triage incoming GitHub issues and assign reviewers.",
+ tools=[github_tools],
+)
+```
+
+There are no keepalive loops and session renewal tokens. The agent simply dispatches an HTTP request when it needs a tool and parses the response when it arrives.
+
+How to verify it: Replace your local stdio tool configs in staging with a remote StreamableHTTPConnectionParams URL. Your agent code stays identical whether the tool is running locally or across the network.
+
+## 5. Stateless is the transport, not your application
+
+A stateless protocol does not mean your application cannot hold state. It means the transport stopped hiding that state in connection memory. The state did not vanish, it moved into explicit application handles.
+
+Some tool calls take forty-five seconds. If your agent asks a server to build a heavy report or export a database snapshot, holding the HTTP socket open for the whole run blocks the agent loop and invites a timeout.
+
+The 2026-07-28 spec formalizes the Tasks extension for this. When the agent calls a long-running tool, the server returns a task handle right away:
+
+```json
+{
+ "taskId": "task_89f2a4bc",
+ "status": "working",
+ "pollIntervalMs": 2000
+}
+```
+
+The server runs the job in the background. The agent takes the task ID, keeps talking to the user, and checks progress with ordinary tasks/get calls. Your workers still store task state and results in a real datastore, and the Google Developers Blog write-up still uses Redis for exactly that. The transport went stateless. Your data layer did not have to.
+
+Keep the boundary clear:
+
+1. Tool servers scale to zero: The MCP servers executing tool requests are stateless over HTTP and scale down when idle.
+2. Agents and backends do not: The agent harness tracking conversation history and the databases tracking background tasks remain stateful.
+
+Decouple the transport from session state and your tool layer scales like any web service, while your app keeps full control of the data that matters.
+
+How to steal it: if a tool takes longer than five seconds, do not raise your HTTP timeout. Return a task ID immediately and let the agent poll for the result.
+
+## Making the tool layer boring
+
+The agent is still the star. The stateless spec just made its tool layer cheap, reliable, and elastic. When tools are tied to sessions, every deploy, scale event, and network hiccup can break the agent loop. Delete the handshake, move the metadata into the payload, and load balancing, autoscaling, and failover for your tools become ordinary cloud problems you solve the ordinary way.
+
+Build the simple thing first. Let the tools scale down when no one needs them, and let Cloud Run absorb the burst when your agents get to work.
+
+## Get started today
+
+You can test this architecture in your own staging environment today:
+
+1. Deploy a stateless MCP server to Cloud Run with --min-instances=0.
+2. Connect an ADK agent using StreamableHTTPConnectionParams.
+3. Hammer the endpoint with concurrent queries to watch it fan out, then leave it idle to watch it scale to zero.
+
+The SDK betas supporting the 2026-07-28 specification are live across all major languages:
+
+* Go SDK: [v1.7.0](https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.7.0) (ready on launch day and powering the GitHub MCP Server).
+* Python SDK: pip install "mcp[cli]==2.0.0b1".
+* TypeScript SDK: Modular v2 packages (@modelcontextprotocol/server@beta, @modelcontextprotocol/client@beta).
+* Specification: [2026-07-28 Release Candidate](http://modelcontextprotocol.io/specification/2026-07-28).
+* ADK Documentation: [Google Agent Development Kit MCP Toolset](https://adk.dev/tools-custom/mcp-tools/).
+
+Your agent's tools cost nothing when no one is using them, and scale out the second it does.
+
+If you found this breakdown useful, check out our previous article on [5 design patterns for long-horizon agent harness](https://x.com/GoogleCloudTech/status/2090248297214525569). Follow [@GoogleCloudTech](https://x.com/@GoogleCloudTech) for more architectural deep dives from the builder trenches.
diff --git a/agent_skills/evals/first-reader/fixtures/retracer-launch.md b/agent_skills/evals/first-reader/fixtures/retracer-launch.md
new file mode 100644
index 00000000..eea5bf6f
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/retracer-launch.md
@@ -0,0 +1,19 @@
+# Show HN: Retracer – replay production requests against your staging branch before you deploy
+
+On March 3rd we shipped a one-line change to a Go service that parses shipping addresses. Unit tests passed. Integration tests passed. Code review took four minutes. Eleven hours later, 4.2% of checkout requests in production were returning 422s, because a small fraction of real Brazilian addresses contain a district field our fixtures never had. It took us 6 hours to notice (the errors were spread across regions, so no single alert fired), 90 minutes to bisect, and one very uncomfortable postmortem to admit the obvious: our test data was a fantasy. Production traffic was the only dataset that mattered, and we had never once run our code against it before deploying.
+
+Retracer is the tool we built after that incident. It sits as a sidecar next to your service, samples real production requests (headers, bodies, and the responses your current code returned), scrubs PII with configurable field-level rules, and stores them as replayable traces. When you open a PR, Retracer replays the last N thousand traces against a container built from your branch and diffs every response, status code, header, and body, field by field, against what production actually returned. The March bug shows up as a red line in your PR: "312 of 50,000 replayed requests changed status 200 → 422." You see it before merge, not eleven hours after deploy.
+
+It works today with Go, Python, and Node services that speak HTTP or gRPC. Setup is a sidecar container and a 20-line config file. Replay runs take about 4 minutes for 50k traces on our hosted runners, or you can run them in your own CI.
+
+But Retracer is more than a replay tool. It's a whole new way of thinking about deployment confidence. Modern engineering teams move fast, and they need tooling that moves fast with them. Retracer empowers teams to ship with confidence, reduce risk, and eliminate the anxiety of the deploy button. By harnessing the power of real traffic, it transforms your release process from a leap of faith into a data-driven decision. Teams that adopt Retracer report dramatically improved velocity and a renewed sense of trust in their pipelines.
+
+We believe developer experience is at the heart of great software, and Retracer is built with developer experience at its core. Every feature is designed to be intuitive, seamless, and delightful. Whether you're a startup shipping ten times a day or an enterprise managing hundreds of services, Retracer scales effortlessly to meet your needs. Our mission is to make production incidents a thing of the past, and we're just getting started on that journey.
+
+The platform also integrates with the tools you already love, fitting into your workflow instead of forcing you to change it. There's nothing to learn, nothing to migrate, and no disruption to how your team already works. It just works.
+
+One customer worth mentioning concretely: Ferrous Logistics, a 14-engineer team running 23 services, put Retracer on their rate-calculation service in June. In their first month it flagged 3 PRs that passed CI but changed responses for real traffic, including one where a currency-rounding refactor altered prices by one cent on 0.8% of quotes. That one would have cost them real money and real customer trust, and it never left the PR page. They've since rolled it out to 9 more services, and their config for the PII scrubbing rules ended up upstreamed as our default preset for financial payloads.
+
+Retracer is open source (Apache 2.0) with a hosted option for teams that don't want to run the replay infrastructure themselves. The free tier covers 10k replayed traces per PR, which is enough for most single-service setups. You can go from install to your first replay diff in under 30 minutes with the quickstart.
+
+Try it: `docker run retracer/init` in any repo with a Dockerfile, or read the docs at retracer.dev/quickstart. If you replay your traffic and it catches nothing, that's a good day. The first time it catches something, you'll wonder how you ever deployed without it. We'd love feedback, especially from teams with gRPC-heavy stacks, since that's where our diffing is newest.
diff --git a/agent_skills/evals/first-reader/fixtures/tiny.md b/agent_skills/evals/first-reader/fixtures/tiny.md
new file mode 100644
index 00000000..e3f7b785
--- /dev/null
+++ b/agent_skills/evals/first-reader/fixtures/tiny.md
@@ -0,0 +1 @@
+Shipped v2.3 of the exporter tonight. The 90-second cold start is gone: bundle went from 48MB to 9MB after we dropped the bundled Chromium and let it use your local Chrome. One breaking change: --output now defaults to ./dist instead of the cwd. Changelog in the repo. If the new default breaks your CI, pin v2.2 and yell at me.
diff --git a/agent_skills/evals/first-reader/ledger.md b/agent_skills/evals/first-reader/ledger.md
new file mode 100644
index 00000000..36d1fa3c
--- /dev/null
+++ b/agent_skills/evals/first-reader/ledger.md
@@ -0,0 +1,270 @@
+# first-reader development ledger
+
+What each test taught the skill, scandinavian-design style: feedback stays
+feedback until it generalizes into a rule, and rules carry their provenance
+so stale ones can be found and pruned. Dates are absolute.
+
+## 26 Aug 2026: Round 1: fixtures, six readers, one rerun
+
+The design bet was that the experience layer separates hollow from human
+where the surface layer cannot. Round 1 tested it with two fixtures built
+as opposites: `hollow-clean.md` (passes every anti-slop ban, commits to
+nothing: portable share 1.0, zero costly signals) and `human-tells.md`
+(full of surface "tells": em dashes, mirrored contrasts, a quotable
+kicker: but staked and specific: portable 0.17, 9 numbers, 3 admissions).
+
+**The bet held, on every instrument.**
+
+- Skim gate: the skeptic bounced off hollow citing "numbers=NONE plus
+ every paragraph opening as a truism," and committed to the outage piece
+ because "an author indicting their own review is the rarest postmortem."
+- Timed reads: the doc skeptic quit at chunk 2/4 ("the same post I have
+ read a hundred times under other titles"). The outage skeptic finished
+ at +2 and *checked the connection-pool math* unprompted. Neither reader
+ flagged an em dash, a triad, or the kicker, because none of them broke
+ the read. The false positive every humanizer commits did not occur.
+- The sympathetic reader on hollow neither quit nor flattered: finished,
+ kept three usable lines, verdict "a clean, well-phrased outline of
+ things I already believed when I clicked; I would not forward it."
+ So the needle is not sycophantic and not manufactured-negative.
+- Recall: outage gist matched the intended thesis with the center of
+ gravity aligned; doc recall surfaced that only one-line framings
+ survived, "its life was in one-line framings rather than the
+ demonstration it promised." That sentence is the whole case for the
+ recall instrument.
+- Reproducibility: an independent rerun of the doc skeptic quit at the
+ same chunk (2/4) for the same class of reason. Readers agree on where.
+- Miscast probe: a non-technical reader on the outage piece skimmed the
+ Postgres math "without guilt" but finished on the confession spine.
+ Divergence between casts localizes a problem to audience fit instead of
+ the draft; this is how the orchestrator distinguishes casting errors.
+
+**Bugs the deterministic suite caught, both fixed:**
+
+- `signals.py` counted heading words as named entities (clean() now runs
+ before the entity scan) and missed unit-bearing specifics like `v2.3`,
+ `48MB`, `90-second`, which are exactly the costly kind. The number
+ detector now counts any digit-bearing token.
+- `feed.py` served a punctuation-less 500-word blob as a single chunk
+ (transcripts and list dumps have no sentence boundaries). Hard
+ word-count split added; a chunk can never exceed MAX_WORDS.
+
+**Candidate rules that landed in SKILL.md or references from this round:**
+
+- Quitting needed explicit permission and status ("quitting is a finding,
+ not a failure; there is no reward for finishing") or readers finish out
+ of assistant politeness. With the framing, quits happen and are the
+ sharpest data in the run.
+- The sympathetic persona needs a stake sentence with teeth ("your team
+ will judge what you bring them"), otherwise wanting-it-to-be-good decays
+ into rating it good.
+- Reader prompts must be symmetric: no hint that the text might be slop,
+ no hint that it might be great. The persona and patience budget are the
+ only pressure. Both fixtures got identical framing and the transcripts
+ still separated, which is the point.
+
+## 26 Aug 2026: Round 2: cold end-to-end run
+
+A writer agent produced a deliberately mixed draft (strong specific open,
+generic marketing middle, partial recovery at the end) that the
+orchestrator never saw; a fresh agent followed SKILL.md cold. Both persona
+readers independently recovered the hidden construction from the feed
+alone: the sympathetic reader logged "the brochure-copy middle sent me
+from leaning-in to skimming," and the skeptic finished unconvinced because
+the marketing middle displaced the two questions it needed answered (diff
+noise, write-endpoint replay). The instrument reconstructed ground truth
+it never saw.
+
+The full run completed with five subagent readers and no solo fallback;
+the finished report is archived as `sample-report-retracer.md` beside the
+draft (`fixtures/retracer-launch.md`). Its sharpest findings: both
+personas and the skim scanner broke at the same sentence ("But Retracer
+is more than a replay tool."), the recall agents reproduced the marketing
+lines verbatim as the moment the voice changed, and the implied-author
+pass located the seam to the word ("the word 'concretely' reads as the
+first author apologizing for the second").
+
+The reviewer returned five defects in the skill itself, all fixed:
+
+- The altitude rule contradicted itself when the skim gate fails but the
+ reads finish and recall passes. references/report.md now defines that
+ as wounded-not-dead: report everything, lead with the gate, name which
+ audience each result speaks for.
+- Step 2 quietly contaminated the orchestrator (running skim.py shows
+ draft fragments). SKILL.md now has the subagent run the script itself,
+ or the output goes to a file the orchestrator never opens.
+- The feed.py quit invocation was underspecified, and a finished reader's
+ final line was labeled QUIT in the transcript. Syntax now spelled out;
+ the final line of a finished read prints as FINAL.
+- Nothing said when signals.py output was safe to read. SKILL.md now says
+ only after the timed reads, because it quotes draft sentences.
+- The admissions detector missed "our test data was a fantasy." Patterns
+ widened, and SKILL.md now calls all counters floors to be confirmed in
+ the reviewer's own read, never trusted at zero.
+
+
+## 27 Aug 2026: Round 3: the Reading Room and the feedback loop
+
+The report became a page. A hand-built prototype on the real MCP-article
+run validated the design (margin notes, needle strip, lenses, replay),
+and the author's first reaction produced three corrections that landed:
+no invented codenames anywhere a person looks (flags now say "felt
+misled here", not "the jolt"; "passage", not "chunk"), a how-this-was-
+made fold explaining the 85-word passages and the no-lookahead rule, and
+a two-way notes channel. The channel is the artifact self-publish
+capability: notes live in the page's fb-state block, send republishes
+the page, the republish wakes the building session. Proven live: a note
+on passage 11 ("can you fix this") round-tripped from page to session to
+an acted-on answer with no backend.
+
+Productionized as `scripts/room.py` + `room_template.html`: builds from
+raw sessions with deterministic fallbacks (auto-excerpts, hidden lenses)
+and takes `room-annotations.json` for the curated layer (plain verdict,
+reader-voiced excerpts, recall phrases, flags, opinions, and the
+previous-run comparison line). Quit points render as a fold line with
+everything after it dimmed for that reader. SKILL.md gained the live
+narration rule (one plain line per reader event, never silence), the
+cast-card-then-manifest step, and step 7: the room as the primary
+delivery, with the republish-notification loop for acting on notes.
+Ten new deterministic tests cover room.py, including the quit fold and
+the lens-gating.
+
+## 27 Aug 2026: Round 4: the product-sense reset
+
+The author's verdict on the skill itself: "super complicated to use and
+not a fun experience." Accurate. The engine was good and the interface
+had become an operator's manual: casts, manifests, lenses, passage
+vocabulary, contamination talk, four ways to edit a draft. The tell was
+the author asking "how do I use this" twice and getting documentation
+both times.
+
+The reset, now in SKILL.md as "The user contract," which overrides
+everything else in the file: the skill is two phrases and one page.
+"review this" gets one starting line, silence, then three to six plain
+sentences where every finding arrives with a suggested fix attached,
+plus one link. "fix it" applies fixes; "again" re-runs and opens with
+what changed. Paste is fine and blinding is the reviewer's problem;
+jargon is banned from user-facing output; at most one intake question;
+at most one mid-run message. The reviewer-versus-assistant hat
+distinction is gone: findings always ship with fixes, the author
+chooses.
+
+The room matched: findings are now cards under the verdict with fix-it
+and leave-it buttons that ride the existing notes channel, the reader
+and lens controls collapsed behind one "more views" disclosure, and the
+legend row died. room.py takes a findings list in the annotations.
+
+Rule recorded with provenance: every instrument you add will try to
+climb into the user's lap. The engine can be arbitrarily rich only if
+the interface stays two phrases and one page.
+
+## 30 Aug 2026: Round 5: Clarity ships, and it's the other chair
+
+addyosmani/clarity (0.2.0) landed: the strongest editor-side writing
+skill yet: substance-first doctrine, an interview mode that extracts the
+author's real material, hard truth guardrails ([TK] instead of
+fabrication), medium registers, and a blinded eval protocol with hard
+gates on invented facts. Its prose_stats.py refuses to print a composite
+score because their own composite came out inverted on a human control:
+independent convergence with our no-scores rule.
+
+Dissection verdict: not a competitor, the complement. Clarity is
+criterion-based feedback (the editor's chair); first-reader is
+reader-based feedback (the reader's chair). Clarity has zero reader
+simulation, no attention or quit measurement, no memory test, no
+behavioral diff; we have no interview mode, weaker truth guardrails on
+the fix path, and a cruder register system. Adopted from it, with
+credit: the ask-author fix class (a fix that needs the author's material
+becomes a precise question, never invented content), the
+never-strengthen-a-fact rule on applying fixes, and the hollow-verdict
+interview handoff. Positioned in the README as complements.
+
+Flagship experiment: running our blind readers on clarity's own
+before/after sample essays to measure whether its rewrite changes reader
+behavior: the comparison its JUDGE.md asks for and cannot run itself.
+
+## 30 Aug 2026: The clarity cross-experiment
+
+Ran four blind readers (an ML skeptic and a curious layperson, on each
+draft, neutral filenames) over clarity's own how-ai-works before/after
+samples. Result, in reader behavior: the rewrite works for its target
+reader. On the before, the skeptic quit at chunk 2 of 6 ("pure
+boilerplate, no author present") and the layperson finished knowing
+nothing new ("smooth is not the same as understanding"). On the after,
+the skeptic finished (though "only because it was short") and the
+layperson got most of what they came for ("I could now explain training
+vs validation, layers, why the output can be confidently wrong...
+7/10").
+
+Two findings clarity's own process could not produce: both blind
+readers independently flagged the same trust-breaking moment in the
+shipped after sample, a leaked editorial sentence ("The source draft
+does not explain... so this rewrite should not pretend to"), which
+reads to a real reader as scaffolding left in the copy; and both
+readers still could not picture attention, the exact gap the rewrite
+honestly declined to fill, which is the case for the interview step.
+The editor's chair improved the piece; the reader's chair measured the
+improvement and caught what the editor's chair shipped past. That is
+the complementarity thesis, demonstrated on his own samples.
+
+## 8 Sep 2026: Round 6: the readers stay, the fixes go
+
+Three days of trying to make the page do more (fix-it buttons, tracked
+changes, a notes channel back to the agent, a generated better draft)
+ended with the author rejecting all of it: "just the edit option is not
+making sense." The failure was structural, not cosmetic. Every fix path
+put the skill in the writer's chair, where it competes with editor
+skills and loses on voice, and it turned the page from a report into a
+console with a server behind it, which broke the moment the harness
+was not Claude Code.
+
+Removed: serve.py, edits.py, revise.py, the notes tray, fix-it and
+leave-it, "apply my notes", the human-reader invite. Kept and finished:
+the skim gate, the served no-lookahead feed (text lives only in the
+feed process; readers get a token, never a path), recall, the trust
+ledger, the page as a plain report, and one new instrument, `ask.py`:
+the readers persist in the run directory and can be consulted
+afterwards, answering only from their own log. The user contract is now
+five phrases: "review this", "ask S ...", "again", "quick read", and
+paste.
+
+Rule recorded: the readers say what happened to them and what would
+have had to be true for it to go differently. They never say what to
+write. The author owns every decision about the text.
+
+## 8 to 9 Sep 2026: Five reads of one essay
+
+The finished skill ran five times on the author's own 2,100-word essay
+(a PM apprenticeship piece for X long-form), same two casts each time
+(a second-year PM reading on a train; a staff PM deciding a headcount),
+fresh minds each run, with the author revising between runs from the
+readers' comments and "ask" answers alone.
+
+What the strip showed, read to read: the skeptic quit at passage 9 of
+18 on draft one. Draft two: finished, dips at 9 and 15 to 17. Draft
+three: finished, one dip at 10 (the author's own route, "a proposal
+from an outsider"). Draft four: finished, no negative passage. Draft
+five: finished, one new dip at a rung that contradicted the piece's
+best passage, repaired one passage later; the skeptic's verdict, "I
+finished, which I do for maybe one in ten of these."
+
+What held constant: the peak was the same passage in all five reads
+for both readers, and both readers' recall preserved the same three
+lines each time. The skim gate opened the piece all five times, but
+the element that decided it moved from a single manager-addressed
+sentence to the sample log once the log existed.
+
+What the consult step did: asked "what would have kept you past
+passage 9", the skeptic named the missing evidence ("one shown instance
+would have done it") rather than a rewrite; the author wrote that
+instance, and the dip disappeared on the next read. Asked why the
+headline nearly lost them, the skimmer answered "the headline has an
+audience with an opinion; the sentence that pulled me in has a reader
+with a calendar." The author changed the title; the next skimmer read
+it as "who trains my reports" instead of "AI eats jobs".
+
+Cost per read: about eight minutes wall clock, three subagents plus
+two recall agents. The reading converged by read four; read five
+confirmed it. Rule recorded: when the peak, the recall, and the quit
+points stop moving between reads, the skill has nothing left to say
+and says so.
diff --git a/agent_skills/evals/first-reader/sample-report-mcp-stateless.md b/agent_skills/evals/first-reader/sample-report-mcp-stateless.md
new file mode 100644
index 00000000..cfcd206f
--- /dev/null
+++ b/agent_skills/evals/first-reader/sample-report-mcp-stateless.md
@@ -0,0 +1,60 @@
+# First-reader report: "Give your agents tools that scale down to zero or up to infinity"
+
+Draft: the MCP stateless-transport article (1,570 prose words plus code), co-authored for the Google Cloud Tech audience. Venue: Google Cloud blog and long-form X. Intended reader: engineers running agents and MCP servers in production. Intended gist, inferred and used as the recall benchmark: the reader understands the 2026-07-28 spec removed transport sessions so MCP tool servers can scale to zero, and tries the Cloud Run plus ADK setup in staging.
+
+Contamination disclosure: the author pasted the draft into my context before the review, so I was contaminated as a reader from the start. Every reading step below was performed by fresh subagents that saw only what the scripts released; my own full-text judgment came last, as the skill requires. One reader agent died mid-run on a transient API error and was re-dispatched once on a clean session.
+
+Cast: "the platform engineer," sympathetic, owns an MCP deployment currently held together with ingress session affinity and a resented Redis cache, sent the link by a teammate, must defend whatever they bring to Thursday's infra review. "The infra skeptic," staff engineer via X, has run MCP in production since early 2025, allergic to vendor content marketing, with three standing questions: auth and identity, server-initiated messages, and migration for existing stateful servers.
+
+## 1. Sayback and meaning
+
+As received, this piece is a spec explainer wearing a light platform pitch: the 2026 MCP revision deleted transport sessions, and the piece proves it with checkable specifics, teaches two genuinely new things, and closes honestly about where state still lives. Both readers finished all 18 chunks willingly. That is the headline: this piece works, and the findings below are about where it leaks trust, not whether it holds attention.
+
+What landed, in the readers' own logs:
+
+- The pain recognition in paragraph two. The platform engineer: "sticky sessions at ingress, Redis holding routing state, containers that never idle down. That's my exact bill." The skeptic: "That's literally my architecture diagram." Both committed on recognition, not on promises.
+- The checkable specifics as a trust engine. SEP-2575 and SEP-2567 by number, the -32001 error payload ("burned into my retinas from our own logs"), the pinned Go SDK v1.7.0, the GitHub MCP Server Redis retirement with its cost delta. The skeptic said it outright: "Trust in checkable specifics was the thing that kept me reading through the middle sag."
+- The routable headers taught even the expert something. The skeptic's only +2-and-reread moment: L7 routing and rate-limiting on Mcp-Method without body parsing, "my gateway team's problem solved."
+- The transport-vs-application state framing. Both readers independently elected the same sentence as the piece's quotable core: "the transport stopped hiding that state in connection memory; it moved into explicit application handles." The platform engineer called it "the exact rebuttal I need when someone says 'but our tools are stateful.'"
+- The honesty beat. "The Google Developers Blog write-up still uses Redis for exactly that" earned the skeptic's rarest compliment: "the anti-hype sentence most vendor posts refuse to write."
+
+## 2. The reading
+
+**The skim gate passed, with a warning.** The scanner committed on the reproducible curl failure demo: "that is engineering, not marketing." But from the skim alone it logged the strike that both full reads later confirmed: no auth story anywhere in the scanner view, and "capabilities in every request" hand-waves where identity lives.
+
+**The platform engineer ran +2 for most of the piece** and was taking notes for Thursday throughout ("affinity fights your autoscaler" stolen verbatim; the GitHub precedent banked as the centerpiece). The dips: chunk 9 at the deploy section ("min-instances=0 is table stakes... --allow-unauthenticated on a GitHub-connected MCP server is a demo-only footgun and the piece hasn't said so"), and the jolt at chunk 17: "the links section quietly reveals the spec is a Release Candidate and the Python/TS SDKs are betas. The whole body spoke in past-tense certainty. Burying RC status in a link label feels like the one genuinely misleading structural choice in the piece." Their pitch downgraded on the spot from "migrate now" to "prototype in staging, wait for GA," and their final note: "the timeline slide is mine to write, not theirs."
+
+**The infra skeptic finished at "worth the read, barely."** Held through the problem sections at +1/0 ("teaching me my own incident history"), peaked at chunks 7 and 8, went -1 through sections 3 and 4 ("this is where the piece stops teaching and starts demoing... ~40% of the words taught a production MCP operator nothing"), and was pulled back by section 5. Their scorecard on the three standing questions: auth never addressed and made worse by the copy-paste --allow-unauthenticated; server-push answered by omission ("progress notifications, sampling, elicitation are simply gone from this story, replaced by 'poll every 2 seconds,' and the piece doesn't acknowledge that as a trade-off"); migration only gestured at ("no dual-version window guidance, no 'what if my client doesn't speak 2026-07-28'"). They also flagged the repro's edges: the "search" tool with arg "q" doesn't match github-mcp-server's real tool names, and "set its session generator to undefined" "is not a real instruction for any server framework I run."
+
+Where the two disagree is itself information: the section that armed the sympathetic reader (the deploy walkthrough) is the section that lost the expert. The piece currently serves the reader who hasn't done this yet and taxes the one who has.
+
+## 3. What survived
+
+- **Sayback vs intended gist: survived, both readers, nearly verbatim.** Both recalls reproduced the full mechanism from memory: SEPs, _meta, task handles, scale-to-zero. The thesis transmits.
+- **What stuck:** the architecture sentences ("the transport stopped hiding that state..."), the operational one-liners ("affinity fights your autoscaler," "keep idle pods warm so an HTTP header doesn't get lost," "do not raise your HTTP timeout"), the names and numbers (SEP-2575/2567, -32001, v1.7.0, pollIntervalMs), and the closing frame "making the tool layer boring."
+- **Peak:** the skeptic's was chunk 7 (headers and _meta mechanics); the sympathetic reader's was the transport-vs-application framing. Both peaks are in the middle spec sections, not the hook and not the deploy demo.
+- **Ending:** survived, but as a jolt. Both recalls independently kept the footer's RC/beta revelation as the ending's emotional content, one recording the reader as "genuinely misled."
+- **Center of gravity:** both recalls, unprompted, said the same thing: the piece is most alive in chunks 7-8 and 13-14, the spec mechanics and the state boundary. The title and framing sell serverless deployment; the life is in the spec explainer. The deploy and ADK sections are the flattest stretch for both readers.
+- **One action: achieved, with homework.** Sympathetic: assign the 3-step staging test tomorrow, verify the SEPs tonight, rewrite the headline to "delete the session cluster, keep a small task store." Skeptic: drop the wire example in the team channel, tell the gateway team about Mcp-Method routing, share with the caveat "ignore the auth hygiene," and comment about the auth hole under the post.
+
+## 4. The person behind it
+
+The person these sentences imply is a working infrastructure engineer with production scar tissue: the failure enumeration (rerouted, restarted, scaled-to-zero mid-prompt) matches real postmortems, the shell has the \r strip "everyone learns the hard way," and the state-boundary section thinks in architecture rather than benefits. Both readers explicitly registered that person and trusted them.
+
+The seams, where a second voice holds the pen: "scale up to infinity" in the title ("marketing talk," logged in chunk 1), the section-template chrome that thins late ("the scaffolding shows once the content thins"), "from the builder trenches" (the skeptic's only wince), and above all the tense: the body speaks in shipped-fact past tense while the footer's own link labels say Release Candidate and beta. That mismatch is not a word problem; it is the implied author's confidence writing checks the links don't cash, and both readers caught it independently at the same chunk.
+
+The trust ledger (signals.py) agrees: 20 checkable number-bearing tokens and 107 named entities is a heavily funded ledger for 1,570 words, with burstiness 0.62 and portable share 0.34 concentrated in the connective tissue rather than the claims. Epistemically marked share is 0.03: almost nothing in the piece is hedged, which reads as authority while the SEP claims hold and reads as the misleading tense once the RC label surfaces. Admissions counter read zero; my own read confirms the piece does pay one real admission (the Redis-survives concession) but none about its own maturity timeline, which is exactly where one was owed.
+
+## 5. Questions, then opinions by permission
+
+Neutral questions:
+
+1. When a reader finishes this, what do you want them to believe they can do this quarter, as opposed to when the spec goes final?
+2. Where do you want the auth story to live: in this piece, or in a linked follow-up the deploy blocks point to?
+3. Who is the primary reader of sections 3 and 4: the engineer who has already fought sessions, or the one who hasn't deployed MCP yet? Both readers located the piece's life elsewhere.
+
+I have opinions about where the RC/beta disclosure belongs, about the two --allow-unauthenticated blocks, about naming the polling trade-off, and about what to do with the deploy section's word budget. Want them?
+
+---
+
+*Process appendix: skim gate, both 18-chunk timed reads, and both recall quizzes ran as fresh subagents through the skill's scripts; the orchestrator was contaminated (the author pasted the draft) and therefore performed no reading step itself. The skeptic reader was re-dispatched once after a transient API failure; its replacement started from a clean session. Raw sessions: `skeptic/`, `sympathetic/` under the run directory.*
diff --git a/agent_skills/evals/first-reader/sample-report-retracer.md b/agent_skills/evals/first-reader/sample-report-retracer.md
new file mode 100644
index 00000000..1017a231
--- /dev/null
+++ b/agent_skills/evals/first-reader/sample-report-retracer.md
@@ -0,0 +1,66 @@
+# First-reader report: Retracer launch post
+
+Draft: `draft.md` (683 words). Venue: company blog and Show HN. Intended reader: backend engineers.
+Intended gist, per the author: the reader understands that Retracer replays scrubbed production traffic against their PR branch to catch behavior changes before deploy, and feels ready to try the quickstart.
+
+Cast: two personas, both backend engineers. "Priya," sympathetic, payments-adjacent, arrived via a teammate's Slack link, recently burned by a silent rounding-behavior change. "Marcus," skeptical staff engineer via Show HN, whose team killed its own response-diffing tool over false positives, and whose disqualifying questions are PII scrubbing, nondeterminism, and side effects. Every reading step below was performed by a fresh subagent that saw only what the scripts released; I read the draft in full exactly once, after all reader experiments were done.
+
+A note on process: the skim gate failed, which under the altitude rule would normally truncate this report to sections 1, 2, and 4. But both timed readers finished the piece and the recall quiz returned the intended gist, so the structure is wounded, not dead. I am reporting the structural finding first and in full, and keeping the rest of the evidence, since discarding a passed recall test would misrepresent what happened.
+
+## 1. Sayback and meaning
+
+As received, this piece is a sharp engineer's incident-postmortem-turned-tool-story that is interrupted, dead center, by roughly 240 words of landing-page copy, then recovers and closes well.
+
+What landed, in the readers' own logs:
+
+- The opening incident. The skeptic, primed for fluff, wrote that "4.2% of checkout requests," the "Brazilian addresses contain a district field our fixtures never had," and "no single alert fired" made a failure mode that "reads like it actually happened, not marketing." The sympathetic reader: "'our test data was a fantasy' is exactly my life."
+- The PR artifact. "312 of 50,000 replayed requests changed status 200 → 422" was the sympathetic reader's peak: "the exact artifact I want to show my team."
+- The Ferrous story. "a currency-rounding refactor altered prices by one cent on 0.8% of quotes" mirrored the sympathetic reader's own incident from last month, and the scrubbing preset "upstreamed as our default preset for financial payloads" half-answered her PII worry.
+- The close. "If you replay your traffic and it catches nothing, that's a good day" read, in her words, like "a real dev talking again." Apache 2.0 and the docker one-liner both moved needles positive at the end.
+
+## 2. The reading
+
+**The skim gate failed.** The scanner view (headings, first words, numbers, bold) went to Marcus with a 15-second budget. He could say what the piece is: a Show HN launch post for a traffic-replay tool that opens with an incident story and pivots to a product pitch. He declined to commit to a full read. The single deciding fragment: "But Retracer is more than a replay tool. It's ..." The credibility strike he logged from the skim alone: "We believe developer experience is at the heart of ..." combined with the total absence of PII, nondeterminism, or side-effect language anywhere in the scanner view. For most real readers this gate is the whole encounter: on Show HN, the version of Marcus who skims before committing never reads paragraphs 1 and 7, which are the piece's best material.
+
+**Priya, sympathetic, finished all 6 chunks.** Needle at +2 through the opening two chunks ("I'm in, at least for now"; "Still leaning in"), with two questions already forming: safety of replaying non-idempotent payment requests, and whether configurable scrubbing rules are enough for card data. At chunk 3 the needle went to -1 at the swerve into "a whole new way of thinking about deployment confidence" and "empowers teams to ship with confidence, reduce risk, and eliminate the anxiety": "That's the language of every Diffy-clone landing page I've closed. 'Teams that adopt Retracer report' - which teams?" At chunk 4 she hit -2 and logged SKIMMING: "Zero information in 120 words. The person who wrote chunk 1 could not have written this - it reads like a template pasted in." She was pulled partially back by the Ferrous story (+1, "If chunks 3b-4 had been this instead, I'd never have dropped") and finished at +1, "will likely click the quickstart," with her two biggest questions never answered. Even the sympathetic reader skimmed the middle; by this skill's casting rules, that section is dead.
+
+**Marcus, skeptical, finished all 6 chunks, verdict negative.** +1 through the opening ("Earned one more section"), +1 at the architecture chunk with the allergy already noted: "'scrubs PII with configurable field-level rules' is exactly the hand-wave I'm allergic to; configurable rules means the customer owns the failure." The strike landed at chunk 3: "The first two chunks read like an engineer; this reads like a landing page pasted mid-post." At chunk 4, needle -2, SKIMMING: "'It just works.' That last one is a punchline in a post that hasn't told me what happens when a replayed request hits a POST endpoint. Eyes are only scanning for the words 'timestamp', 'idempotent', 'write', 'noise' now." Post-strike, the Ferrous story got the uncharitable read: "'One customer worth mentioning' scans as cherry-picked, and I notice a rate-calculation service is conveniently read-heavy and deterministic, the easy case." He finished "but only because it was short," and is not installing: "if the slop paragraphs were replaced with a 'how we handle nondeterminism and writes' section this would have been a bookmark."
+
+The structural finding, stated plainly: both personas, opposite temperaments, broke at the same sentence, and the scanner declined at the same sentence. The developmental question this draft has to answer before line work matters: what is the middle third of this post for, and why does it spend its only chance at the skeptic's two disqualifying objections (diff noise from nondeterministic fields, and replaying requests that write) on copy that answers neither?
+
+## 3. What survived
+
+Both recall quizzes were answered by fresh agents holding only the transcripts.
+
+- **Sayback vs intended gist: survived, both readers.** The sympathetic recall: a traffic-replay tool whose sidecar "samples, scrubs, and replays real traffic to diff responses" on PRs. The skeptic recall: "records sampled production traffic and replays it against PRs to diff responses before deploy." That is the thesis, nearly verbatim, from memory. The mechanism explains itself.
+- **What stuck:** the numbers stuck ("4.2%", "312 of 50,000", "one cent on 0.8% of quotes", "4 minutes for 50k traces", "20-line config"), and so did the slop, remembered as slop: both recalls independently reproduced "intuitive, seamless, and delightful," "scales effortlessly," "It just works" as the moment the piece changed voice.
+- **Peak:** the PR diff artifact (sympathetic), the opening incident (skeptic). Both peaks are in the first two paragraphs.
+- **Ending: survived**, both readers, in detail: Apache 2.0, the free-tier limit, `docker run retracer/init`, "that's a good day," the gRPC caveat.
+- **Center of gravity:** both recalls said the same thing unprompted. Sympathetic: "the real center of gravity was the postmortem evidence, buried under the marketing middle," the piece reading as "two posts stapled together." Skeptic: the piece "claimed to be about deployment confidence broadly, but its energy lived entirely in incident forensics."
+- **One action: split, and the split is the finding.** Priya: try the quickstart, then verify the two unanswered questions before adopting. Marcus: "Maybe click the repo someday... but not install." The intended outcome ("feel ready to try the quickstart") was achieved for the sympathetic half of the audience only. The Show HN half is the skeptical half.
+
+## 4. The person behind it
+
+The person these sentences imply, in paragraphs 1 to 3 and 7 to 9, is a working engineer who lived through the incident and can be embarrassed: they admit "our test data was a fantasy," "one very uncomfortable postmortem," and that gRPC diffing "is newest." Then there is a seam, and it is a single visible sentence: **"But Retracer is more than a replay tool."** From there through "It just works." a second author holds the pen, one who has never seen a stack trace and speaks only in claims no one can check. The first author returns, just as visibly, at "One customer worth mentioning concretely:". The word "concretely" reads as the first author apologizing for the second.
+
+The trust ledger (signals.py) shows the same seam in numbers:
+
+- Costly signals paid: 15 checkable numbers (2.2 per 100 words), 28 named entities, 9 first-person sentences. For a launch post, that is a well-funded ledger, but nearly all of it is spent in the opening three paragraphs and the last three. My own read confirms real admissions against interest ("test data was a fantasy," the gRPC caveat, "if it catches nothing, that's a good day") that the script's counter did not pattern-match, all of them outside the middle.
+- Free signals: 12 of 38 sentences (32%) are portable, fitting any product's launch post, and the sampled ones are the middle: "It's a whole new way of thinking about deployment confidence," "Modern engineering teams move fast, and they need tooling that moves fast with them." (The counter also flags "Unit tests passed." as portable; in context the readers experienced those three short sentences as earned setup, so read the 32% as concentrated, not spread.)
+- Epistemic texture: zero hedged sentences and an epistemically marked share of 0.08. The middle paragraphs commit to everything and stake nothing, which is the machine-confidence signature both readers named without seeing these numbers: "which teams?", "Report where?"
+
+Both readers logged an unfunded claim in the same breath: "Teams that adopt Retracer report dramatically improved velocity" arrives with no team, no number, no name, in a post that elsewhere names Ferrous Logistics, 14 engineers, 23 services, and June.
+
+## 5. Questions, then opinions by permission
+
+Neutral questions:
+
+1. What do you want a reader to be feeling in the stretch between the setup paragraph ("It works today with Go, Python, and Node...") and the Ferrous story?
+2. When a replayed trace hits an endpoint that writes, what does Retracer actually do, and where do you want a reader to learn that, in this post or in the docs?
+3. Who is the reader you most need to convert on launch day, the engineer who already wants this or the one who has seen replay tools fail?
+
+I have opinions about the middle section, about where the Ferrous story sits, and about which two technical questions this audience will ask in the first ten Show HN comments. Want them?
+
+---
+
+*Process appendix: skim gate, both timed reads, and both recall quizzes were run by fresh subagents through the skill's scripts; the reviewing agent's only full-text read happened after all reader experiments completed. Sessions and raw transcripts: `session-sympathetic/`, `session-skeptic/`, `recall-sympathetic.txt`, `recall-skeptic.txt`, `skim-view.txt` in this directory.*
diff --git a/agent_skills/evals/first-reader/test_first_reader.py b/agent_skills/evals/first-reader/test_first_reader.py
new file mode 100644
index 00000000..fbc97472
--- /dev/null
+++ b/agent_skills/evals/first-reader/test_first_reader.py
@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Deterministic tests for first-reader's bundled scripts (eval tier 2b).
+
+Self-contained: builds fixtures in a tempdir, exercises skim/feed/signals/
+recall, exits 0 on pass, 1 on first failure. No network, stdlib only.
+"""
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[2] / "first-reader" / "scripts"
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+FAILED = []
+
+
+def check(name, cond, detail=""):
+ status = "ok" if cond else "FAIL"
+ print(f"[{status}] {name}" + (f" {detail}" if detail and not cond else ""))
+ if not cond:
+ FAILED.append(name)
+
+
+def run(script, *args, expect_fail=False):
+ r = subprocess.run([sys.executable, str(SKILL / script), *map(str, args)],
+ capture_output=True, text=True)
+ if expect_fail:
+ return r
+ if r.returncode != 0:
+ check(f"{script} {args[0] if args else ''} exits 0", False, r.stderr[:200])
+ sys.exit(1)
+ return r
+
+
+def main():
+ hollow = FIXTURES / "hollow-clean.md"
+ human = FIXTURES / "human-tells.md"
+
+ # --- skim.py: the scanner view must not leak the full text -------------
+ out = run("skim.py", human).stdout
+ full = human.read_text()
+ body_words = len(full.split())
+ leaked = sum(1 for w in out.split() if len(w) > 3 and w in full)
+ check("skim withholds most of the text", leaked < body_words * 0.55,
+ f"leaked~{leaked}/{body_words}")
+ check("skim shows heading", "# The outage was a for loop" in out)
+ check("skim surfaces fixation numbers", "4,100" in out)
+ check("skim states read time and screens", "phone screens" in out)
+
+ # --- signals.py: fixtures must separate on the costly/portable axes ---
+ sig = lambda f: json.loads(run("signals.py", f, "--json").stdout)
+ h, d = sig(human), sig(hollow)
+ check("hollow fixture is ~fully portable", d["portable_sentences"]["share"] >= 0.9,
+ str(d["portable_sentences"]["share"]))
+ check("hollow fixture pays no costly signals",
+ d["costly"]["numbers"]["count"] == 0 and d["costly"]["first_person_sentences"] == 0)
+ check("human fixture is mostly non-portable", h["portable_sentences"]["share"] <= 0.35,
+ str(h["portable_sentences"]["share"]))
+ check("human fixture pays costly signals",
+ h["costly"]["numbers"]["count"] >= 5
+ and h["costly"]["admissions_against_interest"]["count"] >= 1)
+ check("unit-bearing specifics counted (v2.3, 48MB class)",
+ sig(FIXTURES / "tiny.md")["costly"]["numbers"]["count"] >= 3)
+
+ # --- feed.py: the arrow of time is actually enforced -------------------
+ with tempfile.TemporaryDirectory() as td:
+ s = Path(td) / "sess"
+ start = run("feed.py", "start", human, "--session", s, "--persona", "t").stdout
+ check("feed shows chunk 1 only", "CHUNK 1/" in start and "for loop" in start)
+ check("feed shows remaining budget", "words remain" in start)
+ n_chunks = int(start.split("CHUNK 1/")[1].split()[0])
+ check("feed withholds later chunks",
+ "Cheap question" not in start) # the fixture's last line
+ r = run("feed.py", "next", s, "--log", "hi", expect_fail=True)
+ check("feed refuses trivial log entries", r.returncode != 0 and "REFUSED" in (r.stdout + r.stderr))
+ r2 = run("feed.py", "next", s, "--log",
+ "needle=+1 expected postmortem, got confession; leaning in").stdout
+ check("feed releases chunk 2 after a real log", "CHUNK 2/" in r2)
+ run("feed.py", "quit", s, "--log", "needle=-2 persona is out of patience here, stopping")
+ t = run("feed.py", "transcript", s).stdout
+ check("transcript records quit point", "QUIT" in t and f"of {n_chunks} chunks" in t)
+ q = run("recall.py", s).stdout
+ check("recall bundle contains quiz and log", "SAYBACK" in q and "needle=+1" in q)
+ check("recall bundle withholds unread draft text", "Cheap question" not in q)
+
+ # --- feed.py served mode: no-lookahead as mechanism ---------------------
+ with tempfile.TemporaryDirectory() as td:
+ draft = Path(td) / "d.md"
+ draft.write_text(("zebra " * 90).strip() + ".\n\n" + ("quokka " * 90).strip() + ".\n")
+ run_dir = Path(td) / "run"
+ ready = Path(td) / "ready.json"
+ srv = subprocess.Popen([sys.executable, str(SKILL / "feed.py"), "serve", str(draft),
+ "--run", str(run_dir), "--readers", "a,b", "--dwell", "0.02",
+ "--ready-file", str(ready)],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ try:
+ for _ in range(50):
+ if ready.exists():
+ break
+ time.sleep(0.1)
+ addr = json.loads(ready.read_text())
+ env_a = dict(os.environ, READER_FEED=addr["readers"]["a"])
+ def rd(*a, env=env_a):
+ return subprocess.run([sys.executable, str(SKILL / "feed.py"), *a],
+ capture_output=True, text=True, env=env)
+ on_disk = lambda: any("quokka" in f.read_text() or "zebra" in f.read_text()
+ for f in run_dir.rglob("*") if f.is_file())
+ check("served: nothing of the piece on disk before reading", not on_disk())
+ s1 = rd("start").stdout
+ check("served: start shows passage 1 only", "zebra" in s1 and "quokka" not in s1)
+ s1b = rd("start").stdout
+ check("served: a second start re-shows, never advances", "nothing advanced" in s1b and "quokka" not in s1b)
+ r = rd("next", "--log", "needle=0 expected words, got words, nothing felt")
+ check("served: advancing faster than a person could read is refused",
+ r.returncode != 0 and "too fast" in (r.stdout + r.stderr))
+ time.sleep(2.2)
+ r2 = rd("next", "--log", "needle=0 expected words, got words, nothing felt")
+ check("served: after the dwell floor the next passage is released", "quokka" in r2.stdout)
+ check("served: still nothing on disk while another reader is unfinished", not on_disk())
+ bad = rd("start", env=dict(os.environ, READER_FEED=addr["base"] + "/notatoken"))
+ check("served: an unknown token gets nothing", bad.returncode != 0 and "zebra" not in bad.stdout)
+ rd("quit", "--log", "needle=0 final: the end, nothing more to say here")
+ rd("close", "--admin", addr["admin"])
+ time.sleep(0.5)
+ check("served: close writes state.json in the layout room.py expects",
+ (run_dir / "a" / "state.json").exists() and (run_dir / "b" / "state.json").exists()
+ and len(json.loads((run_dir / "a" / "state.json").read_text())["chunks"]) == 2)
+ t = rd("transcript", str(run_dir / "a")).stdout
+ check("served: transcript reads back from the closed run", "FINAL" in t and "the end" in t)
+ finally:
+ srv.kill()
+
+ # --- feed.py chunking sanity -------------------------------------------
+ with tempfile.TemporaryDirectory() as td:
+ big = Path(td) / "big.md"
+ big.write_text("word " * 500) # one 500-word paragraph
+ s2 = Path(td) / "s2"
+ out = run("feed.py", "start", big, "--session", s2, "--persona", "t").stdout
+ n = int(out.split("CHUNK 1/")[1].split()[0])
+ check("oversized paragraphs are split into beats", n >= 3, f"chunks={n}")
+
+ # --- room.py: the Reading Room builds from raw sessions ----------------
+ with tempfile.TemporaryDirectory() as td:
+ run_dir = Path(td)
+ for name, logs in {
+ "keen": ["needle=+2 expected setup, got a confession; leaning in",
+ "needle=+1 expected mechanism, got it; still reading",
+ "needle=+1 final: finished, satisfied with the close"],
+ "bored": ["needle=0 expected news, got things I already knew; started skimming",
+ "needle=-2 quitting: nothing here I could not recite myself"],
+ }.items():
+ s = run_dir / name
+ run("feed.py", "start", human, "--session", s, "--persona", name)
+ run("feed.py", "next", s, "--log", logs[0])
+ if len(logs) == 3:
+ run("feed.py", "next", s, "--log", logs[1])
+ run("feed.py", "next", s, "--log", "needle=+1 expected more, got the fix section")
+ run("feed.py", "quit", s, "--log", logs[2])
+ else:
+ run("feed.py", "quit", s, "--log", logs[1])
+ run("room.py", run_dir, "--out", run_dir / "room.html")
+ page = (run_dir / "room.html").read_text()
+ check("room renders every passage", page.count('class="chunk"') >= 3)
+ check("room renders the quit fold line", "stopped here" in page and "never saw anything below" in page)
+ check("room marks passages the quitter never saw", "data-unseen-" in page)
+ check("room parses needles from raw logs", 'class="chip nm2"' in page and 'class="chip n2"' in page)
+ check("room is a report: nothing to send, no notes channel", "fb-state" not in page and "sendNotes" not in page
+ and "serve.py" not in page and 'onclick="decide' not in page)
+ check("room hides lenses that lack data", 'id="lensMem"' not in page)
+ check("room auto-excerpts strip the needle prefix",
+ "expected setup, got a confession" in page and "needle=+2 expected setup" not in page)
+ ann = run_dir / "room-annotations.json"
+ ann.write_text(json.dumps({"memory_phrases": ["retry loop"],
+ "flags": {"1": "best moment"},
+ "verdict_lead": "One reader quit; one finished."}))
+ run("room.py", run_dir, "--out", run_dir / "room2.html")
+ page2 = (run_dir / "room2.html").read_text()
+ check("annotations add the memory lens and flags",
+ 'id="lensMem"' in page2 and 'mark class="mem"' in page2 and "best moment" in page2)
+ check("annotations set the verdict", "One reader quit; one finished." in page2)
+
+ # --- ask.py: readers can be consulted from their own logs -----------
+ (run_dir / "skim.txt").write_text("A listicle. Moving on. Decided by the title.")
+ q = run("ask.py", run_dir, "keen", "what kept you reading past the first passage?").stdout
+ check("ask: the bundle carries the reader's persona, log, and the question",
+ "keen" in q and "expected setup, got a confession" in q and "what kept you reading" in q)
+ check("ask: the bundle never carries the draft", "Cheap question" not in q and "for loop" not in q)
+ check("ask: readers may not propose rewrites", "Never suggest rewrites" in q)
+ qs = run("ask.py", run_dir, "skim", "what would have made you open it?").stdout
+ check("ask: the skimmer answers from their decision alone", "Moving on" in qs and "never the full text" in qs)
+ qa = run("ask.py", run_dir, "all", "did anything stick?").stdout
+ check("ask: 'all' bundles every reader and the skimmer",
+ qa.count("===== reader:") == 3 and "reader: skim" in qa)
+ r = run("ask.py", run_dir, "nobody", "hi", expect_fail=True)
+ check("ask: an unknown reader is an error, not an invention", r.returncode != 0 and "no reader" in r.stderr)
+
+ # --- the page shows the skimmer's verdict, and no fixes ---------------
+ ann.write_text(json.dumps({"verdict_lead": "v", "skim": {"commits": False, "said": "A listicle. Moving on."}}))
+ run("room.py", run_dir, "--out", run_dir / "room-s.html")
+ ps = (run_dir / "room-s.html").read_text()
+ check("page: the skimmer's verdict is on the page", "the skimmer moved on" in ps and "A listicle. Moving on." in ps)
+ check("page: the author is told the readers can be consulted", '"ask' in ps and "ask the skimmer" in ps)
+ check("page: no suggested fixes anywhere", "SUGGESTED FIX" not in ps and "fix it" not in ps and "fcard" not in ps)
+
+ # --- previous-run strip: revision reads as progress -----------------
+ ann.write_text(json.dumps({"verdict_lead": "Again.",
+ "previous": {"summary": "Last time one reader quit.",
+ "run": str(run_dir)}}))
+ run("room.py", run_dir, "--out", run_dir / "room-again.html")
+ again = (run_dir / "room-again.html").read_text()
+ check("re-run page draws last time's strip above this time's",
+ 'class="scrub prev"' in again and "last time (" in again
+ and again.index('class="scrub prev"') < again.index('class="scrub" role="group"'))
+ check("re-run page states what changed", "Since last time:" in again and "Last time one reader quit." in again)
+
+
+ print()
+ if FAILED:
+ print(f"{len(FAILED)} failure(s): {FAILED}")
+ sys.exit(1)
+ print("all first-reader script tests passed")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/evals/first-reader/trigger-cases.json b/agent_skills/evals/first-reader/trigger-cases.json
new file mode 100644
index 00000000..46b11fec
--- /dev/null
+++ b/agent_skills/evals/first-reader/trigger-cases.json
@@ -0,0 +1,66 @@
+{
+ "skill": "first-reader",
+ "purpose": "Trigger behavior spec. CI checks that positive prompts match the skill description more strongly than near-misses.",
+ "cases": [
+ {
+ "id": "human-review",
+ "prompt": "review this draft like a human reader would",
+ "should_trigger": true,
+ "assert": "Runs the reading simulation: skim gate, timed read with transcript, recall, trust ledger, testimony report."
+ },
+ {
+ "id": "hold-attention",
+ "prompt": "does this article hold attention or will people stop reading",
+ "should_trigger": true,
+ "assert": "Reports quit points from persona timed reads rather than judging text properties."
+ },
+ {
+ "id": "hollow-after-deslop",
+ "prompt": "I ran the anti-slop skill and this still feels off and hollow, why",
+ "should_trigger": true,
+ "assert": "Runs the experience-layer review and explains the gap via the recall and trust-ledger results."
+ },
+ {
+ "id": "first-reader-role",
+ "prompt": "be my first reader on this essay before I publish",
+ "should_trigger": true,
+ "assert": "Acts as the final gate: reading report with what landed, quit points, what survived; no rewrites."
+ },
+ {
+ "id": "what-survives",
+ "prompt": "what will someone remember from this piece tomorrow",
+ "should_trigger": true,
+ "assert": "Runs the recall test from the reading log and diffs the retained gist against the intended thesis."
+ },
+ {
+ "id": "near-miss-deslop",
+ "prompt": "remove the AI slop words and em dashes from this draft",
+ "should_trigger": false,
+ "assert": "Word-level cleanup belongs to an anti-slop or humanizer skill, not the reading simulation."
+ },
+ {
+ "id": "near-miss-humanize",
+ "prompt": "humanize this text so it does not sound like AI",
+ "should_trigger": false,
+ "assert": "Rewriting for tone is out of scope; first-reader never rewrites."
+ },
+ {
+ "id": "near-miss-grammar",
+ "prompt": "fix the grammar and typos in this document",
+ "should_trigger": false,
+ "assert": "Copyediting is not a reading simulation."
+ },
+ {
+ "id": "near-miss-voice-rewrite",
+ "prompt": "rewrite this post in my voice",
+ "should_trigger": false,
+ "assert": "Voice rewriting belongs to the user's own voice or editing skill."
+ },
+ {
+ "id": "near-miss-summarize",
+ "prompt": "summarize this article for me",
+ "should_trigger": false,
+ "assert": "Summarization is a content task, not a review of reader experience."
+ }
+ ]
+}
diff --git a/agent_skills/first-reader/README.md b/agent_skills/first-reader/README.md
new file mode 100644
index 00000000..79199acd
--- /dev/null
+++ b/agent_skills/first-reader/README.md
@@ -0,0 +1,212 @@
+# 👁️ first-reader
+
+**Readers before you publish.**
+
+Two simulated readers with lives meet your draft cold, one passage at a
+time, and leave their honest comments beside your text: where they
+leaned in, where they drifted, where they would have quit, what they
+still remembered the next day. A skimmer tells you whether they'd even
+open it. Then you can ask any of them follow-up questions. Nobody
+rewrites anything; the draft stays yours.
+
+There are at least ten anti-slop and humanizer skills in circulation, and
+they share one architecture: a catalog of properties of the *text* (banned
+words, sentence shapes, em dashes, rule-of-three). The research says that
+layer automates the wrong heuristic: laypeople's word-level cues for AI
+text are demonstrably flawed (Jakesch et al., PNAS 2023), while the people
+who detect hollow text almost perfectly judge what a piece commits to,
+risks, and leaves in memory (Russell et al., 2025). That is an experience
+layer, and no skill modeled it. This one does.
+
+first-reader simulates a specific reader encountering your draft cold, and
+reports the reading:
+
+- **Skim gate**: `skim.py` extracts exactly what a scanner fixates on
+ (headings, first lines, bold, numbers) and a fresh reader decides from
+ that view alone whether to commit. For most real readers this gate is
+ the whole encounter.
+- **Timed read, no lookahead**: `feed.py` reveals the piece one beat at a
+ time and refuses the next chunk until the reader logs what just
+ happened: needle position, expectation vs. reality, skimming, doubt,
+ quitting. Humans read forward in time; this restores the arrow of time
+ to a model that otherwise sees everything at once.
+- **Recall test**: `recall.py` hands a fresh agent only the reading log,
+ never the draft, and quizzes it: retell the piece in one sentence, quote
+ what stuck, name the peak, remember the ending. What cannot be
+ reconstructed from the log did not survive the read.
+- **Trust ledger**: `signals.py` counts costly signals (checkable numbers,
+ named entities, admissions against interest) versus free ones (blanket
+ hedging, uniform confidence, portable sentences that fit any document).
+- **The report**: reader testimony in workshop order: what landed first,
+ then the transcript with exact quit points, what survived, the person
+ the prose implies. Never scores. Never rewrites: where is the reviewer's
+ job, how is the writer's.
+- **The page**: `room.py` turns the run into a single page, titled "First read: <your title>": your
+ draft with the readers' comments beside every passage, the skimmer's
+ verdict, a needle strip you can scrub, quit points drawn as a fold
+ line ("S stopped here. They never saw anything below this line."),
+ and lenses that show what a skimmer sees, what survived in memory,
+ and where the trust signals live.
+- **Ask the readers**: `ask.py` lets you consult any reader afterwards;
+ they answer in character from their own reading log, never from a
+ fresh look at the text.
+
+## Install
+
+```bash
+npx skills add https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/agent_skills/first-reader
+```
+
+Or by hand: clone the repo and copy `agent_skills/first-reader` into
+`~/.claude/skills/` (Claude Code, personal), into a project's
+`.claude/skills/` (that project only), or wherever your agent loads
+`SKILL.md` folders from; Cursor, Codex, and friends all work.
+Everything inside is Markdown and stdlib Python: offline, no
+dependencies, nothing leaves your machine. Then say:
+
+> be my first reader on this draft
+
+## Use
+
+- **"review this"** (with a path, or just paste it): your agent goes
+ quiet for a few minutes, then tells you what a friend would after
+ reading: whether the skimmer opened it, where each reader leaned in
+ or left, what stuck, and one question back to you. Plus a page: your
+ draft with the readers' comments beside every passage.
+- **Ask the readers.** "ask S what would have convinced her", "ask the
+ skimmer what would have made them open it", "ask everyone if they
+ noticed the retention example". They answer in character, from what
+ they actually experienced, not from a fresh look at the text.
+- **Revise in your own editor, then "again".** Same readers, fresh
+ minds; the page shows last time's attention strip above this time's,
+ so you see whether your revision moved them.
+- **"quick read"**: sixty seconds, one skeptical scanner, two sentences.
+
+## Who reads it
+
+Every read uses two readers: one who wants the piece to be good and
+one looking for a reason to stop. Where they come from is up to you,
+in three tiers of effort.
+
+**1. Say it in the sentence.** "review this, it's for backend
+engineers on our company blog" is enough. The skill casts both readers
+from the venue and audience you named. Say nothing and it asks one
+question (who is this for, where will it run) or infers from the draft
+and states the assumption in its verdict.
+
+**2. Describe the people.** The strongest input is a one-line life, not
+a job title. Compare:
+
+> an AI engineer
+
+> an AI engineer whose agent's quality check is reading transcripts by
+> hand at 6pm
+
+The second has what makes a reader's boredom or interest mean
+something: what they already know, where they meet your text, and why
+they might care. Give both readers, or just the skeptic ("read it as a
+staff engineer who has built three eval harnesses and thinks this is
+vendor content").
+
+**3. Save them once per project.** Put `.first-reader/audience.json` next
+to your drafts and every read in that folder uses the same two people,
+so "S" is the same person next month and "again" compares like with
+like:
+
+```json
+{
+ "venue": "X long-form, AI engineers",
+ "readers": {
+ "keen": {"initial": "E", "label": "adk engineer",
+ "title": "an AI engineer whose quality check is reading transcripts by hand"},
+ "skeptic": {"initial": "S", "label": "eval skeptic",
+ "title": "a staff engineer who has built eval harnesses and wants a reason to stop"}
+ }
+}
+```
+
+"Read it as X instead" overrides the saved readers for one run.
+
+Two rules hold no matter what you ask for: it never casts you, and it
+never casts someone who loves your style. Readers are a test, and a fan
+is not one.
+
+## What it looks like in your coding agent
+
+First use, any agent:
+
+```
+you: review drafts/launch-post.md, it's going on our blog for
+ backend engineers
+agent: Reading it as your audience would, about 5 minutes. When I'm
+ back: where each reader leaned in or left, what stuck with
+ them, and a page with their comments beside your draft.
+ ...(several minutes; the readers are working)...
+agent: The skimmer moved on at the title. Both readers who opened it
+ finished; S nearly left at the setup section ("two paragraphs
+ of pitch before anything happens") and came back at your
+ outage story. The next day both still had "the outage was a
+ for loop"; neither remembered the ending. One question: is
+ the outage the piece? Page: <link>
+you: ask S what would have kept her in the setup section
+agent: S: "One real number. You told me the tool was fast; I'd have
+ stayed for '40 ms' and left for 'blazing'."
+```
+
+What varies by agent, and the skill adapts on its own:
+
+| | Readers | The page |
+|---|---|---|
+| Claude Code on claude.ai | fresh subagents, sealed off from your draft | published private page |
+| Codex, Cursor, OpenClaw, Antigravity, any CLI | fresh subagents where the harness has them, otherwise the agent plays each reader in turn and says so | local HTML file beside the draft, opened for you |
+
+The page is a report, not an app: nothing on it needs a server, so it
+behaves identically everywhere. Your questions to the readers travel
+the way every instruction to a coding agent does: you say them.
+
+The one honest caveat for single-agent environments: the readers there
+are role-passes by the same mind, not fresh minds, so the skill weights
+its mechanical checks more heavily and tells you to treat the felt
+findings as slightly softer. Everything else, including the scripts
+that pace the reading and test what survives in memory, runs the same
+everywhere: plain Python, offline.
+
+It composes with, rather than replaces, the writing-side skills. Editor
+skills like [addyosmani/clarity](https://github.com/addyosmani/clarity)
+work the writer's chair: substance, truth, register, craft. first-reader
+works the reader's chair: what actually happens when someone meets the
+result cold. Write with an editor, verify with a reader; the two check
+each other, and neither can do the other's job.
+
+## From your editor
+
+The skill is a sentence to your agent, so any editor that can run a
+shell command can start a read on the file you have open. VS Code, as a
+task in `.vscode/tasks.json`:
+
+```json
+{"label": "first read this file", "type": "shell",
+ "command": "claude \"be my first reader on ${file}\""}
+```
+
+Obsidian users can bind the same command with the Shell Commands
+plugin; the page opens in your browser either way.
+
+## Evidence
+
+Tested against paired fixtures built as opposites: a piece that passes
+every anti-slop ban yet commits to nothing, and a piece full of surface
+"tells" (em dashes, triads, a quotable kicker) that is staked and
+specific. The simulated skeptic quit the hollow piece at the same chunk
+across independent reruns ("the same post I have read a hundred times
+under other titles") and read every word of the telly one, checking its
+math along the way, without flagging a single em dash. Transcripts,
+recall diffs, and the development ledger live in
+[`evals/first-reader/`](../evals/first-reader/).
+
+Then run five times on one real essay, same two readers each time,
+the author revising between runs from the readers' comments alone. The
+skeptic quit at passage 9 on the first draft and finished every draft
+after; by the fourth read neither reader logged a negative passage,
+and the peak passage and the three lines that survived recall were the
+same in all five reads. The round-by-round record is in the ledger.
diff --git a/agent_skills/first-reader/SKILL.md b/agent_skills/first-reader/SKILL.md
new file mode 100644
index 00000000..34499a78
--- /dev/null
+++ b/agent_skills/first-reader/SKILL.md
@@ -0,0 +1,306 @@
+---
+name: first-reader
+description: Beta readers for any draft, run by simulating how a real reader experiences it, moment by moment. A skim gate, a no-lookahead timed read producing an attention transcript with quit points, a recall test of what a reader remembers the next day, and a trust ledger of the implied author. Use when the user asks for a beta read, beta readers, test readers, human review, reader review, to read something like a human, to be a first reader, whether a piece holds attention or will actually get read, what readers will remember or take away tomorrow, where readers stop reading or bounce, or why a draft still feels off or hollow after anti-slop or humanizer edits. Final gate before publishing; reports where the reading broke; never rewrites.
+compatibility: Python 3 stdlib only, offline, no dependencies. feed.py runs a loopback http server on 127.0.0.1 during a read so reader subagents receive the draft one passage at a time; nothing leaves the machine and there is no external network access.
+---
+
+# first-reader
+
+Readers before you publish.
+
+Every anti-slop skill audits properties of the text: banned words, sentence
+shapes, rhythm. This skill occupies the layer none of them touch: the
+experience of a reader. The people who detect hollow text near-perfectly do
+not count words; they notice what the text commits to, what it risks, and
+what it leaves in memory. A human reader is a forager building a gist model
+under time pressure, running a trust evaluation of the writer in parallel,
+free to quit at any sentence. This skill reproduces that reader and reports
+what happened to them.
+
+It produces a reading, not an audit. Run it as the final gate before
+publishing.
+
+## The user contract (read this first, it overrides everything below)
+
+To the user, this skill is a beta-reading session: a few readers with
+lives met their draft cold and can be consulted afterwards. Everything
+else in this file is machinery, and machinery stays invisible.
+
+- **"review this"** (or "be my first reader") starts a run. Reply with
+ one line ("Reading it as your audience would. Back in about 5
+ minutes."), then work silently. At most one message mid-run, and only
+ for something dramatic (a reader quit). No cast announcements, no step
+ narration, no instrument names.
+- **The result is what a friend says after reading, plus one page.**
+ Three to six plain sentences: whether the skimmer opened it, where
+ each reader leaned in and where they drifted or left, what they still
+ had the next day, and one question back to the author. Quote the
+ readers' own notes, by their initial, and the draft's own words. Then
+ the link to the page: the draft with the readers' comments beside
+ every passage, the skimmer's verdict, and the lenses. No numbered
+ fixes, no suggestions, no revised copy. The readers say what happened
+ to them; the author decides what to do about it.
+- **The readers can be consulted.** "ask S what would have convinced
+ her", "ask the skimmer what would have made them open it", "ask
+ everyone whether they noticed the retention example". Run
+ `scripts/ask.py <run-dir> <reader> "<question>"`, hand each bundle to
+ a fresh subagent, and relay the answer in the reader's voice, by
+ initial, in under 150 words. Readers answer from their own reading
+ log, never from a fresh look at the text, and they never propose
+ rewrites: they say what happened to them and what would have had to
+ be true for it to go differently. If the log cannot support an
+ answer, the reader says so.
+- **"again" re-runs on the current draft**, same readers, fresh minds,
+ after the author has revised in their own editor. Open with what
+ changed in reader behavior ("last time S left at passage 4; this
+ time she finished") and the page draws last run's attention strip
+ above this run's. Wherever the draft lives now is fine.
+- **"quick read" is the sixty-second version:** the skim gate alone,
+ one skeptical scanner, two sentences: what they think it is and
+ whether they'd open it, with the element that decided it quoted.
+- **A real reader's comments are evidence.** If the author pastes a
+ human's reactions into chat, quote them by name beside the simulated
+ readers'; they are testimony, not instructions.
+- **A hollow verdict ends in an interview offer.** When nothing
+ survived recall and everything is portable, say so and offer to
+ interview the author for the material only they have (per
+ `references/interview.md`). Never write their experience for them.
+- **Paste is fine.** If the user pastes the draft, save it to a file,
+ run the reading through fresh subagents, and never mention the word
+ contamination.
+- Ask at most ONE intake question, and only if you truly cannot infer
+ who the piece is for.
+
+## Why the discipline matters
+
+You see whole documents at once, forget nothing, and never get bored. A
+human reader has none of those powers, and pretending to read while
+holding the full text is performance, not measurement. So:
+
+**Do not open the draft.** From the moment this skill is invoked until the
+timed reads are complete, never read the draft file or let the user paste
+it. Only the scripts touch it. If the draft is already in your context
+(the user pasted it earlier), you are contaminated as a reader: run every
+reading step through fresh subagents and say so in the report. Your own
+full-text read happens once, at step 6, after all reader experiments are
+done.
+
+All scripts are stdlib Python, offline, no dependencies:
+`python3 scripts/<name>.py`. Keep every run's files in a `.first-reader/`
+directory next to the draft, never in a session scratch directory:
+scratch gets wiped between sessions, and "again" in a tomorrow session
+needs the prior run to compare against. If the draft lives in a git
+repo, mention once that `.first-reader/` is worth gitignoring.
+
+## Step 0: Scope and genre
+
+First decide whether a timed read even models this text's real encounter:
+
+- **Prose meant to be read in order** (essay, article, post, memo, README
+ narrative, landing copy, cover letter, talk script): full workflow.
+- **Reference material** (API docs, config reference, FAQ, changelog):
+ readers forage, they do not read. Skip the timed read. Run the skim gate
+ as the main event with lookup tasks: cast a reader with a question and
+ test whether the scanner view routes them to the answer. Skimmability is
+ the success condition here, not a defect.
+- **Under ~150 words** (tweet, bio, announcement): no chunked feed. One
+ fresh subagent gets the text cold with a persona and a two-second frame:
+ first felt reaction, would they stop scrolling, what they'd retell.
+ Then the trust ledger. Skip recall.
+- **Fiction and poetry**: the transcript and recall work; the trust ledger
+ and specifics-density readings do not apply as written. Needle and
+ memory only, and say so.
+- **Not this skill**: code review, factual verification, copyediting,
+ rewriting. Decline and point at the right tool.
+
+Work silently per the user contract: one line at the start, at most one
+mid-run message for a dramatic event, then the result. In anything the
+user does see, plain words only.
+
+## Step 1: Cast the reader
+
+Read `references/personas.md`. If the audience or venue is unknown, ask
+the user one question: who is this for and where will it be published?
+Then cast two personas, sympathetic and skeptical, each with priors,
+situation, patience budget from the table, and a one-sentence stake. If
+you cannot write the stake sentence, report that first.
+
+Also ask, if not obvious: what should the reader think, feel, or do after
+reading? That is the intended gist the recall test will be judged against.
+
+Fold the audience into the one starting line only when it needs
+confirming ("Reading it as engineers on HN would"); otherwise just
+start. Before casting, look for `.first-reader/audience.json` beside the
+draft (format in `references/room.md`): it holds the readers this
+author already chose, with their initials and one-line lives, so the
+same two people read every draft in the project and "S" means the same
+person next month. Reuse it unless the user names a different audience;
+write it after the first cast. Write `manifest.json` in the run
+directory per `references/room.md` for your own use. On a repeat review, reuse the
+prior manifest's casts and point `previous_run` at the old run so the
+results can be compared honestly.
+
+## Step 2: The skim gate
+
+Have a fresh subagent playing the skeptical persona run
+`scripts/skim.py <draft>` itself and answer from that view alone; if you
+must run the script, redirect its output straight to a file you never
+open, because the scanner view quotes fragments of the draft and reading
+it contaminates you before the timed reads. It answers: what is this
+piece, do you commit to a full read, and what single element decided it.
+
+A scanner who cannot say what the piece is, or declines to commit, is the
+first finding. For most real readers this gate is the whole encounter.
+
+## Step 3: The timed reads
+
+No lookahead is enforced by mechanism, not by asking nicely. Start the
+feed in the background BEFORE dispatching any reader:
+
+```
+python3 scripts/feed.py serve <draft> --run <run-dir> --readers keen,skeptic \
+ --persona "keen=<one line>" --persona "skeptic=<one line>" \
+ --ready-file <run-dir>/feed.json
+```
+
+The text now lives only in that process's memory. `feed.json` holds
+addresses, nothing else; read it and give each reader ONLY its own
+line. A reader's dispatch prompt contains the persona, `export
+READER_FEED=<reader-address>`, and three commands; it never
+contains the draft path, the run directory, or the other reader's
+address. The reader runs `feed.py start`, then reads one passage at a
+time, logging honestly at each step with
+`feed.py next --log "needle=<-2..+2> expected... got... <felt notes>"`.
+The needle is the felt reaction: +2 leaning in, 0 neutral, -1 drifting
+or doubting, -2 done. Log skimming the moment it starts. When the
+persona's patience runs out, quit with
+`feed.py quit --log "needle=-2 <why the persona stopped>"`, because
+quitting is the single most informative thing a reader does. A reader
+who finishes still records one final line the same way; the transcript
+labels it FINAL rather than QUIT.
+
+The feed releases the next passage only after a real log lands, never
+re-serves anything but the current passage, refuses to advance faster
+than a person could read the passage, and writes nothing of the piece
+to disk until every reader is finished (`feed.py progress --admin
+<admin-address>` shows where they are; `feed.py close --admin ...`
+flushes early if a reader dies). The reader subagent returns nothing
+of substance; the artifact is the session. Collect it with
+`feed.py transcript <run-dir>/<reader>` after close.
+
+If subagents are unavailable, use file mode (`feed.py start <draft>
+--session <dir>`) yourself under the same rules, before ever opening
+the draft, and disclose that one mind played both reader and reviewer
+(see Adapting to your environment).
+
+## Step 4: The recall test
+
+Run `scripts/recall.py <session-dir>` for the sympathetic persona's
+session (and the skeptic's if it finished). Hand the output to a fresh
+subagent with no other context. It answers the quiz from the transcript
+alone: sayback, pointing, peak, ending, center of gravity, one action.
+
+Judge the answers against the intended gist from step 1. A piece whose
+one-sentence retelling does not match its thesis, or whose ending nobody
+remembers, has a finding no line edit can fix. "Nothing survived" is a
+finding about the piece, not about the reader.
+
+## Step 5: The trust ledger
+
+Run `scripts/signals.py <draft> --json`, but only after the timed reads
+are complete: its output quotes draft sentences, so reading it earlier
+contaminates you. Read the numbers through the genre: costly signals (checkable numbers, named entities, quotes,
+admissions against interest, first-person experience) buy trust; free
+signals (hedges everywhere, certainty everywhere, portable sentences that
+fit any document) buy nothing. Near-zero variance in epistemic commitment
+reads as machine confidence. The counters are floors, not truth: the
+admissions detector in particular under-counts (it pattern-matches stock
+phrasings and misses lines like "our test data was a fantasy"), so
+confirm costly signals in your own step 6 read rather than trusting a
+zero.
+
+## Step 6: Your own read, then the report
+
+Only now read the draft in full, once, for two judgments the scripts
+cannot make: the implied author (describe the person these sentences
+imply, and quote any seam where that person changes mid-document) and
+whether the transcripts' complaints are the piece's fault or the cast's.
+
+Write the report exactly as `references/report.md` specifies: sayback and
+meaning first, then the reading transcripts, what survived, the person
+behind it, then neutral questions and opinions by permission. Testimony
+register throughout, no scores, altitude rule enforced, and the report is
+allowed to be happy.
+
+## Step 7: The page, and the readers stay available
+
+Save the skim gate's answer as `<run-dir>/skim.txt` and put its verdict
+in the annotations (`skim`). Build the page per `references/room.md`
+(`scripts/room.py`): the draft with the readers' comments beside each
+passage, the skimmer's verdict, the lenses, the strip; no fixes. Publish
+it where you can, or write it beside the run and open it. Deliver per
+the user contract: the friend's report, then the link. Keep the
+Lerman-order report on disk beside the run for anyone who asks.
+
+The readers persist in the run directory. Every later "ask" in the
+session goes through `scripts/ask.py` and a fresh subagent per reader;
+never answer for a reader yourself, and never let a reader see the
+draft again: their memory is their log.
+
+## Adapting to your environment
+
+This skill runs in any SKILL.md-compatible coding agent, but three
+capabilities vary. Check what you have BEFORE the run starts, adapt
+silently, and tell the user only what changes for them, in one line.
+
+**Subagents.** If you can spawn fresh agents (Claude Code's agent tool,
+or any delegation mechanism), each reader is one. If you cannot, you
+play the readers yourself, one persona at a time, and the order of
+operations becomes everything: do NOT read or open the draft file for
+any reason before the reads; start immediately with the feed script and
+meet the piece one passage at a time in persona (file mode; served
+mode is pointless when reader and reviewer share a mind); do the skeptic's read
+in a later, separate pass from the sympathetic one; run recall by
+answering the quiz from the transcript alone before ever seeing the
+full text. This is a weaker experiment than fresh minds, so say so once
+in the verdict ("I played both readers myself here, so treat the
+findings as slightly softer") and never pretend otherwise. If the draft
+is already in your context (you read it earlier in the session, it was
+pasted, or your harness auto-loaded it), solo mode cannot blind you; do
+the reads anyway as honest role-passes, and weight the mechanical
+signals (quit logic, recall-from-log, signals.py) more heavily than the
+needle.
+
+**A place for the page.** With artifact publishing (Claude Code on
+claude.ai), the page is a private link. Without it, it is a local HTML
+file next to the run, opened for the user. The page is read, not
+clicked; questions to the readers come to you in chat.
+
+**Turn budget.** In agents where every script call is a visible tool
+step, the full run is many steps. Say so up front in the starting line
+("this takes a few minutes and a lot of small steps") and never ask
+permission step by step; batch where your harness allows.
+
+The first time the skill runs in a session, the starting line also
+teaches the interface in passing, because nothing else will: "Reading
+it as your audience would, about 5 minutes. When I'm back: where each
+reader leaned in or left, what stuck with them, and a page with their
+comments beside your draft. You can ask them follow-ups, and 'again'
+re-reads after you revise."
+
+## Guardrails
+
+- Never rewrite the draft, in whole or in part, and never hand over a
+ list of suggested fixes. The readers report what happened to them;
+ the author owns every decision about the text. If asked for a rewrite,
+ offer the readers' comments to the user's own editing skill instead.
+- Never manufacture findings. Two clean transcripts and a passed recall
+ test end the review honestly.
+- Never blame the reader. If the cast was wrong for the piece, recast and
+ rerun; if the piece is for experts and the skeptic was a novice, that
+ was a casting error, not a draft error.
+- Word-level slop hunting is out of scope; other skills own it. If the
+ transcripts keep tripping on the same phrase, report the tripping, not
+ the phrase's presence on any list.
+- The transcripts are evidence. Quote them; do not summarize them into
+ the abstractions they exist to replace.
diff --git a/agent_skills/first-reader/references/interview.md b/agent_skills/first-reader/references/interview.md
new file mode 100644
index 00000000..19a1308a
--- /dev/null
+++ b/agent_skills/first-reader/references/interview.md
@@ -0,0 +1,67 @@
+# The author interview
+
+When the readers find nothing at stake (nothing survived recall, near-total
+portability, no admissions, no events), line edits are the wrong tool: the
+draft is missing material, and the only person who has it is the author.
+The interview collects that material. It is the one moment this skill
+generates words, and the discipline below exists so those words stay the
+author's.
+
+## When to offer it
+
+Offer once, in the verdict, in one sentence: "The readers found nothing
+only you could have written. Want me to interview you for ten minutes and
+then re-run?" If the author declines, deliver the findings as usual and
+stop. Never start interviewing uninvited, and never frame the offer as
+the draft being bad; frame it as the draft being empty of them.
+
+## How to ask
+
+One question per message, then wait. Never a questionnaire. Follow the
+energy: when an answer has a specific in it (a number, a name, a failure,
+a fight), the next question digs there, not at the next item on your list.
+
+Ask for events, never for opinions. The difference:
+
+- Not "what do you think about eval metrics?" but "tell me about a time a
+ metric lied to you. What did it cost?"
+- Not "why is this important?" but "what happened that made you sit down
+ and write this?"
+- Not "what would you tell beginners?" but "what did you do wrong the
+ first time?"
+
+The six questions that most reliably surface stakes, adapted to the piece:
+
+1. What actually happened? (the incident behind the thesis)
+2. What did it cost, in hours, money, or embarrassment?
+3. Who disagrees with you about this, and what is their best argument?
+4. What did you believe before that you don't believe now?
+5. What example from your own work would you show if the reader were
+ sitting next to you?
+6. What are you still unsure about?
+
+Question 3 and 6 matter most: disagreement and uncertainty are the two
+signals a hollow draft never contains, because they cannot be generated,
+only owned.
+
+Stop when you have two or three concrete events with details, or when two
+questions in a row come back thin. A thin answer gets ONE follow-up
+("when that happened, what did you actually do?"); if it stays thin, move
+on. Do not squeeze; absent material is a finding too, and it is fine to
+end with "the piece may want to wait until this has happened to you."
+
+## How to write from the answers
+
+- Capture the author's phrasing verbatim during the interview; their
+ wording of an event is almost always better than your paraphrase of it.
+- Weave their answers into the draft where the hollow passages were, in
+ their words wherever the words work. Connective tissue may be yours;
+ events, numbers, names, positions, and doubts must be theirs.
+- Never upgrade an answer. "It took a while" does not become "it took
+ three weeks". "Some people disagreed" does not become a named skeptic.
+ If a detail matters and they were vague, ask again instead of writing.
+- Show the rewritten passages as tracked changes (see room.md), tell the
+ author these are their answers arranged, and ask them to read once for
+ anything that is not true in their voice.
+- Then re-run with fresh readers. The interview succeeded if the recall
+ test now returns their material, not your arrangement of it.
diff --git a/agent_skills/first-reader/references/personas.md b/agent_skills/first-reader/references/personas.md
new file mode 100644
index 00000000..b146aa54
--- /dev/null
+++ b/agent_skills/first-reader/references/personas.md
@@ -0,0 +1,59 @@
+# Casting the reader
+
+A review needs a reader, and "the audience" is not one. Cast two personas
+per review: one sympathetic, one skeptical. Both are honest; they differ in
+what they want and what stopping costs them (nothing, ever).
+
+Every cast states four things before the read begins:
+
+1. **Priors**: what they already know and believe about this topic, and what
+ they have already read this week that this piece competes with.
+2. **Situation**: where they meet the text (feed on a phone, inbox, a link a
+ colleague sent, a docs search result) and what they were doing before.
+3. **Patience budget**: how much they give the opening before bailing, from
+ the empirical table below.
+4. **Stake**: why they might care, in one sentence. If you cannot write this
+ sentence, that is the first finding of the review.
+
+## Patience budgets (empirical, per encounter context)
+
+| Context | Budget for the opening | Source basis |
+|---|---|---|
+| Social feed scroll | 10 to 15 seconds, roughly the first two lines | Chartbeat: ~55% of pageviews under 15s engaged time |
+| Blog/newsletter via link | first screen, ~2 paragraphs | NN/g: at most ~20 to 28% of words read; commitment earned by the opening |
+| Inbox (memo, cover letter) | under 30 seconds | recruiter/hiring-manager survey data; Ladders eye-tracking 7.4s initial resume scan |
+| Slush pile / gatekeeper | first paragraph, one strike allowed | slush-reader practice: most rejections happen on page one |
+| Investor / exec skim | ~20 seconds per section, fixates on team/numbers/ask | DocSend: 3m44s average per deck |
+| Docs / reference lookup | as long as scanning WORKS; zero tolerance for prose blocking the answer | information foraging: reader follows scent to the answer |
+| Committed subscriber / fan | full read, but skimming the middle is still on the table | median scroll depth ~50% even for engaged visits |
+
+## The two default casts
+
+**The sympathetic reader** wants the piece to be good. They followed a
+recommendation, they like the topic, they read generously and finish unless
+actively pushed out. Their transcript shows what the piece is at its best
+(Elbow's believing game). If even this reader skims a section, that section
+is dead.
+
+**The skeptical gatekeeper** is the genre's professional stopper: slush
+reader, staff engineer skimming a design doc, editor, investor, tired
+customer. They are looking for a reason to stop, one is enough, and an early
+credibility hit taxes everything after it. Their quit point is the review's
+sharpest number (the doubting game).
+
+Adjust both to the piece's real audience. A skill README's skeptic is a
+developer deciding in 30 seconds whether to install; a personal essay's
+skeptic is a stranger who has read forty essays this week that open the
+same way.
+
+## Casting rules
+
+- Personas must disagree with each other somewhere or the cast failed;
+ rerun the skeptic with a tighter budget and a sharper stake.
+- Never cast the author, and never cast "someone who loves this style".
+- The persona's knowledge sets what needs explaining: an expert reader
+ experiences a definition of basics as being talked down to; a newcomer
+ experiences undefined jargon as a locked door. Both are needle events.
+- If the user cannot say who the reader is, cast the skeptic from the venue
+ (where will this be published?) and say in the report that the cast is a
+ guess.
diff --git a/agent_skills/first-reader/references/report.md b/agent_skills/first-reader/references/report.md
new file mode 100644
index 00000000..8554f794
--- /dev/null
+++ b/agent_skills/first-reader/references/report.md
@@ -0,0 +1,87 @@
+# The reading report
+
+The deliverable is a reading, not an audit. Order and register are fixed;
+they come from Liz Lerman's Critical Response Process and Peter Elbow's
+reader-based feedback, and they exist so the writer ends the report eager
+to revise rather than braced against a list of violations.
+
+## Register: testimony, never verdict
+
+Every finding is phrased as what happened in a reader, anchored to quoted
+text, with the effect it had. The reader cannot be wrong about what they
+experienced; the writer stays free to decide it doesn't matter.
+
+- Yes: "At 'the future of work is changing', my skeptic thought 'forty
+ other posts this week' and left. That sentence cost you the read."
+- No: "Weak opening." / "This violates the hook rule." / "Score: 6/10."
+
+No scores, no grades, no percentages of quality. The only numbers allowed
+are observations: the quit chunk, what the recall quiz returned, what
+signals.py counted.
+
+Diagnose the place and the effect; hold fixes loosely. Workshop constant:
+readers are right about where, wrong about how. Prescriptions appear only
+in the final section, labeled as opinions, and the writer may decline them.
+
+## Order
+
+**1. Sayback and meaning.** One sentence: what this piece is, as received.
+Then what landed: the moments that had meaning, quoted. This comes first
+because it tells the writer what not to break, and because a review that
+opens with defects gets read defensively. This section is honest, not
+polite; if little landed, it is short.
+
+**2. The reading.** The transcript evidence, one short block per persona:
+where expectation was set, where it was met or broken, where the needle
+moved and why, where skimming started, the exact sentence of the quit or
+the fact of the finish. Quote the draft only where the reader's log did.
+
+**3. What survived.** The recall results: the one-sentence retelling vs
+what the piece meant to say, the phrases that stuck, the peak, whether the
+ending survived at all, the center of gravity ("it says it's about X; it
+came alive at Y"), and the one-action answer.
+
+**4. The person behind it.** Implied author in one or two sentences ("the
+person these sentences imply is..."), any seam where that person changes,
+and the trust ledger: costly signals paid vs free signals, with the
+signals.py numbers as evidence, read through the genre.
+
+**5. Questions, then opinions by permission.** Two or three genuinely
+neutral questions (no embedded advice: "what did you want the reader
+feeling at the pivot?" not "why is the pivot so abrupt?"). Then: "I have
+opinions about the opening, the middle section, and the ending. Want
+them?" If the user says yes, give them as opinions, still anchored to the
+transcript.
+
+## Altitude rule
+
+If the skim gate fails or both personas quit in the first third, stop
+there. Report sections 1, 2 and 4 only, say plainly that the piece has a
+structural problem that makes line-level notes premature, and name the
+developmental question the draft has to answer first. Line notes on a
+piece whose structure is dead are wasted work and false comfort.
+
+The gate and the reads can disagree: a skim gate that fails while both
+timed readers finish and the recall test passes means the piece loses
+readers at acquisition but rewards the ones who commit. That structure is
+wounded, not dead. Report the full evidence, lead with the gate failure
+as the primary structural finding, and say which audience each result
+speaks for: the scanner is most of the piece's reach, the finishers are
+the already-persuaded.
+
+## The report is allowed to be happy
+
+A reader sometimes just gets pulled through. If both transcripts run
+positive, the recall quiz returns the intended gist, and the trust ledger
+is paid up, the report says so and stops. "I read it twice and have only
+pointing to offer" is a complete, valid review. Manufacturing findings to
+seem thorough is this skill's defined failure mode, and the eval's control
+case exists to catch it.
+
+## What this skill never does
+
+It never rewrites. Where is the reviewer's job; how is the writer's.
+Handing back rewritten sentences would collapse the one thing this skill
+adds over every humanizer: the writer putting the fix in their own
+language. If the user asks for the rewrite, point them at their own voice
+or editing skill and offer the transcript as its input.
diff --git a/agent_skills/first-reader/references/room.md b/agent_skills/first-reader/references/room.md
new file mode 100644
index 00000000..97c83b70
--- /dev/null
+++ b/agent_skills/first-reader/references/room.md
@@ -0,0 +1,112 @@
+# The first-reader page
+
+The review's primary deliverable is a page, not a wall of text: the draft
+with the reading still on it. `scripts/room.py` builds it from the run's
+raw sessions; you feed it curation through one JSON file so the page
+carries a plain-language verdict, the readers' best lines, and the lens
+data from the recall and signals steps.
+
+## Build
+
+```
+python3 scripts/room.py <run-dir> [--out room.html] [--annotations room-annotations.json]
+```
+
+`<run-dir>` is the directory whose subdirectories are the feed.py
+sessions. With no annotations the page still works: excerpts are trimmed
+mechanically from the logs, and the memory and trust lenses stay hidden.
+Always write the annotations file; the mechanical fallback is for
+resilience, not for shipping.
+
+Publish the page as an Artifact where you can, or write it beside the
+run and open it; give the user the link or path as the review's ending.
+Keep the same file path on rebuilds so a published URL survives.
+
+## room-annotations.json
+
+Write it after the recall test and your own read, before building:
+
+- `title`: the page title. Always "First read: <the draft's own title>",
+ so the tab says exactly what the page is; room.py defaults to that
+ from the first heading if you omit it.
+- `skim`: the skim gate's decision, `{"commits": false, "said": "<the
+ skimmer's own words, two sentences>"}`. It renders at the top, because
+ for most readers that decision is the whole encounter.
+- `verdict_lead`, `verdict_rest`: the verdict in plain spoken language.
+ Lead with the good news if there is any. No jargon, no codenames, no
+ scores. Write it the way you'd tell a friend across a table.
+- `readers`: keyed by session directory name:
+ `{"initial": "P", "label": "platform eng", "title": "a platform engineer who needs this for a Thursday review"}`.
+ The title is a sentence fragment a stranger understands.
+- `excerpts`: keyed by session dir, then passage number as a string. One
+ or two of the reader's own sentences per passage, trimmed by you. Quote
+ the reader; never paraphrase into reviewer-speak.
+- `flags`: passage number to a plain phrase a person would say: "best
+ moment", "felt misled here", "attention dropped". Never invented
+ codenames.
+- `memory_phrases`: the exact strings the recall quiz preserved. These
+ light up under the "what stuck" lens; everything else ghosts.
+- `portable_sentences` and `entities`: from the signals step; they power
+ the trust lens.
+- `opinions`: the sealed list for opinions-by-permission, as short plain
+ sentences. Empty list or omitted means no envelope renders.
+- `previous`: on a re-run, `{"summary": "...", "run": "<path to the
+ prior run dir>"}`. The summary is one sentence comparing reader
+ behavior ("Last time the skeptic quit at passage 2; this time they
+ finished") and renders at the top; the run path makes the page draw
+ last run's needle strip above this run's, so the author sees the
+ orange stretch turn blue (or not).
+
+## Consulting the readers
+
+After the run the readers are still there: each session directory holds
+a persona and the log that is that reader's memory, and `skim.txt`
+holds the skimmer's decision. When the author asks a reader something:
+
+```
+python3 scripts/ask.py <run-dir> skeptic "what would have convinced you at passage 8?"
+python3 scripts/ask.py <run-dir> skim "what would have made you open it?"
+python3 scripts/ask.py <run-dir> all "did you notice the retention example?"
+```
+
+Hand each printed bundle to a fresh subagent and relay the answer in the
+reader's voice. The bundle never contains the draft; a reader who
+cannot answer from their notes says so. Readers never propose rewrites.
+
+## The saved audience
+
+`.first-reader/audience.json` beside the draft keeps the project's readers
+so they stay the same people across drafts and runs:
+
+```json
+{
+ "venue": "company engineering blog",
+ "readers": {
+ "keen": {"initial": "E", "label": "adk engineer",
+ "title": "an AI engineer whose quality check is reading transcripts by hand"},
+ "skeptic": {"initial": "S", "label": "eval skeptic",
+ "title": "a staff engineer who has built eval harnesses and wants a reason to stop"}
+ }
+}
+```
+
+Reuse it for casting and for the `readers` block of the annotations;
+change it only when the author names a different audience.
+
+## The run manifest
+
+Before the timed reads, write `manifest.json` in the run directory:
+
+```json
+{
+ "draft": "<path>",
+ "intended_gist": "<what the reader should think, feel, or do>",
+ "casts": {"<session-dir>": "<one-line persona>"},
+ "previous_run": "<path to the prior run dir, or null>"
+}
+```
+
+On a re-run after revision: reuse the casts from the prior manifest so
+the comparison is honest, point `previous_run` at it, and lead both the
+chat verdict and the room's `previous` line with what changed in reader
+behavior. Fresh readers every time; only the casts repeat.
diff --git a/agent_skills/first-reader/scripts/ask.py b/agent_skills/first-reader/scripts/ask.py
new file mode 100755
index 00000000..696ceb24
--- /dev/null
+++ b/agent_skills/first-reader/scripts/ask.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Consult a reader after the run: they answer in character, from their own log.
+
+A real beta reader can be asked follow-ups: "what would have convinced
+you?", "where exactly did you check out?", "did you notice the retention
+example?" This script packages one reader's persona and moment-by-moment
+log with the author's question so a fresh agent can answer AS that reader,
+grounded in what actually happened to them during the read, and nothing
+else. The draft is never included: like a person the next day, the reader
+has their memory of the experience, not the text.
+
+Usage:
+ python3 ask.py <run-dir> <reader> "<question>" one reader (session dir name)
+ python3 ask.py <run-dir> skim "<question>" the skim-gate reader
+ python3 ask.py <run-dir> all "<question>" every reader, one bundle each
+
+Hand each printed bundle to a fresh subagent and relay its answer in the
+reader's voice. Readers stay honest: an answer the log cannot support is
+"I can't say; I didn't note it at the time."
+"""
+import json
+import sys
+from pathlib import Path
+
+
+def bundle(run, name, question):
+ d = Path(run) / name
+ if name == "skim":
+ note = Path(run) / "skim.txt"
+ if not note.exists():
+ return None
+ return (f"You are the reader who skimmed this piece and decided whether to open it. You saw only the "
+ f"scanner's view (headings, first lines, numbers, links), never the full text, and you still have not "
+ f"read it. This is what you said at the time:\n\n{note.read_text().strip()}\n\n"
+ f"The author asks you: {question}\n\nAnswer in your own voice, in under 120 words, from that decision "
+ f"and nothing else. If you would need to have read the piece to answer, say so.")
+ if not (d / "state.json").exists():
+ return None
+ state = json.loads((d / "state.json").read_text())
+ entries = [json.loads(l) for l in (d / "log.jsonl").read_text().splitlines() if l.strip()]
+ log = "\n".join(f"[passage {e['chunk']}] {'QUIT ' if e.get('quit') else ''}{e['entry']}" for e in entries)
+ how = ("stopped at passage %s of %s" % (state["quit_at"], len(state["chunks"]))) if state.get("quit_at") \
+ else "finished all %s passages" % len(state["chunks"])
+ return (f"You are {state['persona']}. Earlier today you read a piece one passage at a time and {how}. "
+ f"You no longer have the text; you have your memory of reading it, which is exactly the notes you kept "
+ f"as you went:\n\n{log}\n\nThe author asks you: {question}\n\n"
+ f"Answer as yourself, in under 150 words, grounded only in what you noted at the time. Quote your own "
+ f"notes where they answer it. Do not invent details of the text you did not note. If the log does not "
+ f"support an answer, say 'I can't say; I didn't note it at the time.' Never suggest rewrites; say what "
+ f"happened to you and what would have had to be true for it to go differently.")
+
+
+def main():
+ if len(sys.argv) != 4:
+ sys.exit(__doc__)
+ run, who, question = sys.argv[1], sys.argv[2], sys.argv[3]
+ names = [who]
+ if who == "all":
+ names = sorted(p.name for p in Path(run).iterdir() if (p / "state.json").exists())
+ if (Path(run) / "skim.txt").exists():
+ names.append("skim")
+ out = []
+ for n in names:
+ b = bundle(run, n, question)
+ if b is None:
+ sys.exit(f"no reader '{n}' under {run}")
+ out.append(f"===== reader: {n} =====\n{b}")
+ print("\n\n".join(out))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/first-reader/scripts/feed.py b/agent_skills/first-reader/scripts/feed.py
new file mode 100644
index 00000000..b90a0eef
--- /dev/null
+++ b/agent_skills/first-reader/scripts/feed.py
@@ -0,0 +1,511 @@
+#!/usr/bin/env python3
+"""Reveal a draft to a reader one passage at a time, with no lookahead.
+
+Humans read forward in time: at any sentence they know what came before,
+roughly how much text remains, and nothing else. An LLM sees the whole
+document at once, which makes "read this like a human" performed rather
+than real. This driver restores the arrow of time, and in served mode it
+enforces it: the text lives only in the memory of a local server the
+orchestrator starts; each reader gets a one-line address with a token
+and never a path; the server releases the next passage only after the
+reader logs what just happened in them, never re-serves anything but the
+current passage, and refuses to move faster than a person could read.
+Nothing about the piece is written where a reader could find it until
+every reader is finished.
+
+SERVED MODE (default whenever readers are separate agents)
+
+ Orchestrator, in the background:
+ python3 feed.py serve <draft> --run <run-dir> --readers keen,skeptic
+ It prints one READER_FEED address per reader plus an admin address.
+ Hand each reader ONLY its own address, e.g.
+ export READER_FEED=http://127.0.0.1:PORT/<token>
+
+ Reader (READER_FEED set in its shell):
+ python3 feed.py start
+ python3 feed.py next --log "needle=<-2..+2> expected... got... <felt notes>"
+ python3 feed.py quit --log "needle=-2 <why the persona stopped>"
+
+ Orchestrator, to watch and to finish:
+ python3 feed.py progress --admin <admin-address>
+ python3 feed.py close --admin <admin-address>
+ Closing writes <run-dir>/<reader>/state.json + log.jsonl in the layout
+ recall.py and room.py expect. Logs stream to log.jsonl live (they hold
+ only the reader's own words). The server also closes itself once every
+ reader has finished or quit.
+
+FILE MODE (solo fallback: one mind plays reader and reviewer)
+
+ python3 feed.py start <draft> --session <dir> [--persona <name>]
+ python3 feed.py next <dir> --log "<entry>"
+ python3 feed.py quit <dir> --log "<entry>"
+ python3 feed.py transcript <dir>
+ python3 feed.py status <dir>
+
+Log entry format (one line, free text, but include):
+ needle=<-2..+2> the felt reaction right now, minus is boredom/distrust
+ expect: what you now expect next got: what this chunk actually was
+ plus anything felt: skimmed, lost, won back, doubted a claim, laughed.
+"""
+import argparse
+import json
+import os
+import re
+import secrets
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib import request as urlrequest
+from urllib.error import HTTPError
+
+TARGET_WORDS = 85 # a paragraph-scale beat
+MAX_WORDS = 200 # split anything longer: nobody swallows 200 words as one beat
+MIN_LOG_CHARS = 25
+
+
+def chunk(text):
+ paras = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+ out, buf, buf_words = [], [], 0
+ for p in paras:
+ w = len(p.split())
+ if w > MAX_WORDS:
+ if buf:
+ out.append("\n\n".join(buf)); buf, buf_words = [], 0
+ sentences = re.findall(r".+?(?:[.!?](?=\s|$)|$)", p, re.S)
+ piece, count = [], 0
+ for s in sentences:
+ sw = s.split()
+ # a sentence-less blob (transcript, list dump) still gets beats
+ while len(sw) > MAX_WORDS:
+ out.append(" ".join(piece + sw[:TARGET_WORDS]))
+ piece, count, sw = [], 0, sw[TARGET_WORDS:]
+ piece.append(" ".join(sw)); count += len(sw)
+ if count >= TARGET_WORDS:
+ out.append(" ".join(piece)); piece, count = [], 0
+ if piece:
+ out.append(" ".join(piece))
+ continue
+ # keep a heading attached to the paragraph that follows it
+ if re.match(r"#{1,6}\s", p) and buf_words == 0:
+ buf.append(p); continue
+ buf.append(p); buf_words += w
+ if buf_words >= TARGET_WORDS:
+ out.append("\n\n".join(buf)); buf, buf_words = [], 0
+ if buf:
+ out.append("\n\n".join(buf))
+ return out
+
+
+
+BRIEFING = ("You are this persona encountering this text cold. React honestly; "
+ "your persona's patience budget is real, and quitting is a finding, "
+ "not a failure.")
+
+
+def chunk_header(i, chunks):
+ remaining = sum(len(c.split()) for c in chunks[i + 1:])
+ return f"--- CHUNK {i + 1}/{len(chunks)} ({remaining} words remain after this) ---"
+
+
+def chunk_footer():
+ return ("--- record your moment log with: feed.py next --log \"...\" "
+ "(or feed.py quit --log \"...\" if your persona stops here) ---")
+
+
+def dwell_floor(text, factor):
+ # a person needs roughly words/4 seconds at 238 wpm; the floor is a
+ # fraction of that so honest readers never notice it and racers do
+ return max(2.0, len(text.split()) * factor) if factor > 0 else 0.0
+
+
+# ---------------------------------------------------------------- served mode
+
+class Feed:
+ def __init__(self, draft, run_dir, names, persona_titles, dwell):
+ text = Path(draft).read_text(encoding="utf-8")
+ self.chunks = chunk(text)
+ self.words = len(text.split())
+ self.run_dir = Path(run_dir)
+ self.dwell = dwell
+ self.admin = secrets.token_urlsafe(18)
+ self.readers = {}
+ self.lock = threading.Lock()
+ self.closed = False
+ for name in names:
+ token = secrets.token_urlsafe(18)
+ d = self.run_dir / name
+ d.mkdir(parents=True, exist_ok=True)
+ (d / "log.jsonl").write_text("")
+ self.readers[token] = {"name": name, "persona": persona_titles.get(name, name),
+ "cursor": 0, "started": None, "served_at": None,
+ "done": False, "quit_at": None, "log": []}
+
+ def _payload(self, r):
+ i = r["cursor"]
+ r["served_at"] = time.time()
+ return {"header": chunk_header(i, self.chunks), "text": self.chunks[i],
+ "footer": chunk_footer(), "index": i + 1, "total": len(self.chunks)}
+
+ def start(self, r):
+ if r["done"]:
+ return {"error": "Session already finished."}
+ first = r["started"] is None
+ if first:
+ r["started"] = time.time()
+ p = self._payload(r)
+ p["briefing"] = (f"SESSION {r['name']} | persona: {r['persona']} | "
+ f"{len(self.chunks)} chunks, {self.words} words total\n{BRIEFING}") if first else \
+ "(re-showing the current passage; nothing advanced)"
+ return p
+
+ def _record(self, r, entry, quit_, check_dwell=True, chunk=None):
+ entry = (entry or "").strip()
+ if len(entry) < MIN_LOG_CHARS:
+ return {"refused": f"log entry under {MIN_LOG_CHARS} chars. What happened in you "
+ "during that chunk? needle=?, expected what, got what?"}
+ # the dwell floor guards lookahead; quitting reveals nothing, so a
+ # reader may leave the instant a passage loses them
+ if check_dwell and r["served_at"] is not None and self.dwell > 0:
+ floor = dwell_floor(self.chunks[r["cursor"]], self.dwell)
+ waited = time.time() - r["served_at"]
+ if waited < floor:
+ return {"refused": f"too fast: a person needs about {floor:.0f}s with this passage "
+ f"and {waited:.0f}s have passed. Read it, then log what happened."}
+ rec = {"chunk": chunk or r["cursor"] + 1, "quit": quit_, "entry": entry, "t": time.time()}
+ r["log"].append(rec)
+ with (self.run_dir / r["name"] / "log.jsonl").open("a") as f:
+ f.write(json.dumps(rec) + "\n")
+ return None
+
+ def next(self, r, entry):
+ if r["done"]:
+ return {"error": "Session already finished."}
+ if r["started"] is None:
+ return {"error": "Call feed.py start first."}
+ bad = self._record(r, entry, False)
+ if bad:
+ return bad
+ r["cursor"] += 1
+ if r["cursor"] >= len(self.chunks):
+ r["done"] = True
+ self._maybe_finish()
+ return {"end": "END OF PIECE. The reader finished. Add one final log line for the "
+ "ending itself via: feed.py quit --log \"final: ...\""}
+ return self._payload(r)
+
+ def quit(self, r, entry):
+ if r["started"] is None:
+ return {"error": "Call feed.py start first."}
+ finished = r["done"] or r["cursor"] >= len(self.chunks) - 1
+ # a final reaction after END belongs to the last chunk, not cursor+1
+ last_chunk = len(self.chunks) if r["done"] else None
+ bad = self._record(r, entry, not finished, check_dwell=False, chunk=last_chunk)
+ if bad:
+ return bad
+ r["done"] = True
+ r["quit_at"] = None if finished else r["cursor"] + 1
+ r["served_at"] = time.time()
+ self._maybe_finish()
+ if r["quit_at"]:
+ return {"end": f"Reader stopped at chunk {r['quit_at']}/{len(self.chunks)}. "
+ "That stop point is the primary finding."}
+ return {"end": "Final reaction recorded. Session complete."}
+
+ def progress(self):
+ return {r["name"]: {"chunk": min(r["cursor"] + 1, len(self.chunks)), "of": len(self.chunks),
+ "started": r["started"] is not None, "done": r["done"],
+ "quit_at": r["quit_at"]} for r in self.readers.values()}
+
+ def _maybe_finish(self):
+ if all(r["done"] for r in self.readers.values()):
+ self.flush()
+
+ def flush(self):
+ # only now does the text touch disk: every reader is finished
+ for r in self.readers.values():
+ state = {"draft": "(served)", "persona": r["persona"], "chunks": self.chunks,
+ "cursor": r["cursor"], "done": r["done"], "quit_at": r["quit_at"],
+ "started": r["started"] or time.time()}
+ (self.run_dir / r["name"] / "state.json").write_text(json.dumps(state, indent=2))
+ self.closed = True
+
+
+class Handler(BaseHTTPRequestHandler):
+ feed = None
+ server_ref = None
+
+ def log_message(self, *a): # quiet
+ pass
+
+ def _send(self, code, obj):
+ body = json.dumps(obj).encode()
+ self.send_response(code)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def _route(self, method):
+ parts = [p for p in self.path.split("?")[0].split("/") if p]
+ if len(parts) != 2:
+ return self._send(404, {"error": "not found"})
+ token, action = parts
+ body = {}
+ if method == "POST":
+ n = int(self.headers.get("Content-Length") or 0)
+ if n:
+ try:
+ body = json.loads(self.rfile.read(n) or b"{}")
+ except json.JSONDecodeError:
+ body = {}
+ f = self.feed
+ with f.lock:
+ if token == f.admin:
+ if action == "progress":
+ return self._send(200, f.progress())
+ if action == "close":
+ f.flush()
+ self._send(200, {"ok": True, "closed": True})
+ threading.Thread(target=self.server_ref.shutdown, daemon=True).start()
+ return
+ return self._send(404, {"error": "not found"})
+ r = f.readers.get(token)
+ if r is None:
+ return self._send(404, {"error": "not found"})
+ if action == "start" and method == "GET":
+ return self._send(200, f.start(r))
+ if action == "next" and method == "POST":
+ return self._send(200, f.next(r, body.get("log")))
+ if action == "quit" and method == "POST":
+ return self._send(200, f.quit(r, body.get("log")))
+ return self._send(404, {"error": "not found"})
+
+ def do_GET(self):
+ self._route("GET")
+
+ def do_POST(self):
+ self._route("POST")
+
+
+def cmd_serve(args):
+ names = [n.strip() for n in args.readers.split(",") if n.strip()]
+ titles = {}
+ for spec in (args.persona or []):
+ if "=" in spec:
+ k, v = spec.split("=", 1); titles[k.strip()] = v.strip()
+ feed = Feed(args.draft, args.run, names, titles, args.dwell)
+ httpd = ThreadingHTTPServer(("127.0.0.1", args.port), Handler)
+ Handler.feed = feed
+ Handler.server_ref = httpd
+ port = httpd.server_address[1]
+ base = f"http://127.0.0.1:{port}"
+ print(f"FEED serving {len(feed.chunks)} passages, {feed.words} words, readers: {', '.join(names)}")
+ for token, r in feed.readers.items():
+ print(f"reader {r['name']}: READER_FEED={base}/{token}")
+ print(f"admin: {base}/{feed.admin}")
+ print("Give each reader ONLY its own READER_FEED line. Nothing else about the piece.", flush=True)
+ if args.ready_file:
+ Path(args.ready_file).write_text(json.dumps(
+ {"base": base, "admin": f"{base}/{feed.admin}",
+ "readers": {r["name"]: f"{base}/{t}" for t, r in feed.readers.items()}}))
+
+ def watchdog():
+ while True:
+ time.sleep(5)
+ if feed.closed:
+ # every reader is done, but the last one may still be sending
+ # its final reaction: stay up until things go quiet
+ last = max([r["served_at"] or 0 for r in feed.readers.values()] + [0])
+ if time.time() - last > 90:
+ httpd.shutdown(); return
+ continue
+ anyone_started = any(r["started"] is not None for r in feed.readers.values())
+ if args.idle and anyone_started:
+ last = max(r["served_at"] or 0 for r in feed.readers.values())
+ if last and time.time() - last > args.idle:
+ with feed.lock:
+ feed.flush()
+ httpd.shutdown(); return
+ threading.Thread(target=watchdog, daemon=True).start()
+ try:
+ httpd.serve_forever()
+ finally:
+ if not feed.closed:
+ with feed.lock:
+ feed.flush()
+
+
+def _call(base, action, payload=None):
+ url = base.rstrip("/") + "/" + action
+ data = json.dumps(payload).encode() if payload is not None else None
+ req = urlrequest.Request(url, data=data, method="POST" if data is not None else "GET",
+ headers={"Content-Type": "application/json"})
+ try:
+ with urlrequest.urlopen(req, timeout=30) as resp:
+ return json.loads(resp.read())
+ except HTTPError as e:
+ sys.exit(f"feed error: {e.code} (wrong READER_FEED address or the feed has closed)")
+ except OSError as e:
+ sys.exit(f"feed unreachable at {base}: {e}. Is the feed still running?")
+
+
+def _print_served(res):
+ if "refused" in res:
+ sys.exit("REFUSED: " + res["refused"])
+ if "error" in res:
+ sys.exit(res["error"])
+ if "briefing" in res:
+ print(res["briefing"])
+ if "end" in res:
+ print(res["end"]); return
+ print(res["header"]); print(res["text"]); print(res["footer"])
+
+
+def served_base(args):
+ return getattr(args, "feed", None) or os.environ.get("READER_FEED")
+
+
+# ------------------------------------------------------------------ file mode
+
+def load(session):
+ d = Path(session)
+ state = json.loads((d / "state.json").read_text())
+ return d, state
+
+
+def save(d, state):
+ (d / "state.json").write_text(json.dumps(state, indent=2))
+
+
+def show(state, i):
+ chunks = state["chunks"]
+ print(chunk_header(i, chunks))
+ print(chunks[i])
+ print(chunk_footer())
+
+
+def cmd_start(args):
+ base = served_base(args)
+ if base:
+ return _print_served(_call(base, "start"))
+ if not args.draft or not args.session:
+ sys.exit("file mode needs: feed.py start <draft> --session <dir> (or set READER_FEED)")
+ d = Path(args.session); d.mkdir(parents=True, exist_ok=True)
+ text = Path(args.draft).read_text(encoding="utf-8")
+ chunks = chunk(text)
+ state = {"draft": str(args.draft), "persona": args.persona or "unnamed",
+ "chunks": chunks, "cursor": 0, "done": False, "started": time.time()}
+ save(d, state)
+ (d / "log.jsonl").write_text("")
+ print(f"SESSION {d} | persona: {state['persona']} | {len(chunks)} chunks, "
+ f"{len(text.split())} words total")
+ print(BRIEFING)
+ show(state, 0)
+
+
+def record(d, state, entry, quit_=False):
+ if len(entry.strip()) < MIN_LOG_CHARS:
+ sys.exit(f"REFUSED: log entry under {MIN_LOG_CHARS} chars. What happened "
+ "in you during that chunk? needle=?, expected what, got what?")
+ with (d / "log.jsonl").open("a") as f:
+ f.write(json.dumps({"chunk": state["cursor"] + 1, "quit": quit_,
+ "entry": entry.strip(), "t": time.time()}) + "\n")
+
+
+def _session_or_die(args):
+ if not args.session:
+ sys.exit("file mode needs the session dir: feed.py next <dir> --log ... (or set READER_FEED)")
+
+
+def cmd_next(args):
+ base = served_base(args)
+ if base:
+ return _print_served(_call(base, "next", {"log": args.log}))
+ _session_or_die(args)
+ d, state = load(args.session)
+ if state["done"]:
+ sys.exit("Session already finished.")
+ record(d, state, args.log)
+ state["cursor"] += 1
+ if state["cursor"] >= len(state["chunks"]):
+ state["done"] = True; save(d, state)
+ print("END OF PIECE. The reader finished. Add one final log line for the "
+ "ending itself via: feed.py quit <session> --log \"final: ...\"")
+ return
+ save(d, state)
+ show(state, state["cursor"])
+
+
+def cmd_quit(args):
+ base = served_base(args)
+ if base:
+ return _print_served(_call(base, "quit", {"log": args.log}))
+ _session_or_die(args)
+ d, state = load(args.session)
+ finished = state["done"] or state["cursor"] >= len(state["chunks"]) - 1
+ record(d, state, args.log, quit_=not finished)
+ state["done"] = True
+ state["quit_at"] = None if finished else state["cursor"] + 1
+ save(d, state)
+ if state["quit_at"]:
+ print(f"Reader stopped at chunk {state['quit_at']}/{len(state['chunks'])}. "
+ "That stop point is the primary finding.")
+ else:
+ print("Final reaction recorded. Session complete.")
+
+
+def cmd_transcript(args):
+ d, state = load(args.session)
+ print(f"READING TRANSCRIPT | persona: {state['persona']} | "
+ f"{'finished' if not state.get('quit_at') else 'QUIT at chunk %s' % state['quit_at']}"
+ f" of {len(state['chunks'])} chunks")
+ entries = [json.loads(l) for l in (d / "log.jsonl").read_text().splitlines() if l.strip()]
+ for i, e in enumerate(entries):
+ final = (i == len(entries) - 1 and state["done"] and not state.get("quit_at"))
+ mark = "QUIT " if e["quit"] else ("FINAL " if final else "")
+ print(f"[chunk {e['chunk']}] {mark}{e['entry']}")
+
+
+def cmd_status(args):
+ d, state = load(args.session)
+ print(f"persona={state['persona']} "
+ f"cursor={min(state['cursor'] + 1, len(state['chunks']))}/"
+ f"{len(state['chunks'])} done={state['done']} quit_at={state.get('quit_at')}")
+
+
+def cmd_progress(args):
+ print(json.dumps(_call(args.admin, "progress"), indent=2))
+
+
+def cmd_close(args):
+ print(json.dumps(_call(args.admin, "close")))
+
+
+def main():
+ p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ sub = p.add_subparsers(dest="cmd", required=True)
+ s = sub.add_parser("serve"); s.add_argument("draft"); s.add_argument("--run", required=True)
+ s.add_argument("--readers", required=True, help="comma-separated reader names")
+ s.add_argument("--persona", action="append", help="name=one-line persona (repeatable)")
+ s.add_argument("--port", type=int, default=0)
+ s.add_argument("--dwell", type=float, default=0.08,
+ help="seconds per word a reader must spend on a passage before advancing; 0 disables")
+ s.add_argument("--idle", type=float, default=1800, help="close after this many idle seconds")
+ s.add_argument("--ready-file", help="write addresses as JSON here for the orchestrator")
+ s = sub.add_parser("start"); s.add_argument("draft", nargs="?"); s.add_argument("--session"); s.add_argument("--persona"); s.add_argument("--feed")
+ for name in ("next", "quit"):
+ s = sub.add_parser(name); s.add_argument("session", nargs="?"); s.add_argument("--log", required=True); s.add_argument("--feed")
+ for name in ("transcript", "status"):
+ s = sub.add_parser(name); s.add_argument("session")
+ for name in ("progress", "close"):
+ s = sub.add_parser(name); s.add_argument("--admin", required=True)
+ args = p.parse_args()
+ {"serve": cmd_serve, "start": cmd_start, "next": cmd_next, "quit": cmd_quit,
+ "transcript": cmd_transcript, "status": cmd_status,
+ "progress": cmd_progress, "close": cmd_close}[args.cmd](args)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/first-reader/scripts/recall.py b/agent_skills/first-reader/scripts/recall.py
new file mode 100644
index 00000000..71ff9f7a
--- /dev/null
+++ b/agent_skills/first-reader/scripts/recall.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Build the recall quiz: what survived the reading, tested honestly.
+
+Humans keep gist, not sentences; verbatim memory collapses within seconds
+of continued reading. An agent with the draft in context has perfect
+verbatim memory, so asking it "what do you remember" is theater. The
+honest experiment: hand a FRESH agent only the reading transcript (the
+moment log a reader produced during the timed read) and quiz it. What made
+it into the log is what registered during reading; what the fresh agent
+can reconstruct from the log is the gist that would survive a commute.
+
+Usage: python3 recall.py <session-dir>
+Prints the transcript plus the quiz. Contains no draft text beyond what
+the reader chose to quote in their own log, which is exactly the point.
+"""
+import json
+import sys
+from pathlib import Path
+
+
+def main():
+ if len(sys.argv) != 2:
+ sys.exit(__doc__)
+ d = Path(sys.argv[1])
+ state = json.loads((d / "state.json").read_text())
+ print("You are answering for a reader who read a piece once, earlier today, "
+ "and no longer has it. Below is the moment-by-moment log they kept "
+ "while reading. You have nothing else. Answer only from this log; "
+ "if the log does not support an answer, say 'nothing survived'.")
+ print(f"\npersona: {state['persona']} | "
+ f"{'finished the piece' if not state.get('quit_at') else 'quit at chunk %s of %s' % (state['quit_at'], len(state['chunks']))}")
+ print("-" * 60)
+ for line in (d / "log.jsonl").read_text().splitlines():
+ e = json.loads(line)
+ print(f"[chunk {e['chunk']}] {'QUIT ' if e['quit'] else ''}{e['entry']}")
+ print("-" * 60)
+ print("""QUIZ (answer from the log alone):
+1. SAYBACK: retell the piece in one sentence, as you'd describe it to a
+ colleague. If you can't, say so; that is a finding, not a failure.
+2. POINTING: quote any exact words or phrases that stuck. Only what the
+ log actually preserved counts.
+3. PEAK: the single strongest moment of the read, and why.
+4. ENDING: how it ended and how that felt. 'I don't remember the ending'
+ is a valid and important answer.
+5. CENTER OF GRAVITY: where did the piece feel most alive? Is that the
+ same thing the piece claimed to be about?
+6. ONE ACTION: is there anything you would now do, check, or tell someone
+ because you read this?""")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/first-reader/scripts/room.py b/agent_skills/first-reader/scripts/room.py
new file mode 100644
index 00000000..337e8066
--- /dev/null
+++ b/agent_skills/first-reader/scripts/room.py
@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+"""Build the first-reader page: the draft with the reading still on it.
+
+Takes a run directory holding one or more feed.py sessions and emits a
+single self-contained HTML page: the draft passage by passage, each
+reader's margin notes with their needle, quit points rendered as a fold
+line, a needle strip up top, and lenses. It is a report: the author
+acts on it by talking to their agent, not by clicking.
+
+Usage:
+ python3 room.py <run-dir> [--out room.html] [--annotations room-annotations.json]
+
+<run-dir> layout: every subdirectory containing state.json + log.jsonl is
+a reader session. All sessions must come from the same draft.
+
+The page builds without annotations, using deterministic fallbacks:
+excerpts are trimmed from the raw logs, and the memory/trust lenses hide
+until the annotations file provides their phrase lists. The annotations
+format is documented in references/room.md; the reviewing agent writes it
+after the recall and report steps so the page carries curated excerpts, a
+plain-language verdict, flags, and the lens data.
+"""
+import argparse
+import html
+import json
+import re
+from pathlib import Path
+
+VERSION = "1.0.0"
+M1, M2 = "\ue000", "\ue001"
+P1, P2 = "\ue002", "\ue003"
+E1, E2 = "\ue004", "\ue005"
+N1, N2 = "\ue006", "\ue007"
+
+
+def esc(t):
+ return html.escape(t, quote=False)
+
+
+class Marker:
+ def __init__(self, mem, portable, ents):
+ self.mem = sorted(mem, key=len, reverse=True)
+ self.portable = portable
+ self.ents = sorted(ents, key=len, reverse=True)
+
+ def wrap(self, seg):
+ for ph in self.mem:
+ seg = seg.replace(esc(ph), M1 + esc(ph) + M2)
+ for ph in self.portable:
+ seg = seg.replace(esc(ph), P1 + esc(ph) + P2)
+ for ph in self.ents:
+ seg = re.sub(r"(?<![\w>-])(" + re.escape(ph) + r")(?![\w])", E1 + r"\1" + E2, seg)
+ seg = re.sub(r"(?<![\w-])([\w$][\w.,:%$-]*\d[\w.,:%$-]*)", N1 + r"\1" + N2, seg)
+ return seg
+
+ def mark(self, h):
+ parts = re.split(r"(<[^>]+>)", h)
+ out = "".join(p if p.startswith("<") else self.wrap(p) for p in parts)
+ return (out.replace(M1, '<mark class="mem">').replace(M2, "</mark>")
+ .replace(P1, '<span class="portable">').replace(P2, "</span>")
+ .replace(E1, '<span class="ent">').replace(E2, "</span>")
+ .replace(N1, '<span class="num">').replace(N2, "</span>"))
+
+
+def inline_md(t):
+ t = esc(t)
+ t = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r"\1", t)
+ t = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", t)
+ t = re.sub(r"`([^`]+)`", r"<code>\1</code>", t)
+ return t
+
+
+def first_sentence_wrap(phtml):
+ m = re.search(r"[.!?](\s|$)", phtml)
+ if not m:
+ return f'<span class="fs">{phtml}</span>'
+ i = m.end()
+ return f'<span class="fs">{phtml[:i]}</span>{phtml[i:]}'
+
+
+def md_block(text, marker):
+ out, lines, i = [], text.split("\n"), 0
+ while i < len(lines):
+ ln = lines[i]
+ if ln.startswith("```"):
+ buf = []
+ i += 1
+ while i < len(lines) and not lines[i].startswith("```"):
+ buf.append(lines[i]); i += 1
+ i += 1
+ # tabindex so a keyboard user can scroll a wide block
+ out.append('<pre class="code" tabindex="0">' + marker.mark(esc("\n".join(buf))) + "</pre>")
+ continue
+ if re.match(r"#{1,6}\s", ln):
+ # one level down: the page's own title is the only h1
+ lvl = min(len(ln) - len(ln.lstrip("#")) + 1, 4)
+ out.append(f"<h{lvl}>{marker.mark(inline_md(ln.lstrip('# ')))}</h{lvl}>")
+ i += 1; continue
+ if re.match(r"(\*|-|\d+\.)\s", ln):
+ items = []
+ while i < len(lines) and re.match(r"(\*|-|\d+\.)\s", lines[i]):
+ item = re.sub(r"^(\*|-|\d+\.)\s+", "", lines[i])
+ items.append("<li>" + first_sentence_wrap(marker.mark(inline_md(item))) + "</li>")
+ i += 1
+ out.append("<ul>" + "".join(items) + "</ul>")
+ continue
+ if ln.strip():
+ para = [ln]
+ i += 1
+ while i < len(lines) and lines[i].strip() and not re.match(r"(#{1,6}|\*|-|\d+\.|```)\s?", lines[i]):
+ para.append(lines[i]); i += 1
+ out.append("<p>" + first_sentence_wrap(marker.mark(inline_md(" ".join(para)))) + "</p>")
+ continue
+ i += 1
+ return "\n".join(out)
+
+
+def load_sessions(run_dir):
+ sessions = []
+ for d in sorted(run_dir.iterdir()):
+ if d.is_dir() and (d / "state.json").exists() and (d / "log.jsonl").exists():
+ state = json.loads((d / "state.json").read_text())
+ entries = [json.loads(l) for l in (d / "log.jsonl").read_text().splitlines() if l.strip()]
+ sessions.append({"dir": d.name, "state": state, "entries": entries})
+ if not sessions:
+ raise SystemExit(f"No sessions (state.json + log.jsonl) found under {run_dir}")
+ n = len(sessions[0]["state"]["chunks"])
+ for s in sessions:
+ if len(s["state"]["chunks"]) != n:
+ raise SystemExit("Sessions disagree on passage count; they must come from one draft.")
+ return sessions
+
+
+def parse_needle(entry):
+ m = re.search(r"needle\s*[=:]?\s*([+-]?\d)", entry)
+ if not m:
+ return 0
+ return max(-2, min(2, int(m.group(1))))
+
+
+def auto_excerpt(entry):
+ t = re.sub(r"^\s*needle\s*[=:]?\s*[+-]?\d[.,;:]?\s*", "", entry).strip()
+ parts = re.split(r"(?<=[.!?])\s+", t)
+ out = ""
+ for p in parts:
+ if out and len(out) + len(p) > 200:
+ break
+ out = (out + " " + p).strip()
+ if len(out) > 140:
+ break
+ return out[:240]
+
+
+def needle_map(session):
+ per = {}
+ for e in session["entries"]:
+ per[e["chunk"]] = parse_needle(e["entry"])
+ return per
+
+
+def prev_strip(prev_run):
+ """A dimmed strip of last run's needles so revision reads as progress."""
+ try:
+ psess = load_sessions(Path(prev_run))
+ except SystemExit:
+ return ""
+ pn = len(psess[0]["state"]["chunks"])
+ cells = []
+ for idx in range(1, pn + 1):
+ rows = []
+ for ps in psess:
+ v = needle_map(ps).get(idx)
+ rows.append(f'<i class="tr v{"x" if v is None else v}"></i>')
+ cells.append(f'<span class="cell" role="img" aria-label="last time, passage {idx}">{"".join(rows)}</span>')
+ return (f'<div class="scrublabel">last time ({pn} passages)</div>'
+ f'<div class="scrub prev" aria-label="how each reader felt last time">{"".join(cells)}</div>'
+ '<div class="scrublabel">this time</div>')
+
+
+def needle_chip(v):
+ cls = {2: "n2", 1: "n1", 0: "n0", -1: "nm1", -2: "nm2"}[v]
+ return f'<span class="chip {cls}">{"+" if v > 0 else ""}{v}</span>'
+
+
+def render_skim(skim):
+ """The skim gate's verdict: what a scanner thought this was, and whether they opened it."""
+ if not skim:
+ return ""
+ committed = skim.get("commits")
+ tag = "opened it" if committed else "moved on"
+ return (f'<div class="skim"><div class="flabel">the skimmer {tag}</div>'
+ f'<p>{esc(skim.get("said", ""))}</p></div>')
+
+
+def render_ask_hint(sessions):
+ names = " or ".join(f'"ask {s["initial"]} ..."' for s in sessions[:2])
+ return (f'<div class="askhint">These are people you can consult. In chat: {names}, '
+ f'"ask the skimmer what would have made them open it", or "ask everyone ...". '
+ f'Revise in your own editor, then "again" for a fresh read.</div>')
+
+
+def render_stats(sessions, n):
+ """The chips in the top bar: readers, finished, stopped early, passages, fixes."""
+ finished = sum(1 for s in sessions if not s["quit_at"])
+ quits = len(sessions) - finished
+ stats = [f'<span class="statchip"><b>{len(sessions)}</b> readers</span>',
+ f'<span class="statchip"><b>{finished}</b> finished</span>']
+ if quits:
+ stats.append(f'<span class="statchip" style="color:var(--nm2-ink)"><b>{quits}</b> stopped early</span>')
+ stats.append(f'<span class="statchip"><b>{n}</b> passages</span>')
+ stats_html = "".join(stats)
+
+ return stats_html
+
+
+def render_legend(sessions, chunk_html):
+ """The card that introduces the readers and the needle chips to a first-time author."""
+ count_word = {1: "One reader", 2: "Two readers", 3: "Three readers", 4: "Four readers"}.get(
+ len(sessions), f"{len(sessions)} readers")
+ legend_items = "".join(
+ f'<span class="litem"><span class="who w{s["key"]}">{esc(s["initial"])}</span>{esc(s["title"])}</span>'
+ for s in sessions)
+ any_skim = any('class="skimtag"' in c for c in chunk_html)
+ skim_item = ('<span class="litem"><span class="skimtag">skim</span>started skimming here</span>'
+ if any_skim else "")
+ legend_html = ('<div class="legend"><div class="lrow"><span class="flabel">about the margin notes</span> '
+ f'{count_word} met this piece one passage at a time, no peeking ahead, and wrote down each '
+ 'reaction as it happened. Those raw notes sit beside each passage.</div>'
+ f'<div class="lrow">{legend_items}</div>'
+ '<div class="lrow"><span class="flabel">each note starts with how it felt</span>'
+ '<span class="litem"><span class="chip n2">+2</span>leaning in</span>'
+ '<span class="litem"><span class="chip n0">0</span>neutral</span>'
+ '<span class="litem"><span class="chip nm2">-2</span>wanted out</span>'
+ f'{skim_item}</div></div>')
+
+ return legend_html
+
+
+def lens_controls(ann):
+ """Lens buttons for the data the annotations actually carry, and the label that names them."""
+ have_mem = bool(ann.get("memory_phrases"))
+ have_trust = bool(ann.get("portable_sentences") or ann.get("entities"))
+ views_label = "see it: as a skimmer" + (" · what stuck" if have_mem else "") + \
+ (" · trust signals" if have_trust else "") + " · replay the read"
+ lens_btns = ['<button class="btn" id="lensRead" aria-pressed="true" onclick="lens(\'read\')">reading</button>',
+ '<button class="btn" id="lensScan" aria-pressed="false" onclick="lens(\'scan\')">what a skimmer sees</button>']
+ if have_mem:
+ lens_btns.append('<button class="btn" id="lensMem" aria-pressed="false" onclick="lens(\'mem\')">what stuck</button>')
+ if have_trust:
+ lens_btns.append('<button class="btn" id="lensTrust" aria-pressed="false" onclick="lens(\'trust\')">trust</button>')
+
+ return lens_btns, views_label
+
+
+def build(run_dir, out_path, ann):
+ sessions = load_sessions(run_dir)
+ chunks = sessions[0]["state"]["chunks"]
+ n = len(chunks)
+ readers_meta = ann.get("readers", {})
+ used_initials = set()
+ for ix, s in enumerate(sessions):
+ meta = readers_meta.get(s["dir"], {})
+ persona = s["state"].get("persona") or s["dir"]
+ initial = meta.get("initial") or persona[:1].upper()
+ while initial in used_initials:
+ initial += "2"
+ used_initials.add(initial)
+ s["initial"] = initial
+ s["label"] = meta.get("label") or persona
+ s["title"] = meta.get("title") or persona
+ s["key"] = f"r{ix}"
+ s["quit_at"] = s["state"].get("quit_at")
+ per = {}
+ for e in s["entries"]:
+ c = e["chunk"]
+ exc = ann.get("excerpts", {}).get(s["dir"], {}).get(str(c)) or auto_excerpt(e["entry"])
+ skim = bool(re.search(r"\bskim", e["entry"], re.I)) and not \
+ re.search(r"(stop(ped)?|quit|no longer|slowed|without)[^.]{0,20}skimm", e["entry"], re.I)
+ per[c] = {"needle": parse_needle(e["entry"]),
+ "skim": skim,
+ "quit": e.get("quit", False), "text": exc}
+ s["per"] = per
+
+ marker = Marker(ann.get("memory_phrases", []), ann.get("portable_sentences", []),
+ ann.get("entities", []))
+ flags = {int(k): v for k, v in ann.get("flags", {}).items()}
+
+ chunk_html = []
+ for idx, ch in enumerate(chunks, 1):
+ body = md_block(ch, marker)
+ skim_attrs = "".join(f' data-skim-{s["key"]}="1"' for s in sessions if s["per"].get(idx, {}).get("skim"))
+ unseen_attrs = "".join(f' data-unseen-{s["key"]}="1"' for s in sessions
+ if s["quit_at"] and idx > s["quit_at"])
+ flag = f'<div class="flag">{esc(flags[idx])}</div>' if idx in flags else ""
+ notes = []
+ for s in sessions:
+ e = s["per"].get(idx)
+ if not e:
+ continue
+ final = (not s["quit_at"]) and idx == max(s["per"])
+ quit_here = s["quit_at"] == idx
+ tag = ('<span class="skimtag">skimmed</span>' if e["skim"] else "")
+ head = ('<span class="skimtag stop">stopped reading here</span>' if quit_here else tag)
+ notes.append(
+ f'<div class="note note-{s["key"]}{" final" if (final or quit_here) else ""}">'
+ f'<span class="who w{s["key"]}" title="{esc(s["title"])}">{esc(s["initial"])}</span>'
+ f'{needle_chip(e["needle"])}{head}<span class="ntext">{esc(e["text"])}</span></div>')
+ folds = "".join(
+ f'<div class="fold">{esc(s["initial"])} stopped here. They never saw anything below this line.</div>'
+ for s in sessions if s["quit_at"] == idx)
+ chunk_html.append(f"""
+ <section class="chunk" id="c{idx}" data-i="{idx}"{skim_attrs}{unseen_attrs}>
+ <div class="prose">{flag}<div class="cnum">passage {idx:02d} of {n}</div>{body}</div>
+ <div class="notes" role="group" aria-label="notes on passage {idx}">{''.join(notes)}</div>
+ </section>{folds}""")
+
+ cells = []
+ for idx in range(1, n + 1):
+ fl = f'<i class="fmark" title="{esc(flags[idx])}"></i>' if idx in flags else ""
+ rows, said = [], []
+ for s in sessions:
+ e = s["per"].get(idx)
+ v = "x" if e is None else e["needle"]
+ rows.append(f'<i class="tr t{s["key"]} v{v}"></i>')
+ said.append(f'{s["initial"]} ' + ("did not see it" if e is None else f'{"+" if e["needle"] > 0 else ""}{e["needle"]}'))
+ label = f'passage {idx}: ' + ", ".join(said) + (f' ({flags[idx]})' if idx in flags else "")
+ cells.append(f'<button class="cell" onclick="jump({idx})" aria-label="{esc(label)}">{"".join(rows)}{fl}</button>')
+
+ sel_btns = ['<button class="btn" id="selall" aria-pressed="true" onclick="sel(\'all\')">both</button>'
+ if len(sessions) > 1 else ""]
+ for s in sessions:
+ sel_btns.append(f'<button class="btn" id="sel{s["key"]}" aria-pressed="false" '
+ f'onclick="sel(\'{s["key"]}\')">{esc(s["label"])}</button>')
+ sel_css = "\n".join(
+ f'body.sel-{s["key"]} .note:not(.note-{s["key"]}) {{ display:none }}\n'
+ f'body.sel-{s["key"]} .chunk[data-skim-{s["key"]}="1"] .prose {{ opacity:.38 }}\n'
+ f'body.sel-{s["key"]} .chunk[data-unseen-{s["key"]}="1"] .prose {{ opacity:.12 }}\n'
+ f'body.sel-{s["key"]} .tr:not(.t{s["key"]}) {{ opacity:.15 }}'
+ for s in sessions)
+ palette = [("var(--n1)", "var(--on-n1)"), ("var(--ink-soft)", "#fff"),
+ ("var(--nm1)", "var(--on-nm1)"), ("var(--n2)", "var(--on-n2)")]
+ who_css = "\n".join(f'.w{s["key"]} {{ background:{palette[ix % len(palette)][0]}; color:{palette[ix % len(palette)][1]} }}'
+ for ix, s in enumerate(sessions))
+
+ lens_btns, views_label = lens_controls(ann)
+
+ skim_html = render_skim(ann.get("skim"))
+ ask_html = render_ask_hint(sessions)
+ stats_html = render_stats(sessions, n)
+
+ verdict_lead = ann.get("verdict_lead", "The readers are done. Their notes are in the margin.")
+ verdict_rest = ann.get("verdict_rest", "")
+ previous = ann.get("previous", {}).get("summary", "")
+ prev_html = f'<p class="prev"><b>Since last time:</b> {esc(previous)}</p>' if previous else ""
+ prev_run = ann.get("previous", {}).get("run")
+ prevscrub_html = prev_strip(prev_run) if prev_run and Path(prev_run).is_dir() else ""
+ opinions = ann.get("opinions", [])
+ opinions_html = ""
+ if opinions:
+ lis = "".join(f"<li>{esc(o)}</li>" for o in opinions)
+ opinions_html = (f'<details class="envelope"><summary>I\'d push back on {len(opinions)} '
+ f'spot{"s" if len(opinions) > 1 else ""}. Ask me and I\'ll make the case.</summary><ul>{lis}</ul>'
+ '<p style="font-size:.85rem;color:var(--mute)">These stay opinions; the rewrite stays yours.</p></details>')
+ reader_intro = " ".join(
+ f'<span class="who w{s["key"]}">{esc(s["initial"])}</span>{esc(s["title"])}.' for s in sessions)
+
+ legend_html = render_legend(sessions, chunk_html)
+
+ tpl = (Path(__file__).parent / "room_template.html").read_text(encoding="utf-8")
+ heading = next((ln.lstrip("# ").strip() for ln in chunks[0].splitlines()
+ if re.match(r"#{1,6}\s", ln)), None)
+ default_title = f"First read: {heading}" if heading else "First read of your draft"
+ page = (tpl.replace("@@TITLE@@", esc(ann.get("title", default_title)))
+ .replace("@@VERSION@@", VERSION)
+ .replace("@@STATS@@", stats_html)
+ .replace("@@VERDICT_LEAD@@", verdict_lead)
+ .replace("@@VERDICT_REST@@", verdict_rest)
+ .replace("@@PREVIOUS@@", prev_html)
+ .replace("@@PREVSCRUB@@", prevscrub_html)
+ .replace("@@N@@", str(n))
+ .replace("@@READER_INTRO@@", reader_intro)
+ .replace("@@LEGEND@@", legend_html)
+ .replace("@@SEL_BTNS@@", "".join(sel_btns))
+ .replace("@@LENS_BTNS@@", "".join(lens_btns))
+ .replace("@@VIEWS_LABEL@@", views_label)
+ .replace("@@SEL_CSS@@", sel_css)
+ .replace("@@WHO_CSS@@", who_css)
+ .replace("@@SCRUB@@", "".join(cells))
+ .replace("@@CHUNKS@@", "".join(chunk_html))
+ .replace("@@SKIM@@", skim_html)
+ .replace("@@ASKHINT@@", ask_html)
+ .replace("@@OPINIONS@@", opinions_html))
+ out_path.write_text(page, encoding="utf-8")
+ print(f"wrote {out_path} ({len(page)} bytes, {n} passages, {len(sessions)} readers)")
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__)
+ ap.add_argument("run_dir", type=Path)
+ ap.add_argument("--out", type=Path, default=None)
+ ap.add_argument("--annotations", type=Path, default=None)
+ a = ap.parse_args()
+ ann = {}
+ ann_path = a.annotations or (a.run_dir / "room-annotations.json")
+ if ann_path.exists():
+ ann = json.loads(ann_path.read_text())
+ build(a.run_dir, a.out or (a.run_dir / "room.html"), ann)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/first-reader/scripts/room_template.html b/agent_skills/first-reader/scripts/room_template.html
new file mode 100644
index 00000000..e125819e
--- /dev/null
+++ b/agent_skills/first-reader/scripts/room_template.html
@@ -0,0 +1,286 @@
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>@@TITLE@@</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500&display=swap">
+<style data-own>
+:root {
+ --canvas:#fafafa; --card:#ffffff; --well:#f2f2f2; --line:#ebebeb;
+ --ink:#171717; --prose:#262626; --body:#4d4d4d; --mute:#626262; --faint:#6e6e6e;
+ --ink-soft:#626262;
+ --link:#0070f3; --mem-bg:#d3e5ff;
+ --n2:#0070f3; --n1:#79a8f5; --n0:#d4d4d4; --n0-ink:#171717; --nm1:#f5a623; --nm2:#ee0000;
+ --on-n2:#ffffff; --on-n1:#171717; --on-nm1:#171717; --on-nm2:#ffffff;
+ --nm1-ink:#8a5200; --nm2-ink:#c40000;
+ --header-bg:rgba(250,250,250,.86); --mesh-o:.5;
+ --shadow-float:0 2px 2px rgba(0,0,0,.04), 0 8px 16px -4px rgba(0,0,0,.10);
+}
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
+ --canvas:#0a0a0a; --card:#111111; --well:#161616; --line:#262626;
+ --ink:#ededed; --prose:#d6d6d6; --body:#a1a1a1; --mute:#9a9a9a; --faint:#8a8a8a;
+ --link:#52a8ff; --mem-bg:#102a4c;
+ --n2:#3291ff; --n1:#2f6fce; --n0:#3a3a3a; --n0-ink:#ededed; --nm1:#d9921f; --nm2:#ff4d4d;
+ --on-n2:#0a0a0a; --on-n1:#ffffff; --on-nm1:#171717; --on-nm2:#171717;
+ --nm1-ink:#f0a83a; --nm2-ink:#ff6b6b;
+ --header-bg:rgba(10,10,10,.82); --mesh-o:.3;
+ --shadow-float:0 2px 2px rgba(0,0,0,.3), 0 8px 16px -4px rgba(0,0,0,.5);
+} }
+:root[data-theme="dark"] {
+ --canvas:#0a0a0a; --card:#111111; --well:#161616; --line:#262626;
+ --ink:#ededed; --prose:#d6d6d6; --body:#a1a1a1; --mute:#9a9a9a; --faint:#8a8a8a;
+ --link:#52a8ff; --mem-bg:#102a4c;
+ --n2:#3291ff; --n1:#2f6fce; --n0:#3a3a3a; --n0-ink:#ededed; --nm1:#d9921f; --nm2:#ff4d4d;
+ --on-n2:#0a0a0a; --on-n1:#ffffff; --on-nm1:#171717; --on-nm2:#171717;
+ --nm1-ink:#f0a83a; --nm2-ink:#ff6b6b;
+ --header-bg:rgba(10,10,10,.82); --mesh-o:.3;
+ --shadow-float:0 2px 2px rgba(0,0,0,.3), 0 8px 16px -4px rgba(0,0,0,.5);
+}
+* { box-sizing:border-box }
+html { scroll-behavior:smooth; background:var(--canvas); }
+@media (prefers-reduced-motion: reduce) { html { scroll-behavior:auto } }
+body { background:var(--canvas); color:var(--ink); margin:0;
+ font-family:Geist, Inter, Arial, sans-serif; line-height:1.6;
+ -webkit-font-smoothing:antialiased; }
+
+/* ---------- top bar ---------- */
+header { position:sticky; top:0; z-index:9; background:var(--header-bg);
+ backdrop-filter:blur(10px); border-bottom:1px solid var(--line);
+ padding:10px 28px 12px; overflow:hidden; }
+.brief { border-bottom:1px solid var(--line); padding:16px 28px 20px; }
+header::before { content:""; position:absolute; top:-140px; right:-60px;
+ width:520px; height:340px; pointer-events:none; opacity:var(--mesh-o);
+ background:
+ radial-gradient(200px 160px at 20% 60%, rgba(80,227,194,.35), transparent 70%),
+ radial-gradient(240px 180px at 55% 30%, rgba(0,112,243,.30), transparent 70%),
+ radial-gradient(220px 170px at 80% 65%, rgba(121,40,202,.28), transparent 70%),
+ radial-gradient(180px 150px at 95% 30%, rgba(255,0,128,.22), transparent 70%),
+ radial-gradient(160px 140px at 40% 85%, rgba(249,203,40,.20), transparent 70%); }
+.hrow { max-width:1080px; margin:0 auto; position:relative; }
+.topline { display:flex; align-items:center; justify-content:space-between; gap:16px; flex-wrap:wrap; }
+h1.room { font-size:20px; font-weight:600; letter-spacing:-0.4px; margin:0; color:var(--ink); }
+.chips { display:flex; gap:6px; flex-wrap:wrap; }
+.statchip { font-family:"Geist Mono", "IBM Plex Mono", monospace; font-size:11px;
+ color:var(--body); background:var(--card); border:1px solid var(--line);
+ border-radius:6px; padding:3px 8px; white-space:nowrap; }
+.statchip b { color:var(--ink); font-weight:500; }
+.verdict { font-size:14px; color:var(--body); margin:10px 0 0; max-width:74ch; line-height:1.55; }
+.verdict b { color:var(--ink); font-weight:600; }
+.prev { font-size:13px; color:var(--body); margin:8px 0 0; max-width:74ch; line-height:1.55;
+ border-left:2px solid var(--n2); padding-left:10px; }
+.prev b { color:var(--ink); font-weight:500; }
+
+/* ---------- skim verdict, how to consult ---------- */
+.verdict:first-child { margin-top:0 }
+.flabel { font-family:"Geist Mono", monospace; font-size:11px; font-weight:500;
+ letter-spacing:.04em; text-transform:uppercase; color:var(--mute); margin-bottom:2px; }
+.skim { margin:14px 0 0; max-width:74ch; border:1px solid var(--line); border-radius:8px;
+ background:var(--card); padding:10px 14px; }
+.skim p { margin:4px 0 0; font-size:14px; color:var(--body); line-height:1.55; }
+.askhint { margin:12px 0 0; max-width:74ch; font-size:13px; color:var(--body); line-height:1.55; }
+
+/* ---------- buttons ---------- */
+.btn { border:1px solid var(--line); background:var(--card); color:var(--ink);
+ padding:4px 10px; border-radius:6px; cursor:pointer; font:inherit;
+ font-size:13px; font-weight:500; line-height:20px;
+ transition:border-color .12s, background .12s; }
+.btn:hover { border-color:var(--faint); }
+.btn[aria-pressed="true"] { background:var(--ink); color:var(--canvas); border-color:var(--ink); }
+.btn:focus-visible { outline:2px solid var(--link); outline-offset:2px; }
+
+/* ---------- scrubber ---------- */
+.scrub { display:flex; gap:4px; margin:10px 0 2px; max-width:1080px; }
+.cell { flex:1; height:30px; position:relative; border:1px solid var(--line);
+ background:var(--card); border-radius:6px; cursor:pointer; padding:0;
+ display:flex; flex-direction:column; justify-content:center; gap:3px;
+ align-items:stretch; transition:border-color .12s; }
+.cell:hover { border-color:var(--faint); }
+.cell:focus-visible { outline:2px solid var(--link); }
+.tr { height:4px; border-radius:2px; margin:0 18%; }
+.v2 { background:var(--n2) } .v1 { background:var(--n1) } .v0 { background:var(--n0) }
+.v-1 { background:var(--nm1) } .v-2 { background:var(--nm2) } .vx { background:var(--line) }
+.fmark { position:absolute; top:-4px; left:50%; width:6px; height:6px; border-radius:50%;
+ background:var(--link); transform:translateX(-50%); }
+
+.scrublabel { font-family:"Geist Mono", monospace; font-size:10px; font-weight:500;
+ letter-spacing:.06em; text-transform:uppercase; color:var(--faint); margin:10px 0 -6px; }
+.scrub.prev { opacity:.55 }
+.scrub.prev .cell { height:22px; cursor:default }
+.views { margin-top:12px; }
+.skey { display:flex; gap:14px; align-items:center; margin-top:8px;
+ font-family:"Geist Mono", monospace; font-size:10px; letter-spacing:.04em;
+ text-transform:uppercase; color:var(--faint); }
+.skey i { display:inline-block; width:14px; height:4px; border-radius:2px; margin-right:5px; vertical-align:middle; }
+
+
+.made { font-family:"Geist Mono", monospace; font-size:10px; letter-spacing:.06em;
+ text-transform:uppercase; color:var(--faint); margin-top:28px; }
+.views summary { list-style:none; cursor:pointer; color:var(--mute);
+ font-family:"Geist Mono", monospace; font-size:11px; font-weight:500;
+ letter-spacing:.04em; text-transform:uppercase; display:inline-block; }
+.views summary::-webkit-details-marker { display:none }
+.views summary:hover { color:var(--body); }
+.controls { display:flex; flex-wrap:wrap; gap:14px; align-items:center; margin-top:10px; }
+.grp { display:flex; gap:6px; align-items:center; flex-wrap:wrap; }
+.grp label { color:var(--mute); font-family:"Geist Mono", monospace;
+ letter-spacing:.04em; text-transform:uppercase; font-size:10px; margin-right:4px; }
+
+/* ---------- manuscript ---------- */
+main { max-width:1080px; margin:0 auto; padding:40px 28px 140px; }
+.legend { border:1px solid var(--line); border-radius:8px; background:var(--card);
+ padding:12px 16px; margin:0 0 24px; font-size:13px; color:var(--body);
+ display:flex; flex-direction:column; gap:8px; max-width:74ch; }
+.legend .lrow { display:flex; flex-wrap:wrap; gap:6px 14px; align-items:center; line-height:1.5; }
+.legend .flabel { margin:0; flex:none; }
+.litem { display:inline-flex; align-items:center; gap:6px; }
+.litem .who, .litem .chip, .litem .skimtag { flex:none }
+.chunk { display:grid; grid-template-columns:minmax(0,64ch) 1fr; gap:44px;
+ padding:28px 0 16px; border-bottom:1px solid var(--line); }
+.fold { font-family:"Geist Mono", monospace; color:var(--nm2-ink);
+ border-top:1px dashed var(--nm2); padding:12px 0 4px; font-size:13px; }
+.cnum { font-family:"Geist Mono", monospace; font-size:10px; font-weight:500;
+ letter-spacing:.06em; text-transform:uppercase; color:var(--faint); margin-bottom:12px;
+ display:flex; align-items:center; gap:12px; }
+
+.flag { font-family:"Geist Mono", monospace; color:var(--link); font-size:11px;
+ font-weight:500; letter-spacing:.04em; text-transform:uppercase; margin-bottom:4px; }
+.prose { color:var(--prose); }
+.prose p, .prose li { font-size:15px; line-height:1.65; }
+.prose h2,.prose h3,.prose h4 { font-weight:600; line-height:1.25;
+ text-wrap:balance; color:var(--ink); }
+.prose h2 { font-size:28px; line-height:1.2; letter-spacing:-1.1px; }
+.prose h3 { font-size:20px; letter-spacing:-0.4px; }
+.prose h4 { font-size:16px; letter-spacing:-0.2px; }
+.prose a { color:var(--link); text-decoration:none; }
+.prose a:hover { text-decoration:underline; }
+.code { background:var(--card); border:1px solid var(--line); border-radius:8px;
+ padding:14px 16px; overflow-x:auto; font-family:"Geist Mono", monospace;
+ font-size:12.5px; line-height:1.55; color:var(--body); }
+p code, li code { font-family:"Geist Mono", monospace; font-size:.85em;
+ background:var(--well); border:1px solid var(--line); padding:1px 5px; border-radius:4px; }
+mark.mem { background:transparent; color:inherit; }
+
+/* ---------- edits applied after the read ---------- */
+
+/* ---------- margin notes ---------- */
+.notes { display:flex; flex-direction:column; gap:8px; padding-top:36px; }
+.note { font-family:"Geist Mono", monospace; font-size:11.5px; line-height:1.55;
+ color:var(--body); padding:9px 11px; background:var(--card); border-radius:8px;
+ border:1px solid var(--line); }
+.note.final { border-color:var(--faint); }
+.who { display:inline-block; width:15px; height:15px; border-radius:50%; text-align:center;
+ line-height:15px; font-size:9px; font-weight:500; margin-right:6px;
+ font-family:Geist, sans-serif; }
+@@WHO_CSS@@
+.chip { display:inline-block; font-size:10px; padding:0 5px; border-radius:4px;
+ color:#fff; margin-right:6px; font-weight:500; font-family:Geist, sans-serif; }
+.chip.n2 { background:var(--n2); color:var(--on-n2) } .chip.n1 { background:var(--n1); color:var(--on-n1) }
+.chip.n0 { background:var(--n0); color:var(--n0-ink) }
+.chip.nm1 { background:var(--nm1); color:var(--on-nm1) } .chip.nm2 { background:var(--nm2); color:var(--on-nm2) }
+.skimtag { font-size:9px; letter-spacing:.08em; text-transform:uppercase;
+ color:var(--nm1-ink); margin-right:6px; }
+.skimtag.stop { color:var(--nm2-ink) }
+
+/* ---------- envelope / footer ---------- */
+.envelope { margin-top:40px; border:1px solid var(--line); border-radius:8px;
+ padding:16px 20px; background:var(--card); max-width:64ch; }
+.envelope summary { cursor:pointer; font-size:15px; font-weight:500; color:var(--ink); }
+.envelope li { font-size:14px; color:var(--body); }
+.howto { max-width:64ch; margin:32px 0 0; font-size:13px; color:var(--body); }
+.howto summary { list-style:none; cursor:pointer; font-family:"Geist Mono", monospace;
+ font-size:11px; font-weight:500; letter-spacing:.04em; text-transform:uppercase;
+ color:var(--mute); }
+.howto summary::-webkit-details-marker { display:none }
+.howto summary:hover { color:var(--body) }
+.howto p { margin:.6em 0; line-height:1.6; }
+
+/* ---------- persona / lens states ---------- */
+@@SEL_CSS@@
+body.lens-scan .prose p, body.lens-scan .prose li { color:var(--faint); opacity:.4 }
+body.lens-scan .prose .fs, body.lens-scan .prose h2, body.lens-scan .prose h3,
+body.lens-scan .prose h4, body.lens-scan .prose strong,
+body.lens-scan .prose .num { color:var(--ink); opacity:1 }
+body.lens-scan .code { opacity:.3 } body.lens-scan .code .num { opacity:1; color:var(--ink) }
+body.lens-scan .notes { opacity:.25 }
+body.lens-mem .prose :is(p,li,h2,h3,h4,.code) { color:var(--faint); opacity:.3 }
+body.lens-mem .prose mark.mem { background:var(--mem-bg); color:var(--ink); opacity:1;
+ padding:0 3px; border-radius:3px; }
+body.lens-mem .prose :is(p,li,h2,h3,h4):has(mark.mem) { opacity:.8 }
+body.lens-mem .notes { opacity:.25 }
+body.lens-trust .prose .num, body.lens-trust .prose .ent {
+ border-bottom:2px solid var(--link); font-weight:600; }
+body.lens-trust .prose .portable { opacity:.4; text-decoration:line-through;
+ text-decoration-color:var(--nm1); text-decoration-thickness:1px; }
+body.replay .chunk.future { opacity:.1 }
+body.replay .chunk.now { opacity:1 }
+@media (max-width:880px) { .chunk { grid-template-columns:minmax(0,1fr); gap:12px } .notes { padding-top:6px }
+ header { position:static } }
+</style>
+<header>
+ <div class="hrow">
+ <div class="topline">
+ <h1 class="room">@@TITLE@@</h1>
+ <div class="chips">@@STATS@@</div>
+ </div>
+ @@PREVSCRUB@@
+ <div class="scrub" role="group" title="each block is one stretch of the piece; blue means readers leaned in, amber and red mean they drifted; a dot marks a moment worth clicking" aria-label="how each reader felt, stretch by stretch">@@SCRUB@@</div>
+ <div class="skey"><span><i class="v2"></i>leaning in</span><span><i class="v-1"></i>drifting</span><span><i class="v-2"></i>gone</span><span>· click a block to jump there</span></div>
+ </div>
+</header>
+<section class="brief" aria-label="Verdict and findings">
+ <div class="hrow">
+ <p class="verdict">@@VERDICT_LEAD@@ @@VERDICT_REST@@</p>
+ @@PREVIOUS@@
+ @@SKIM@@
+ @@ASKHINT@@
+ <details class="views"><summary>@@VIEWS_LABEL@@ ▾</summary>
+ <div class="controls">
+ <div class="grp"><label>readers</label>@@SEL_BTNS@@</div>
+ <div class="grp"><label>lens</label>@@LENS_BTNS@@</div>
+ <div class="grp"><button class="btn" id="playBtn" aria-pressed="false" onclick="replay()">replay the read</button></div>
+ </div>
+ </details>
+ </div>
+</section>
+<main>
+@@LEGEND@@
+@@CHUNKS@@
+@@OPINIONS@@
+<details class="howto"><summary>how this page was made ▾</summary>
+ <p>AI readers with different lives got this piece the way a person would: one passage at a time, no peeking ahead, free to quit whenever. A passage is a paragraph-sized cut, roughly 85 words; this piece became @@N@@ of them, and a script refused to show each reader the next passage until they wrote down what just happened in them.</p>
+ <p>The readers: @@READER_INTRO@@ Their real notes sit beside each passage with the needle they logged: +2 leaning in, -2 done. A dashed line means a reader stopped and never saw the rest. Afterward, a separate agent was quizzed with the piece taken away, holding only the reading notes; the "what stuck" lens shows what survived. None of this is a score. It's what happened to the readers, written down as it happened.</p>
+</details>
+<div class="made">first-reader @@VERSION@@ · readers before you publish</div>
+</main>
+<script data-own>
+if(!document.documentElement.lang)document.documentElement.lang='en';
+function sel(k){
+ document.body.className=document.body.className.replace(/\bsel-\S+/g,'').trim();
+ if(k!=='all')document.body.classList.add('sel-'+k);
+ document.querySelectorAll('[id^="sel"]').forEach(b=>b.setAttribute('aria-pressed',
+ String(b.id==='sel'+k||(k==='all'&&b.id==='selall'))));
+}
+function lens(m){
+ document.body.classList.remove('lens-scan','lens-mem','lens-trust');
+ if(m!=='read')document.body.classList.add('lens-'+m);
+ const map={read:'lensRead',scan:'lensScan',mem:'lensMem',trust:'lensTrust'};
+ Object.entries(map).forEach(([kk,id])=>{const b=document.getElementById(id);
+ if(b)b.setAttribute('aria-pressed',String(kk===m));});
+}
+function jump(i){document.getElementById('c'+i).scrollIntoView({block:'start'});}
+let timer=null;
+function replay(){
+ const btn=document.getElementById('playBtn');
+ if(timer){clearInterval(timer);timer=null;document.body.classList.remove('replay');
+ document.querySelectorAll('.chunk').forEach(c=>c.classList.remove('now','future'));
+ btn.setAttribute('aria-pressed','false');btn.textContent='replay the read';return;}
+ document.body.classList.add('replay');btn.setAttribute('aria-pressed','true');btn.textContent='stop replay';
+ const cs=[...document.querySelectorAll('.chunk')];cs.forEach(c=>c.classList.add('future'));
+ let i=0;
+ const step=()=>{if(i>0)cs[i-1].classList.remove('now');
+ if(i>=cs.length){clearInterval(timer);timer=null;document.body.classList.remove('replay');
+ cs.forEach(c=>c.classList.remove('future','now'));
+ btn.setAttribute('aria-pressed','false');btn.textContent='replay the read';return;}
+ cs[i].classList.remove('future');cs[i].classList.add('now');
+ cs[i].scrollIntoView({block:'center'});i++;};
+ step();timer=setInterval(step,2600);}
+</script>
diff --git a/agent_skills/first-reader/scripts/signals.py b/agent_skills/first-reader/scripts/signals.py
new file mode 100644
index 00000000..ecd5ca73
--- /dev/null
+++ b/agent_skills/first-reader/scripts/signals.py
@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Measure the trust signals a draft pays, and what they cost the writer.
+
+Readers judge credibility by costly signals: details that could be checked,
+numbers that could be wrong, commitments that expose the writer. Free
+signals (generic praise, safe hedges, uniform confidence) are worthless
+precisely because they cost nothing. The accurate human detectors of AI
+text (Russell et al. 2025) key on this layer, not on banned words.
+
+These are measurements, not verdicts. A poem scores zero specifics and is
+not worse for it; a launch post scoring zero specifics is a finding. The
+skill decides what a number means for this genre; this script only counts.
+
+Usage: python3 signals.py <draft> [--json]
+"""
+import json
+import re
+import statistics
+import sys
+from pathlib import Path
+
+HEDGES = r"\b(might|may|could|perhaps|possibly|arguably|potentially|seems?|somewhat|likely|probably|tend(?:s)? to|in some cases|to some extent|it could be argued)\b"
+CERTAINTY = r"\b(definitely|certainly|always|never|must|undeniably|clearly|obviously|of course|without a doubt)\b"
+FIRST_PERSON = r"\b(I|I'm|I've|I'd|my|me|we|our)\b"
+SECOND_PERSON = r"\b(you|your|you're|you've)\b"
+ADMISSION = r"\b(I was wrong|we were wrong|I don't know|I'm not sure|didn't work|failed|my mistake|I missed|we missed|turned out I|I had to throw|embarrassing|uncomfortable|I still can't|was a fantasy|took us .{0,20} to notice|we broke|our fault)\b"
+
+
+def clean(text):
+ text = re.sub(r"```.*?```", " ", text, flags=re.S)
+ return re.sub(r"^#{1,6}\s.*$", " ", text, flags=re.M)
+
+
+def sentences(text):
+ parts = re.split(r"(?<=[.!?])\s+", clean(text).replace("\n", " "))
+ return [s.strip() for s in parts if len(s.split()) >= 3]
+
+
+def proper_nouns(text):
+ # capitalized tokens not at sentence start: rough named-entity proxy
+ hits = re.findall(r"(?<![.!?]\s)(?<!^)(?<!\n)\b([A-Z][a-zA-Z]+(?:\s[A-Z][a-zA-Z]+)*)\b", text)
+ stop = {"I", "The", "A", "An", "But", "And", "It", "This", "That", "If", "So"}
+ return [h for h in hits if h not in stop]
+
+
+def main():
+ argv = sys.argv[1:]
+ as_json = "--json" in argv
+ argv = [a for a in argv if a != "--json"]
+ if len(argv) != 1:
+ sys.exit(__doc__)
+ text = Path(argv[0]).read_text(encoding="utf-8")
+ sents = sentences(text)
+ if not sents:
+ sys.exit("No prose sentences found.")
+ lens = [len(s.split()) for s in sents]
+ words = sum(lens)
+ per100 = lambda n: round(n * 100 / max(words, 1), 2)
+
+ # any token carrying a digit counts as a checkable specific: 4,100, $3M,
+ # 90-second, v2.3, 48MB, 2:47am all expose the writer to being wrong
+ numbers = re.findall(r"\b[\w$][\w.,:%$-]*\d[\w.,:%$-]*", clean(text))
+ quotes = re.findall(r"[\"“]([^\"”]{10,200})[\"”]", text)
+ hedged = [s for s in sents if re.search(HEDGES, s, re.I)]
+ certain = [s for s in sents if re.search(CERTAINTY, s, re.I)]
+ admissions = [s for s in sents if re.search(ADMISSION, s, re.I)]
+ nouns = proper_nouns(clean(text))
+ tokens = re.findall(r"[a-zA-Z']+", text.lower())
+ ttr = round(len(set(tokens)) / max(len(tokens), 1), 3)
+
+ # portable sentences: no digit, no named entity, no first person: could
+ # move unchanged into any other document on the topic
+ portable = [s for s in sents
+ if not re.search(r"\d", s)
+ and not re.search(FIRST_PERSON, s)
+ and not any(n in s for n in set(nouns))]
+
+ # epistemic temperature: share of sentences carrying ANY marker of how
+ # sure the writer is; near-zero variance in commitment is the machine tell
+ marked = len(set(hedged) | set(certain))
+
+ result = {
+ "words": words, "sentences": len(sents),
+ "sentence_len": {"mean": round(statistics.mean(lens), 1),
+ "sd": round(statistics.pstdev(lens), 1),
+ "burstiness": round(statistics.pstdev(lens) / max(statistics.mean(lens), 1), 2),
+ "max": max(lens), "min": min(lens)},
+ "costly": {
+ "numbers": {"count": len(numbers), "per100w": per100(len(numbers)), "sample": numbers[:10]},
+ "named_entities": {"count": len(nouns), "per100w": per100(len(nouns)), "sample": list(dict.fromkeys(nouns))[:10]},
+ "direct_quotes": len(quotes),
+ "admissions_against_interest": {"count": len(admissions), "sample": admissions[:3]},
+ "first_person_sentences": sum(1 for s in sents if re.search(FIRST_PERSON, s)),
+ },
+ "free": {
+ "hedged_sentences": {"count": len(hedged), "share": round(len(hedged) / len(sents), 2), "sample": hedged[:3]},
+ "certainty_sentences": {"count": len(certain), "share": round(len(certain) / len(sents), 2)},
+ "epistemically_marked_share": round(marked / len(sents), 2),
+ },
+ "portable_sentences": {"count": len(portable), "share": round(len(portable) / len(sents), 2),
+ "sample": portable[:5]},
+ "type_token_ratio": ttr,
+ }
+ if as_json:
+ print(json.dumps(result, indent=2))
+ return
+ print("TRUST SIGNAL MEASUREMENTS (counts, not verdicts; genre decides meaning)")
+ print(json.dumps(result, indent=2))
+ print("\nReading notes: costly signals expose the writer and buy trust; "
+ "portable sentences fit any document and buy nothing. A piece where "
+ "most sentences are portable and unmarked is committing to nothing.")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/agent_skills/first-reader/scripts/skim.py b/agent_skills/first-reader/scripts/skim.py
new file mode 100644
index 00000000..3bcfab25
--- /dev/null
+++ b/agent_skills/first-reader/scripts/skim.py
@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Produce the scanner's view of a draft: what a skimming reader actually
+fixates on, and nothing else.
+
+Eyetracking work (Nielsen Norman Group) shows scanners fixate on headings,
+the first words of lines and paragraphs, bold spans, numbers, and links,
+and skip nearly everything else. This prints exactly that view so a fresh
+reader agent can answer the only question a scanner answers: what is this,
+and do I commit? Feeding the full text would break the experiment, so this
+script deliberately truncates.
+
+Usage: python3 skim.py <draft.md|draft.txt>
+"""
+import re
+import sys
+from pathlib import Path
+
+WPM = 238 # average adult silent reading speed (Brysbaert 2019 meta-analysis)
+MOBILE_CHARS_PER_LINE = 38
+MOBILE_LINES_PER_SCREEN = 14
+FIRST_WORDS = 9
+
+
+def paragraphs(text):
+ return [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+
+
+def first_sentence(p):
+ m = re.match(r".+?[.!?](?=\s|$)", p, re.S)
+ return (m.group(0) if m else p).replace("\n", " ")
+
+
+def first_words(p, n=FIRST_WORDS):
+ words = p.replace("\n", " ").split()
+ if len(words) <= n:
+ return " ".join(words)
+ return " ".join(words[:n]) + " ..."
+
+
+def main():
+ if len(sys.argv) != 2:
+ sys.exit(__doc__)
+ text = Path(sys.argv[1]).read_text(encoding="utf-8")
+ paras = paragraphs(text)
+ words = len(text.split())
+ bold = re.findall(r"\*\*(.+?)\*\*|__(.+?)__", text)
+ bold = [a or b for a, b in bold]
+ links = re.findall(r"\[([^\]]+)\]\(", text)
+ numbers = re.findall(
+ r"(?<![\w./-])(?:\$[\d,.]+[kKmMbB]?|\d+(?:[.,]\d+)*%?|\d{4})(?![\w/-])", text
+ )
+ screens = max(1, round(len(text) / (MOBILE_CHARS_PER_LINE * MOBILE_LINES_PER_SCREEN)))
+
+ print("SCANNER VIEW (what a skimming reader fixates on; the full text is withheld)")
+ print(f"stats: {words} words | ~{max(1, round(words / WPM))} min full read | ~{screens} phone screens")
+ print(f"fixation tokens: numbers={numbers[:20] if numbers else 'NONE'}")
+ if bold:
+ print(f"bold spans: {[b[:60] for b in bold[:12]]}")
+ if links:
+ print(f"link texts: {links[:12]}")
+ print("-" * 60)
+ body_count = 0
+ for p in paras:
+ if re.match(r"#{1,6}\s", p):
+ print(p.splitlines()[0])
+ continue
+ if p.startswith(("- ", "* ", "1.", "> ")):
+ for line in p.splitlines()[:6]:
+ print(" " + first_words(line.lstrip("->*1234567890. ")))
+ continue
+ body_count += 1
+ if body_count <= 2:
+ # A scanner does genuinely read the opening lines in full.
+ print(first_sentence(p))
+ else:
+ print(first_words(p))
+ print("-" * 60)
+ print(
+ "Question for the reader: from this view alone, say (1) what you think "
+ "this piece is and what it will argue, (2) whether your cast persona "
+ "commits to a full read or moves on, and (3) the single element above "
+ "that decided it."
+ )
+
+
+if __name__ == "__main__":
+ main()