@domandigital/craft 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @domandigital/craft
 
+## 0.17.0
+
+### Minor Changes
+
+- ef257c9: Add `craft register`: briefs for writing in four registers (plain, persuasive, warm, literary), and a review-only check that places a document of five paragraphs or more against human baselines for the chosen register. New exports: `registerOf`, `REGISTER_FEATURES`, `REGISTERS`, `registerBrief`, `checkRegister`, `PROFILE`. `REGISTERS.md` ships in the package.
+
+### Patch Changes
+
+- 000f345: `craft calibrate` now says plainly that "flagged" is a look-closer signal, not a verdict that a site is AI-made. No threshold changed.
+- 539b760: A labelled page, a null page and an imported page now count as a home page, so `generic-hero-claim` can fire on them. Before, every local `file://` page read as an inner page and the tell could never fire on a labelled or null set. `Snapshot` gains an optional `home`; absent, the URL decides as before. `craft calibrate` takes `home: false` on a label entry, and its per-tell table shows each tell's catalogue generation.
+
+## 0.16.0
+
+### Minor Changes
+
+- 6545c2e: Calibration tooling. `craft null import <dir> --builder <name> --brief "<text>"` builds a null model from pages another builder made (v0, Lovable), each an HTML file or a folder holding a built `index.html`, served on loopback so root-relative assets resolve. `craft null prompt` prints the prompt to give that builder. `craft calibrate <labels.json>` measures a labelled set (`ai`, `human`, `ai-looking`) and reports precision and recall per tell and CHARACTER.md's first three targets; a page it cannot measure is listed and never counts as a pass. `NullModel` gains an optional `builder`. The blind-test protocol for target 5 is in `docs/blind-test.md`.
+- cb7317e: Lexical and specificity measurement. New exports `lexicalOf`, `vocabulary`, `vocabularyCounts`, `LEXICAL_FEATURES`, `STUDY_WORDS` and the `LexicalFeatures` and `StudyWord` types compute how often a block uses craft's own tell words and the published excess-use words, and how particular it is (names, places, figures, trade nouns). Every study word carries its source paper. Measured against the frozen human baselines and the Claude set, no feature met the ship rule, so no tell is added and `CATALOGUE_VERSION` is unchanged; the result is in `calibration/copy-shape/report-lexical.md`.
+
 ## 0.15.0
 
 ### Minor Changes

package/CHARACTER.md

@@ -826,6 +826,53 @@ generated-looking site" and is left out by definition. Snapshots and
 - Both house demos had expired or gated previews on the day. They are not
   measured, not clean.
 
+### Calibration tooling, 2026-09-24
+
+`craft calibrate calibration/labels.json` now does what the `score.mjs`
+scripts did by hand. `labels.json` lists the set:
+
+- the 20 AI-set pages;
+- the seven measured human references, with the two gated previews listed as
+  skipped;
+- wiredge.studio as the first `ai-looking` page: made by people, and it reads
+  as generated.
+
+`calibrate` reports precision and recall per tell and checks targets 1 to 3.
+Its rules:
+
+- A hit on an `ai` or `ai-looking` page counts for a tell, and a hit on a
+  `human` page counts against it, because a tell detects a look, not a maker.
+- Flagged keeps the rule fixed on 2026-09-23: typical against the pooled null,
+  or three or more distinct design tells.
+- A page it cannot measure is listed by name and counted neither way.
+
+`craft null import` builds a null model from another builder's pages, so the
+AI set and the null can include more than Claude. Give each builder the prompt
+`craft null prompt` prints, so its pages answer the same brief.
+
+Target 5, the blind test, is a protocol for people, not a command: see
+`docs/blind-test.md`.
+
+**First run, 2026-09-29** (`craft calibrate calibration/labels.json --fresh`, Playwright driving a headless Chrome through `CRAFT_CHROMIUM`, every page re-snapshotted on the current snapshot version; results in `calibration/results/2026-09-29/`). Against 140 null pages from 7 briefs:
+
+| Target | Result |
+| --- | --- |
+| 1. Generated pages get caught | met: 20 of 20 flagged |
+| 2. Good human sites don't get caught | met on its definition: 0 block hits, 0 of 6 typical. 3 pages not measured: two preview gates and myndex.com, unreachable from this machine |
+| 3. AI-looking sites get caught | met: 1 of 1 (wiredge.studio), one page, so weak evidence |
+
+Read the second row with care. The flagged rule (typical against the null, or three or more distinct design tells) flagged 5 of the 6 measured human sites as tell-heavy, though none is typical and none has a blocking tell. Target 2 as written does not count that. If the rule is meant to say "this looks AI-made", 5 of 6 is a false-positive problem to fix before anything gates on it. It would want a decision on the target, not a quiet threshold change. The set is also small (20 AI, 6 human, 1 AI-looking), all AI pages are Claude's, and 46 of 68 tells never fired on it. Target 4 (the estate) and target 5 (the blind test) are not measured by this command.
+
+**Wider human set, 2026-09-29** (`calibration/results/2026-09-29-wider/`). The human set grew from 6 to 36 measured sites: 20 professionally built well-known sites and 12 live UK small-business sites from the Wayback seed list, plus the original six. The AI and AI-looking sets are unchanged (20 and 1).
+
+| Target | Result |
+| --- | --- |
+| 1. Generated pages get caught | met: 20 of 20 |
+| 2. Good human sites don't get caught | met on its definition: 0 block hits, 0 of 36 typical. 5 not measured (two preview gates, myndex.com unreachable, screwfix.com 403, mubi.com 503) |
+| 3. AI-looking sites get caught | met: 1 of 1, still one page |
+
+The caveat from the first run holds and is now firmer. The flagged rule marked **14 of 36 human sites (39%)** as tell-heavy. It needs either a tighter rule or to stop being read as "looks AI-made". No threshold was changed; that is a decision on the target. Per-tell precision on this set also separates the tells that earn their keep from the ones that do not: `icon-tile-grid` 0.17, `generic-hero-claim` 0.14, `marquee` 0.14, `grid-background` 0.20 and `unproven-claim` 0.36 fire more on human sites than on the AI set, while `cream-palette`, `reflex-font-2`, `italic-serif-display` and `pricing-trio-popular` are at 0.93 or better. 42 of 68 tells never fired. The human sites are not a random sample: they are chosen, well-made and mostly large-brand, and the AI pages are all Claude's. `generic-hero-claim` is 0 of 20 on the AI set because the briefs name a business and a place, so the pages open with a specific line ("Exeter's sole traders", "Chandos Road, Redland"), and the tell is right not to fire on them. It is not a home-page bug: after dd-packages #76 made labelled and null pages count as home pages, the same snapshots re-scored on 2026-09-30 give 0 of 20 on the AI set and 7 of 36 on the human set (one more human hit than the 6 above), and the flagged counts are unchanged (20 of 20 AI, 14 of 36 human). Still to do: an AI set from other builders (`craft null import`), and a decision on the flagged rule.
+
 ### Character report first read, 2026-09-23
 
 `craft report` on each live snapshot with its repo, its own brief's null and
@@ -926,3 +973,7 @@ Catalogue version `2026.09.12`, 68 tells.
 | `no-real-imagery` | 1 | rendered | warn | No photograph on the page | A page with no photograph at all, only icons and illustrations, is the page a model builds when it has no assets. Icon tiles stand in for the evidence a buyer looks for: the work, the premises, the people. |
 | `unproven-claim` | 1 | rendered | warn | Claim with no proof next to it | "Trusted", "fully qualified" and "award-winning" ask the visitor to take the business's word for it. A page built with no reviews and no registration number makes the claim anyway, with nothing beside it. |
 <!-- craft:catalogue:end -->
+
+### Decision on the flagged rule (2026-09-30)
+
+Closed without changing the threshold. The rule was fixed before any result was read, and retuning it on the 56 pages it was measured on would break that. "Flagged" is a **look-closer signal**, not a verdict that a site is AI-made: it catches AI pages reliably (20 of 20) and also marks well-made human sites (14 of 36) that share a few common design habits. Nothing gates on it. Any change to the rule or to the five weak tells (`icon-tile-grid`, `generic-hero-claim`, `marquee`, `grid-background`, `unproven-claim`) must be judged on a fresh human set, not this one. Follow-up, not blocking: an AI set from other builders via `craft null import` (v0, Lovable and similar), which needs pages from those builders.

package/COPY.md

@@ -194,6 +194,11 @@ and confident, never matey: no over-familiar asides ("with me nowhere near
 it"), no American idiom ("shallow wins", "looks busy"), no "honestly" as an
 intensifier. Do not change a brand name, domain or legal entity wording.
 
+For a register other than the house one (plain, persuasive, warm, literary),
+see `REGISTERS.md`: a brief to read before drafting, and a check that places
+a document of five paragraphs or more against human baselines. It reports
+where a draft sits; a person still decides whether the register is right.
+
 ## Word limits
 
 | Element | Limit |

package/README.md

@@ -170,6 +170,14 @@ sentence a reader would take as a checkable fact, marked `sourced` (a source is
 named) or `UNSOURCED`, for a person to check against the primary source. It
 always exits 0: a checklist, not a verdict.
 
+To write in a chosen register (plain, persuasive, warm, literary), read the
+brief before drafting and check a finished document after. See `REGISTERS.md`.
+
+```bash
+npx craft register brief warm                  # what to do before drafting
+npx craft register check letter.md --as warm   # five paragraphs or more; never fails
+```
+
 The same checks run in code:
 
 ```ts

package/REGISTERS.md

@@ -0,0 +1,163 @@
+# Writing in a register
+
+**Canonical.** How to write in a chosen register, and how to check where a
+draft sits. `COPY.md` says what every piece of house copy avoids; a register
+says what a draft reaches for.
+
+| Register | For |
+| --- | --- |
+| `plain` | forms, policies, instructions, professional services |
+| `persuasive` | landing pages, service pages, adverts, sales emails |
+| `warm` | customer emails, enquiry replies, newsletters |
+| `literary` | premium brands, makers, hospitality |
+
+## Using it
+
+1. **Before drafting**, read the brief: `craft register brief warm`. Paste it
+   into a prompt if a model is drafting.
+2. **After drafting**, run `craft copy <file>` as always. The blocking tier
+   and the proof rule hold in every register.
+3. **For a document of five paragraphs or more**, run
+   `craft register check <file> --as warm`. It lists the style features that
+   fall outside the usual range for that register, and which human baseline
+   the draft reads closest to. It never fails a run.
+
+## What the check can and cannot do
+
+It measures style, not content: sentence length, commas, clauses,
+nominalisations, pronoun openers, paired phrases, contractions, person and
+passive voice. Names, figures and specifics are left out, because they say
+what a text is about, not how it is written.
+
+It needs five paragraphs of two to eight sentences each. In
+`calibration/copy-shape/report-registers.md`, single passages from different
+registers overlap too much to place (26 of 258 pair tests separate), while
+five-paragraph averages separate every register pair (78 of 258). Anything
+shorter gets the brief, not a measurement.
+
+Each range is the middle 80% of human documents, so one in five human
+documents falls outside any single range. Read the findings as a
+read-through. They are not a grade.
+
+Each brief is compared with the nearest free human baseline, and none is
+exact:
+
+| Brief | Baseline | Not quite |
+| --- | --- | --- |
+| `plain` | Hansard Commons, 2010 to 2019 | edited debate, not plain writing |
+| `persuasive` | UK small-business websites before 2021 | 715 passages only |
+| `warm` | Enron sent email, 1999 to 2002 | corporate and American |
+| `literary` | English fiction and essays, 1726 to 1925 | older than any brand |
+
+The bands in `src/register/profile.ts` are generated by
+`node scripts/shape/registers.mjs --profile`. Rerun it after adding a
+baseline; never edit the file by hand.
+
+## The briefs
+
+Generated from `src/register/registers.ts` by
+`pnpm --filter @domandigital/craft run docs`. Edit the data, not this block.
+
+<!-- craft:registers:start -->
+## Plain and trustworthy (`plain`)
+
+**Use for:** Forms, policies, terms, instructions, and professional services where the reader must act correctly.
+
+**Before you draft:**
+
+1. Put the most important information first, then taper down to the detail. *(GOV.UK writing guidelines)*
+2. Split any sentence over 25 words into two. *(GOV.UK writing guidelines)*
+3. Choose the short, common word: buy, help, about. *(GOV.UK writing guidelines)*
+4. Write in the active voice, so the reader sees who does what. *(GOV.UK writing guidelines)*
+5. Address the reader as "you", as one person you can actually help. *(GOV.UK writing guidelines)*
+6. Use positive contractions such as "you'll", and write negatives out in full: "do not", "cannot". *(GOV.UK writing guidelines)*
+7. Write headings that say what the section tells the reader, starting with a verb where you can. *(GOV.UK writing guidelines)*
+8. Give each paragraph one job. *(house judgement)*
+
+**Example (fictional):**
+
+- Before: Should you wish to apply for a residents' parking permit, an application form must be completed and submitted to the council prior to the commencement of the permit period.
+- After: Apply for a residents' parking permit before you need it. Fill in the form online. It takes about 10 minutes.
+- Why: The action comes first, the council is no longer the subject, and each sentence does one thing.
+
+**Sources:**
+
+- [GOV.UK writing guidelines](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/): Clear language (the 25-word split, short words, active voice, contractions), clear structure (most important first, headings) and right tone (address the user as "you"). Checked against the live pages on 2026-09-30.
+
+## Persuasive and concise (`persuasive`)
+
+**Use for:** Landing pages, service pages, adverts and sales emails: copy whose job is one action.
+
+**Before you draft:**
+
+1. Put the promise in the headline: what the reader gets, in words they would use. *(Ogilvy, Ogilvy on Advertising (1983))*
+2. Back each claim with something the reader can check: a number, a name, a date, a price. *(COPY.md)*
+3. Write to one reader, as "you", about their problem before your service. *(Caples, Tested Advertising Methods)*
+4. Name the mechanism: how it works, how long it takes, what it costs. *(COPY.md)*
+5. Answer the objection the reader already has, with evidence, in the sentence that follows the claim. *(house judgement)*
+6. Let the copy run as long as the facts last, and cut each sentence that carries none. *(Ogilvy, Ogilvy on Advertising (1983))*
+7. Close with one specific action and what happens straight after it. *(COPY.md)*
+
+**Example (fictional):**
+
+- Before: Transform your garden with our premium landscaping solutions. Quality you can trust.
+- After: We lay a 40 square metre Indian sandstone patio in three days, for £4,800 fitted. Every job since 2014 is on our reviews page. Book a free site visit and get a fixed quote within 48 hours.
+- Why: Size, material, time and price replace the adjectives, the proof sits next to the claim, and the close says what happens next. Fictional business.
+
+**Sources:**
+
+- Ogilvy, Ogilvy on Advertising (1983): Headlines carry the promise because far more people read the headline than the body; specific, informative copy outsells vague copy. Taken from the widely quoted principles; a page-by-page check against the book is still to do.
+- Caples, Tested Advertising Methods: Headlines that appeal to the reader's self-interest, and copy judged by tested response rather than taste. A page-by-page check against the book is still to do.
+- COPY.md: Writing directives (lead with the fact, name the mechanism, persuade with something checkable) and the CTA rule.
+
+## Warm and conversational (`warm`)
+
+**Use for:** Customer emails, replies to enquiries, newsletters and small-business updates.
+
+**Before you draft:**
+
+1. Write the way you would talk to a customer you like: contractions, everyday words. *(Mailchimp Content Style Guide)*
+2. Keep words and sentences simple; being clear matters more than being entertaining. *(Mailchimp Content Style Guide)*
+3. Say what the reader can do, in positive language. *(Mailchimp Content Style Guide)*
+4. Use the active voice. *(Mailchimp Content Style Guide)*
+5. Match the tone to how the reader feels right now: lighter for good news, calm and direct for a problem. *(Mailchimp Content Style Guide)*
+6. Keep humour dry and occasional, and only where it comes naturally. *(Mailchimp Content Style Guide)*
+7. Sign off as a person, with a name. *(house judgement)*
+
+**Example (fictional):**
+
+- Before: Dear Valued Customer, We wish to inform you that your order has been dispatched and will be delivered in due course.
+- After: Hi Sam, your order's on its way. It left our Leicester workshop this morning and should reach you on Thursday. Any questions, just reply to this email. Priya
+- Why: A name at each end, a real day and place instead of "in due course", and a next step. Fictional business.
+
+**Sources:**
+
+- [Mailchimp Content Style Guide](https://styleguide.mailchimp.com/voice-and-tone/): Voice and tone (plainspoken, genuine, dry humour; clear before entertaining; adjust tone to the reader's state) and grammar and mechanics (active voice, contractions, positive language). Its allowance for emoji does not apply: emoji block under COPY.md. Checked against the live pages on 2026-09-30.
+
+## Elegant and literary (`literary`)
+
+**Use for:** Premium brands, makers, hospitality and anything sold on craft and taste rather than price.
+
+**Before you draft:**
+
+1. Choose one precise noun over two adjectives. *(house judgement)*
+2. Let sentence length follow the thought: a long sentence to build, a short one to land. *(COPY.md)*
+3. Carry the detail in concrete facts: material, place, process, time. *(house judgement)*
+4. Trust the reader with one image, state it once, and move on. *(house judgement)*
+5. Keep claims quiet and exact, and let the facts carry the prestige. *(house judgement)*
+6. Draw any metaphor from the maker's own work, and hold it for the whole piece. *(house judgement)*
+7. Read the draft aloud and rework each line that trips the breath. *(house judgement)*
+
+**Example (fictional):**
+
+- Before: Our luxurious, handcrafted candles create an unforgettable ambience of elegance and sophistication.
+- After: Each candle is poured by hand in our Hebden Bridge workshop, forty to a batch. The wax is English rapeseed and the scent is cedar, cut with a little smoke. It burns for sixty hours, and the glass is yours to keep.
+- Why: Place, material, scent and burn time do the work the adjectives claimed. Fictional business.
+
+**Sources:**
+
+- house judgement: No public style authority exists for premium-brand prose. These directives are house judgement, to be revised as the estate grows.
+- [Register separation, 2026-09-29](calibration/copy-shape/report-registers.md): Literary prose (Gutenberg) carries about twice the comma density of the other human registers, the one feature that separated it from all four. Longer, jointed sentences are normal here.
+
+**Always:** Every register keeps the COPY.md blocking tier and the proof rule. Draft first, then run `craft copy <file>` on the draft.
+<!-- craft:registers:end -->

package/dist/{audit-MTUC24XU.js → audit-4SFSLCKY.js}

@@ -9,9 +9,10 @@ import {
   snapshotPage,
   snapshotUrl,
   snapshotUrls
-} from "./chunk-OUQ25LY2.js";
+} from "./chunk-SL5VZJ2J.js";
 import "./chunk-JYNXGCYZ.js";
-import "./chunk-LFNSB6W7.js";
+import "./chunk-WFB6F3BN.js";
+import "./chunk-4QWEAL4G.js";
 import "./chunk-QYBAVU3P.js";
 export {
   PROVENANCE_BUDGET_MS,

package/dist/audit.cjs

@@ -2914,7 +2914,7 @@ var SPECIFICITY_COPY_TELLS = [
     },
     rendered: {
       detect: (s) => {
-        if (!s.firstScreenText || !HOME_URL.test(s.url)) return [];
+        if (!s.firstScreenText || !(s.home ?? HOME_URL.test(s.url))) return [];
         const text = s.firstScreenText.join("\n");
         if (!text.trim() || !specificity(text).generic) return [];
         const h1 = s.headings.find((h) => h.level === 1 && h.top < s.viewport.height);

package/dist/audit.d.cts

@@ -230,6 +230,13 @@ interface Snapshot {
      * claim, not its menu or its calls to action.
      */
     firstScreenText?: string[];
+    /**
+     * Whether this is a site's home page, set by whoever knows: `craft
+     * calibrate` from its labels, and `craft null build` and `null import`,
+     * which ask for a home page. Absent, the URL decides (`HOME_URL`), and a
+     * local file such as `pages/01.html` never reads as one.
+     */
+    home?: boolean;
     /** 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. */

package/dist/audit.d.ts

@@ -230,6 +230,13 @@ interface Snapshot {
      * claim, not its menu or its calls to action.
      */
     firstScreenText?: string[];
+    /**
+     * Whether this is a site's home page, set by whoever knows: `craft
+     * calibrate` from its labels, and `craft null build` and `null import`,
+     * which ask for a home page. Absent, the URL decides (`HOME_URL`), and a
+     * local file such as `pages/01.html` never reads as one.
+     */
+    home?: boolean;
     /** 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. */

package/dist/audit.js

@@ -2879,7 +2879,7 @@ var SPECIFICITY_COPY_TELLS = [
     },
     rendered: {
       detect: (s) => {
-        if (!s.firstScreenText || !HOME_URL.test(s.url)) return [];
+        if (!s.firstScreenText || !(s.home ?? HOME_URL.test(s.url))) return [];
         const text = s.firstScreenText.join("\n");
         if (!text.trim() || !specificity(text).generic) return [];
         const h1 = s.headings.find((h) => h.level === 1 && h.top < s.viewport.height);