@atelic-action/artifact 1.0.0 → 1.1.0

package/README.md

@@ -25,9 +25,9 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `ratingCell` | A star rating table cell for a writeup table, sorted by its figure | `/writeup` |
 | `WriteupBlock`, `WriteupTopic`, `WriteupPart`, `WriteupSheet`, `WriteupSummary`, `WriteupSummaryRow`, `WriteupMarkets`, `WriteupRented`, `WriteupMark`, `WriteupCell`, `WriteupTone`, and the rest of the `Writeup*` types | The shapes a writeup's content is written in | none |
 | `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document (the first two are re exported from ui) | none |
-| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table, each section in three beats, the plan in order | `/read` |
-| `readLabels`, `ReadLabels` | The fixed words the read sets (the gist table's columns, the three beats, the plan's heading), each overridable through `labels` | `/read` |
-| `ReadTier`, `ReadSection`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadSource`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in | none |
+| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table; each section read top to bottom as where we looked (the tools, linked, at the top), what it showed (a short paragraph or two, a compact table of facts, lists of examples under their own headings, and any proof pictures), why (one sentence on a tinted panel), today and after (a two column table), and what we recommend (a checklist); then the plan in order. A beat with no data is left out, heading and all | `/read` |
+| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Where We Looked, What It Showed, Why, Today, After, What We Recommend, the plan's heading), each overridable through `labels` | `/read` |
+| `ReadTier`, `ReadSection`, `ReadTool`, `ReadFact`, `ReadExamples`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in, all plain data so a routine can write a read as JSON. A section's `tools` were its `sources` in 1.0.0; `sources` is still read, and rendered at the top as tools, and `ReadSource` names the same shape as `ReadTool` | none |
 | `Report`, `ReportProps` | The monthly page: the four questions, the seven grades now and before, the sign off, on one letter sheet | `/report` |
 | `ReportLead`, `ReportLeads`, `ReportGradeRow` | The shapes a monthly page's content is written in | none |
 | `Note`, `NoteProps` | The first touch set as a page: the opener, two lanes of findings, where the work would start, the close | `/notes` |
@@ -89,7 +89,7 @@ No environment variables required. Visit [http://localhost:5173](http://localhos
 
 ## Building a Client Artifact
 
-A business's artifacts live in one folder of `atelic-action/writeups`, named by the business's short name and served at `<short>.atelic.me` as its own Vercel project with the folder as its root directory, one path per artifact. That host is the business's one address with the practice: the website build, when one is previewed, sits on it at `/proto`, proxied from its own project ([DEPLOY.md](DEPLOY.md), The Website Build Under /proto). Cut it from this one with `git subtree add --prefix=<short> https://github.com/atelic-action/artifact.git main`, run in `writeups`. A cut is a site, not the package, so it then takes the package from npm instead of carrying its source: delete `src/documents/` and `tst/documents/`, give `package.json` the folder's own name and drop the package's fields (`version`, `files`, `exports`, `sideEffects`, `publishConfig`, `peerDependencies`), and run `bun add @atelic-action/artifact`. The routes and content already import the documents by the package's name, so nothing else changes. Nothing is pulled forward from here afterward: a document reaches the folder with `bun update @atelic-action/artifact`, and everything else with logic in it is `@atelic-action/ui`'s and arrives with `bun update @atelic-action/ui` ([CLAUDE.md](CLAUDE.md), What a Cut Takes From Here). Delete the artifacts the engagement does not need (the route, the content module, and the prerender entry), then touch four surfaces:
+A business's artifacts live in one folder of `atelic-action/writeups`, named by the business's short name and served at `<short>.atelic.me` as its own Vercel project with the folder as its root directory, one path per artifact. That host is the business's one address with the practice: the website build, when one is previewed, sits on it at `/proto`, proxied from its own project ([DEPLOY.md](DEPLOY.md), The Website Build Under /proto). Cut it from this one with `git subtree add --prefix=<short> https://github.com/atelic-action/artifact.git main`, run in `writeups`. A cut is a site, not the package, so it then takes the package from npm instead of carrying its source: delete `src/documents/` and `tst/documents/`, give `package.json` the folder's own name and drop the package's fields (`version`, `files`, `exports`, `sideEffects`, `peerDependencies`), and run `bun add @atelic-action/artifact`. The routes and content already import the documents by the package's name, so nothing else changes. Nothing is pulled forward from here afterward: a document reaches the folder with `bun update @atelic-action/artifact`, and everything else with logic in it is `@atelic-action/ui`'s and arrives with `bun update @atelic-action/ui` ([CLAUDE.md](CLAUDE.md), What a Cut Takes From Here). Delete the artifacts the engagement does not need (the route, the content module, and the prerender entry), then touch four surfaces:
 
 1. **Content**, in `src/content/`. One module per artifact: the real read, every number dated and defensible in the room, graded and shaped by the practice's `FOOTPRINT.md` and written to its pitch surface rules (`Brand/voice.md`, Pitch Surfaces 15 to 21). In `writeup.tsx`, `sheets[]` only groups the blocks; print flows the page across as many letter pages as it needs, and `writeupStops` names the header's stops.
 2. **Images**, split by what they are. Logos are brand marks and go in `public/brand/` (the recipient's logo, e.g. `public/brand/<name>.svg`), which the access wall leaves open so the header and the login page can draw them. The owner's own screens (the full screenshot for the click through and a tight crop for the column) and the QR for the twin, pointing at the bare host (`qr "https://<short>.atelic.me" > public/images/qr.png` with the `qrcode` package), go in `public/images/`, which the wall holds on a private artifact. A cut made before this split moves its recipient logo from `public/images/` to `public/brand/` and repoints `recipient.logo.src`.
@@ -149,7 +149,6 @@ A document is fixed or grown here, in `src/documents/`, with its test in `tst/do
 
 Two things differ from ui. A Trusted Publisher is set on a package that already exists, so the first version, 1.0.0, is published by hand by an owner of the `@atelic-action` scope (`npm publish --access public` from a clean checkout of the tag) before the Trusted Publisher is added and the workflow takes over. And this repo is private, so npm attaches no provenance to what it publishes; the package's source is public on npm all the same, which is why `files` ships only `src/documents/` (README.md and package.json ride along, as npm always includes them), and why nothing in them may name a client.
 
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "The composed documents the Atelic practice hands or sends a business (the writeup, the read, the monthly page, the note, and the sealed document), built from the pieces in @atelic-action/ui",
 	"type": "module",
 	"license": "MIT",
@@ -8,9 +8,6 @@
 		"type": "git",
 		"url": "git+https://github.com/atelic-action/artifact.git"
 	},
-	"publishConfig": {
-		"access": "public"
-	},
 	"files": [
 		"src/documents"
 	],

package/src/documents/Read.tsx

@@ -6,7 +6,7 @@ import {
 	type WriteupGrade,
 	type WriteupPerson,
 } from "@atelic-action/ui/artifact";
-import { ArrowUpRight } from "lucide-react";
+import { ArrowUpRight, Check } from "lucide-react";
 import { type ArtifactLink, type ArtifactParagraph, isEmpty, Paragraph, Runs } from "./Paragraph";
 import { Shot, type WriteupShot } from "./Shot";
 
@@ -15,20 +15,26 @@ import { Shot, type WriteupShot } from "./Shot";
  * before anything changes. Where the writeup says what letter each section
  * earned, the read says why, and what changes. Its shape is the practice's
  * FOOTPRINT.md, under What the Owner Gets: a title and a dated lede; the gist
- * table (every section, its grade, and one line); then the tiers, each
- * section a question in three beats (what we found, why, what changes) with
- * any proof pictures and the tools it was read from; then the plan, in order;
- * then one closing line and the sign off.
+ * table (every section, its grade, and one line); then the tiers; then the
+ * plan, in order; then one closing line and the sign off.
+ *
+ * Each section reads as an aggregator of the tools we looked through, top to
+ * bottom: where we looked (the tools, linked, each with an optional line);
+ * what it showed (a short paragraph or two, a compact table of facts, lists
+ * of examples, and any proof pictures); why, in one sentence on a tinted
+ * panel; today and after, a two column table of what a thing is and what it
+ * becomes; and what we recommend, as a checklist. A beat with nothing in it
+ * is left out, heading and all.
  *
  * It is the writeup's sibling, not a variant: it wears the writeup's column,
- * head, grade chip and key, tier heading, section card, screen, sources, and
- * close (the `.op` classes), and adds only what is its own (the `.rd`
- * classes). The gist table is drawn from the tiers, so a tier added later
- * (Conversion, once the analytics access lands) is one more entry in `tiers`
- * and appears in the table and the body alike, with no change to the props.
- * Every prop is plain data, so a routine can write a read as JSON; the one
- * exception is the sign off person's `role`, which takes a node and is
- * equally happy with a string.
+ * head, grade chip and key, tier heading, section card, screen, and close
+ * (the `.op` classes), and adds only what is its own (the `.rd` classes).
+ * The gist table is drawn from the tiers, so a tier added later (Conversion,
+ * once the analytics access lands) is one more entry in `tiers` and appears
+ * in the table and the body alike, with no change to the props. Every prop
+ * is plain data, so a routine can write a read as JSON; the one exception is
+ * the sign off person's `role`, which takes a node and is equally happy with
+ * a string.
  */
 
 /** A link inside running text: the words the reader clicks and where they go. */
@@ -37,13 +43,36 @@ export type ReadLink = ArtifactLink;
 /** A paragraph: a plain string, or runs of text and links in order. */
 export type ReadParagraph = ArtifactParagraph;
 
-/** A place a reading came from: the tool, opened in a new tab when it has an address. */
-export interface ReadSource {
+/** A tool we looked through: its name, where it opens (in a new tab), and a line on what we read there. */
+export interface ReadTool {
 	label: string;
 	href?: string;
+	/** One short line, e.g. "Page indexing, the last 90 days". */
+	note?: string;
+}
+
+/** The 1.0.0 name for a tool; the same shape. */
+export type ReadSource = ReadTool;
+
+/** One row of a section's facts: a short label and its value, e.g. "Pages on Google" and "9 of 9". */
+export interface ReadFact {
+	label: string;
+	value: ReadParagraph;
+}
+
+/** A list of examples under its own short heading; each item a paragraph that can carry links. */
+export interface ReadExamples {
+	title?: string;
+	items: ReadParagraph[];
+}
+
+/** One row of today and after: what a thing is now, and what it becomes. */
+export interface ReadChange {
+	now: ReadParagraph;
+	after: ReadParagraph;
 }
 
-/** One section of a tier: a question in three beats. */
+/** One section of a tier: a question, read top to bottom in five beats. */
 export interface ReadSection {
 	/** The anchor the gist table links to, e.g. "technical-seo". */
 	id: string;
@@ -55,18 +84,24 @@ export interface ReadSection {
 	grade?: WriteupGrade;
 	/** The one line in the gist table. */
 	gist: ReadParagraph;
-	/** What we found: one paragraph or more. */
+	/** Where we looked: the tools the readings came from, linked, at the top of the section. */
+	tools?: ReadTool[];
+	/** The 1.0.0 name for `tools`, still read and rendered in the same place; `tools` wins when both are set. */
+	sources?: ReadTool[];
+	/** What it showed: one or two short paragraphs. */
 	found: ReadParagraph[];
-	/** A few concrete examples of what was found, as a short list under it. */
-	examples?: ReadParagraph[];
+	/** What it showed, as a compact two column table of facts under the paragraphs. */
+	facts?: ReadFact[];
+	/** What it showed, as lists of examples, each under its own short heading. */
+	examples?: ReadExamples[];
 	/** Proof pictures, each over its caption, e.g. a search result capture per market. */
 	shots?: WriteupShot[];
 	/** Why, in one sentence, set apart. */
 	why: ReadParagraph;
-	/** What changes: one paragraph or more. */
-	changes: ReadParagraph[];
-	/** The tools the readings came from, linked, so the owner can open them. */
-	sources?: ReadSource[];
+	/** Today and after: what each thing is, and what it becomes. */
+	changes?: ReadChange[];
+	/** What we recommend, as a checklist. */
+	recommend?: ReadParagraph[];
 }
 
 /** A tier, e.g. Health: its heading, the question it answers, and its sections in order. */
@@ -109,6 +144,8 @@ export interface ReadClose {
 
 /** The fixed words the page sets, each overridable. */
 export interface ReadLabels {
+	/** The dateline's words before the business, e.g. "Prepared for". */
+	preparedFor: string;
 	/** The gist table's first column. */
 	section: string;
 	/** The gist table's second column. */
@@ -117,24 +154,34 @@ export interface ReadLabels {
 	gist: string;
 	/** What a screen reader hears for a section with no grade. */
 	notGraded: string;
+	/** The beat at the top of a section: the tools we looked through. */
+	tools: string;
+	/** The beat that says what the tools showed. */
 	found: string;
+	/** The one sentence beat. */
 	why: string;
-	changes: string;
-	/** The label over a section's tools. */
-	sources: string;
+	/** The today and after table's first column. */
+	now: string;
+	/** The today and after table's second column. */
+	after: string;
+	/** The checklist beat at the foot of a section. */
+	recommend: string;
 	/** The plan's heading when it names none. */
 	plan: string;
 }
 
 export const readLabels: ReadLabels = {
+	preparedFor: "Prepared for",
 	section: "Section",
 	grade: "Grade",
 	gist: "The Gist",
 	notGraded: "Not graded yet",
-	found: "What We Found",
+	tools: "Where We Looked",
+	found: "What It Showed",
 	why: "Why",
-	changes: "What Changes",
-	sources: "Sources",
+	now: "Today",
+	after: "After",
+	recommend: "What We Recommend",
 	plan: "The Plan",
 };
 
@@ -157,25 +204,101 @@ export interface ReadProps {
 	labels?: Partial<ReadLabels>;
 }
 
-function Sources({ sources, label }: { sources: ReadSource[]; label: string }) {
+/** A paragraph with something to read. Content may arrive as JSON, so a missing one counts as empty. */
+function filled(paragraph: ReadParagraph | undefined | null): paragraph is ReadParagraph {
+	return paragraph !== undefined && paragraph !== null && !isEmpty(paragraph);
+}
+
+function Tools({ tools, label }: { tools: ReadTool[]; label: string }) {
 	return (
-		<footer className="op-sources">
-			<span className="op-sources-label">{label}</span>
-			<ul>
-				{sources.map((source) => (
-					<li key={source.label}>
-						{source.href ? (
-							<a href={source.href} {...newTabProps(source.href, true)}>
-								{source.label}
-								<ArrowUpRight size={12} aria-hidden="true" />
+		<div className="rd-beat rd-tools">
+			<h4>{label}</h4>
+			<ul className="rd-tools-list">
+				{tools.map((tool, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: tools are static content in a fixed order, and a label may repeat
+					<li key={i}>
+						{tool.href ? (
+							<a href={tool.href} {...newTabProps(tool.href, true)}>
+								{tool.label}
+								<ArrowUpRight size={13} aria-hidden="true" />
 							</a>
 						) : (
-							source.label
+							<span className="rd-tool-name">{tool.label}</span>
 						)}
+						{tool.note && <span className="rd-tool-note">{tool.note}</span>}
+					</li>
+				))}
+			</ul>
+		</div>
+	);
+}
+
+function Facts({ facts }: { facts: ReadFact[] }) {
+	return (
+		<table className="rd-facts">
+			<tbody>
+				{facts.map((fact, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: facts are static content in a fixed order
+					<tr key={i}>
+						<th scope="row">{fact.label}</th>
+						<td>
+							<Runs paragraph={fact.value} />
+						</td>
+					</tr>
+				))}
+			</tbody>
+		</table>
+	);
+}
+
+function Changes({ changes, labels }: { changes: ReadChange[]; labels: ReadLabels }) {
+	return (
+		<div className="rd-beat rd-changes">
+			<table className="rd-changes-table">
+				<thead>
+					<tr>
+						<th scope="col" className="rd-now">
+							{labels.now}
+						</th>
+						<th scope="col" className="rd-after">
+							{labels.after}
+						</th>
+					</tr>
+				</thead>
+				<tbody>
+					{changes.map((change, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: rows are static content in a fixed order
+						<tr key={i}>
+							<td className="rd-now" data-label={labels.now}>
+								{filled(change.now) && <Runs paragraph={change.now} />}
+							</td>
+							<td className="rd-after" data-label={labels.after}>
+								{filled(change.after) && <Runs paragraph={change.after} />}
+							</td>
+						</tr>
+					))}
+				</tbody>
+			</table>
+		</div>
+	);
+}
+
+function Recommend({ items, label }: { items: ReadParagraph[]; label: string }) {
+	return (
+		<div className="rd-beat rd-recommend">
+			<h4>{label}</h4>
+			<ul className="rd-checks">
+				{items.map((item, i) => (
+					// biome-ignore lint/suspicious/noArrayIndexKey: recommendations are static content in a fixed order
+					<li key={i}>
+						<Check size={16} strokeWidth={2.5} aria-hidden="true" />
+						<span>
+							<Runs paragraph={item} />
+						</span>
 					</li>
 				))}
 			</ul>
-		</footer>
+		</div>
 	);
 }
 
@@ -190,14 +313,15 @@ function Gist({
 	gradeKey?: ReadProps["gradeKey"];
 	labels: ReadLabels;
 }) {
+	const key = gradeKey ?? [];
 	return (
 		<section className="rd-gist" aria-label={title ? undefined : labels.gist}>
-			{(title || gradeKey) && (
+			{(title || key.length > 0) && (
 				<div className="op-ov-head">
 					{title && <h2 className="op-ov-title">{title}</h2>}
-					{gradeKey && (
+					{key.length > 0 && (
 						<ul className="op-legend">
-							{gradeKey.map((entry) => (
+							{key.map((entry) => (
 								<li key={entry.grade}>
 									<GradeChip grade={entry.grade} />
 									<span>{entry.label}</span>
@@ -263,9 +387,18 @@ function Gist({
 }
 
 function Section({ section, labels }: { section: ReadSection; labels: ReadLabels }) {
-	const found = section.found.filter((paragraph) => !isEmpty(paragraph));
-	const changes = section.changes.filter((paragraph) => !isEmpty(paragraph));
+	const tools = (section.tools ?? section.sources ?? []).filter((tool) => tool?.label?.trim());
+	const found = (section.found ?? []).filter(filled);
+	const facts = (section.facts ?? []).filter((fact) => filled(fact?.value));
+	const examples = (section.examples ?? [])
+		.map((list) => ({ title: list?.title, items: (list?.items ?? []).filter(filled) }))
+		.filter((list) => list.items.length > 0);
 	const shots = section.shots ?? [];
+	const changes = (section.changes ?? []).filter(
+		(change) => filled(change?.now) || filled(change?.after),
+	);
+	const recommend = (section.recommend ?? []).filter(filled);
+	const showed = found.length + facts.length + examples.length + shots.length > 0;
 	return (
 		<section className="op-topic rd-section" id={section.id}>
 			<header className="op-topic-head">
@@ -282,44 +415,46 @@ function Section({ section, labels }: { section: ReadSection; labels: ReadLabels
 					</>
 				)}
 			</header>
-			<div className="rd-beat rd-found">
-				<h4>{labels.found}</h4>
-				{found.map((paragraph, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-					<Paragraph paragraph={paragraph} key={i} />
-				))}
-				{section.examples && section.examples.length > 0 && (
-					<ul className="rd-examples">
-						{section.examples.map((example, i) => (
-							// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
-							<li key={i}>
-								<Runs paragraph={example} />
-							</li>
-						))}
-					</ul>
-				)}
-				{shots.length > 0 && (
-					<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
-						{shots.map((shot) => (
-							<Shot shot={shot} key={shot.src} />
-						))}
-					</div>
-				)}
-			</div>
-			<div className="rd-beat rd-why">
-				<h4>{labels.why}</h4>
-				<Paragraph paragraph={section.why} />
-			</div>
-			<div className="rd-beat rd-changes">
-				<h4>{labels.changes}</h4>
-				{changes.map((paragraph, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-					<Paragraph paragraph={paragraph} key={i} />
-				))}
-			</div>
-			{section.sources && section.sources.length > 0 && (
-				<Sources sources={section.sources} label={labels.sources} />
+			{tools.length > 0 && <Tools tools={tools} label={labels.tools} />}
+			{showed && (
+				<div className="rd-beat rd-found">
+					<h4>{labels.found}</h4>
+					{found.map((paragraph, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
+						<Paragraph paragraph={paragraph} key={i} />
+					))}
+					{facts.length > 0 && <Facts facts={facts} />}
+					{examples.map((list, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: lists are static content in a fixed order, and a title may repeat
+						<div className="rd-examples-block" key={i}>
+							{list.title && <h5>{list.title}</h5>}
+							<ul className="rd-examples">
+								{list.items.map((example, j) => (
+									// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
+									<li key={j}>
+										<Runs paragraph={example} />
+									</li>
+								))}
+							</ul>
+						</div>
+					))}
+					{shots.length > 0 && (
+						<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
+							{shots.map((shot) => (
+								<Shot shot={shot} key={shot.src} />
+							))}
+						</div>
+					)}
+				</div>
 			)}
+			{filled(section.why) && (
+				<div className="rd-beat rd-why">
+					<h4>{labels.why}</h4>
+					<Paragraph paragraph={section.why} />
+				</div>
+			)}
+			{changes.length > 0 && <Changes changes={changes} labels={labels} />}
+			{recommend.length > 0 && <Recommend items={recommend} label={labels.recommend} />}
 		</section>
 	);
 }
@@ -328,9 +463,7 @@ function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 	return (
 		<section className="rd-plan" id={plan.id}>
 			<h2>{plan.title ?? labels.plan}</h2>
-			{plan.lead && !isEmpty(plan.lead) && (
-				<Paragraph paragraph={plan.lead} className="rd-plan-lead" />
-			)}
+			{filled(plan.lead) && <Paragraph paragraph={plan.lead} className="rd-plan-lead" />}
 			<ol className="rd-steps">
 				{plan.steps.map((step) => (
 					<li className="rd-step" key={step.title}>
@@ -342,7 +475,7 @@ function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
 									<span className="rd-step-who">{step.who}</span>
 								</>
 							)}
-							{step.body && !isEmpty(step.body) && (
+							{filled(step.body) && (
 								<>
 									{" "}
 									<Runs paragraph={step.body} />
@@ -375,14 +508,14 @@ export function Read({
 			<article className="op-doc rd-doc">
 				<header className="op-head">
 					<p className="op-meta">
-						Prepared for <b>{preparedFor}</b>
+						{labels.preparedFor} <b>{preparedFor}</b>
 						<span className="op-meta-sep" aria-hidden="true">
 							{" · "}
 						</span>
 						<span className="op-meta-date">{date}</span>
 					</p>
 					<h1>{title}</h1>
-					{!isEmpty(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
+					{filled(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
 				</header>
 				{shownTiers.length > 0 && (
 					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
@@ -399,7 +532,7 @@ export function Read({
 					</div>
 				))}
 				{plan.steps.length > 0 && <Plan plan={plan} labels={labels} />}
-				{!isEmpty(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
+				{filled(close.line) && <Paragraph paragraph={close.line} className="rd-closing" />}
 				{close.signOff && close.person && (
 					<footer className="op-close rd-close">
 						<SignOff signOff={close.signOff} person={close.person} />

package/src/documents/documents.css

@@ -2197,11 +2197,12 @@
 	   THE READ: the baseline's grades explained by cause (Read.tsx). The
 	   writeup's sibling: it sits inside the writeup's own .op root, so the
 	   column, the head, the grade chip and its key, the tier heading, the
-	   section card, the screen, the sources, the close, and every print
-	   rule of the writeup's are its own already. This block adds only what
-	   the read has and the writeup does not: the gist table, the three
-	   beats of a section, the proof pictures in a row, and the numbered
-	   plan. It sets no @page; the writeup's, earlier in this sheet and the
+	   section card, the screen, the close, and every print rule of the
+	   writeup's are its own already. This block adds only what the read has
+	   and the writeup does not: the gist table, the beats of a section (the
+	   tools we looked through, what they showed with its facts and
+	   examples, why, today and after, and what we recommend), the proof
+	   pictures in a row, and the numbered plan. It sets no @page; the writeup's, earlier in this sheet and the
 	   later of the two there, sets letter paper for every artifact page.
 
 	   Tokens only (theme.css).
@@ -2288,7 +2289,7 @@
 		min-width: 0;
 	}
 
-	/* ---- a section: the trade name over the question, then three beats ---- */
+	/* ---- a section: the trade name over the question, then its beats ---- */
 	.atelic-ui .rd-name {
 		margin: 0 0 4px;
 		font-family: var(--font-mono);
@@ -2304,7 +2305,7 @@
 		font-size: 21px;
 	}
 	.atelic-ui .rd-beat {
-		margin-top: 16px;
+		margin-top: 20px;
 		min-width: 0;
 	}
 	.atelic-ui .rd-beat h4 {
@@ -2324,12 +2325,99 @@
 	.atelic-ui .rd-beat p:last-child {
 		margin-bottom: 0;
 	}
+	/* Where we looked: the tools in a row at the top of the section, each a
+	   link with its line under it. */
+	.atelic-ui .rd-tools-list {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: flex;
+		flex-wrap: wrap;
+		gap: 10px 28px;
+	}
+	.atelic-ui .rd-tools-list li {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		min-width: 0;
+		max-width: 100%;
+	}
+	.atelic-ui .rd-tools-list a,
+	.atelic-ui .rd-tool-name {
+		display: inline-flex;
+		align-items: center;
+		gap: 3px;
+		font-size: 15px;
+		font-weight: 600;
+		color: var(--op-accent);
+		text-decoration: none;
+	}
+	.atelic-ui .rd-tool-name {
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-tools-list a:hover {
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+	.atelic-ui .rd-tools-list svg {
+		flex: none;
+	}
+	.atelic-ui .rd-tool-note {
+		font-size: 13px;
+		line-height: 1.35;
+		color: var(--op-ink-faint);
+	}
+
+	/* What it showed: the facts as a compact table of label and value, in
+	   the writeup's table dress (an ink rule over thin row rules). */
+	.atelic-ui .rd-facts {
+		width: 100%;
+		max-width: 620px;
+		margin: 12px 0 0;
+		border-collapse: collapse;
+		border-top: 1.5px solid var(--op-ink);
+		font-size: 15px;
+		line-height: 1.4;
+	}
+	.atelic-ui .rd-facts th,
+	.atelic-ui .rd-facts td {
+		padding: 7px 14px 7px 0;
+		border-bottom: 1px solid var(--neutral-100);
+		text-align: left;
+		vertical-align: top;
+	}
+	.atelic-ui .rd-facts th {
+		width: 55%;
+		font-weight: 400;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-facts td {
+		padding-right: 0;
+		font-weight: 600;
+		color: var(--op-ink);
+		font-variant-numeric: tabular-nums;
+	}
+	.atelic-ui .rd-facts tr:last-child > * {
+		border-bottom: 0;
+	}
+
+	/* The examples: a list or more, each under its own short heading. */
+	.atelic-ui .rd-examples-block {
+		margin-top: 14px;
+		max-width: 68ch;
+	}
+	.atelic-ui .rd-examples-block h5 {
+		margin: 0 0 4px;
+		font-size: 15px;
+		font-weight: 650;
+		color: var(--op-ink);
+	}
 	.atelic-ui .rd-examples {
 		list-style: disc;
-		margin: 8px 0 0;
+		margin: 0;
 		padding-left: 1.2em;
-		max-width: 68ch;
 		color: var(--op-ink-soft);
+		text-wrap: pretty;
 	}
 	.atelic-ui .rd-examples li + li {
 		margin-top: 4px;
@@ -2355,6 +2443,92 @@
 		gap: 14px;
 		margin-top: 14px;
 	}
+	/* A lone picture keeps a screen's size rather than filling the card. */
+	.atelic-ui .rd-shots[data-count="1"] {
+		max-width: 380px;
+	}
+
+	/* Today and after: what a thing is, and what it becomes. Two columns
+	   wide; on a phone each row stacks, each half wearing its label. */
+	.atelic-ui .rd-changes-table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 15px;
+		line-height: 1.45;
+	}
+	.atelic-ui .rd-changes-table thead {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+	}
+	.atelic-ui .rd-changes-table,
+	.atelic-ui .rd-changes-table tbody,
+	.atelic-ui .rd-changes-table tr,
+	.atelic-ui .rd-changes-table td {
+		display: block;
+	}
+	.atelic-ui .rd-changes-table tbody tr {
+		padding: 10px 0;
+		border-bottom: 1px solid var(--neutral-100);
+	}
+	.atelic-ui .rd-changes-table tbody tr:first-child {
+		border-top: 1.5px solid var(--op-ink);
+	}
+	.atelic-ui .rd-changes-table tbody tr:last-child {
+		border-bottom: 0;
+		padding-bottom: 0;
+	}
+	.atelic-ui .rd-changes-table td {
+		text-align: left;
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-changes-table td + td {
+		margin-top: 6px;
+	}
+	.atelic-ui .rd-changes-table td::before {
+		content: attr(data-label);
+		display: block;
+		margin-bottom: 1px;
+		font-family: var(--font-mono);
+		font-size: 11px;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--op-ink-faint);
+	}
+	.atelic-ui .rd-changes-table td.rd-now {
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-changes-table td.rd-after {
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-changes-table td.rd-after::before {
+		color: var(--op-accent);
+	}
+
+	/* What we recommend: a checklist, each item led by the accent's check. */
+	.atelic-ui .rd-checks {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+		display: grid;
+		gap: 8px;
+		max-width: 68ch;
+	}
+	.atelic-ui .rd-checks li {
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		column-gap: 10px;
+		align-items: start;
+		line-height: 1.45;
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-checks svg {
+		margin-top: 0.2em;
+		color: var(--op-accent);
+	}
 
 	/* ---- the plan: the steps in order, numbered ---- */
 	.atelic-ui .rd-plan {
@@ -2448,6 +2622,69 @@
 			padding-left: 20px;
 			padding-right: 16px;
 		}
+		.atelic-ui .rd-facts th {
+			width: 45%;
+		}
+		.atelic-ui .rd-changes-table {
+			display: table;
+			table-layout: fixed;
+		}
+		.atelic-ui .rd-changes-table thead {
+			display: table-header-group;
+			position: static;
+			width: auto;
+			height: auto;
+			overflow: visible;
+			clip: auto;
+		}
+		.atelic-ui .rd-changes-table tbody {
+			display: table-row-group;
+		}
+		.atelic-ui .rd-changes-table tr,
+		.atelic-ui .rd-changes-table tbody tr {
+			display: table-row;
+			padding: 0;
+			border: 0;
+		}
+		.atelic-ui .rd-changes-table th,
+		.atelic-ui .rd-changes-table td {
+			display: table-cell;
+			width: 50%;
+			padding: 9px 18px 9px 0;
+			border-bottom: 1px solid var(--neutral-100);
+			text-align: left;
+			vertical-align: top;
+		}
+		.atelic-ui .rd-changes-table th + th,
+		.atelic-ui .rd-changes-table td + td {
+			margin-top: 0;
+			padding-left: 18px;
+			padding-right: 0;
+			border-left: 1px solid var(--neutral-100);
+		}
+		.atelic-ui .rd-changes-table td::before {
+			content: none;
+		}
+		.atelic-ui .rd-changes-table tbody tr:first-child {
+			border-top: 0;
+		}
+		.atelic-ui .rd-changes-table thead th {
+			padding-top: 0;
+			padding-bottom: 8px;
+			border-bottom: 1.5px solid var(--op-ink);
+			font-family: var(--font-mono);
+			font-size: 11.5px;
+			font-weight: 500;
+			letter-spacing: 0.1em;
+			text-transform: uppercase;
+			color: var(--op-ink-faint);
+		}
+		.atelic-ui .rd-changes-table thead th.rd-after {
+			color: var(--op-accent);
+		}
+		.atelic-ui .rd-changes-table tbody tr:last-child td {
+			border-bottom: 0;
+		}
 		.atelic-ui .rd-shots[data-count="2"] {
 			grid-template-columns: repeat(2, minmax(0, 1fr));
 		}
@@ -2465,6 +2702,10 @@
 			border-color: var(--neutral-200);
 		}
 		.atelic-ui .rd-gist-table tr,
+		.atelic-ui .rd-changes-table tr,
+		.atelic-ui .rd-facts,
+		.atelic-ui .rd-tools,
+		.atelic-ui .rd-checks li,
 		.atelic-ui .rd-closing,
 		.atelic-ui .rd-why,
 		.atelic-ui .rd-step,
@@ -2473,6 +2714,7 @@
 			break-inside: avoid;
 		}
 		.atelic-ui .rd-beat h4,
+		.atelic-ui .rd-examples-block h5,
 		.atelic-ui .rd-plan h2 {
 			break-after: avoid;
 		}