@atelic-action/artifact 4.1.0 → 4.2.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, 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 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 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.
 
-Five 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; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. 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.
+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.
 
 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.
 
@@ -33,6 +33,10 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 | `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` |
+| `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 |
 | `Gate`, `GateProps`, `GatePayload`, `GatePerson` | The sealed document, opened in the browser by the reader's own address, and the payload it opens | `/proposal` |
 | `normalizeEmail` | How a typed address becomes the key a payload opens with; the sealing command mirrors it | none |
 | `documents.css` | The documents' styles, at `@atelic-action/artifact/styles/documents.css` | every route |

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "4.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",
+	"version": "4.2.0",
+	"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",
 	"type": "module",
 	"license": "MIT",
 	"repository": {

package/src/documents/FirstCall.tsx

@@ -0,0 +1,325 @@
+import {
+	type ArtifactParagraph,
+	ArtifactAnchor as FirstCallAnchor,
+	Runs,
+	Shot,
+	type WriteupShot,
+} from "@atelic-action/ui/artifact";
+import { Callout, IconList } from "@atelic-action/ui/components";
+import { Chip } from "@atelic-action/ui/primitives";
+import { ArrowRight, MessageCircleQuestion } from "lucide-react";
+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.
+ *
+ * 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
+ * down the line, so it is written as a page they could read: everything
+ * on it is something we would show them or say to them, and it carries no
+ * desk instruction, no tracking, no prices, and no budget script. The method
+ * behind it (what goes in the brief, the open's three beats, which unit goes
+ * first, the posture in the room) is the practice repo's
+ * 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,
+ * 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
+ * beat every first call carries, set from the labels so no sheet can drop it.
+ */
+
+/** 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. */
+export interface FirstCallFact {
+	label: string;
+	body: FirstCallParagraph;
+	/** Sets the fact apart on a tinted ground, for the one that matters most. */
+	box?: boolean;
+}
+
+/** One numbered step of the open or the close. */
+export interface FirstCallStep {
+	/** The step, set in bold. */
+	label: string;
+	/** The words under it, e.g. the question as it would be asked. */
+	text?: string;
+}
+
+/** One thing to show: the line, where it opens live, and the picture of it. */
+export interface FirstCallShow {
+	text: string;
+	/** Where to open it on the call: in a new tab for an http(s) link, in place otherwise. */
+	href?: string;
+	/**
+	 * The picture, set beside the show lines at thumbnail size and opening
+	 * its `href` (the full capture behind a crop), or itself when there is none.
+	 */
+	shot?: WriteupShot;
+	/** Reads as broken rather than as needing work, for the line that is plainly wrong. */
+	broken?: boolean;
+}
+
+/** The ids the page takes for itself (the shell's main, the sheet's sections), which no unit's id may repeat. */
+export const firstCallSectionIds = ["main", "brief", "open", "close"] as const;
+
+/** One topic: what we show, the questions it raises, the moves it leads to. */
+export interface FirstCallUnit {
+	/** The anchor the unit chips jump to: lowercase, unique, and none of firstCallSectionIds. */
+	id: string;
+	title: string;
+	/** The unit in one breath, under its heading. */
+	tldr: string;
+	show: FirstCallShow[];
+	ask: string[];
+	move: string[];
+}
+
+/** The fixed words the sheet sets, each overridable through `labels`. */
+export interface FirstCallLabels {
+	preparedFor: string;
+	brief: string;
+	open: string;
+	unitsNav: string;
+	tldr: string;
+	show: string;
+	ask: string;
+	move: string;
+	close: string;
+	/** The beat every close ends on. */
+	whoElse: string;
+}
+
+export const firstCallLabels: FirstCallLabels = {
+	preparedFor: "Prepared for",
+	brief: "The Brief",
+	open: "Open",
+	unitsNav: "Units",
+	tldr: "TL;DR",
+	show: "Show",
+	ask: "Ask",
+	move: "Move",
+	close: "Close",
+	whoElse: "Who else decides, and should they join the next call?",
+};
+
+export interface FirstCallProps {
+	title: string;
+	/** Who the call is with, set in the dateline: "Prepared for <person, business>". */
+	preparedFor: string;
+	/** The when line: the date, the 24 hour time, the place, the minutes booked. */
+	when: string;
+	brief: FirstCallFact[];
+	/** A picture beside the brief, e.g. the business's map card. */
+	briefShot?: WriteupShot;
+	open: FirstCallStep[];
+	/** One per topic, as many as the call has. */
+	units: FirstCallUnit[];
+	/** The close's steps; who else decides follows them. */
+	close: FirstCallStep[];
+	labels?: Partial<FirstCallLabels>;
+}
+
+/** The unit's number as the sheet sets it: 01, 02, and on. */
+function unitNumber(index: number): string {
+	return String(index + 1).padStart(2, "0");
+}
+
+/** The read's numbered steps: the open and the close. */
+function Steps({ steps }: { steps: FirstCallStep[] }) {
+	return (
+		<ol className="rd-steps">
+			{steps.map((step, i) => (
+				// biome-ignore lint/suspicious/noArrayIndexKey: steps are static content in a fixed order, and a label may repeat
+				<li className="rd-step" key={i}>
+					<div className="rd-step-body">
+						<p className="rd-step-head">
+							<b className="rd-step-title">{step.label}</b>
+						</p>
+						{step.text && <p>{step.text}</p>}
+					</div>
+				</li>
+			))}
+		</ol>
+	);
+}
+
+/** The writeup's findings block: the callouts down the left, the pictures to the right. */
+function Findings({
+	items,
+	shots,
+	block = false,
+}: {
+	items: ReactNode[];
+	shots: WriteupShot[];
+	/** The block itself, as the writeup sets it, rather than inside a block under its heading. */
+	block?: boolean;
+}) {
+	const classes = [block && "op-block", "op-findings", shots.length > 0 && "has-shots"];
+	return (
+		<div className={classes.filter(Boolean).join(" ")}>
+			<div className="op-findings-list">{items}</div>
+			{shots.length > 0 && (
+				<div className="op-shots">
+					{shots.map((shot, i) => (
+						// biome-ignore lint/suspicious/noArrayIndexKey: shots are static content in a fixed order, and a picture may repeat
+						<Shot shot={{ ...shot, href: shot.href ?? shot.src }} key={i} />
+					))}
+				</div>
+			)}
+		</div>
+	);
+}
+
+function Unit({
+	unit,
+	index,
+	labels,
+}: {
+	unit: FirstCallUnit;
+	index: number;
+	labels: FirstCallLabels;
+}) {
+	const shows = unit.show.map((line, i) => (
+		<Callout
+			tone={line.broken ? "bad" : "warn"}
+			toneLabel={line.broken ? undefined : labels.show}
+			title={
+				line.href ? <FirstCallAnchor href={line.href}>{line.text}</FirstCallAnchor> : line.text
+			}
+			// biome-ignore lint/suspicious/noArrayIndexKey: show lines are static content in a fixed order
+			key={i}
+		/>
+	));
+	const shots = unit.show.flatMap((line) => (line.shot ? [line.shot] : []));
+	return (
+		<>
+			<div className="op-part" id={unit.id}>
+				<h2>
+					<span className="fc-unit-no">{unitNumber(index)}</span> {unit.title}
+				</h2>
+			</div>
+			<section className="op-topic">
+				<header className="op-topic-head">
+					<div>
+						<h3>{labels.tldr}</h3>
+						<p className="op-def">{unit.tldr}</p>
+					</div>
+				</header>
+				<div className="op-blocks">
+					{shows.length > 0 && (
+						<div className="op-block rd-beat fc-show">
+							<h4>{labels.show}</h4>
+							<Findings items={shows} shots={shots} />
+						</div>
+					)}
+					{unit.ask.length > 0 && (
+						<div className="op-block rd-beat fc-ask">
+							<h4>{labels.ask}</h4>
+							<IconList
+								icon={<MessageCircleQuestion size={16} />}
+								items={unit.ask.map((text) => ({ body: text }))}
+							/>
+						</div>
+					)}
+					{unit.move.length > 0 && (
+						<div className="op-block rd-beat fc-move">
+							<h4>{labels.move}</h4>
+							<IconList
+								icon={<ArrowRight size={16} strokeWidth={2.5} />}
+								items={unit.move.map((text) => ({ body: text }))}
+							/>
+						</div>
+					)}
+				</div>
+			</section>
+		</>
+	);
+}
+
+export function FirstCall({
+	title,
+	preparedFor,
+	when,
+	brief,
+	briefShot,
+	open,
+	units,
+	close,
+	labels: overrides,
+}: FirstCallProps) {
+	const labels = { ...firstCallLabels, ...overrides };
+	const facts = brief.map((fact, i) => (
+		<Callout
+			tone="info"
+			variant={fact.box ? "box" : "plain"}
+			title={fact.label}
+			// biome-ignore lint/suspicious/noArrayIndexKey: the brief is static content in a fixed order
+			key={i}
+		>
+			<Runs paragraph={fact.body} />
+		</Callout>
+	));
+	return (
+		<div className="op rd fc">
+			<article className="op-doc rd-doc">
+				<header className="op-head">
+					<p className="op-meta">
+						{labels.preparedFor} <b>{preparedFor}</b>
+						<span className="op-meta-sep" aria-hidden="true">
+							{" · "}
+						</span>
+						<span className="op-meta-date">{when}</span>
+					</p>
+					<h1>{title}</h1>
+				</header>
+
+				{facts.length > 0 && (
+					<section className="op-topic" id="brief">
+						<header className="op-topic-head">
+							<div>
+								<h3>{labels.brief}</h3>
+							</div>
+						</header>
+						<div className="op-blocks">
+							<Findings items={facts} shots={briefShot ? [briefShot] : []} block />
+						</div>
+					</section>
+				)}
+
+				{open.length > 0 && (
+					<section className="rd-plan" id="open">
+						<h2>{labels.open}</h2>
+						<Steps steps={open} />
+					</section>
+				)}
+				{/* Outside the read's plan section, whose link rule would restyle every chip as a prose link. */}
+				{units.length > 1 && (
+					<nav className="fc-units" aria-label={labels.unitsNav}>
+						{units.map((unit, i) => (
+							<Chip dot href={`#${unit.id}`} key={unit.id}>
+								{i + 1}. {unit.title}
+							</Chip>
+						))}
+					</nav>
+				)}
+
+				{units.map((unit, i) => (
+					<Unit unit={unit} index={i} labels={labels} key={unit.id} />
+				))}
+
+				<section className="rd-plan" id="close">
+					<h2>{labels.close}</h2>
+					<Steps steps={[...close, { label: labels.whoElse }]} />
+				</section>
+			</article>
+		</div>
+	);
+}

package/src/documents/documents.css

@@ -1,10 +1,10 @@
 /* The composed documents in this package: the sealed document stage (Gate),
-   the monthly page (Report), the writeup (Writeup), the note (Note), and the
-   read (Read). Moved from @atelic-action/ui's styles/artifact.css with the
+   the monthly page (Report), the writeup (Writeup), the note (Note), the
+   read (Read), and the first call sheet (FirstCall). Moved from @atelic-action/ui's styles/artifact.css with the
    documents (ATE-671), in the order that sheet bundled them, which the two
    @page rules depend on: the later one wins, and 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.
+   one. The note, the read, and the first call sheet follow the writeup and
+   set no @page, so the writeup's stays the one that wins.
 
    The pieces the documents share stay in @atelic-action/ui: the grade chip
    (.op-grade), the sign off (.op-who, .op-sign), the shot (.op-shot), the
@@ -2385,4 +2385,41 @@
 			break-after: avoid;
 		}
 	}
+
+	/* ---- the first call sheet (FirstCall): the writeup's topic and findings
+	   blocks and the read's steps carry it; these are the few rules it adds
+	   (the Claude Design cut of 2026-10-23) ---- */
+	.atelic-ui .fc-units {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 8px;
+		margin-top: 18px;
+	}
+	/* A long unit title wraps rather than pushing the phone page sideways. */
+	.atelic-ui .fc-units .chip {
+		white-space: normal;
+	}
+	.atelic-ui .fc-unit-no {
+		font-family: var(--font-mono);
+		font-weight: 500;
+		color: var(--primary);
+		margin-right: 6px;
+	}
+	.atelic-ui .fc .fc-ask .icon-list {
+		--tone: var(--ink);
+	}
+	.atelic-ui .fc .fc-move .icon-list {
+		--tone: var(--primary);
+	}
+	/* A show line links to where it opens live, but reads as a plain callout:
+	   the link takes the ink and shows itself on hover. */
+	.atelic-ui .fc-show .callout-title a {
+		color: inherit;
+		text-decoration: none;
+	}
+	.atelic-ui .fc-show .callout-title a:hover,
+	.atelic-ui .fc-show .callout-title a:focus-visible {
+		color: var(--primary);
+		text-decoration: underline;
+	}
 }

package/src/documents/index.ts

@@ -4,6 +4,7 @@
  * chip, the sign off, the page components, the button), which this package
  * depends on and never copies, and wears the styles in ./documents.css.
  */
+export * from "./FirstCall";
 export { Gate, type GatePayload, type GatePerson, type GateProps, normalizeEmail } from "./Gate";
 export * from "./Note";
 export * from "./Read";