@domandigital/craft 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -796,6 +796,13 @@ interface SnapshotSection {
     carousel?: boolean;
     /** Version 2: large standalone figures ("500+", "98%", "4.9/5") at 24px or more. */
     figures?: number;
+    /**
+     * Version 2, craft 0.13 and later: the section's visible text, one block per
+     * heading, paragraph, list item or quote, each at most 300 characters, at
+     * most 40. Navigation, buttons and footers are left out. What the
+     * specificity and proof tells read.
+     */
+    text?: string[];
 }
 type ImageRole = "photo" | "illustration" | "icon" | "avatar" | "logo";
 /**
@@ -907,10 +914,17 @@ interface Snapshot {
     /** Version 2: absent when the page could not be screenshotted. */
     visual?: SnapshotVisual;
     /**
-     * Version 2, craft 0.14 and later: every image on the page, largest first, at
+     * Version 2, craft 0.13 and later: every image on the page, largest first, at
      * most 60. Absent in older snapshots, which the imagery tells never judge.
      */
     images?: SnapshotImage[];
+    /**
+     * Version 2, craft 0.13 and later: the text a visitor reads before
+     * scrolling, at most 12 blocks. Navigation, a header without the headline,
+     * and the words on buttons and links are left out: this is the page's
+     * claim, not its menu or its calls to action.
+     */
+    firstScreenText?: string[];
     /** Set when a version 1 snapshot was read and upgraded in memory. */
     migratedFrom?: 1;
     /** The design-system measures trawl has collected since v7, kept so it can switch to this. */
@@ -1144,7 +1158,7 @@ interface CheckReport {
  * Bumped whenever an entry is added, removed or its detection changes, so a
  * report can say which list it was judged against.
  */
-declare const CATALOGUE_VERSION = "2026.09.11";
+declare const CATALOGUE_VERSION = "2026.09.12";
 declare const CATALOGUE: readonly Tell[];
 declare function tellById(id: string): Tell | undefined;
 /**
@@ -1326,6 +1340,252 @@ declare function namedSources(sentence: string): string[];
 declare function findClaims(files: SourceFile[]): ClaimsReport;
 declare function formatClaims(report: ClaimsReport, label?: string): string;
 
+/**
+ * Specificity: how much of a page only this business could have written.
+ *
+ * "Quality you can trust" fits every site in every trade. "Boilers fixed the
+ * same day in Brackley, from £85" fits one. The difference is countable: names,
+ * places, numbers, prices, dates, and the nouns of the trade. A page built
+ * from no brief has almost none, because the model had none to give.
+ *
+ * Pure over text. Two things keep the count honest:
+ *
+ * - A Title Case or all-capitals line carries no capital-letter information,
+ *   so its capitals are not read as names ("Quality You Can Trust" is not a
+ *   proper noun). Its numbers, trade nouns and brief terms still count.
+ * - The stock figures every site uses ("24/7", "100%", "5-star", "No. 1") are
+ *   masked before counting. They are numbers, not specifics.
+ *
+ * A brief (from `--brief`, `art-direction.json` or a null model) adds its own
+ * terms: the business's name, its town and its trade, recognised wherever
+ * they appear, even at the start of a sentence or in a shouted heading.
+ */
+
+type SpecificKind = FactKind | "trade" | "brief";
+interface Specific {
+    kind: SpecificKind;
+    /** As written. */
+    value: string;
+    /** Lower case, for comparing across pages. */
+    key: string;
+}
+interface Specificity {
+    words: number;
+    /** Each distinct specific once: repeating a town ten times does not make a page ten times more particular. */
+    specifics: Specific[];
+    /** Specifics that are not trade nouns: a name, place, number, price, date, contact detail or brief term. */
+    hard: number;
+    /** Distinct trade nouns. */
+    trade: number;
+    /** Distinct specifics per 100 words, to one decimal place. */
+    perHundred: number;
+    /**
+     * No hard specific and fewer than two trade nouns. One trade noun alone
+     * ("quality plumbing you can trust") is what every competitor in the trade
+     * also says.
+     */
+    generic: boolean;
+}
+/**
+ * Concrete nouns of the work, across the trades and local services the estate
+ * builds for. A seed list, grown from what the null models and client sites
+ * show. Deliberately absent: "services", "solutions", "projects", "work",
+ * "quality", which say nothing about what is done.
+ */
+declare const TRADE_NOUNS: readonly string[];
+/**
+ * Stock figures: numbers every site in every trade uses, masked before
+ * counting so they cannot pass for a fact.
+ */
+declare const STOCK_FIGURES: readonly RegExp[];
+declare const countWords: (text: string) => number;
+/**
+ * The brief's own terms: its names and places (capitalised words, even at the
+ * start of a sentence), its numbers, and its trade nouns.
+ */
+declare function briefTerms(brief: string): string[];
+/** Every distinct specific in the text. Lines are read one at a time: pass blocks separated by newlines. */
+declare function specifics(text: string, brief?: string): Specific[];
+/** How particular a text is. Pure. */
+declare function specificity(text: string, brief?: string): Specificity;
+/** What a page says where it makes its case: the first screen, and the sections that sell the work. */
+interface PageCopy {
+    url: string;
+    hero: string[];
+    services: string[];
+    /** Every line of page text: what the other page is checked against. */
+    all: string[];
+}
+/** Blocks as sentences, short fragments dropped. */
+declare function sentencesOf(blocks: string[]): string[];
+/**
+ * The hero and service copy of a snapshot. Null when the snapshot has no page
+ * text: one taken before craft recorded it.
+ */
+declare function pageCopy(snapshot: Snapshot): PageCopy | null;
+interface CopySide {
+    url: string;
+    /** Hero and service sentences read. */
+    sentences: number;
+    /** Of those, how many hold nothing the other page does not also say. */
+    interchangeable: string[];
+    /** interchangeable / sentences, or null with no sentences. */
+    share: number | null;
+    /** Specificity of the hero and service copy together. */
+    perHundred: number;
+}
+interface CompetitorComparison {
+    ours: CopySide;
+    competitor: CopySide;
+    /** A brief's terms were recognised on both pages. */
+    brief: boolean;
+}
+/**
+ * Which hero and service sentences either page could swap with the other:
+ * each holds no specific the other page lacks. A shared town or trade noun is
+ * not unique; the business's own name, its prices and its jobs are. Pure.
+ */
+declare function compareCompetitor(ours: PageCopy, competitor: PageCopy, brief?: string): CompetitorComparison;
+declare function formatCompetitor(result: CompetitorComparison): string;
+
+/**
+ * Shape features: how a short block of copy is built, not which words it uses.
+ *
+ * A three-sentence blurb can pass every vocabulary tell and still read as
+ * generated, because the tell is the construction: a parallel triad, a
+ * conditional stacked between commas, a close that hedges. The density tier
+ * cannot see this; it skips anything under 400 words.
+ *
+ * Pure and zero-dependency. The calibration scripts under `scripts/shape/`
+ * and any future calibrated tells call the same functions, so a published
+ * effect size describes the detector that ships.
+ *
+ * Several features stand in for part-of-speech measures (phrasal
+ * coordination, template skeletons) with word lists. They are approximate by
+ * design, and measured, not assumed, before anything ships on them.
+ */
+/** Sentences in a block. Abbreviations and decimals do not end one. */
+declare function splitSentences(text: string): string[];
+declare function words(text: string): string[];
+/** Words that carry grammar rather than content. Also the skeleton's kept set. */
+declare const FUNCTION_WORDS: Set<string>;
+/**
+ * "A, B and C" with short items. `parallel` when the items share their first
+ * word ("your business, your website and your systems"), the construction a
+ * model reaches for to sound complete.
+ */
+interface Tricolon {
+    text: string;
+    parallel: boolean;
+}
+declare function tricolons(sentence: string): Tricolon[];
+declare function stackedConditional(sentence: string): boolean;
+/** Commas plus subordinators: how many clauses a sentence stacks. */
+declare function clauseDepth(sentence: string): number;
+declare function hedgeCount(text: string): number;
+/** The last sentence ends the block on a qualifier or a condition. */
+declare function hedgedClose(sentences: string[]): boolean;
+declare function nominalisations(text: string): number;
+/**
+ * Present participial clauses: ", making it easy to..." after a comma, or a
+ * sentence that opens on a participle ("Building on this, ..."). Reported at
+ * 5.3 times the human rate in GPT-4o text (PMC11874169). `ing-tail` is a narrow
+ * form of this.
+ */
+declare function participialClauses(sentence: string): number;
+/**
+ * "X and Y" where both sides are single content words ("enquiries and admin",
+ * "clear and simple"). A word-list stand-in for phrasal coordination, reported
+ * at 1.9 times the human rate (PMC11874169). Not preceded by a comma, so a
+ * tricolon's last item is not counted twice.
+ */
+declare function phrasalCoordinations(sentence: string): number;
+/**
+ * A sentence reduced to its function words, with one `_` for each run of
+ * content words. Experimental: a stand-in for part-of-speech templates
+ * (Shaib et al., EMNLP 2024), which need a tagger craft does not carry.
+ */
+declare function skeleton(sentence: string): string[];
+/** Share of the block's skeleton 4-grams that occur more than once. */
+declare function skeletonRepeat(sentences: string[]): number;
+/** Coefficient of variation; null below `min` items, where it means nothing. */
+declare function cv(xs: number[], min: number): number | null;
+interface ShapeFeatures {
+    sentences: number;
+    words: number;
+    tricolons: number;
+    parallelTriads: number;
+    stackedConditionals: number;
+    /** Mean clauses per sentence. */
+    clauseDepth: number;
+    /** Sentence-length CV; null under three sentences. */
+    sentenceCv: number | null;
+    /** Hedges per 100 words. */
+    hedgeRate: number;
+    hedgedClose: boolean;
+    /** Nominalisations per 100 words. */
+    nominalisationRate: number;
+    pronounOpenerShare: number;
+    transitionOpenerShare: number;
+    impersonalOpenerShare: number;
+    commasPerSentence: number;
+    commasPer100: number;
+    /** Participial clauses per sentence. */
+    participialRate: number;
+    /** Phrasal coordinations per 100 words. */
+    coordinationRate: number;
+    /** Experimental. */
+    skeletonRepeat: number;
+}
+/** Every feature for one block of copy: a paragraph, a blurb, an email body. */
+declare function shapeOf(text: string): ShapeFeatures;
+/** How many distinct shape moves a block makes. What a reader reacts to is the stack. */
+declare function shapeMoves(f: ShapeFeatures): string[];
+/** Paragraph-length CV for a document of four or more paragraphs; null below. */
+declare function paragraphUniformity(paragraphs: string[]): number | null;
+/** A block the size of a blurb: 2 to 8 sentences, 20 to 160 words. */
+declare function isBlurb(f: Pick<ShapeFeatures, "sentences" | "words">): boolean;
+
+/**
+ * Specificity tells: a page that could belong to anyone.
+ *
+ * A model given no brief writes the claim every site makes, because it has
+ * nothing particular to say: "Quality you can trust", "Your vision, our
+ * expertise". And it asserts standing ("trusted", "fully qualified",
+ * "award-winning") with nothing next to the assertion to back it, because it
+ * has no reviews and no registration number to put there.
+ *
+ * Both are read from what the page says, not how it looks: `specificity.ts`
+ * counts the particulars.
+ */
+
+/**
+ * The home page's source, where the first claim is made: a root route file
+ * (`app/page.tsx`, `pages/index.tsx`, `src/pages/index.astro`, SvelteKit's
+ * root `+page.svelte`), a top-level `index.html`, or a hero or home component.
+ * Every other page's headline is a label ("Privacy policy", "Boiler
+ * repairs"), not a claim, and is not judged.
+ */
+declare const HOME_FILE: RegExp;
+/** A home page URL: the site root, `index.html`, or a locale root such as `/en-gb/`. */
+declare const HOME_URL: RegExp;
+/**
+ * A claim of standing: what a visitor has to take on trust unless something
+ * next to it backs it. Numbers of years are left out: those are checkable
+ * facts, and `craft copy claims` lists them.
+ */
+declare const STANDING_CLAIM: RegExp;
+/** Accreditation bodies, trade registers and review platforms, by the names they trade under. */
+declare const PROOF_NAMES: readonly string[];
+/** Every claim of standing with no review or accreditation in its section or the one either side. */
+declare function unprovenClaims(s: Snapshot): {
+    claim: string;
+    sentence: string;
+    section: string;
+}[];
+declare const SPECIFICITY_COPY_TELLS: CopyTell[];
+declare const SPECIFICITY_RENDERED_TELLS: RenderedTell[];
+
 /**
  * Baselines: adopt craft on a repo that already has findings, and fail only
  * on new ones.
@@ -1748,6 +2008,16 @@ declare const DISTANCE_WEIGHTS: {
 };
 /** Layout distance, 0 to 1: by role and geometry when both have them, else by kind as in version 1. */
 declare function layoutDistance(a: Fingerprint, b: Fingerprint): number;
+/** ΔE in OKLab. 0.02 is barely visible; by 0.3 two accents read as different colours. */
+declare const ACCENT_SCALE = 0.3;
+/** Grounds sit near white, where a smaller step already reads as a different paper. */
+declare const GROUND_SCALE = 0.15;
+/** A part at or below this distance counts as shared between two sites. */
+declare const SHARED_PART = 0.2;
+/** Two accents within this ΔE_OK read as the same colour family: about 6 on the familiar ΔE scale. */
+declare const ACCENT_SHARED: number;
+/** Two grounds within this ΔE_OK read as the same paper. */
+declare const GROUND_SHARED: number;
 declare function fingerprintDistance(a: Fingerprint, b: Fingerprint): FingerprintDistance;
 /**
  * The nearest neighbours of a fingerprint in a set, closest first. Typicality
@@ -1761,6 +2031,209 @@ declare function nearest<T>(target: Fingerprint, set: {
     distance: FingerprintDistance;
 }[];
 
+/**
+ * `art-direction.json`: what a site decided about how it looks, and why.
+ *
+ * CHARACTER.md's reason rule lives here. Every expressive choice records a
+ * `because` drawn from the client's real world (the shopfront, the van, the
+ * trade's own lettering, the place, the materials) and points at a source
+ * that shows it. A choice with no reason is a default, however good it looks.
+ *
+ * The file also carries the tell exceptions craft has read since phase A, in
+ * the same shape, so an existing file stays valid.
+ */
+
+/** What `craft direction init` writes. Version 1 files still validate, with a warning. */
+declare const DIRECTION_VERSION = 2;
+declare const DIRECTION_VERSIONS: readonly [1, 2];
+/** The customer's own words: evidence for the job map, never for a token. */
+declare const CUSTOMER_KINDS: readonly ["review", "enquiry", "conversation", "search"];
+type CustomerKind = (typeof CUSTOMER_KINDS)[number];
+/**
+ * Where a reason comes from. Deliberately physical: a mood board is not a
+ * source. Customer-voice kinds back the job map. A `reference` is visual
+ * inspiration from outside the client's category, and says where it is from.
+ */
+declare const SOURCE_KINDS: readonly ["livery", "shopfront", "signage", "packaging", "product", "uniform", "interior", "place", "material", "trade", "print", "photo", "founder", "review", "enquiry", "conversation", "search", "reference"];
+type SourceKind = (typeof SOURCE_KINDS)[number];
+interface DirectionSource {
+    /** Short id a choice refers to: "van", "fascia", "price-list". */
+    id: string;
+    kind: SourceKind;
+    /** What it is and where, in a sentence. */
+    note: string;
+    /** A photo or file in the repo, or a URL. */
+    path?: string;
+    /** Colours read off it by a person or by `craft direction propose`, as hex. */
+    colours?: string[];
+    /** Lettering seen on it: "hand-painted sign-writing", "stencilled capitals". */
+    lettering?: string;
+    /** Where a `reference` comes from: "letterpress print", "a railway station", "a bakery". Never the client's own trade. */
+    category?: string;
+}
+/** The expressive choices. Structure is the hierarchy layer, decided from the job. */
+declare const CHOICE_KEYS: readonly ["accent", "ground", "display", "body", "shape", "motif", "signature"];
+type ChoiceKey = (typeof CHOICE_KEYS)[number];
+interface DirectionChoice {
+    /** A colour as hex for accent and ground, a family name for display and body, words otherwise. */
+    value: string;
+    because: string;
+    /** Source ids this reason rests on. */
+    evidence: string[];
+}
+/** One part of the job: what it is, and the customer's words that show it. */
+interface JobPart {
+    value: string;
+    evidence: string[];
+}
+declare const CONSIDERATION: readonly ["low", "considered", "high"];
+type Consideration = (typeof CONSIDERATION)[number];
+/**
+ * What the visitor is trying to get done, from their side. Every hierarchy
+ * reason is checked against it, so it replaces "what do other sites in the
+ * trade do" as the starting point.
+ */
+interface JobMap {
+    /** Verb + object + context: "find" / "an electrician they can trust with a dangerous fault" / "today, without being overcharged". */
+    statement: {
+        verb: string;
+        object: string;
+        context: string;
+    };
+    functional: JobPart;
+    emotional: JobPart;
+    social: JobPart;
+    /** How long and how carefully they decide: an emergency call-out is low, a retained plan is high. */
+    consideration: {
+        value: Consideration;
+        because: string;
+        evidence: string[];
+    };
+    objections: string[];
+    /** Their own words, quoted from a cited source. */
+    language: string[];
+    /** The customer-voice sources the language is quoted from. */
+    evidence: string[];
+}
+/** Page types a hierarchy is declared for. Each page has its own job on the site. */
+declare const PAGE_TYPES: readonly ["home", "service", "about", "pricing", "booking", "contact", "article", "landing"];
+type PageType = (typeof PAGE_TYPES)[number];
+/** Where a call to action can sit: a section role, or the header, or pinned while scrolling. */
+type ActionPosition = SectionRole | "header" | "sticky";
+interface PageHierarchy {
+    primaryAction: {
+        value: string;
+        positions: ActionPosition[];
+        because: string;
+        evidence?: string[];
+    };
+    order: {
+        role: SectionRole;
+        because: string;
+    }[];
+    lead: {
+        value: string;
+        subordinate?: string[];
+        because: string;
+    };
+    journey: {
+        stage: string;
+        because: string;
+    }[];
+}
+declare const HIERARCHY_FIELDS: readonly ["primaryAction", "order", "lead", "journey"];
+interface ArtDirection {
+    $schema?: string;
+    version: (typeof DIRECTION_VERSIONS)[number];
+    client: string;
+    /** Who, where, and what they do, in a sentence or two. The brief a model would have been given. */
+    brief: string;
+    /** Version 2. */
+    job?: JobMap;
+    /** Version 2. Keyed by page type. */
+    hierarchy?: Partial<Record<PageType, PageHierarchy>>;
+    sources: DirectionSource[];
+    choices: Partial<Record<ChoiceKey, DirectionChoice>>;
+    exceptions?: TellException[];
+}
+type DirectionSeverity = "error" | "warn";
+interface DirectionProblem {
+    severity: DirectionSeverity;
+    /** Where in the file: "choices.accent.because", "sources[2].kind". */
+    at: string;
+    message: string;
+}
+interface DirectionReport {
+    valid: boolean;
+    problems: DirectionProblem[];
+    /** How many of the seven choices carry an accepted reason. */
+    decided: number;
+    /** Each layer on its own. A site is only decided when all three are. */
+    layers: {
+        job: boolean;
+        hierarchy: {
+            page: PageType;
+            decided: number;
+            total: number;
+        }[];
+        tokens: {
+            decided: number;
+            total: number;
+        };
+        /** Job decided, at least a home page hierarchy with every field decided, and five of seven tokens. */
+        complete: boolean;
+    };
+}
+
+/**
+ * The estate check before anything is built: declared art directions compared
+ * with each other, not rendered pages.
+ *
+ * `compareToEstate` catches two clients converging after both sites ship. By
+ * then the fix is a retrofit. This compares what each `art-direction.json`
+ * says it will be, so the convergence is caught while it is still a decision.
+ *
+ * The colour thresholds are the rendered check's own (`ACCENT_SHARED`,
+ * `GROUND_SHARED`), so the two checks agree on what "the same accent" means.
+ * It ranks and names what is shared; there is no sibling line until declared
+ * directions have been calibrated against the rendered estate.
+ *
+ * Pure.
+ */
+
+/** What an art direction commits to, as the estate register stores it. */
+interface DirectionSummary {
+    accent?: string;
+    ground?: string;
+    display?: string;
+    body?: string;
+    shape?: string;
+    /** The home page's running order. */
+    order?: SectionRole[];
+    primaryAction?: string;
+    positions?: string[];
+}
+declare function summariseDirection(d: Partial<ArtDirection>): DirectionSummary;
+interface DirectionComparison {
+    shared: string[];
+    accentDelta: number | null;
+    groundDelta: number | null;
+    /** Edit distance over the longer order, 0 to 1; null without both orders. */
+    orderDistance: number | null;
+    /** Worth a look before either is built. */
+    flagged: boolean;
+}
+declare function compareDirections(a: DirectionSummary, b: DirectionSummary): DirectionComparison;
+interface DirectionMatch extends DirectionComparison {
+    id: string;
+}
+/** Every site in the register with a declared direction, most shared first. */
+declare function compareToDeclared(target: DirectionSummary, sites: {
+    id: string;
+    direction?: DirectionSummary;
+}[], exclude?: string): DirectionMatch[];
+declare function formatDirectionMatches(label: string, matches: DirectionMatch[]): string;
+
 /**
  * The estate register: every site the agency has shipped, fingerprinted, so a
  * new one can be checked against its siblings. Signal 3 of CHARACTER.md.
@@ -1793,10 +2266,13 @@ interface EstateSite {
     url: string;
     /** Where the site's source lives, if known: "rmp474/RMP-Electrical". */
     repo?: string;
-    fingerprint: Fingerprint;
+    /** Absent for a direction registered before the site is built. */
+    fingerprint?: Fingerprint;
     /** Rendered tells found when it was added, for the record. */
     tells: string[];
     addedAt: string;
+    /** What its art-direction.json declares, so a new direction is checked before anything is built. */
+    direction?: DirectionSummary;
 }
 interface EstateRegister {
     version: typeof ESTATE_VERSION;
@@ -1808,7 +2284,7 @@ declare function addSite(register: EstateRegister, site: EstateSite): EstateRegi
 /**
  * What two fingerprints effectively share, named the way a person would see
  * it: "Fraunces headline", "no accent", "pill buttons". A part counts when its
- * distance is 0.2 or less.
+ * distance is `SHARED_PART` or less.
  */
 declare function sharedParts(a: Fingerprint, b: Fingerprint, d?: FingerprintDistance): string[];
 interface EstateMatch {
@@ -2131,67 +2607,132 @@ declare const VAGUE_WORDS: readonly ["innovative", "scalable", "end-to-end", "st
 declare const REVIEW_PHRASES: readonly ["great question", "of course!", "absolutely!", "absolutely,", "truly", "genuinely", "deeply", "ultimately", "one-size-fits-all", "one size fits all", "let me know if you'd", "the single most", "by far the most", "hands down the", "arguably the best", "bar none"];
 
 /**
- * `art-direction.json`: what a site decided about how it looks, and why.
+ * The reason rule, one standard for every layer of an art direction.
  *
- * CHARACTER.md's reason rule lives here. Every expressive choice records a
- * `because` drawn from the client's real world (the shopfront, the van, the
- * trade's own lettering, the place, the materials) and points at a source
- * that shows it. A choice with no reason is a default, however good it looks.
+ * A reason has to be specific enough that whoever reads the file next (a
+ * person, Claude, a future tool) cannot drift back to the category default
+ * while following it. "Freight Display, because MMM's photography needs to be
+ * the hero and the type needs to recede" passes. "Freight Display" does not,
+ * and neither does "a familiar structure so visitors feel comfortable".
  *
- * The file also carries the tell exceptions craft has read since phase A, in
- * the same shape, so an existing file stays valid.
+ * Wording rules catch the common ways a default gets dressed up as a reason.
+ * They are lexical, so they can be rephrased around; the tie is the real
+ * guard. A token's reason must mention what its evidence shows. A hierarchy
+ * reason must use this client's job: pasted onto another client's file, it
+ * has to fail.
+ *
+ * Pure.
  */
 
-declare const DIRECTION_VERSION = 1;
-/** Where a reason comes from. Deliberately physical: a mood board is not a source. */
-declare const SOURCE_KINDS: readonly ["livery", "shopfront", "signage", "packaging", "product", "uniform", "interior", "place", "material", "trade", "print", "photo", "founder"];
-type SourceKind = (typeof SOURCE_KINDS)[number];
-interface DirectionSource {
-    /** Short id a choice refers to: "van", "fascia", "price-list". */
-    id: string;
-    kind: SourceKind;
-    /** What it is and where, in a sentence. */
-    note: string;
-    /** A photo or file in the repo, or a URL. */
-    path?: string;
-    /** Colours read off it by a person or by `craft direction propose`, as hex. */
-    colours?: string[];
-    /** Lettering seen on it: "hand-painted sign-writing", "stencilled capitals". */
-    lettering?: string;
-}
-/** The expressive choices. Layout and navigation are not here: they stay conventional. */
-declare const CHOICE_KEYS: readonly ["accent", "ground", "display", "body", "shape", "motif", "signature"];
-type ChoiceKey = (typeof CHOICE_KEYS)[number];
-interface DirectionChoice {
-    /** A colour as hex for accent and ground, a family name for display and body, words otherwise. */
-    value: string;
-    because: string;
-    /** Source ids this reason rests on. */
-    evidence: string[];
-}
-interface ArtDirection {
-    $schema?: string;
-    version: typeof DIRECTION_VERSION;
-    client: string;
-    /** Who, where, and what they do, in a sentence or two. The brief a model would have been given. */
-    brief: string;
+declare const PROPOSED = "PROPOSED:";
+/**
+ * Reasons that are preferences, not evidence. "The client likes it" may be
+ * true and still say nothing about why this site should look this way.
+ */
+declare const PREFERENCE: RegExp;
+/** Adjectives that describe a mood rather than a source. Two or more and the reason is a mood board. */
+declare const MOOD: RegExp;
+/**
+ * A default stated as a reason. Three families: authority ("best practice"),
+ * the crowd ("what competitors do", "most salon sites") and familiarity
+ * ("a familiar layout", "what visitors are used to"). Each is the category
+ * average speaking, which is what the art direction exists to replace.
+ */
+declare const CONVENTION: RegExp;
+/** Content words, lower-case, with a possessive stripped and short words dropped. */
+declare function contentWords(text: string): Set<string>;
+/** Every word of the job a hierarchy reason may tie to. */
+declare function jobWords(job: JobMap): Set<string>;
+interface ReasonInput {
+    /** Where in the file: "choices.accent", "hierarchy.home.order[2]". Problems land at `${at}.because` and `${at}.evidence`. */
+    at: string;
+    because: unknown;
+    evidence?: unknown;
     sources: DirectionSource[];
-    choices: Partial<Record<ChoiceKey, DirectionChoice>>;
-    exceptions?: TellException[];
+    /**
+     * What the reason must be about.
+     *   source    mentions what its cited evidence shows (tokens)
+     *   customer  the same, and every cited source is the customer's own words (the job map)
+     *   job       uses this client's job (hierarchy); evidence optional
+     */
+    tie: "source" | "customer" | "job";
+    job?: JobMap;
 }
-type DirectionSeverity = "error" | "warn";
-interface DirectionProblem {
-    severity: DirectionSeverity;
-    /** Where in the file: "choices.accent.because", "sources[2].kind". */
-    at: string;
-    message: string;
+/** Problems with one reason. None means it counts as decided. */
+declare function checkReason(input: ReasonInput): DirectionProblem[];
+
+/**
+ * The job map: what the visitor is trying to get done, in their words.
+ *
+ * It replaces "what do other sites in the trade do" as the starting point.
+ * Hierarchy reasons are checked against it, so it has to describe this
+ * client's customer, not the category: "find an electrician they can trust
+ * with a dangerous fault, today" is a job; "electrician website" is a label.
+ *
+ * Pure. Quotes are checked against source text the caller can read.
+ */
+
+/** An object that is only trade nouns and website words: "electrician website", "a local salon site". */
+declare function isCategoryLabel(object: string, brief?: string): boolean;
+interface JobContext {
+    brief?: string;
+    /** Text of a cited source's file, when the caller can read it. */
+    readSource?: (source: DirectionSource) => string | undefined;
 }
-interface DirectionReport {
-    valid: boolean;
+declare function validateJob(job: unknown, sources: DirectionSource[], ctx?: JobContext): {
     problems: DirectionProblem[];
-    /** How many of the seven choices carry an accepted reason. */
+    decided: boolean;
+};
+
+/**
+ * The hierarchy layer: what each page puts first, where it asks, and why.
+ *
+ * A conventional order is allowed and never penalised. What fails is an
+ * order nobody chose: every field needs a reason that uses this client's job.
+ * The primary action's reason must also say how the job's consideration (a
+ * two-minute emergency call against a months-long decision) or one of its
+ * objections leads to where the ask sits. The evidence on placement is mixed,
+ * so craft encodes no default position; it requires the reason.
+ *
+ * Pure. The declared order is checked against a version 2 snapshot's section
+ * roles when one is given.
+ */
+
+declare const SECTION_ROLES: readonly SectionRole[];
+interface PageResult {
+    page: PageType;
     decided: number;
+    total: number;
+}
+declare function validateHierarchy(hierarchy: unknown, job: JobMap | undefined, sources: DirectionSource[]): {
+    problems: DirectionProblem[];
+    pages: PageResult[];
+};
+/** Roles a snapshot shows, in running order, without the unclassified ones. */
+declare function renderedOrder(snapshot: Snapshot): SectionRole[] | null;
+/** The declared order against the page that ships. Drift warns; `strict` makes it an error. */
+declare function checkOrder(declared: PageHierarchy | undefined, page: PageType, snapshot: Snapshot, strict?: boolean): DirectionProblem[];
+
+/**
+ * The research prompt for a new client: job material only.
+ *
+ * A research model asked "what do good electrician websites look like"
+ * returns the category average, because that is what it was trained on. So
+ * the prompt craft hands over asks only about the customer (their situation,
+ * objections, words, where they look) and forbids describing the category's
+ * sites. Visual references, when wanted, come from outside the category.
+ *
+ * Pure text. Nothing here calls a model.
+ */
+interface ResearchInput {
+    brief: string;
+    client?: string;
+    /** Add prompts for visual references from outside the category. */
+    visual?: boolean;
 }
+/** The trade words in a brief, for naming what not to research. */
+declare function tradeOf(brief: string): string[];
+declare function researchPrompt(input: ResearchInput): string;
 
 /**
  * Checking an art direction: the file's shape, the reason rule, and whether
@@ -2203,14 +2744,30 @@ interface DirectionReport {
 interface ValidateContext {
     /** The fingerprint of the rendered site, to check the file against what ships. */
     fingerprint?: Fingerprint;
+    /** The rendered page itself, to check the declared order against its section roles. */
+    snapshot?: Snapshot;
+    /** Which page the snapshot is. Default home. */
+    page?: PageType;
+    /** Drift between the file and the page is an error, for a pre-launch gate. */
+    strict?: boolean;
     /** Which cited paths exist, when the caller can look. */
     pathExists?: (path: string) => boolean;
+    /** Text of a cited source's file, for checking quoted customer language. */
+    readSource?: (source: DirectionSource) => string | undefined;
+    /** Declared directions of the other sites in the estate, to catch convergence before build. */
+    estate?: {
+        id: string;
+        direction?: DirectionSummary;
+    }[];
+    /** This site's id in the estate, left out of the comparison. */
+    estateId?: string;
 }
 declare function validateDirection(input: unknown, ctx?: ValidateContext): DirectionReport;
 
 /**
  * A first art-direction.json for a site that exists: what it does today,
- * written down, with every reason left empty.
+ * written down (its tokens and, from a version 2 snapshot, its running order),
+ * with every reason and the whole job map left empty.
  *
  * Empty on purpose. `validateDirection` fails the file until each choice has
  * a source and a reason, so the first thing init produces is the list of
@@ -2277,7 +2834,6 @@ declare function licencesJson(): string;
  * Pure. Pixels come in as numbers; the CLI decodes the images.
  */
 
-declare const PROPOSED = "PROPOSED:";
 interface PaletteColour {
     hex: string;
     /** Share of sampled pixels, 0 to 1. */
@@ -2301,6 +2857,11 @@ interface ProposeInput {
         id: string;
         fingerprint: Fingerprint;
     }[];
+    /** Accents other sites have declared but not yet shipped: a sibling can happen before either is built. */
+    declared?: {
+        id: string;
+        accent: string;
+    }[];
 }
 interface Proposal {
     key: ChoiceKey;
@@ -2390,4 +2951,4 @@ declare function characterReport(input: CharacterInputs, copyTells?: Set<string>
 
 declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
 
-export { AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type ComponentPair, type ComponentTypicality, type ContrastCheck, type ContrastReport, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, LICENCES, LIGHTNESS_CURVE, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROMO_BADGE, PROPOSED, PROVENANCE_SCAN_BYTES, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RenderedTell, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_AVATAR_HOSTS, STOCK_PHOTO_HOSTS, STOCK_PHRASES, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, closestComponents, compareFacts, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, craftTokens, createBaseline, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatClaims, formatComparison, formatHex, formatReport, globToRegExp, groundName, harvest, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, layoutDistance, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseBaseline, parseColour, parseCraftConfig, parseHex, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, severityExceptions, shapeName, sharedParts, shouldAnimate, siblingLine, stockAvatarSource, stockSource, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, typeFeatureTokens, typicality, validateDirection, visibleText, visualMeasures, wcagContrast, wordListsJson };
+export { ACCENT_SCALE, ACCENT_SHARED, AI_PHRASES, AI_SOURCE_TYPES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type ActionPosition, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, COMPONENT_ROLES, CONSIDERATION, CONVENTION, CUSTOMER_KINDS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type CompetitorComparison, type ComponentPair, type ComponentTypicality, type Consideration, type ContrastCheck, type ContrastReport, type CopySide, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, type CustomerKind, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DIRECTION_VERSIONS, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionComparison, type DirectionMatch, type DirectionProblem, type DirectionReport, type DirectionSource, type DirectionSummary, type DurationName, EASE, EASE_TUPLE, EDGE_STEP, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, FUNCTION_WORDS, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FingerprintSection, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, GROUND_SCALE, GROUND_SHARED, type Gamut, type Generation, HIERARCHY_FIELDS, HOME_FILE, HOME_URL, HOUSE, HOUSE_BUDGET, HOUSE_LOCKED, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, IMAGERY_TELLS, type ImageProvenance, type ImageRole, JSON_SCHEMA_VERSION, type JobContext, type JobMap, type JobPart, LICENCES, LIGHTNESS_CURVE, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_RUNS, MOOD, type MotionDecision, type MotionKind, type MultiClient, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PAGE_TYPES, PILL_LIMIT, PLAINER_WORDS, PREFERENCE, PROMO_BADGE, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, type PageHierarchy, type PageResult, type PageType, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, READABLE_SNAPSHOT_VERSIONS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, RENDERED_TELLS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type ReasonInput, type RenderedTell, type ResearchInput, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, type RgbaImage, SCALE, SECTION_ROLES, SHADCN_LIMIT, SHADCN_PRIMITIVES, SHARED_PART, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPECIFICITY_COPY_TELLS, SPECIFICITY_RENDERED_TELLS, SPRING, STANDING_CLAIM, STOCK_AVATAR_HOSTS, STOCK_FIGURES, STOCK_PHOTO_HOSTS, STOCK_PHRASES, type SarifOptions, type SarifTell, type SectionGeometry, type SectionKind, type SectionRhythmOptions, type SectionRole, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShapeFeatures, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotImage, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SnapshotVisual, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Specific, type SpecificKind, type Specificity, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type Tricolon, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, catalogueTable, characterReport, checkCopy, checkOrder, checkPair, checkReason, checkRestraint, choicesOf, clauseDepth, closestComponents, compareCompetitor, compareDirections, compareFacts, compareToDeclared, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, contentWords, countWords, craftTokens, createBaseline, cv, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, globToRegExp, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, jobWords, layoutDistance, licencesJson, makeSnapshot, motionTokens, namedSources, nearest, nominalisations, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, pageCopy, paletteFromPixels, paragraphUniformity, parseBaseline, parseColour, parseCraftConfig, parseHex, participialClauses, phrasalCoordinations, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, renderedOrder, researchPrompt, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeMoves, shapeName, shapeOf, words as shapeWords, sharedParts, shouldAnimate, siblingLine, skeleton, skeletonRepeat, specificity, specifics, splitSentences, stackedConditional, stockAvatarSource, stockSource, summariseDirection, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, tradeOf, tricolons, typeFeatureTokens, typicality, unprovenClaims, validateDirection, validateHierarchy, validateJob, visibleText, visualMeasures, wcagContrast, wordListsJson };