super-ux 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.30.0 — 2026-08-05
+
+The verbal identity layer. `docs/ux/` decides what the product does; the new
+`docs/brand/` decides how it speaks — one voice, many registers, and a linter
+that makes copy drift as findable as chain drift.
+
+### The contract — `brand-contract v1`
+
+`docs/brand/` is a second artifact root beside `docs/ux/`, seeded by the
+installer: `voice.md` (a voice pack, five fixed axes as IS / IS NOT, the
+narrative, the invariants that survive translation), `terminology.md` (our
+words, banned words, exact entity and tier spellings), `facts.md` (the only
+source of any figure in public copy), `channels.md` (one record per surface),
+`strings.md` (the interface string registry, key → `file:line` → scenario),
+and `locales/<code>.md`.
+
+Separate root on purpose: the brand also governs surfaces that are not UX at
+all — a store listing, an ad, a post. The pack derives from `foundation.md`
+and never the reverse.
+
+### Two skills
+
+- **`brand-voice`** — defines and holds the identity. Six shipped voice packs
+  (`operator-brief`, `calm-expert`, `peer-builder`, `editorial-premium`,
+  `plain-service`, `playful-consumer`), each declaring the degeneration it
+  collapses into when overdone, so an overshoot is a finding rather than a
+  matter of taste. Invoked with no task it reports state and proposes exactly
+  one next action, and never invents a missing fact to close a gap.
+- **`copywriting`** — writes in the voice and never writes *to* it. A missing
+  term or an unsourced number is reported, because adding it is the other
+  skill's decision.
+
+Commands: `/brand`, `/brand-init`, `/brand-update`, `/brand-lint`, `/copy`.
+
+### `brand_lint.py` — 31 deterministic checks
+
+Seeded as `docs/brand/lint.py`. Contract and sources (B001–B006), terminology
+(B010–B012), string consistency (B020–B025), facts (B030–B032), channel
+physics (B040–B043), bot safety (B050–B054), machine-drafting markers
+(B060–B061), locales (B070–B073). Exit 0 clean, 1 warnings, 2 errors;
+`--fix` touches only casing, the iOS keyword field, and re-pointing a registry
+row whose string is unchanged. 32 fixtures, one per code, each watched failing
+against a planted defect before it was trusted — and they run in CI.
+
+Three rules it exists to enforce: one action keeps one name everywhere; a
+number in public copy has a sourced row or is not written; no humor on error,
+destructive-confirm, billing or paywall surfaces, in any voice.
+
+### Catalog
+
+`BP-182..205` in six clusters of four — voice and consistency, product
+microcopy, conversion copy, bot safety, channel physics, localization — and
+`PRN-22..24`. New entries carry a sixth field, `Checked:`, dating the last
+verification against the source. It starts at BP-182 deliberately:
+backfilling it onto BP-001..181 would record a verification nobody performed.
+New tags `brand-voice` `copy` `narrative` `terminology` `channel-physics`
+`seo` `aeo` `aso` — `voice` was already taken, and it means a voice interface.
+
+### Elsewhere
+
+`ux-audit` gains scope `copy`, the judgement twin of the linter. `ux_doctor`
+reads the brand marker, because a pack on an old contract is internally
+consistent and the linter stays quiet about it. Scenarios gain an optional
+`Strings:` field. The brand hard rule ships in the Claude rule template and a
+new Cursor rule.
+
+### Fixed
+
+- `CONTRIBUTING.md` told maintainers to run `npm publish --access public`
+  by hand in `sshlg-skills` after a release. Every repo in the family has
+  published from CI on a `v*` tag since that text was written.
+
 ## 0.29.0 — 2026-08-05
 
 A pass aimed at the installed base rather than the catalog. Run across the

package/README.md

@@ -100,6 +100,41 @@ plugin user-globally — any combination in one run. Also works straight from
 GitHub: `npx github:ssheleg/super-ux --cursor <dir>`, or clone and run
 `./install.sh --cursor <dir>`.
 
+## The brand layer — how the product speaks
+
+`docs/ux/` decides what the product does. **`docs/brand/`** decides how it
+speaks, under `brand-contract v1`: one voice, many registers, and a linter
+that makes copy drift as findable as chain drift.
+
+| File | Holds |
+|---|---|
+| `voice.md` | the pack, five fixed axes, narrative, invariants, locales |
+| `terminology.md` | our words, banned words, entity and tier names |
+| `facts.md` | canonical figures — the only source of a number in public copy |
+| `channels.md` | one record per surface: register deltas, limits, bans |
+| `strings.md` | the interface string registry → `file:line` → scenario |
+| `locales/<code>.md` | address form, length coefficient, dead idioms, keywords |
+
+Two skills: **`brand-voice`** defines and holds the identity (six shipped
+voice packs, each declaring the degeneration it collapses into when overdone);
+**`copywriting`** writes in it and never writes *to* it — a missing term or an
+unsourced number is reported, never invented.
+
+Commands: `/brand` (status → one recommended action), `/brand-init`,
+`/brand-update`, `/brand-lint`, `/copy`.
+
+```bash
+python3 docs/brand/lint.py
+```
+
+31 deterministic checks — banned words, one action under two names, a figure
+with no sourced fact, a field over its limit with the locale coefficient
+applied, blocked AI crawlers, keyword stuffing, humor on a billing screen,
+a locale that lags without saying so. Exit 0 clean, 1 warnings, 2 errors.
+
+Clean means *checkable*, not *good*: tone drift, unproven claims and a voice
+that has overshot its own failure mode are judged by `/ux-audit copy`.
+
 ## The hard rule
 
 Installed into your project's `CLAUDE.md` (and as the always-on Cursor rule):

package/bin/super-ux.js

@@ -86,23 +86,46 @@ function installCursor(target, force) {
       console.log(`seed:    ${dst}`);
     }
   }
+  // The brand pack lives beside the UX chain, not inside it: it also governs
+  // surfaces that are not UX at all — a store listing, an ad, a post.
+  fs.mkdirSync(path.join(target, 'docs', 'brand', 'locales'), { recursive: true });
+  for (const tpl of [
+    'README', 'voice', 'terminology', 'facts', 'channels', 'strings',
+  ]) {
+    const dst = path.join(target, 'docs', 'brand', `${tpl}.md`);
+    if (fs.existsSync(dst)) {
+      console.log(`keep:    ${dst} exists (never overwritten)`);
+    } else {
+      fs.copyFileSync(path.join(ROOT, 'templates', 'brand', `${tpl}.md`), dst);
+      console.log(`seed:    ${dst}`);
+    }
+  }
+  {
+    const dst = path.join(target, 'docs', 'brand', 'locales', 'en.md');
+    if (!fs.existsSync(dst)) {
+      fs.copyFileSync(path.join(ROOT, 'templates', 'brand', 'locale.md'), dst);
+      console.log(`seed:    ${dst}`);
+    }
+  }
+
   // The linter is code, not a template — refresh it to the shipped version.
   // Shipped via package.json files[]; if that ever regresses, warn instead of
   // dying on an ENOENT stack trace after the rules are already installed.
   // Paths stay literal so test/validate.py can read them out of this source and
   // check them against package.json files[] — a variable segment here silently
   // turns that check into a directory prefix nobody ships.
-  for (const [src, from, dst] of [
-    ['ux_lint.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py'), 'lint.py'],
-    ['ux_doctor.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_doctor.py'), 'doctor.py'],
+  for (const [src, from, area, dst] of [
+    ['ux_lint.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_lint.py'), 'ux', 'lint.py'],
+    ['ux_doctor.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'ux_doctor.py'), 'ux', 'doctor.py'],
+    ['brand_lint.py', path.join(ROOT, 'plugins', 'super-ux', 'scripts', 'brand_lint.py'), 'brand', 'lint.py'],
   ]) {
-    const to = path.join(target, 'docs', 'ux', dst);
+    const to = path.join(target, 'docs', area, dst);
     if (fs.existsSync(from)) {
       fs.copyFileSync(from, to);
       console.log(`sync:    ${to}`);
     } else {
       console.error(
-        `warning: ${src} not found in this package (${from}); docs/ux/${dst} was not installed.\n` +
+        `warning: ${src} not found in this package (${from}); docs/${area}/${dst} was not installed.\n` +
           `         Get it from https://github.com/${REPO}/blob/main/plugins/super-ux/scripts/${src}`
       );
     }

package/cursor/rules/brand-voice.mdc

@@ -0,0 +1,37 @@
+---
+description: Brand voice and copy — docs/brand/ is the source of truth for how the product speaks; any public-facing text change updates it in the same change and passes docs/brand/lint.py
+alwaysApply: false
+---
+
+# Brand voice (super-ux)
+
+`docs/ux/` decides what the product does. `docs/brand/` decides how it
+speaks, under `brand-contract v1`.
+
+## Before writing any user-visible text
+
+Read `docs/brand/voice.md`, `terminology.md`, and the `channels.md` record
+for the surface. No pack yet → run `/brand-init` rather than improvising a
+voice; a product whose copy was invented surface by surface is the drift
+this layer removes.
+
+## Rules
+
+- Any change to public text updates `docs/brand/` in the same change.
+- Never quote a figure with no row in `facts.md`. Never invent a fact,
+  statistic, quote or expert — report the gap.
+- One action, one name, everywhere it appears. Check `strings.md` first.
+- A register moves the voice axes; it never crosses the invariants listed in
+  `voice.md`.
+- No humor, exclamation marks or emoji on error, destructive confirm,
+  billing or paywall surfaces, in any voice.
+- New interface strings get a `strings.md` row: key, `file:line`, scenario.
+
+## Check
+
+```bash
+python3 docs/brand/lint.py
+```
+
+Exit 0 clean, 1 warnings, 2 errors. Clean means checkable, not good — the
+judgement half is `/ux-audit copy`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Scenario-driven UI development for AI agents (Claude Code, Cursor, 70+ agents): a versioned design chain in docs/ux/, a scenario-first hard rule, a deterministic drift linter, and evidence-backed UX audits. This package is the installer CLI.",
   "bin": {
     "super-ux": "bin/super-ux.js"
@@ -11,6 +11,7 @@
     "templates",
     "plugins/super-ux/scripts/ux_lint.py",
     "plugins/super-ux/scripts/ux_doctor.py",
+    "plugins/super-ux/scripts/brand_lint.py",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"