@domandigital/craft 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @domandigital/craft
 
+## 0.6.0
+
+### Minor Changes
+
+- 8c6304b: Character, phase A: a tell catalogue, a source scanner, a copy engine, and the `craft` command.
+
+  The standard asks whether a surface is well made. The new CHARACTER.md asks
+  whether anyone decided how it looks. A site can pass every craft number and
+  still be the indigo-and-Inter answer a model gives any brief.
+
+  - `scanSource(files)` finds 21 design tells in markup, component code and CSS,
+    tagged by generation: the first wave (indigo, blue-to-purple gradients, Inter,
+    glass panels, hero straight into a trust strip, icon-card grids, reveal on
+    every section, pills everywhere, a stock shadcn dump) and the second (cream
+    grounds, italic serif display, eyebrow chips, icon tiles, bento grids, radial
+    glows, graph-paper backgrounds, marquees, hairline-border cards, intro
+    cinematics).
+  - It reads classes the way Tailwind does, through `cn()`, `clsx()` and `cva()`,
+    and colour in hex, `rgb()`, `hsl()` and `oklch()` in raw CSS, `@theme` blocks
+    and arbitrary values. Hue is judged in OKLCh, so a violet set as `#5a35d1` is
+    caught.
+  - `checkCopy(files)` finds 8 copy tells, including em dashes, "not just X, it's
+    Y", staccato triplets and "where X meets Y". The word and phrase lists are
+    exported data with a test per entry.
+  - `craft scan [--staged]`, `craft copy`, `craft tells list`. Exceptions are
+    declared in `art-direction.json` with a `because`; one without a reason is
+    not applied and is reported.
+  - Every tell ships as `warn`. Nothing blocks until its estate hits have been
+    read. Every entry has a flag case per detection path and a pass case, and
+    the test proves each one fires on its own.
+
+  STANDARD.md section 10 now hands layout defaults to CHARACTER.md. Still eleven sections.
+
+- 161a771: The house copy rules move into craft, so `copy-check` can become a thin wrapper over `craft copy --json`.
+
+  - Ten tells carry the lists that claude-kit's `copy-check` hardcoded: `ai-phrase`,
+    `plainer-word`, `plain-english`, `buzzword`, `negative-reassurance`, `emoji`,
+    `no-x-no-y`, `no-x-badge`, `review-phrase` and `vague-word`. `not-just-but` now
+    covers every form of contrastive negation the house rules name, including the
+    parallel participle ("dispatched from here, not shipped in from Seoul").
+    Each word and phrase belongs to exactly one tell, with a test per entry.
+    Every tell still ships as `warn`. Catalogue `2026.09.2`, 39 tells.
+  - `copy-ok` or `craft-ok` on a finding's line, or the line above, suppresses it.
+    Suppressed findings are listed in `report.suppressed`, never hidden.
+  - `craft copy` never reads a comment as copy, reads JSX text that runs into an
+    expression, reads the text inside HTML held in a string, sees short strings
+    for the dash, emoji and badge tells, leaves a lone dash placeholder alone,
+    and reads `.jsonl` (a Sanity export) a document per line.
+  - Class lists written with arbitrary values (`bg-[var(--bg-elevated)]`) are no
+    longer read as prose.
+
+- 8093ad7: Phase B: the rendered page. `craft snapshot`, `craft audit`, rendered detection paths and a fingerprint.
+
+  - `@domandigital/craft/audit` captures a snapshot of a live page in Chromium: faces by
+    text and headline, colours by painted area, button shape, sections in running order
+    and which wait for a scroll, glass, gradients, glows, grid backgrounds, marquees,
+    hairline-shadow cards, the eyebrow chip, and an intro that covers the page at load.
+    Playwright is an optional peer dependency; the core import never loads a browser.
+    `collectInPage` is exported for any caller already driving a page.
+  - 18 tells gain a rendered detection path, with their own flag and pass snapshots,
+    proved like every other path. `auditSnapshot(snapshot)` judges a saved snapshot
+    without a browser. Catalogue `2026.09.3`.
+  - `fingerprint(snapshot)` and `fingerprintDistance(a, b)`: accent and ground in
+    OKLCh, display and body faces, roundness, reveal density, effects and running order,
+    compared 0 to 1. `nearest()` ranks a set.
+  - `craft audit <url | snapshot.json> [--repo dir]` reports the page and its source
+    together, with the fingerprint. `HTTPS_PROXY` is honoured.
+  - Colour parsing reads `oklab()` and `color(srgb ...)`, which browsers return.
+  - First estate baseline recorded in CHARACTER.md and `calibration/estate/2026-09-23/`.
+
+- ee6d6cd: Phase C: `art-direction.json`, the reason rule, and `craft direction init | validate | propose`.
+
+  - A schema for the seven expressive choices (accent, ground, display, body, shape, motif,
+    signature), the sources in the client's world they come from, and the tell exceptions
+    from phase A. Ships as `art-direction.schema.json` for editors.
+  - `validateDirection` applies the reason rule: a reason is a sentence, cites a declared
+    source and mentions what that source shows; preferences, mood boards and unconfirmed
+    proposals are rejected; a value on the tell catalogue needs an exception. Given a
+    fingerprint it warns where the page does not show what the file declares.
+  - `initDirection` writes today's choices with empty reasons. `propose` reads dominant
+    colours off PNG photos (`paletteFromPixels`, k-means in OKLab) and drafts choices ranked
+    away from the reflex band and the estate, every one marked `PROPOSED:` until a person
+    rewrites it.
+  - An exceptions-only file stays valid.
+
 ## 0.5.0
 
 ### Minor Changes

package/CHARACTER.md

@@ -0,0 +1,335 @@
+# The character standard
+
+[STANDARD.md](./STANDARD.md) asks whether a surface is well made. This document
+asks a second question: **did anyone decide how it looks, or is it the answer a
+model gives when nobody told it otherwise?**
+
+A site can pass every craft number and still read as generated. Indigo accent,
+Inter, a glass card over the hero, a strip of logos, three icon cards, every
+section fading up on scroll. None of those is wrong. Together they say nobody
+chose anything.
+
+## Change the look, not the page grammar
+
+First impressions favour pages that look typical for their category (Tuch et
+al., 2012). So this standard **never rewards strangeness**. Navigation, where
+the call to action sits, reading order and legibility stay conventional. They
+remain the job of STANDARD.md and the page audit.
+
+Character goes into the surface: the display face, the accent, the shape
+language, the motif, the one signature moment. That is where a model's defaults
+show, and where a real business has something of its own to draw on.
+
+## Three signals, and a reason behind every choice
+
+Any fixed list of tells goes stale. Ban Inter and a model moves to Space
+Grotesk. So the list is one signal of three, and the other two keep working as
+model defaults move.
+
+| Signal | Question | Status |
+| --- | --- | --- |
+| 1. Known tells | Does it use a choice on the catalogue below? | **Shipped**: source, copy, and on the rendered page for 18 tells (`craft audit`). |
+| 2. Counterfactual typicality | Would Claude have built this anyway, for this brief? | Planned. About 20 `claude -p` runs per brief; distance from those answers. |
+| 3. Distance from the estate | Does it look like the agency's other sites? | Fingerprint and distance shipped; the estate register is planned. The agency's biggest tell is its clients looking like siblings. |
+
+**The reason rule.** Every expressive choice records a `because`, with evidence
+from the client's real world: the shopfront, the van, the trade's own look, the
+place, the materials. A token with no reason is a default. This is the part that
+adds character rather than only removing tells. It lives in `art-direction.json`.
+
+## Tells are tagged by generation
+
+| Gen | What it is |
+| --- | --- |
+| 1 | The first wave: indigo, blue-to-purple gradients, Inter, glass, three icon cards. |
+| 2 | What models moved to once the first wave was named: cream grounds and italic serifs, eyebrow chips, bento grids, marquees, intro cinematics. |
+| 3 | Whatever the harvester finds next. |
+
+A report counts findings by generation, so it can say *which* wave a site was
+built in, not only that it has tells.
+
+## Every tell ships as a warning
+
+Nothing blocks until its hits across the estate have been read by a person and
+the rule tuned against them. A rule that blocks on day one gets switched off by
+day three. `--strict` fails on any finding, for a surface that has been
+cleaned and should stay clean.
+
+## Declaring the direction
+
+`art-direction.json` at the site root records the seven expressive choices
+(accent, ground, display face, body face, shape, motif, signature moment), the
+sources in the client's world they come from, and why. Layout and navigation
+are not choices here: they stay conventional.
+
+```json
+{
+  "version": 1,
+  "client": "RMP Electrical",
+  "brief": "A two-person electrical contractor in Brackley doing rewires and EV chargers.",
+  "sources": [
+    { "id": "van", "kind": "livery", "note": "The Transit van, bottle green with cream sign-writing.", "path": "brand/van.png" }
+  ],
+  "choices": {
+    "accent": {
+      "value": "#1f4d3a",
+      "because": "The bottle green is the van's own paint, and the van is what people in Brackley recognise.",
+      "evidence": ["van"]
+    }
+  }
+}
+```
+
+`craft direction validate` applies the reason rule. A choice is decided only
+when its reason is at least a sentence, cites a declared source, and mentions
+what that source shows (naming only the colour does not count). It rejects a
+preference ("the client likes it"), a mood board (two or more of modern,
+clean, premium, elegant and the rest), and a value on the tell catalogue
+without an exception carrying the same reason. Given a snapshot, it warns
+where the page does not show what the file declares.
+
+`craft direction init` writes what the site does today with every reason
+empty, so the first thing it produces is the list of things nobody decided.
+Run on RMP's live home page (2026-09-23) it records Fraunces, Manrope, a cream
+ground and pill buttons, three of them on the catalogue, and zero of seven
+choices decided.
+
+`craft direction propose` reads the dominant colours off each source's PNG
+photo, ranks accent candidates away from the reflex violet band and from the
+rest of the estate (`--estate` a folder of snapshots), and drafts choices.
+Every draft reason starts `PROPOSED:`, which validate rejects: a person looks
+at the van, agrees the green is the van's green, and says so in their own
+words.
+
+The editor schema ships as `@domandigital/craft/art-direction.schema.json`.
+A file from phase A that holds only exceptions stays valid.
+
+## Declaring an exception
+
+Doman Digital's own brand is violet. A hue rule with no way to say so flags the
+agency's own site on every commit. So an exception is declared, with its reason,
+in `art-direction.json` at the site root:
+
+```json
+{
+  "exceptions": [
+    {
+      "tell": "ai-violet",
+      "because": "Violet has been the Doman Digital mark since 2019: the van, the cards, the signage.",
+      "evidence": "brand/van-livery.jpg"
+    }
+  ]
+}
+```
+
+An exception with no `because`, or one shorter than a sentence, is not applied
+and is reported. An applied exception is still listed in every report with the
+count it silenced, so it stays visible.
+
+## Using it
+
+```bash
+craft scan                 # markup, components and stylesheets under .
+craft scan --staged        # the git index, for a pre-commit hook
+craft copy app content     # the prose a visitor reads
+craft tells list           # the catalogue this build judges against
+craft audit https://example.co.uk --repo .   # the rendered page and its source, one report
+craft snapshot https://example.co.uk --out home.json
+```
+
+`--json` gives the full report. Exit code is 0 on warnings, 1 on a block (or
+any finding under `--strict`), 2 on a usage error.
+
+`scan` reads classes the way Tailwind does: `className="..."`, the literals
+inside `cn()`, `clsx()` and `twMerge()`, and each `cva()` variant separately.
+It reads colour in hex, `rgb()`, `hsl()` and `oklch()`, in raw CSS, Tailwind v4
+`@theme` blocks and arbitrary values, and judges hue in OKLCh. A framework's
+own palette definitions are ignored: a colour counts when a site uses it, not
+when the framework defines it.
+
+`copy` reads Markdown outside code, text between tags (including text that
+runs into an expression, such as a label followed by `{count}`), string literals that
+read as sentences, and the text inside HTML held in a string, such as an email
+template. Short strings are read too, for the tells that fit in a label: an em
+dash, an emoji, a "No catch." badge. Comments are never copy. It reads `.json`
+and `.jsonl`, so a Sanity export can be checked a document per line. It skips
+READMEs, changelogs and `_`-prefixed folders when walking a directory, because
+those are for the people who build the site.
+
+A real person's own words, a review or a testimonial, must never be edited to
+pass. Mark the line, or the line above it, with `copy-ok` or `craft-ok`. Marked
+findings are listed in every report with where they are, never hidden. The
+same markers work for `craft scan`.
+
+## The rendered page
+
+`craft audit` opens the page in Chromium, waits five seconds, and records what
+a visitor gets as a snapshot: the faces that set the text and the headline,
+the colours by painted area, the buttons' shape, the sections in running
+order and which ones wait for a scroll, and the effects (glass, glows,
+marquees, an intro that covers the page at load). The same tells then judge
+it, so a report can say "Inter in source and on the page", or catch the
+violet a CMS sets that no source file names.
+
+It needs Playwright, as an optional peer dependency: `npm i -D playwright`.
+The core import never loads a browser. A saved snapshot can be judged again
+anywhere with `craft audit home.json`. `HTTPS_PROXY` is honoured, and a
+`localhost` or `NO_PROXY` host is reached directly.
+
+Every audit also prints a **fingerprint**: accent and ground in OKLCh, the
+display and body faces, button roundness, reveal density, the effects and the
+running order. `fingerprintDistance` compares two of them, 0 to 1, weighted
+towards accent and type. Signals 2 and 3 are both this distance, measured
+against different sets.
+
+Known limit: a computed font family is the family the stylesheet asked for.
+A face that failed to load is still reported under its name.
+
+## The house copy rules live here
+
+Since catalogue `2026.09.2` the rule lists of claude-kit's
+`house-style/copy-rules.md` are carried by tells in this catalogue:
+`ai-phrase`, `plainer-word`, `plain-english`, `buzzword`,
+`negative-reassurance`, `em-dash`, `emoji`, `not-just-but`, `no-x-no-y` and
+`no-x-badge` are its blocking tier; `review-phrase` and `vague-word` its review
+tier. craft ships all of them as `warn`. `copy-check` in claude-kit is a thin
+wrapper over `craft copy --json` and decides which tells fail a commit, so the
+lists exist once, here, with a test per entry.
+
+The swap was checked against the old checker on 2,570 files across the seven
+client repos (2026-09-23). The old checker found 193 issues, craft finds every
+one of them that is visitor copy. The rest, 29, were the old checker reading
+code comments, asset keys (`brows-hero-seamless`), a regex that strips em
+dashes, and three words (`truly`, `genuinely`, `deeply`) that the house rules
+keep in the review tier and the old list had drifted into blocking. Four real
+misses in craft were fixed on the way: em dashes in JSX text next to an
+expression, a lone dash placeholder in a table cell, prose inside HTML held in
+a string, and the contrastive negation in a live welcome email that is the
+reason that rule exists.
+
+## Calibration
+
+The targets, recorded here with the date once each has been run:
+
+- **AI set** (pages generated by `claude -p` from about 20 briefs): 90% or more
+  flagged as typical or tell-heavy. *Not yet run.*
+- **Human set** (the ten references in claude-kit's `reference-set.md`): zero
+  block hits and low typicality. *Not yet run.*
+- **Estate baseline** (all seven client repos and live URLs): every hit read by
+  a person before any rule blocks. **First run 2026-09-23**, below.
+
+A first read of one internal repo (dd-library, 157 source files, 2026-09-22)
+found Inter Tight and Fraunces in the base template, 21 scroll reveals and 31
+pills, and one false positive: Tailwind's `amber-50`, the stock warning-notice
+fill, read as a cream page ground. That rule now matches named cream tokens and
+measured colour only.
+
+### Estate baseline, 2026-09-23
+
+`craft scan` over each repo and `craft audit` on each live home page at
+1440 x 900. Snapshots and the table are in `calibration/estate/2026-09-23/`.
+Cells read *source findings / R if seen on the rendered page*. Nothing here
+blocks; it is for a person to read.
+
+| Tell | DD | MMM | Sensphere | Harrison James | HJ Beauty | Chair and Blade | RMP |
+|---|---|---|---|---|---|---|---|
+| `reflex-font` | 15 / · | 2 / · | 3 / R | 2 / R | 2 / · | 1 / · |  |
+| `reflex-font-2` | 7 / R | 34 / R | 2 / · | 1 / R | 3 / R | 4 / R | 12 / R |
+| `ai-violet` | 36 / · | 9 / · | 18 / R |  |  |  |  |
+| `gradient-text` |  | 2 / · |  |  |  |  |  |
+| `glass-panel` | 9 / · | 45 / · | 13 / · |  | 1 / · |  |  |
+| `hero-then-proof` | 9 / · | 1 / R | · / R |  | 1 / · | 1 / · | 2 / R |
+| `icon-tile-grid` | 1 / R | 9 / · | · / R |  | · / R |  | 1 / R |
+| `reveal-everywhere` | 1 / · | 1 / · |  |  |  |  |  |
+| `pill-everything` | 1 / R | 1 / · | 1 / · |  |  |  | 1 / R |
+| `shadcn-dump` |  | 1 / · |  |  |  |  |  |
+| `cream-palette` |  | 3 / · |  |  |  |  | 18 / R |
+| `italic-serif-display` |  | 4 / · |  |  |  | 8 / · | 1 / R |
+| `hero-eyebrow-chip` | 1 / · | 1 / · |  |  |  |  | · / R |
+| `icon-tile-stack` | 1 / · | 93 / · | 4 / · |  |  |  | 18 / · |
+| `radial-spotlight-glow` | 6 / R | 14 / R | 5 / R |  |  |  |  |
+| `grid-background` |  | 2 / · |  |  |  |  |  |
+| `marquee` | 1 / · |  |  |  | 3 / R | · / R |  |
+| `thin-border-wide-shadow` |  | 2 / · | 4 / R |  |  |  |  |
+| `intro-cinematic` |  | · / R |  |  |  | 2 / · |  |
+
+What it shows:
+
+- **The three survey findings reproduce where they can.** Sensphere's violet
+  is found in source (18) and on its buttons; MMM's intro, glows and glass are
+  in source and its intro and glows on the page; MMM reveals 60% of the
+  sections below its fold on scroll, three of five, one short of the rendered
+  threshold, and its source is over the reveal limit. Rise & Bloom's glass
+  hero and icon grid could not be checked: that repo is not attached to this
+  session.
+- **Every site ships a reflex face.** Twelve of fourteen site-face pairs are
+  on one of the two lists. Fraunces sets the headline on DD, HJ Beauty and RMP.
+- **DD and RMP are the closest pair** (fingerprint distance 0.46: Fraunces
+  headlines, pill buttons, a green accent). Chair and Blade is furthest from
+  everything (0.59 to 0.77). This is signal 3's first measurement.
+- **DD's violet is its brand.** Its 36 source hits wait for the exception in
+  its `art-direction.json`.
+
+False positives found and fixed in this run:
+
+- `glass-panel` on the page fired on five of seven sites. Every one was a
+  sticky or fixed nav bar with a blurred background, which is ordinary chrome.
+  The rendered path now ignores anything in a `header` or `nav`, fixed or
+  sticky, and anything smaller than a panel.
+- `next/font` and CSS-variable family names (`__Inter_d65c78`,
+  `cormorantGaramond`) are now read back to the face's name, or every Next.js
+  site would have passed the font tells.
+
+Not yet read by a person: the source counts for `icon-tile-stack` (MMM 93)
+and `glass-panel` (MMM 45) look high and are the first to check.
+
+## The catalogue
+
+Generated from the package. Run `pnpm --filter @domandigital/craft run docs`
+after changing an entry; a test fails until you do.
+
+<!-- craft:catalogue:start -->
+Catalogue version `2026.09.3`, 39 tells.
+
+| Id | Gen | Surface | Severity | Tell | Why it is a default |
+| --- | --- | --- | --- | --- | --- |
+| `reflex-font` | 1 | source + rendered | warn | Reflex font | Inter, Roboto, Poppins and friends are what a model sets when nothing in the brief names a face. Every site in the estate ships one. |
+| `reflex-font-2` | 2 | source + rendered | warn | Second-wave reflex font | Ban Inter and a model reaches for Inter Tight, DM Sans, Manrope, Space Grotesk or an Instrument/Fraunces serif. A swap inside the reflex list is not a decision. |
+| `ai-violet` | 1 | source + rendered | warn | Indigo-violet accent | Tailwind's indigo and violet are the accent a model picks for any brand it knows nothing about. Hue is read in OKLCh, so a hex violet is caught as well as a class name. |
+| `blue-purple-gradient` | 1 | source + rendered | warn | Blue-to-purple gradient | The first-wave hero background. It says 'software product' on a plumber's site. |
+| `gradient-text` | 1 | source + rendered | warn | Gradient-filled heading | Gradient text is the model's way of making a heading look designed without deciding what it should look like. |
+| `glass-panel` | 1 | source + rendered | warn | Glass panel | A translucent blurred card over a busy background is the stock way to put text on a hero image. It costs contrast and says nothing about the client. |
+| `hero-then-proof` | 1 | source + rendered | warn | Hero straight into a trust strip | Six of seven estate sites go hero, then logos or stats. It is the landing-page template's order, not the client's story. |
+| `icon-tile-grid` | 1 | source + rendered | warn | Three-column icon-card grid | Three cards, each an icon, a heading and two lines, is what a model builds for any list of services. |
+| `reveal-everywhere` | 1 | source + rendered | warn | Reveal on every section | When every block fades up on scroll, the motion stops meaning anything and the page feels slow. MMM had 70, DD 40, sen-sphere 27. |
+| `pill-everything` | 1 | source + rendered | warn | Pills everywhere | rounded-full on every button, badge and tag is the framework's friendliest default. MMM had 162, DD 125. A shape used everywhere is not a shape language. |
+| `shadcn-dump` | 1 | source | warn | Stock component dump | A generator exports the whole shadcn/ui kit whether the site uses it or not. Rise & Bloom ships a full set under its own book, vine and petal assets. |
+| `cream-palette` | 2 | source + rendered | warn | Cream ground | Once white-and-violet was named, models moved to a warm off-white: parchment, linen, oat. It reads as 'tasteful' in the same way everywhere. |
+| `italic-serif-display` | 2 | source + rendered | warn | Italic serif display | A serif heading with one italic word ('Beauty, reimagined') is the second wave's signature move. |
+| `hero-eyebrow-chip` | 2 | source + rendered | warn | Eyebrow chip above the hero | A small bordered pill ('New · Now booking') above the headline is in almost every generated hero. |
+| `icon-tile-stack` | 2 | source | warn | Icon in a tinted tile | A library icon in a soft rounded square, stacked above a heading, is the stock card header. |
+| `bento-grid` | 2 | source | warn | Bento grid | Mixed-size tiles in a grid became the default 'features' layout of the second wave. |
+| `radial-spotlight-glow` | 2 | source + rendered | warn | Radial glow | A soft blurred blob or radial spotlight behind the hero is atmosphere without a subject. |
+| `grid-background` | 2 | source + rendered | warn | Graph-paper background | A faint 1px line or dot grid behind the hero is the developer-tool look, borrowed by everyone. |
+| `marquee` | 2 | source + rendered | warn | Scrolling marquee | An endless strip of logos or words is the second wave's trust strip. It moves so it looks alive. |
+| `thin-border-wide-shadow` | 2 | source + rendered | warn | Hairline border, wide shadow | A near-invisible border under a large soft shadow is the stock 'elevated card'. |
+| `intro-cinematic` | 2 | source + rendered | warn | Intro cinematic | A logo animation that runs before the page is something a model adds to make a site feel premium. Three estate sites open with one. It delays the page for every visitor. |
+| `ai-vocabulary` | 1 | copy | warn | AI vocabulary | Tapestry, elevate, nestled, unparalleled: words that appear in generated copy far more than in anything a business owner writes. |
+| `stock-phrase` | 1 | copy | warn | Stock phrase | Phrases every generated services page uses. They fill space where a fact should be. |
+| `ai-phrase` | 1 | copy | warn | AI phrase | Let's dive in, here's the thing, at its core, seamless, rest assured: the phrase list of the house copy rules. A reader has seen each one in a thousand generated pages. |
+| `plainer-word` | 1 | copy | warn | A plainer word exists | Empower, leverage, harness, delve: each stands in for a plainer verb, and the swap is a reliable sign nobody chose the word. |
+| `plain-english` | 2 | copy | warn | 'Plain English' | Told to avoid jargon, a model announces that it is avoiding jargon. 'Explained plainly' swaps a synonym and keeps the tell. |
+| `buzzword` | 1 | copy | warn | Buzzword | Cutting-edge, world-class, reach out, turnkey: corporate filler older than any model, and still the first thing a model writes about a business it knows nothing about. |
+| `negative-reassurance` | 1 | copy | warn | Negative reassurance | 'No hidden fees', 'no surprises', 'never locked in' reassure by naming the fear, and plant it in a reader who did not have it. |
+| `vague-word` | 1 | copy | warn | Vague word | Innovative, scalable, end-to-end, solutions: each can be true, and each is used where the writer had nothing specific to say. |
+| `review-phrase` | 1 | copy | warn | Review-tier phrase | Truly, genuinely, ultimately, 'the single most', 'bar none': normal English once, and a tell when they stack. The house rules keep them for review, never blocking. |
+| `hollow-imperative` | 1 | copy | warn | Hollow imperative | 'Discover', 'Experience', 'Transform your' as the opening verb of a heading or button is a call to action with nothing in it. |
+| `rhetorical-opener` | 1 | copy | warn | Rhetorical question opener | 'Looking for...?', 'Tired of...?', 'Ready to...?' opens with the model guessing at the reader instead of telling them something. |
+| `em-dash` | 2 | copy | warn | Em dash | Generated copy leans on the em dash to join clauses. House copy does not use it. |
+| `emoji` | 1 | copy | warn | Emoji in copy | A sparkle or a rocket beside a heading is decoration a model adds to seem friendly. It dates the page and reads as a social post. |
+| `not-just-but` | 2 | copy | warn | Contrastive negation | 'It's not just a haircut, it's an experience', 'dispatched from here, not shipped in': the contrast-and-reveal template is the most recognisable construction in generated copy. |
+| `no-x-no-y` | 2 | copy | warn | 'No X, no Y' list | 'No obligation, no spam.' Defining the business by what it is not, itemised, is the same template as contrastive negation. |
+| `no-x-badge` | 2 | copy | warn | 'No X' badge | 'No catch.', 'NO JARGON GUIDE': a short standalone 'No X' reads as a slapped-on kicker, and worse when the same one is reused across pieces. |
+| `staccato-triplet` | 2 | copy | warn | Staccato triplet | Three fragments in a row ('Fast. Friendly. Local.' or 'No fuss. No jargon. Just results.') is the second wave's favourite rhythm. |
+| `where-x-meets-y` | 2 | copy | warn | 'Where X meets Y' | 'Where luxury meets comfort' is a tagline shape that fits every business and so describes none. |
+<!-- craft:catalogue:end -->

package/PRINCIPLES.md

@@ -91,3 +91,17 @@ instead: a piecewise-linear map pinned at 0 and 1 that passes through
 (curve value, actual value) for the anchor. Monotonic by construction, and every
 other step keeps its relative position. The anchors define the ramp; the curve
 only sets the spacing between them.
+
+## Well made is not the same as decided
+
+A surface can clear every number in the standard and still read as generated.
+The craft rules measure quality; they cannot see that the accent, the face and
+the section order are the ones a model picks for every brief it knows nothing
+about. That is a different question, so it is a different document:
+[CHARACTER.md](./CHARACTER.md).
+
+Two things keep it from becoming a taste police. It only ever changes the look,
+never the page grammar, because a page that looks typical for its category is
+the one visitors trust first. And it never asks for novelty. It asks for a
+reason: every expressive choice records where it came from in the client's own
+world, and a choice with no reason is the one flagged.

package/README.md

@@ -4,7 +4,8 @@ The Doman Digital house craft standard, as numbers.
 
 OKLCh colour ramps that snap to colours you already ship, semantic tokens derived
 with measured WCAG **and** APCA contrast, one motion vocabulary shared by CSS and
-JS, and a base stylesheet. Zero runtime dependencies.
+JS, a base stylesheet, and a scanner that finds the AI look in source and copy.
+Zero runtime dependencies.
 
 Read [PRINCIPLES.md](./PRINCIPLES.md) for why each rule is a rule.
 
@@ -71,6 +72,37 @@ rule cited, including a section on what is deliberately *not* a rule. Its
 canonical numbers are compared against the code on every test run, so the
 document cannot drift from what ships.
 
+## Character: finding the AI look
+
+The standard asks whether a surface is well made. [CHARACTER.md](./CHARACTER.md)
+asks whether anyone decided how it looks, or whether it is what a model builds
+when nobody told it otherwise.
+
+```bash
+npx craft scan            # markup, components, stylesheets
+npx craft scan --staged   # pre-commit: the git index only
+npx craft copy app content
+npx craft tells list
+```
+
+Every finding names the tell, its generation (1: indigo, Inter, glass; 2: cream,
+italic serif, eyebrow chips, bento), the line, and what to do instead. Every
+tell ships as a warning. A brand that really is violet declares it, with a
+reason, in `art-direction.json`:
+
+```json
+{ "exceptions": [{ "tell": "ai-violet", "because": "Violet is on the van, the cards and the fascia." }] }
+```
+
+The same checks run in code:
+
+```ts
+import { checkCopy, formatReport, scanSource } from "@domandigital/craft";
+
+const report = scanSource([{ path: "app/page.tsx", text }]);
+console.log(formatReport(report, "craft scan"));
+```
+
 ## The anchor guarantee
 
 Every hex you pass in comes back out unchanged — the same string, byte for byte.
@@ -99,6 +131,9 @@ checkable rather than asserted.
 | Restraint | `checkRestraint`, `HOUSE_BUDGET` |
 | Tailwind | `tailwindV3Preset` (v3), `tailwindV4Theme` / `craft.tailwind.css` (v4) |
 | Emit | `craftTokens`, `emitCss`, `motionTokens` |
+| Character | `scanSource`, `checkCopy`, `formatReport`, `CATALOGUE`, `CATALOGUE_VERSION`, `catalogueTable`, `runTell`, `tellById` |
+| Character colour | `parseColour`, `findColours`, `isAiViolet`, `isCream`, `AI_VIOLET` |
+| Character lists | `REFLEX_FONTS_1`, `REFLEX_FONTS_2`, `SHADCN_PRIMITIVES`, `AI_WORDS`, `STOCK_PHRASES`, `REVEAL_LIMIT`, `PILL_LIMIT`, `SHADCN_LIMIT` |
 
 ## Licence
 

package/STANDARD.md

@@ -164,7 +164,10 @@ The package emits **plain CSS custom properties** precisely so these stay free:
   so Framer Motion, GSAP and CSS agree without the package choosing one.
 - **Where tokens live.** A `:root` block, a generated file, a Tailwind theme —
   the package does not care.
-- **Layout, grid and component structure.** Out of scope.
+- **Layout, grid and component structure.** Not a rule. Layout *defaults*
+  (hero straight into a trust strip, three icon cards, a reveal on every
+  section) are measured as character in [CHARACTER.md](./CHARACTER.md), as
+  warnings with a declared-exception path, never as rules here.
 - **Brand voice, copy, and photography grading.** Separate standards.
 
 A rule here has to be one that is wrong to break. Everything else is a default.

package/art-direction.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@domandigital/craft/art-direction.schema.json",
+  "title": "art-direction.json",
+  "description": "What a site decided about how it looks, and why. Every choice carries a reason from the client's real world and cites a source that shows it. The reason rule itself is enforced by `craft direction validate`; this schema only checks the shape.",
+  "type": "object",
+  "required": ["version", "client", "brief", "sources", "choices"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "client": { "type": "string", "minLength": 1 },
+    "brief": { "type": "string", "description": "Who, where, and what they do, in a sentence or two." },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "note"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "kind": { "enum": ["livery", "shopfront", "signage", "packaging", "product", "uniform", "interior", "place", "material", "trade", "print", "photo", "founder"] },
+          "note": { "type": "string" },
+          "path": { "type": "string" },
+          "colours": { "type": "array", "items": { "type": "string" } },
+          "lettering": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "choices": {
+      "type": "object",
+      "propertyNames": { "enum": ["accent", "ground", "display", "body", "shape", "motif", "signature"] },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["value", "because", "evidence"],
+        "properties": {
+          "value": { "type": "string" },
+          "because": { "type": "string" },
+          "evidence": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    },
+    "exceptions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["tell", "because"],
+        "properties": {
+          "tell": { "type": "string" },
+          "because": { "type": "string" },
+          "evidence": { "type": "string" },
+          "path": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}