@domandigital/craft 0.14.0 → 0.16.0

package/dist/index.d.cts

@@ -1448,6 +1448,158 @@ interface CompetitorComparison {
 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;
+
+/**
+ * Lexical and specificity features for a short block of copy.
+ *
+ * The sentence-shape features (shape.ts) did not separate model copy from
+ * people's at blurb length. These measure what a block says and which words it
+ * reaches for: how many of the tell words and phrases craft already lists, how
+ * many words with published excess-use evidence, and how particular the block
+ * is (names, places, figures, the nouns of the trade).
+ *
+ * Pure and zero-dependency, and used both by the calibration scripts and by
+ * any tell that ships on the result.
+ *
+ * Every word in STUDY_WORDS carries its source. Models change what they
+ * over-use between generations (Juzek and Ward found "boasts" gone and
+ * "underscore" up sharply from GPT-3.5 to GPT-4o-mini), so a listed word is a
+ * measurement with a date, not a fact about models.
+ */
+interface StudyWord {
+    word: string;
+    source: string;
+}
+/**
+ * Words with published excess-use evidence. Academic register, so a word here
+ * is a candidate to measure in marketing copy, not a tell.
+ */
+declare const STUDY_WORDS: readonly StudyWord[];
+/** Every word or phrase the features look for, with where it came from. */
+declare function vocabulary(): {
+    word: string;
+    source: string;
+}[];
+/** Occurrences per vocabulary word in the text. */
+declare function vocabularyCounts(text: string): Map<string, number>;
+interface LexicalFeatures {
+    /** Hits from craft's own tell lists, per 100 words. */
+    listRate: number;
+    /** Hits from the published excess-use words, per 100 words. */
+    studyRate: number;
+    /** Distinct specifics (names, places, figures, dates, contact details, brief terms) per 100 words. */
+    hardPer100: number;
+    /** Distinct trade nouns per 100 words. */
+    tradePer100: number;
+    /** All specifics per 100 words. */
+    specificsPer100: number;
+    /** 1 when there is no hard specific and fewer than two trade nouns. */
+    generic: number;
+    /** Distinct money, date, time and number specifics. */
+    figures: number;
+    /** Distinct names and brief terms. */
+    names: number;
+}
+declare const LEXICAL_FEATURES: readonly (keyof LexicalFeatures)[];
+declare function lexicalOf(text: string, brief?: string): LexicalFeatures;
+
 /**
  * Specificity tells: a page that could belong to anyone.
  *
@@ -1910,6 +2062,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
@@ -1923,6 +2085,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.
@@ -1955,10 +2320,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;
@@ -1970,7 +2338,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 {
@@ -2035,9 +2403,18 @@ interface NullRun {
 interface NullModel {
     version: typeof NULL_VERSION;
     brief: string;
+    /**
+     * The prompt each page was built from. For imported pages, the prompt the
+     * person was asked to give the builder: `craft null prompt` prints it.
+     */
     prompt: string;
-    /** What was asked for with --model, or "default". */
+    /** What was asked for with --model, or "default"; "unknown" for imported pages unless given. */
     model: string;
+    /**
+     * The tool that built the pages, when they were imported rather than
+     * generated here: "v0", "lovable". Absent for `craft null build`.
+     */
+    builder?: string;
     catalogueVersion: string;
     builtAt: string;
     runs: NullRun[];
@@ -2293,67 +2670,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
@@ -2365,14 +2807,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
@@ -2439,7 +2897,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. */
@@ -2463,6 +2920,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;
@@ -2477,6 +2939,90 @@ declare function propose(input: ProposeInput): {
     direction: ArtDirection;
 };
 
+/**
+ * Calibration: how well the catalogue separates pages a person has labelled.
+ *
+ * A labelled set holds three kinds of page. `ai` pages were generated. `human`
+ * pages were made by people. `ai-looking` pages were made by people and still
+ * read as generated to someone who looks at many sites: they are what the
+ * tells are for, since a tell detects a look, not a maker. So a tell's hit on
+ * an `ai` or an `ai-looking` page counts for it, and a hit on a `human` page
+ * counts against it.
+ *
+ * The verdict is the one CHARACTER.md fixed before any result was read: a page
+ * is flagged when it is typical against the null models, or tell-heavy (three
+ * or more distinct design tells). With no null models, tell-heavy decides.
+ *
+ * The targets are CHARACTER.md's first three. Target 4 (no siblings in the
+ * estate) is `craft estate compare`; target 5 (people cannot tell) is the blind
+ * test in docs/blind-test.md, which no tool here can run.
+ *
+ * Pure. Taking snapshots and reading files lives in the CLI.
+ */
+declare const LABELS: readonly ["ai", "ai-looking", "human"];
+type Label = (typeof LABELS)[number];
+/** Targets 1 and 3: this share of the set flagged, or more. */
+declare const FLAGGED_TARGET = 0.9;
+/** Target 2: this share of the human set typical, or less. */
+declare const HUMAN_TYPICAL_TARGET = 0.1;
+interface MeasuredPage {
+    id: string;
+    label: Label;
+    /** Every catalogue tell found on the page, each once. */
+    tells: string[];
+    /** Findings in the blocking tier. */
+    blocking: number;
+    /** Against the pooled null models; absent when none were given. */
+    typicality?: {
+        score: number;
+        typical: boolean;
+    };
+}
+interface UnmeasuredPage {
+    id: string;
+    label: Label;
+    reason: string;
+}
+interface LabelSummary {
+    label: Label;
+    pages: number;
+    flagged: number;
+    typical: number | null;
+    tellHeavy: number;
+    blocking: number;
+}
+interface TellRate {
+    tell: string;
+    hits: Record<Label, number>;
+    /** Hits on `ai` and `ai-looking` pages over all hits. */
+    precision: number;
+    /** `ai` and `ai-looking` pages hit, over all of them measured. Null when there are none. */
+    recall: number | null;
+}
+interface TargetCheck {
+    target: string;
+    /** Null when no page with that label was measured. */
+    met: boolean | null;
+    detail: string;
+}
+interface Calibration {
+    pages: number;
+    /** Whether typicality was measured, or tell-heavy alone decided. */
+    typicality: boolean;
+    labels: LabelSummary[];
+    tells: TellRate[];
+    /** Catalogue tells that fired on no page. */
+    silent: string[];
+    targets: TargetCheck[];
+    unmeasured: UnmeasuredPage[];
+}
+/** Tells about the look, not the words: what "tell-heavy" counts. */
+declare function designTells(tells: string[]): string[];
+declare function isFlagged(page: MeasuredPage): boolean;
+declare function calibrate(pages: MeasuredPage[], unmeasured?: UnmeasuredPage[]): Calibration;
+/** `notes` are lines the caller knows and the numbers do not show, printed under the heading. */
+declare function formatCalibration(c: Calibration, notes?: string[]): string;
+
 /**
  * The character report: the three signals and the reason rule, read together.
  *
@@ -2552,4 +3098,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 CompetitorComparison, type ComponentPair, type ComponentTypicality, type ContrastCheck, type ContrastReport, type CopySide, 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, 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, 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, PROOF_NAMES, PROPOSED, PROVENANCE_SCAN_BYTES, type PageCopy, 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, 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 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 TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, closestComponents, compareCompetitor, compareFacts, compareToEstate, componentDistance, componentShared, componentTypicalities, componentTypicality, componentsOf, countWords, craftTokens, createBaseline, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatClaims, formatComparison, formatCompetitor, 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, pageCopy, paletteFromPixels, parseBaseline, parseColour, parseCraftConfig, parseHex, propose, protectedFacts, ramp, rampFromAnchors, readSnapshot, retrofitPlan, runTell, scanProvenance, scanSource, sectionRhythm, semantic, sentencesOf, severityExceptions, shapeName, sharedParts, shouldAnimate, siblingLine, specificity, specifics, stockAvatarSource, stockSource, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, typeFeatureTokens, typicality, unprovenClaims, 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 Calibration, 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, FLAGGED_TARGET, 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, HUMAN_TYPICAL_TARGET, 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, LABELS, LEXICAL_FEATURES, LICENCES, LIGHTNESS_CURVE, type Label, type LabelSummary, type LexicalFeatures, type LicenceEntry, type LicenceSubject, MIN_DECIDED, MIN_RUNS, MOOD, type MeasuredPage, 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, STUDY_WORDS, 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 StudyWord, type Surface, TELL_HEAVY, TRADE_NOUNS, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type TargetCheck, type Tell, type TellException, type TellRate, type Tricolon, type TypeStep, type Typicality, type UnmeasuredPage, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, briefTerms, calibrate, 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, designTells, emitCss, emptyEstate, estateComponentPairs, estatePairs, exitDuration, extractHtml, faceLicence, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatCalibration, formatClaims, formatComparison, formatCompetitor, formatDirectionMatches, formatHex, formatReport, globToRegExp, groundName, harvest, hedgeCount, hedgedClose, hexToOklch, holdHouseBlocks, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isBlurb, isCategoryLabel, isCream, isFlagged, jobWords, layoutDistance, lexicalOf, 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, vocabulary, vocabularyCounts, wcagContrast, wordListsJson };