@atelic-action/artifact 4.2.1 → 5.0.0

package/README.md

@@ -2,12 +2,12 @@
 
 The documents the practice hands or sends a business, as a published package and as the site a business's folder is cut from. This repo is two things at once:
 
-- **The package**, `@atelic-action/artifact` on npm: the composed documents (the writeup, the read, the monthly page, the note, the first call sheet, and the sealed document), each with its prop types and its default labels, and the stylesheet they wear. It ships `src/documents/` and nothing else, as source, the way `@atelic-action/ui` does, and depends on that package for every piece a document is built from.
+- **The package**, `@atelic-action/artifact` on npm: the composed documents (the read, the monthly page, the note, the first call sheet, and the sealed document), each with its prop types and its default labels, and the stylesheet they wear. It ships `src/documents/` and nothing else, as source, the way `@atelic-action/ui` does, and depends on that package for every piece a document is built from.
 - **The seed**: the routes, the content stubs, the config, the stub files the host finds by path, and the tests a new folder of `atelic-action/artifacts` is cut from, and the template site that shows every document on fictional content.
 
 Three layers, each a version the next depends on (ATE-671): `@atelic-action/ui` holds the pieces, this package holds the documents built from them, and each business's folder holds only its content, routes, and config. A document fix reaches a folder by bumping this package; a piece fix by bumping ui here, then this package in the folder.
 
-Six artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/the-read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause, with the plan in order between the gist and the cards; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page; and the **first call sheet** at `/first-call`, the desk's page for the first call with a business that booked off a cold first touch, used to guide the call and not sent for now, written so it could be shared with them later. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
+Five artifacts live in the template site: the **read** at `/the-read`, the graded document a business gets from the practice, built from one snapshot at one of two depths (a prospect's, from public readings alone; a customer's, from their own consoles as well), a web page first with its printed copy derived from it, the grades explained by cause with the plan in order between the scorecard and the cards; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page; and the **first call sheet** at `/first-call`, the desk's page for the first call with a business that booked off a cold first touch, used to guide the call and not sent for now, written so it could be shared with them later. The bare host sends a reader to the read. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
 
 The method behind them (the seven sections, the four grades from A to D, the rented line, what moved, and when an artifact is private) is the practice repo's `FOOTPRINT.md`. This repo builds to it and never restates it.
 
@@ -21,19 +21,18 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 
 | Export | What it is | Route |
 |---|---|---|
-| `Topic` | The writeup's section card on its own: the trade name linked to its definition, the one liner, the grade, the why line, the blocks, and the sources, with an `extra` slot after the blocks. The read renders its sections through it | `/writeup` |
-| `Writeup`, `WriteupProps` | The graded document an owner gets: the overview, the three tiers of section cards, the close | `/writeup` |
-| `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, all three re exported from ui | none |
-| `Read`, `ReadProps` | The baseline's grades explained by cause: the scorecard, a `ReportCard` with each row a link to its card, with an optional `note` callout over it for what the read leaves out; each section on the writeup's card (`ReadSection` extends `WriteupTopic`: the trade name linked to its definition, the one liner, the grade, the why line as the summary, the writeup's blocks, and the sources at the foot) plus the read's own today and after (a two column table) and what we recommend (a checklist). The plan, numbered and in order, sits between the gist and the cards, so the whole program reads before any one card's detail. A beat with no data is left out | `/the-read` |
-| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the scorecard's screen reader words, Today, After, Recommendations, the plan's heading), each overridable through `labels` | `/the-read` |
-| `ReadTier`, `ReadSection`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in. `ReadSection` is a `WriteupTopic` plus `gist`, `changes`, and `recommend`; its `why` and a finding's `body` take a paragraph (a string, or runs of text and links) as well as a node, so a routine can still write a read as JSON | none |
+| `TheRead`, `TheReadProps` | The graded document a business gets, built from one snapshot: the dated lede; the scorecard, a `ReportCard` with each row a link to its card and the earlier letter beside a row that moved, with an optional `note` callout over it for what the read leaves out; the plan, numbered and in order, between the scorecard and the cards, so the whole program reads before any one card's detail; then the tiers, each section on the card (the trade name linked to its definition, the one liner, the grade, the why line as the summary, the blocks, and the sources at the foot) plus the read's own today and after (a two column table) and what we recommend (a checklist), a tier opening on a `markets` table of letters and closing on the `rented` line when it has them; the closing line and the sign off. `access` says which depth it is (`"public"`, from public readings alone, or `"private"`, from the owner's consoles too), and a public read with no note gets the `publicNote` label over its scorecard. `print` adds the lockup and the twin's QR to the printed copy. A beat with no data is left out | `/the-read` |
+| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the scorecard's screen reader words, Before, Rented, Today, After, Recommendations, the plan's heading, the public note), each overridable through `labels` | `/the-read` |
+| `ReadAccess`, `ReadTier`, `ReadSection`, `ReadChange`, `ReadRecommendation`, `ReadMarkets`, `ReadMarketRow`, `ReadRented`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadPrint`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in. `ReadSection` is a `ReadTopic` plus `gist`, `before`, `changes`, and `recommend`; its `why`, a finding's `body`, a market row's `read`, and the rented `text` take a paragraph (a string, or runs of text and links) as well as a node, so a routine can write a read as JSON | none |
+| `Topic` | The section card on its own: the trade name linked to its definition, the one liner, the grade, the why line, the blocks, and the sources, with an `extra` slot after the blocks. The read renders every section through it | `/the-read` |
+| `ratingCell` | A star rating table cell for a `table` block, sorted by its figure | `/the-read` |
+| `ReadTopic`, `ReadBlock`, `ReadInnerBlock`, `ReadChecks`, `ReadTable`, `ReadBar`, `ReadScale`, `ReadStats`, `ReadColumns`, `ReadFindings`, `ReadShots`, `ReadMore`, `ReadBullet`, `ReadSource`, `ReadMark`, `ReadCell`, `ReadSorted`, `ReadTone` | The shapes a section card and its blocks are written in | none |
+| `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document, all three re exported from ui under ui's names | 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` |
 | `NoteLane`, `NoteFinding`, `NoteStart`, `NoteStep`, `NoteClose`, `NoteLink`, `NoteParagraph` | The shapes a note's content is written in | none |
-| `FirstCall`, `FirstCallProps` | The desk's sheet for the first call with a business that booked off a cold first touch: the brief with a picture beside it, the open as numbered steps, one unit per topic (a TL;DR, then show, ask, and move, each show line linked live with its picture opening the full capture), and the close, which always ends on who else decides. Not sent for now, but open like the host and shareable later, so it carries no desk instruction; it lives beside the writeup | `/first-call` |
+| `FirstCall`, `FirstCallProps` | The desk's sheet for the first call with a business that booked off a cold first touch: the brief with a picture beside it, the open as numbered steps, one unit per topic (a TL;DR, then show, ask, and move, each show line linked live with its picture opening the full capture), and the close, which always ends on who else decides. Not sent for now, but open like the host and shareable later, so it carries no desk instruction; it lives beside the read | `/first-call` |
 | `firstCallLabels`, `FirstCallLabels` | The fixed words the sheet sets (Show, Ask, Move, the close's who else decides beat, and the rest), each overridable through `labels` | `/first-call` |
 | `firstCallSectionIds` | The ids the page takes for itself (the shell's `main`, the brief, the open, the close), which a unit's `id` must not repeat; the content test checks it | none |
 | `FirstCallFact`, `FirstCallStep`, `FirstCallShow`, `FirstCallUnit`, `FirstCallParagraph` | The shapes a first call sheet's content is written in, all plain data, so a skill writes the sheet as JSON | none |
@@ -49,10 +48,10 @@ What a document is built from stays in `@atelic-action/ui`, and this package imp
 bun add @atelic-action/artifact @atelic-action/ui
 ```
 
-Peer dependencies: `@atelic-action/ui` at `^3.0.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
+Peer dependencies: `@atelic-action/ui` at `^3.4.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
 
 ```tsx
-import { Writeup } from "@atelic-action/artifact";
+import { TheRead } from "@atelic-action/artifact";
 import { buildPageHead } from "@atelic-action/ui/artifact";
 ```
 
@@ -66,7 +65,7 @@ The documents' sheet goes after every ui sheet and before the site's `theme.css`
 4. `@atelic-action/artifact/styles/documents.css`
 5. The site's `theme.css`, last
 
-Every rule in the sheet sits in the `atelic-ui` layer and under the `.atelic-ui` root class, exactly as ui's sheets do, so any rule a site writes outside a layer still wins over it. 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; their order is load bearing.
+Every rule in the sheet sits in the `atelic-ui` layer and under the `.atelic-ui` root class, exactly as ui's sheets do, so any rule a site writes outside a layer still wins over it. The sheet holds two `@page` rules, the monthly page's and then the read's, and the later one wins for every page a site prints; their order is load bearing.
 
 From 1.2.0 the two sheets do not overlap: ui 2.0.0's `artifact.css` holds only the pieces, and this sheet holds only the documents and both `@page` rules. A site on ui 1.x stays on artifact 1.1.x, which carries the shot's rules and the shell's print rules itself.
 
@@ -96,10 +95,10 @@ No environment variables required. Visit [http://localhost:5173](http://localhos
 
 A business's artifacts live in one folder of `atelic-action/artifacts`, 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 `artifacts`. 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.
+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 `the-read.tsx`, `access` says whether anything came from the owner's own consoles and the content test holds it to the host's; print flows the page across as many letter pages as it needs, and `theReadStops` 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`.
 3. **Config**, in `src/site.config.ts`. `url` is the host, `access` is `"public"` or `"private"` (private when anything came from the owner's own consoles), `recipient` is the business it was prepared for (with its `logo` under `/brand/`), `sender` is the practice, and `analytics` is the HubSpot loader so an open reports to the CRM, with `identify` naming who each link identifies so the open lands on that person's contact (`bun run reader <email>` mints a reader, sealed so no address ships in the page's script, and prints their link; a private artifact needs nobody listed, because the wall identifies whoever signs in; [DEPLOY.md](DEPLOY.md), Who Opened It).
-4. **The printed copy**: `bun build`, then `bun run print dist/client public/writeup.pdf`, which prints with every collapsible open and reports the sheet count, or `bun run print dist/client <out.pdf> 1 /report` for the monthly page, which fails if it misses its one sheet. Commit the writeup's PDF beside the page, and file a dated copy in the client's folder of the practice repo.
+4. **The printed copy**: `bun build`, then `bun run print dist/client public/the-read.pdf`, which prints with every collapsible open and reports the sheet count, or `bun run print dist/client <out.pdf> 1 /report` for the monthly page, which fails if it misses its one sheet. Commit the read's PDF beside the page, and file a dated copy in the client's folder of the practice repo.
 
 A private artifact deploys only behind the armed wall, which holds the screenshots, the PDF, and the built content chunks as well as the pages, and `bun run check:wall <short>.atelic.me` must pass before any link goes out ([ACCESS-GATE.md](ACCESS-GATE.md)).
 
@@ -128,7 +127,7 @@ The theme stays the practice's (Geist, ink, the orange) unless the artifact shou
 | `bun build` | Access guard + typecheck + build + prerender every page |
 | `bun test` / `bun test:run` | Tests (watch / once) |
 | `bun lint` / `bun lint:fix` | Biome check / auto fix |
-| `bun run print <url or dist/client> <out.pdf> [sheets] [page]` | Prints a page (the writeup unless named) through headless Chrome, reports the sheet count, and checks it when one is given |
+| `bun run print <url or dist/client> <out.pdf> [sheets] [page]` | Prints a page (the read unless named) through headless Chrome, reports the sheet count, and checks it when one is given |
 | `bun run check:wall <host> [path ...]` | Proves a private artifact's live host answers every document with the wall |
 | `bun run seal <config.json> [out.json]` | Seals a document for its named readers ([GATE.md](GATE.md)) |
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "4.2.1",
-	"description": "The composed documents the Atelic practice hands or sends a business (the writeup, the read, the monthly page, the note, the first call sheet, and the sealed document), built from the pieces in @atelic-action/ui",
+	"version": "5.0.0",
+	"description": "The composed documents the Atelic practice hands or sends a business (the read, the monthly page, the note, the first call sheet, and the sealed document), built from the pieces in @atelic-action/ui",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -37,12 +37,12 @@
 		"format": "biome format . --write"
 	},
 	"peerDependencies": {
-		"@atelic-action/ui": "^3.1.0",
+		"@atelic-action/ui": "^3.4.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0"
 	},
 	"devDependencies": {
-		"@atelic-action/ui": "^3.1.0",
+		"@atelic-action/ui": "^3.4.0",
 		"@biomejs/biome": "^2.0.0",
 		"@playwright/test": "^1.60.0",
 		"@sentry/react": "^10.0.0",

package/src/documents/FirstCall.tsx

@@ -14,7 +14,7 @@ import type { ReactNode } from "react";
  * The first call sheet: what the practice scans during the first call with a
  * business that booked off a cold first touch. The brief, the open, then one
  * unit per topic, each a show, an ask, and a move, then the close. It lives
- * at `<short>.atelic.me/first-call` beside the writeup it walks.
+ * at `<short>.atelic.me/first-call` beside the read it walks.
  *
  * The practice uses it to guide the call and does not send it for now, but
  * it is open like the rest of the host and may be shared with the business
@@ -26,8 +26,8 @@ import type { ReactNode } from "react";
  * Outreach/discovery.md, The First Call Set, and nothing here restates it.
  * The document owns only the shape.
  *
- * It is the writeup's and the read's sibling and wears their classes: the
- * writeup's topic and findings blocks for the brief and each unit's show,
+ * It is the read's sibling and wears its classes: the
+ * read's topic and findings blocks for the brief and each unit's show,
  * the read's numbered steps for the open and the close. Its own few rules
  * sit under fc- in documents.css. Every prop is plain data, so a skill can
  * write a sheet as JSON. The close always ends on who else decides, the one
@@ -37,7 +37,7 @@ import type { ReactNode } from "react";
 /** A paragraph: a plain string, or runs of text and links in order. */
 export type FirstCallParagraph = ArtifactParagraph;
 
-/** One line of the brief: who, how they booked, the listing, the writeup. */
+/** One line of the brief: who, how they booked, the listing, the read. */
 export interface FirstCallFact {
 	label: string;
 	body: FirstCallParagraph;
@@ -151,7 +151,7 @@ function Steps({ steps }: { steps: FirstCallStep[] }) {
 	);
 }
 
-/** The writeup's findings block: the callouts down the left, the pictures to the right. */
+/** The read's findings block: the callouts down the left, the pictures to the right. */
 function Findings({
 	items,
 	shots,
@@ -159,7 +159,7 @@ function Findings({
 }: {
 	items: ReactNode[];
 	shots: WriteupShot[];
-	/** The block itself, as the writeup sets it, rather than inside a block under its heading. */
+	/** The block itself, as the read sets it, rather than inside a block under its heading. */
 	block?: boolean;
 }) {
 	const classes = [block && "op-block", "op-findings", shots.length > 0 && "has-shots"];

package/src/documents/Note.tsx

@@ -19,8 +19,8 @@ import { Callout } from "@atelic-action/ui/components";
  * what sits under the hood, where the work would start, and the close. It
  * reads on a phone first and prints to one letter sheet.
  *
- * It is the writeup's sibling, not a variant of it: a site wraps it in
- * ArtifactShell exactly as it wraps the writeup, and it reuses the writeup's
+ * It is the read's sibling, not a variant of it: a site wraps it in
+ * ArtifactShell exactly as it wraps the read, and it reuses the read's
  * pieces where they fit (the Callout a finding is set in, the owner's screen,
  * the sign off). Every prop is plain data, so a routine can write a note as
  * JSON; the one exception is the sign off person's `role`, which takes a node

package/src/documents/Report.tsx

@@ -13,7 +13,7 @@ import type { ReactNode } from "react";
  * the leads block answering the four questions the Statement of Work
  * promises, in that order, each a figure and one plain sentence; then the
  * seven grades with what moved since last month and since the baseline; then
- * the sign off. It wears the writeup's grade chip and sign off, and the
+ * the sign off. It wears the read's grade chip and sign off, and the
  * artifact shell's header on screen; print drops the header and the credit
  * band, so the sheet is the document alone.
  */
@@ -55,7 +55,7 @@ export interface ReportProps {
 	leads: ReportLeads;
 	/** The seven sections, in the footprint's order. */
 	grades: ReportGradeRow[];
-	/** The sign off, the same lockup the writeup closes on. */
+	/** The sign off, the same lockup the read closes on. */
 	close: { signOff: string; person: WriteupPerson };
 }