@atelic-action/ui 1.0.0 → 1.1.0

package/README.md

@@ -33,6 +33,7 @@ Every export, grouped by the entry it is imported from. The gallery column links
 | `readCookie`, `Tone` | `@atelic-action/ui/components` | The cookie reader the watermark uses, and the tone type | none |
 | `Button`, `Chip`, `Eyebrow`, `Lead`, `SectionHeading` | `@atelic-action/ui/primitives` | The small pieces a page is set in | [#primitives](https://ui.atelic.me/#primitives) |
 | `Writeup`, `ratingCell` | `@atelic-action/ui/artifact` | The graded document an owner gets, and its star rating table cell | [#writeup](https://ui.atelic.me/#writeup) |
+| `Read`, `readLabels` | `@atelic-action/ui/artifact` | The read: a customer's baseline grades explained by cause at the end of the first week, with the plan in order, and its default fixed words | [#read](https://ui.atelic.me/#read) |
 | `Report` | `@atelic-action/ui/artifact` | The monthly page an Operate client gets | [#report](https://ui.atelic.me/#report) |
 | `Note` | `@atelic-action/ui/artifact` | The first touch page, for a business with no published email | [#note](https://ui.atelic.me/#note) |
 | `Gate`, `normalizeEmail` | `@atelic-action/ui/artifact` | The sealed document, opened in the browser by the reader's own address | [#gate](https://ui.atelic.me/#gate) |
@@ -331,7 +332,7 @@ The two pieces a reader sees are ordinary components, in `@atelic-action/ui/comp
 
 `@atelic-action/ui/artifact` is everything the artifact template shared across its cuts, so a fix reaches every business's documents with one version bump:
 
-- **The documents:** `Writeup`, `Report`, `Note`, and `Gate` (the sealed document, with its `GatePayload` type; a reader's address is the key, so a payload never lists it, and the component identifies a reader to HubSpot by the address they typed), plus the `GradeChip` and `SignOff` they share, and every content type they take (`WriteupProps`, `ReportProps`, `NoteProps`, `GateProps`, and the rest).
+- **The documents:** `Writeup`, `Read`, `Report`, `Note`, and `Gate` (the sealed document, with its `GatePayload` type; a reader's address is the key, so a payload never lists it, and the component identifies a reader to HubSpot by the address they typed), plus the `GradeChip` and `SignOff` they share, and every content type they take (`WriteupProps`, `ReadProps`, `ReportProps`, `NoteProps`, `GateProps`, and the rest).
 - **The shell:** `ArtifactShell`, the `.atelic-ui` scope with the skip link, the dark header, the credit band, and the watermark around a page.
 - **The contract and the head:** the `ArtifactConfig` types, and `buildPageHead` and `canonicalUrl` with their `PageMeta` type.
 - **Who opened it:** `mintToken`, `sealReader`, `openReader`, `readerId`, `readerLink`, and `whoIsReading`. The same six are also built and exported alone as `@atelic-action/ui/artifact/readers`, because a Playwright spec and a script run under Node, which compiles nothing inside `node_modules`.
@@ -352,6 +353,8 @@ export function ArtifactShell(props: Omit<ArtifactShellProps, "currentPath">) {
 
 **The note** is the first touch for a business whose site publishes no email address, served at `/notes` and wrapped in `ArtifactShell` exactly as the writeup is. It is the writeup's sibling, not a variant: a title and a dateline, the opener, two lanes of findings (what the customer sees, what sits under the hood), the steps the work would start with, and the close over the shared `SignOff`. Every prop is plain data, so a routine can write a note as JSON; a paragraph is a string or an array of strings and `{ text, href }` links, and the sign off person's `role` is the one field that also takes a node. A finding is a `Callout` with its `WriteupShot` under it. Its column is the writeup's 920px, centered under the header with the header's `--gutter`, and its text runs the column's full width. A finding sets its screen under its words on a phone and beside them, on the right, when wide and on paper. It reads on a phone first, stacks the two lanes as separate sections top to bottom at every width and on paper, never side by side, and prints to one letter sheet under the writeup's `@page`.
 
+**The read** is what a customer gets at the end of an engagement's first week, before anything changes: the baseline's grades explained by cause (FOOTPRINT.md, What the Owner Gets). It is the writeup's sibling and wears the writeup's own `.op` root, so its column, head, grade chip and key, tier headings, section cards, screens, sources, close, and print rules are the writeup's; `artifact.css` adds only its `.rd` classes. Top to bottom: a title, the dateline, and a lede of two or three sentences; the gist table (Section, Grade, The Gist), drawn from the tiers so it can never disagree with the body, each section's name linking to its card and a section with no grade showing a quiet dash; then each tier's sections, each headed by its question with its trade name over it and its grade beside it, in three beats (what we found, with an optional short list of examples and any proof pictures in a row under their captions; why, one sentence set apart; what changes) and the tools it was read from; then the plan, numbered, each step a bold title and a sentence or two, with `who` naming a step that is the owner's own; then one closing line over the shared `SignOff`. A later tier (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, and a tier with no sections yet is left out of both. Every prop is plain data, the note's paragraph shape (a string, or runs of text and `{ text, href }` links), so a routine can write a read as JSON. The fixed words (the column heads, the beat labels, the plan's heading) are `readLabels`, and `labels` overrides any of them. A site wraps it in `ArtifactShell` exactly as it wraps the writeup; it sets no `@page`, so the writeup's stays the one that wins.
+
 **The sealed document's classes.** `Gate` renders the opened document as the HTML it was sealed from, so its markup is the content's, and `artifact.css` styles what that HTML may wear inside `.gate-content`: the tier row (`.gate-tiers` of `.gate-tier` cards, `.is-picked` on the recommended one, `.gate-tier-name`, `.gate-tier-price`, `.gate-tier-note`, and the `.gate-tier-math` sum column of `.gate-tier-was`, `.gate-tier-credit`, `.gate-tier-mathlabel`, and the price), `ul.icon-list` for a list led by inline lucide icons (sized for the card inside a tier), `ul.gate-checks`, and, from 1.0.0 (ATE-599, pulled up from the Wynkoop and Outdoors Geek hosts), the `.gate-addons` row that seats two `.gate-tier.is-addon` monthly cards side by side under the builds, an inline SVG mark inside `.gate-tier-mathlabel` that stays on the label's line, and the `.gate-footnote` line under the tiers that the mark points at. A folder stylesheet that carried any of these deletes it.
 
 The documents import no stylesheet of their own. A site imports `@atelic-action/ui/styles/artifact.css` in its base sheet after `gate.css` and before its `theme.css`, so every page carries the rules whichever route it is. The sheet holds two `@page` rules, the monthly page's and then the writeup's, and the later one wins for every page a site prints; the order inside the sheet is the order the template's build bundled them in and is load bearing.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, the component library, the access gate, and the app shell they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/artifact/Note.tsx

@@ -1,5 +1,11 @@
 import { Callout } from "../components";
-import { newTabProps } from "../lib/newTabProps";
+import {
+	type ArtifactLink,
+	type ArtifactParagraph,
+	isEmpty,
+	ArtifactAnchor as NoteAnchor,
+	Paragraph,
+} from "./Paragraph";
 import { Shot, type WriteupShot } from "./Shot";
 import { SignOff, type WriteupPerson } from "./SignOff";
 
@@ -20,13 +26,10 @@ import { SignOff, type WriteupPerson } from "./SignOff";
  */
 
 /** A link inside running text: the words the reader clicks and where they go. */
-export interface NoteLink {
-	text: string;
-	href: string;
-}
+export type NoteLink = ArtifactLink;
 
 /** A paragraph: a plain string, or runs of text and links in order. */
-export type NoteParagraph = string | Array<string | NoteLink>;
+export type NoteParagraph = ArtifactParagraph;
 
 /** One defect and what it costs, with the owner's screen under it when there is one. */
 export interface NoteFinding {
@@ -86,39 +89,6 @@ export interface NoteProps {
 	close: NoteClose;
 }
 
-/** A link opens in a new tab when it leaves the page, and in place when it is an anchor or a mail link. */
-function NoteAnchor({ href, children }: { href: string; children: string }) {
-	return (
-		<a href={href} {...newTabProps(href, /^https?:/i.test(href))}>
-			{children}
-		</a>
-	);
-}
-
-/** A paragraph with nothing to read: a blank string, or runs that are all blank strings. A link always counts. */
-function isEmpty(paragraph: NoteParagraph): boolean {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return runs.every((run) => typeof run === "string" && run.trim() === "");
-}
-
-function Paragraph({ paragraph, className }: { paragraph: NoteParagraph; className?: string }) {
-	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
-	return (
-		<p className={className}>
-			{runs.map((run, i) =>
-				typeof run === "string" ? (
-					run
-				) : (
-					// biome-ignore lint/suspicious/noArrayIndexKey: runs are static content in a fixed order
-					<NoteAnchor href={run.href} key={i}>
-						{run.text}
-					</NoteAnchor>
-				),
-			)}
-		</p>
-	);
-}
-
 function Finding({ finding }: { finding: NoteFinding }) {
 	return (
 		<li className={finding.shot ? "nt-finding has-shot" : "nt-finding"}>

package/src/artifact/Paragraph.tsx

@@ -0,0 +1,65 @@
+import { newTabProps } from "../lib/newTabProps";
+
+/**
+ * Plain data text for the documents a routine can write as JSON (the note
+ * and the read): a paragraph is a string, or runs of text and links in
+ * order. A link opens in a new tab when it leaves the page, and in place
+ * when it is an anchor or a mail link.
+ */
+
+/** A link inside running text: the words the reader clicks and where they go. */
+export interface ArtifactLink {
+	text: string;
+	href: string;
+}
+
+/** A paragraph: a plain string, or runs of text and links in order. */
+export type ArtifactParagraph = string | Array<string | ArtifactLink>;
+
+/** A link opens in a new tab when it leaves the page, and in place when it is an anchor or a mail link. */
+export function ArtifactAnchor({ href, children }: { href: string; children: string }) {
+	return (
+		<a href={href} {...newTabProps(href, /^https?:/i.test(href))}>
+			{children}
+		</a>
+	);
+}
+
+/** A paragraph with nothing to read: a blank string, or runs that are all blank strings. A link always counts. */
+export function isEmpty(paragraph: ArtifactParagraph): boolean {
+	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
+	return runs.every((run) => typeof run === "string" && run.trim() === "");
+}
+
+/** The runs alone, for a container that is not a paragraph (a list item, a table cell). */
+export function Runs({ paragraph }: { paragraph: ArtifactParagraph }) {
+	const runs = typeof paragraph === "string" ? [paragraph] : paragraph;
+	return (
+		<>
+			{runs.map((run, i) =>
+				typeof run === "string" ? (
+					run
+				) : (
+					// biome-ignore lint/suspicious/noArrayIndexKey: runs are static content in a fixed order
+					<ArtifactAnchor href={run.href} key={i}>
+						{run.text}
+					</ArtifactAnchor>
+				),
+			)}
+		</>
+	);
+}
+
+export function Paragraph({
+	paragraph,
+	className,
+}: {
+	paragraph: ArtifactParagraph;
+	className?: string;
+}) {
+	return (
+		<p className={className}>
+			<Runs paragraph={paragraph} />
+		</p>
+	);
+}

package/src/artifact/Read.tsx

@@ -0,0 +1,406 @@
+import { ArrowUpRight } from "lucide-react";
+import { newTabProps } from "../lib/newTabProps";
+import { GradeChip, gradeLabel, type WriteupGrade } from "./GradeChip";
+import { type ArtifactLink, type ArtifactParagraph, isEmpty, Paragraph, Runs } from "./Paragraph";
+import { Shot, type WriteupShot } from "./Shot";
+import { SignOff, type WriteupPerson } from "./SignOff";
+
+/**
+ * The read: what a customer gets at the end of an engagement's first week,
+ * 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.
+ *
+ * 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.
+ */
+
+/** A link inside running text: the words the reader clicks and where they go. */
+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 {
+	label: string;
+	href?: string;
+}
+
+/** One section of a tier: a question in three beats. */
+export interface ReadSection {
+	/** The anchor the gist table links to, e.g. "technical-seo". */
+	id: string;
+	/** The section's trade name, e.g. "Technical SEO": the gist table's Section column, and the line over the question. */
+	name: string;
+	/** The question the section answers, in the owner's words, e.g. "Can Google read the site?". The section's heading. */
+	question: string;
+	/** The baseline's grade. Omit for a section not yet graded; the table shows a quiet dash. */
+	grade?: WriteupGrade;
+	/** The one line in the gist table. */
+	gist: ReadParagraph;
+	/** What we found: one paragraph or more. */
+	found: ReadParagraph[];
+	/** A few concrete examples of what was found, as a short list under it. */
+	examples?: ReadParagraph[];
+	/** 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[];
+}
+
+/** A tier, e.g. Health: its heading, the question it answers, and its sections in order. */
+export interface ReadTier {
+	/** The anchor a header stop points at, e.g. "health". */
+	id?: string;
+	/** The tier's name, e.g. "Health". */
+	title: string;
+	/** The question the tier answers, in the owner's words. */
+	lead?: string;
+	sections: ReadSection[];
+}
+
+/** One step of the plan: a bold title and a sentence or two. */
+export interface ReadStep {
+	title: string;
+	body?: ReadParagraph;
+	/** Whose step it is when it is not the practice's, e.g. "Yours" or a name; set beside the title. */
+	who?: string;
+}
+
+/** The plan: the steps in order, numbered. */
+export interface ReadPlan {
+	/** The anchor a header stop points at, e.g. "plan". */
+	id?: string;
+	/** The heading; defaults to the `plan` label. */
+	title?: string;
+	/** A line over the steps. */
+	lead?: ReadParagraph;
+	steps: ReadStep[];
+}
+
+/** The close: one line, then the sign off. */
+export interface ReadClose {
+	/** One sentence, e.g. what follows and when. */
+	line: ReadParagraph;
+	signOff?: string;
+	person?: WriteupPerson;
+}
+
+/** The fixed words the page sets, each overridable. */
+export interface ReadLabels {
+	/** The gist table's first column. */
+	section: string;
+	/** The gist table's second column. */
+	grade: string;
+	/** The gist table's third column. */
+	gist: string;
+	/** What a screen reader hears for a section with no grade. */
+	notGraded: string;
+	found: string;
+	why: string;
+	changes: string;
+	/** The label over a section's tools. */
+	sources: string;
+	/** The plan's heading when it names none. */
+	plan: string;
+}
+
+export const readLabels: ReadLabels = {
+	section: "Section",
+	grade: "Grade",
+	gist: "The Gist",
+	notGraded: "Not graded yet",
+	found: "What We Found",
+	why: "Why",
+	changes: "What Changes",
+	sources: "Sources",
+	plan: "The Plan",
+};
+
+export interface ReadProps {
+	title: string;
+	/** The business, set in the dateline. */
+	preparedFor: string;
+	/** The ISO date, e.g. "2026-10-16". */
+	date: string;
+	/** Two or three sentences under the title. */
+	lede: ReadParagraph;
+	/** The heading over the gist table, e.g. "At a Glance". */
+	gistTitle?: string;
+	/** The key: what each letter means, in a few words each. */
+	gradeKey?: Array<{ grade: WriteupGrade; label: string }>;
+	/** The tiers in order. Each section appears in the gist table and in the body. */
+	tiers: ReadTier[];
+	plan: ReadPlan;
+	close: ReadClose;
+	labels?: Partial<ReadLabels>;
+}
+
+function Sources({ sources, label }: { sources: ReadSource[]; 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" />
+							</a>
+						) : (
+							source.label
+						)}
+					</li>
+				))}
+			</ul>
+		</footer>
+	);
+}
+
+function Gist({
+	tiers,
+	title,
+	gradeKey,
+	labels,
+}: {
+	tiers: ReadTier[];
+	title?: string;
+	gradeKey?: ReadProps["gradeKey"];
+	labels: ReadLabels;
+}) {
+	return (
+		<section className="rd-gist" aria-label={title ? undefined : labels.gist}>
+			{(title || gradeKey) && (
+				<div className="op-ov-head">
+					{title && <h2 className="op-ov-title">{title}</h2>}
+					{gradeKey && (
+						<ul className="op-legend">
+							{gradeKey.map((entry) => (
+								<li key={entry.grade}>
+									<GradeChip grade={entry.grade} />
+									<span>{entry.label}</span>
+								</li>
+							))}
+						</ul>
+					)}
+				</div>
+			)}
+			<div className="rd-gist-card">
+				<table className="rd-gist-table">
+					<thead>
+						<tr>
+							<th scope="col" className="rd-gist-section">
+								{labels.section}
+							</th>
+							<th scope="col" className="rd-gist-grade">
+								{labels.grade}
+							</th>
+							<th scope="col" className="rd-gist-read">
+								{labels.gist}
+							</th>
+						</tr>
+					</thead>
+					{tiers.map((tier) => (
+						<tbody key={tier.title}>
+							<tr className="rd-gist-tier">
+								<th scope="rowgroup" colSpan={3}>
+									{tier.title}
+								</th>
+							</tr>
+							{tier.sections.map((section) => (
+								<tr key={section.id}>
+									<th scope="row" className="rd-gist-section">
+										<a href={`#${section.id}`}>{section.name}</a>
+									</th>
+									<td className="rd-gist-grade">
+										{section.grade ? (
+											<>
+												<span className="op-sr-only">{gradeLabel[section.grade]}</span>
+												<span aria-hidden="true">
+													<GradeChip grade={section.grade} />
+												</span>
+											</>
+										) : (
+											<>
+												<span className="op-sr-only">{labels.notGraded}</span>
+												<span className="op-dash" aria-hidden="true" />
+											</>
+										)}
+									</td>
+									<td className="rd-gist-read">
+										<Runs paragraph={section.gist} />
+									</td>
+								</tr>
+							))}
+						</tbody>
+					))}
+				</table>
+			</div>
+		</section>
+	);
+}
+
+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 shots = section.shots ?? [];
+	return (
+		<section className="op-topic rd-section" id={section.id}>
+			<header className="op-topic-head">
+				<div>
+					<p className="rd-name">{section.name}</p>
+					<h3>{section.question}</h3>
+				</div>
+				{section.grade && (
+					<>
+						<span className="op-sr-only">{`${labels.grade} ${gradeLabel[section.grade]}`}</span>
+						<span className="rd-grade" aria-hidden="true">
+							<GradeChip grade={section.grade} />
+						</span>
+					</>
+				)}
+			</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} />
+			)}
+		</section>
+	);
+}
+
+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" />
+			)}
+			<ol className="rd-steps">
+				{plan.steps.map((step) => (
+					<li className="rd-step" key={step.title}>
+						<p>
+							<b className="rd-step-title">{step.title}</b>
+							{step.who && (
+								<>
+									{" "}
+									<span className="rd-step-who">{step.who}</span>
+								</>
+							)}
+							{step.body && !isEmpty(step.body) && (
+								<>
+									{" "}
+									<Runs paragraph={step.body} />
+								</>
+							)}
+						</p>
+					</li>
+				))}
+			</ol>
+		</section>
+	);
+}
+
+export function Read({
+	title,
+	preparedFor,
+	date,
+	lede,
+	gistTitle,
+	gradeKey,
+	tiers,
+	plan,
+	close,
+	labels: overrides,
+}: ReadProps) {
+	const labels = { ...readLabels, ...overrides };
+	const shownTiers = tiers.filter((tier) => tier.sections.length > 0);
+	return (
+		<div className="op rd">
+			<article className="op-doc rd-doc">
+				<header className="op-head">
+					<p className="op-meta">
+						Prepared for <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" />}
+				</header>
+				{shownTiers.length > 0 && (
+					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+				)}
+				{shownTiers.map((tier) => (
+					<div className="rd-tier" key={tier.title}>
+						<div className="op-part" id={tier.id}>
+							<h2>{tier.title}</h2>
+							{tier.lead && <p>{tier.lead}</p>}
+						</div>
+						{tier.sections.map((section) => (
+							<Section section={section} labels={labels} key={section.id} />
+						))}
+					</div>
+				))}
+				{plan.steps.length > 0 && <Plan plan={plan} labels={labels} />}
+				{!isEmpty(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} />
+					</footer>
+				)}
+			</article>
+		</div>
+	);
+}

package/src/artifact/index.ts

@@ -13,6 +13,7 @@ export { Gate, type GatePayload, type GatePerson, type GateProps, normalizeEmail
 export { GradeChip, gradeLabel } from "./GradeChip";
 export * from "./Note";
 export { buildPageHead, canonicalUrl, type PageMeta } from "./pageHead";
+export * from "./Read";
 export * from "./Report";
 export {
 	mintToken,

package/src/styles/artifact.css

@@ -3,8 +3,8 @@
    share. Moved whole from the artifact template, in the order its build
    bundled them (the shared classes, the stage, the monthly page, the
    writeup), which the two @page rules depend on: the later one wins, and
-   the writeup's is the later one. The note follows the writeup and sets
-   no @page, so the writeup's stays the one that wins. They sit in the package's layer like
+   the writeup's is the later one. The note and the read follow the writeup
+   and set no @page, so the writeup's stays the one that wins. They sit in the package's layer like
    every sheet here, so any rule a site writes outside a layer still wins
    over them whatever its specificity. */
 @layer atelic-ui {
@@ -2293,4 +2293,289 @@
 			break-inside: avoid;
 		}
 	}
+
+	/* =================================================================
+	   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
+	   later of the two there, sets letter paper for every artifact page.
+
+	   Tokens only (theme.css).
+	   ================================================================= */
+
+	/* Prose links read as links here, where the writeup's are quiet. */
+	.atelic-ui .rd-lede a,
+	.atelic-ui .rd-beat a,
+	.atelic-ui .rd-gist-read a,
+	.atelic-ui .rd-plan a,
+	.atelic-ui .rd-closing a {
+		color: var(--op-accent);
+		text-decoration: underline;
+		text-underline-offset: 2px;
+		text-decoration-thickness: 1px;
+		overflow-wrap: anywhere;
+	}
+
+	/* ---- the gist table: section, grade, and one line, under its tier ---- */
+	.atelic-ui .rd-gist {
+		margin-top: 26px;
+	}
+	.atelic-ui .rd-gist-card {
+		min-width: 0;
+		background: var(--op-card);
+		border: 1px solid var(--op-rule);
+		border-radius: var(--radius-md);
+		box-shadow: var(--shadow-sm);
+		overflow: hidden;
+	}
+	.atelic-ui .rd-gist-table {
+		width: 100%;
+		border-collapse: collapse;
+		font-size: 15px;
+		line-height: 1.45;
+	}
+	.atelic-ui .rd-gist-table thead th {
+		padding: 9px 12px;
+		text-align: left;
+		font-family: var(--font-mono);
+		font-size: 11px;
+		font-weight: 500;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--op-ink-faint);
+		border-bottom: 1px solid var(--op-rule);
+	}
+	.atelic-ui .rd-gist-tier th {
+		padding: 7px 12px;
+		background: var(--surface-alt);
+		text-align: left;
+		font-family: var(--font-mono);
+		font-size: 11.5px;
+		font-weight: 500;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-gist-table tbody tr + tr > * {
+		border-top: 1px solid var(--op-rule);
+	}
+	.atelic-ui .rd-gist-table tbody th[scope="row"],
+	.atelic-ui .rd-gist-table td {
+		padding: 11px 12px;
+		vertical-align: top;
+		text-align: left;
+	}
+	.atelic-ui .rd-gist-table .rd-gist-section {
+		font-weight: 650;
+		letter-spacing: -0.01em;
+		width: 30%;
+	}
+	.atelic-ui .rd-gist-table tbody .rd-gist-section a:hover {
+		color: var(--op-accent);
+	}
+	.atelic-ui .rd-gist-table .rd-gist-grade {
+		width: 1%;
+		white-space: nowrap;
+		text-align: center;
+	}
+	.atelic-ui .rd-gist-table td.rd-gist-read {
+		color: var(--op-ink-soft);
+		text-wrap: pretty;
+		min-width: 0;
+	}
+
+	/* ---- a section: the trade name over the question, then three beats ---- */
+	.atelic-ui .rd-name {
+		margin: 0 0 4px;
+		font-family: var(--font-mono);
+		font-size: 11.5px;
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--op-ink-faint);
+	}
+	.atelic-ui .rd-grade .op-grade {
+		width: 42px;
+		height: 42px;
+		border-radius: 12px;
+		font-size: 21px;
+	}
+	.atelic-ui .rd-beat {
+		margin-top: 16px;
+		min-width: 0;
+	}
+	.atelic-ui .rd-beat h4 {
+		margin: 0 0 6px;
+		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-beat p {
+		margin: 0 0 10px;
+		max-width: 68ch;
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-beat p:last-child {
+		margin-bottom: 0;
+	}
+	.atelic-ui .rd-examples {
+		list-style: disc;
+		margin: 8px 0 0;
+		padding-left: 1.2em;
+		max-width: 68ch;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-examples li + li {
+		margin-top: 4px;
+	}
+	/* Why is one sentence, set apart: a tinted panel with the accent's rule. */
+	.atelic-ui .rd-why {
+		padding: 12px 14px;
+		border-left: 3px solid var(--op-accent);
+		border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+		background: var(--surface-alt);
+	}
+	.atelic-ui .rd-why p {
+		font-size: 16.5px;
+		font-weight: 550;
+		line-height: 1.45;
+		color: var(--op-ink);
+	}
+	/* The proof pictures sit in a row at one size, a search capture per
+	   market; a phone stacks them. */
+	.atelic-ui .rd-shots {
+		display: grid;
+		grid-template-columns: minmax(0, 1fr);
+		gap: 14px;
+		margin-top: 14px;
+	}
+
+	/* ---- the plan: the steps in order, numbered ---- */
+	.atelic-ui .rd-plan {
+		margin-top: 34px;
+		scroll-margin-top: calc(var(--nav-height) + 16px);
+	}
+	.atelic-ui .rd-plan h2 {
+		font-size: 27px;
+		font-weight: 650;
+		letter-spacing: -0.025em;
+		line-height: 1.1;
+		margin: 0;
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-plan-lead {
+		margin: 6px 0 0;
+		font-size: 16.5px;
+		color: var(--op-ink-soft);
+	}
+	.atelic-ui .rd-steps {
+		list-style: none;
+		counter-reset: rd-step;
+		margin: 12px 0 0;
+		padding: 0;
+		background: var(--op-card);
+		border: 1px solid var(--op-rule);
+		border-radius: var(--radius-md);
+		box-shadow: var(--shadow-sm);
+	}
+	.atelic-ui .rd-step {
+		counter-increment: rd-step;
+		display: grid;
+		grid-template-columns: auto minmax(0, 1fr);
+		column-gap: 12px;
+		padding: 14px 16px;
+	}
+	.atelic-ui .rd-step + .rd-step {
+		border-top: 1px solid var(--op-rule);
+	}
+	.atelic-ui .rd-step::before {
+		content: counter(rd-step);
+		display: inline-grid;
+		place-items: center;
+		width: 28px;
+		height: 28px;
+		border: 1.5px solid var(--op-accent);
+		border-radius: 999px;
+		color: var(--op-accent);
+		font-size: 14px;
+		font-weight: 700;
+		line-height: 1;
+	}
+	.atelic-ui .rd-step p {
+		margin: 3px 0 0;
+		color: var(--op-ink-soft);
+		text-wrap: pretty;
+	}
+	.atelic-ui .rd-step-title {
+		font-weight: 650;
+		color: var(--op-ink);
+	}
+	.atelic-ui .rd-step-who {
+		display: inline-block;
+		margin-left: 2px;
+		padding: 1px 8px;
+		border: 1px solid var(--neutral-200);
+		border-radius: 999px;
+		font-family: var(--font-mono);
+		font-size: 11px;
+		letter-spacing: 0.06em;
+		text-transform: uppercase;
+		vertical-align: 0.15em;
+		color: var(--op-ink-soft);
+	}
+
+	/* ---- the close: one line, then the sign off under its rule ---- */
+	.atelic-ui .rd-closing {
+		margin: 34px 0 0;
+		max-width: 62ch;
+		font-size: 17px;
+		line-height: 1.5;
+		color: var(--op-ink);
+	}
+
+	/* ---- wide and on paper: the pictures beside each other ---- */
+	@media print, (min-width: 721px) {
+		.atelic-ui .rd-gist-table tbody th[scope="row"],
+		.atelic-ui .rd-gist-table td,
+		.atelic-ui .rd-gist-table thead th,
+		.atelic-ui .rd-gist-tier th {
+			padding-left: 20px;
+			padding-right: 16px;
+		}
+		.atelic-ui .rd-shots[data-count="2"] {
+			grid-template-columns: repeat(2, minmax(0, 1fr));
+		}
+		.atelic-ui .rd-shots[data-count="3"] {
+			grid-template-columns: repeat(3, minmax(0, 1fr));
+		}
+	}
+
+	/* ---- print: the writeup's rules carry the page; these hold the read's
+	   own blocks whole ---- */
+	@media print {
+		.atelic-ui .rd-gist-card,
+		.atelic-ui .rd-steps {
+			box-shadow: none;
+			border-color: var(--neutral-200);
+		}
+		.atelic-ui .rd-gist-table tr,
+		.atelic-ui .rd-closing,
+		.atelic-ui .rd-why,
+		.atelic-ui .rd-step,
+		.atelic-ui .rd-close,
+		.atelic-ui .rd-shots .op-shot {
+			break-inside: avoid;
+		}
+		.atelic-ui .rd-beat h4,
+		.atelic-ui .rd-plan h2 {
+			break-after: avoid;
+		}
+	}
 }