nimiq-branding-cli 1.1.1 → 1.2.1

package/.audit/report.json

@@ -0,0 +1,71 @@
+{
+  "generatedAtNote": "timestamp stamped by caller",
+  "verdict": "clean",
+  "repos": {
+    "hub": {
+      "branch": "master",
+      "pinned": "cf2ea419",
+      "live": "cf2ea419",
+      "pinnedFull": "cf2ea41941e433fa8e28ff4fe3d60870005c2115",
+      "liveFull": "cf2ea41941e433fa8e28ff4fe3d60870005c2115",
+      "via": "local",
+      "drifted": false
+    },
+    "wallet": {
+      "branch": "master",
+      "pinned": "656ed569",
+      "live": "656ed569",
+      "pinnedFull": "656ed569dac0e20ff61bba95a4fef14fce3541d6",
+      "liveFull": "656ed569dac0e20ff61bba95a4fef14fce3541d6",
+      "via": "local",
+      "drifted": false
+    },
+    "nimiq-ui": {
+      "branch": "main",
+      "pinned": "68e96cde",
+      "live": "68e96cde",
+      "pinnedFull": "68e96cdeb1104bd5cd1556f5cd2619b8509c4529",
+      "liveFull": "68e96cdeb1104bd5cd1556f5cd2619b8509c4529",
+      "via": "local",
+      "drifted": false
+    },
+    "nimiq-style": {
+      "branch": "master",
+      "pinned": "21c10a14",
+      "live": "21c10a14",
+      "pinnedFull": "21c10a14b324a133ddb78f906015765bf6cb13ec",
+      "liveFull": "21c10a14b324a133ddb78f906015765bf6cb13ec",
+      "via": "local",
+      "drifted": false
+    },
+    "vue-components": {
+      "branch": "master",
+      "pinned": "3c5b9724",
+      "live": "3c5b9724",
+      "pinnedFull": "3c5b97247e68a8bdcba5e904ff8ac29482995759",
+      "liveFull": "3c5b97247e68a8bdcba5e904ff8ac29482995759",
+      "via": "local",
+      "drifted": false
+    }
+  },
+  "driftedComponents": [],
+  "tokenDrift": [],
+  "unknownPaths": [],
+  "verify": {
+    "ran": false
+  },
+  "newComponents": [
+    "vue-components:src/components/Account.vue",
+    "vue-components:src/components/AccountDetails.vue",
+    "vue-components:src/components/AccountSelector.vue",
+    "vue-components:src/components/BottomOverlay.vue",
+    "vue-components:src/components/Carousel.vue",
+    "vue-components:src/components/CircleSpinner.vue",
+    "vue-components:src/components/CopyableField.vue",
+    "vue-components:src/components/LanguageSelector.vue",
+    "vue-components:src/components/LongPressButton.vue",
+    "vue-components:src/components/QrScanner.vue",
+    "vue-components:src/components/Wallet.vue"
+  ],
+  "summary": "verdict: clean · 0/5 upstream(s) drifted · 0 component(s) upstream-touched · 0 token-drift · 0 unknown path(s) · verify skipped"
+}

package/.audit/report.md

@@ -0,0 +1,33 @@
+# nq audit report
+
+**verdict: clean · 0/5 upstream(s) drifted · 0 component(s) upstream-touched · 0 token-drift · 0 unknown path(s) · verify skipped**
+
+## Upstream pins vs live
+
+| repo | branch | pinned | live | drifted | changed files |
+|---|---|---|---|---|---|
+| hub | master | `cf2ea419` | `cf2ea419` | no | — |
+| wallet | master | `656ed569` | `656ed569` | no | — |
+| nimiq-ui | main | `68e96cde` | `68e96cde` | no | — |
+| nimiq-style | master | `21c10a14` | `21c10a14` | no | — |
+| vue-components | master | `3c5b9724` | `3c5b9724` | no | — |
+
+## New-component radar
+
+Upstream components with no registry port yet (candidates — cross-ref FEATURES.md):
+
+- `vue-components:src/components/Account.vue`
+- `vue-components:src/components/AccountDetails.vue`
+- `vue-components:src/components/AccountSelector.vue`
+- `vue-components:src/components/BottomOverlay.vue`
+- `vue-components:src/components/Carousel.vue`
+- `vue-components:src/components/CircleSpinner.vue`
+- `vue-components:src/components/CopyableField.vue`
+- `vue-components:src/components/LanguageSelector.vue`
+- `vue-components:src/components/LongPressButton.vue`
+- `vue-components:src/components/QrScanner.vue`
+- `vue-components:src/components/Wallet.vue`
+
+---
+
+Verdicts: **clean** (nothing moved) · **safe** (only learnings-"ignore" churn → auto-PR pin bump) · **risky** (component/token/unknown/verify-fail → human review).

package/AUDIT.md

@@ -0,0 +1,60 @@
+# Staying current with Nimiq — the self-learning branding audit
+
+`nq verify` proves our **port matches the vendored upstream truth render**. But that render is a
+frozen snapshot — if Nimiq redesigns a component or changes a token upstream, `verify` stays green
+against a stale reference. `nq audit` closes that gap: it watches the **live** Nimiq source and tells
+you when the real design has moved away from what the registry ships.
+
+## The two axes of branding accuracy
+
+| Axis | Question | Tool |
+|---|---|---|
+| Port fidelity | Does our component still render like the upstream truth? | `nq verify` |
+| Upstream currency | Has the live Nimiq source moved away from our pin? | `nq audit` |
+
+## What `nq audit` does
+
+1. **Upstream drift** — compares each `pinned` commit in [`upstream-pins.json`](upstream-pins.json)
+   to the live branch tip (`git ls-remote` locally or in CI). For drifted repos it gets the changed
+   file list (local clone `git diff`, or the GitHub compare API in CI).
+2. **Provenance intersection** — every component's `meta.json` has a `source` block listing the exact
+   upstream files it was ported from. Changed files are intersected with these → drift is attributed to
+   the precise components it touches. **A changed file that any component lists is always escalated to
+   `risky` before the learnings rules run**, so broad benign-churn rules can never hide a real change.
+3. **Token / framework drift** — flags changes to the design-token sources (`nimiq-style`, `@nimiq/css`).
+4. **Port fidelity** — runs `nq verify all` and folds the result in.
+5. **New-component radar** — lists upstream `@nimiq/vue-components` with no registry port yet.
+
+Output: `.audit/report.json` (machine) + `.audit/report.md` (human).
+
+## Verdicts
+
+- **clean** — nothing moved, ports green. No action.
+- **safe** — upstream moved, but every changed file is learnings-classified benign (deps, tests, i18n,
+  app logic, flow views), no component/token touched, and verify passed → the weekly workflow **auto-PRs
+  a pin bump**. Safe because the gate proved nothing visual changed.
+- **risky** — a component's real source changed (needs hand re-port), a token changed, an **unknown** path
+  needs triage, or verify failed → the workflow opens/updates a **rolling GitHub issue** for a human.
+
+## The self-learning loop (`audit/learnings.json`)
+
+Each changed path is classified `ignore` / `token` / `branding` by glob rules. Unmatched paths are
+`unknown` and surfaced for triage. **Resolving a triage = appending a rule** (with `seenCount++` and a
+`learnedFrom` note). Next run, that churn auto-classifies — fewer false alarms, faster known fixes. The
+store gets smarter every week. Seed rules came from the 2026-06-16 reconciliation of the hub/wallet
+Bitcoin/Ledger/swap drift, which touched none of our ports.
+
+## Weekly automation
+
+[`.github/workflows/audit.yml`](.github/workflows/audit.yml) runs every Monday (and on demand via
+`workflow_dispatch`): re-snaps references for a platform-consistent verify, runs `nq audit`, then
+auto-PRs safe pin bumps or files the rolling issue. The pin record in `upstream-pins.json` is the
+single committed source of truth for "what we are current with".
+
+## Triage workflow (when you get a `risky` issue)
+
+1. Read `.audit/report.md`. For each **upstream-touched component**, diff the upstream file and re-port
+   the truth render → `node scripts/snap.mjs <name>` → `node bin/nq.js verify <name>`.
+2. For each **unknown path**, decide if it's benign or branding-relevant and add a rule to
+   `audit/learnings.json` (that's the learning).
+3. Bump the pin in `upstream-pins.json`, run `nq sync-skill`, commit.

package/LINT.md

@@ -0,0 +1,158 @@
+# nq lint — brand + breathability enforcement
+
+`nq audit` watches the *upstream* Nimiq design for drift. `nq lint` is the other direction:
+it renders **your** page (desktop + a 390px mobile pass) and checks it against the Nimiq rules,
+so the brand discipline that used to live only as prose (the 21 rules + AI-slop blacklist in the
+`nimiq-ui` skill) becomes something a machine can actually *deny*, not just something a human is
+asked to remember.
+
+```bash
+nq lint <file.html | url>     # render + check; exit 1 if any ERROR
+nq lint page.html --fix       # also auto-fix the safe text violations in place
+nq lint https://site/ --json  # machine-readable
+```
+
+It renders with the same Playwright harness as `nq verify` (no new runtime dep). For URLs it
+dismisses a language-picker splash (e.g. nimiq.tech) and scrolls to trigger lazy sections;
+decorative SVG fields (honeycomb / identicon fences) are excluded from every measurement.
+
+> **Lint source files, not live URLs, when you can.** A built/static `.html` file renders
+> deterministically. A live SPA adds splash gates, lazy hydration and thousands of decorative
+> nodes — handled, but fragile. URL mode is for spot-checks; the gate should point at source.
+
+---
+
+## Two layers
+
+### ERRORS — off-brand slop (hard-fail, exit 1)
+Unambiguous, deterministic, and verified **not** to fire on nimiq.com itself (see calibration).
+These are the "make us not do AI things" set.
+
+| Check | Rule | Auto-fix |
+|---|---|---|
+| em/en dashes in copy | skill rule 18 | `--fix` → comma |
+| periods on display titles / CTAs | skill rule 16 | `--fix` → strip |
+| glassmorphism (translucent surface + backdrop blur) | skill rule 10 | manual |
+| borders on inputs | skill rule 1 | manual (inset box-shadow) |
+| off-palette colors | skill rule 13 | manual |
+| low-contrast blue/navy text on dark | skill rule 20 | manual → `#0CA6FE` / white |
+
+**Blue/navy on dark (rule 20)** is the headline a11y+brand check. A blue-family foreground (hue
+195–245°) sitting on a dark surface (luminance < 0.12) below the AA floor — **4.5:1 normal, 3.0:1
+large** — fails. Raw `#0582CA` on navy = 3.63:1 and `#265DD7` = 2.61:1 both error; the on-dark
+variant `#0CA6FE` (5.68:1) and white pass cleanly. The background is read from the element's *own*
+surface first (so blue text on a light card nested in a dark section is not a false positive), and
+gradient-filled CTAs with white text are never flagged.
+
+### WARNINGS — breathability / density (advisory, never block)
+These **cannot** hard-fail: nimiq.com's own marketing trips several of them (it runs 12 font
+sizes and 31–38% dense sections). They're calibrated to the measured Nimiq envelope and exist
+to flag *"this is getting busy, is it justified?"* — the deterministic half of PRINCIPLES law 4
+("white space does the structural work").
+
+**Breathability / density**
+
+| Check | Threshold | Why |
+|---|---|---|
+| body text wider than ~88ch | `> 88ch` | prose measure caps at 78ch; nimiq.com p90 ≈ 84ch |
+| dense sections (text-ink ratio) | `> 18%` of a full-width band | nimiq.com pages run 5–12% page ink |
+| off-scale spacing | values not on the curated scale | warn-and-snap, not fail |
+| type-scale sprawl | `> 12` distinct text sizes | calm app ≈ 4; busy marketing ≈ 12 |
+| colored / long / pill uppercase eyebrow | colored, >24 chars, or a pill | grey section labels are fine (rules 8, 17) |
+
+**Depth / motion / form** (from the design recon)
+
+| Check | Threshold |
+|---|---|
+| non-pill action buttons | a text button radius below a full pill (and not a nav trigger) |
+| flat-fill colored button | a brand-colored button with no radial gradient |
+| wrong gradient anchor | a linear-gradient, or a radial not at bottom-right / `100% 100%` |
+| non-Nimiq easing | the Material `cubic-bezier(0.4,0,0.2,1)` on a button (use `cubic-bezier(0.25,0,0,1)`) |
+| off-scale border-radius | not on `3 · 4 · 6 · 8 · 10 · 12` or a full pill / 50% |
+| harsh near-black shadow | `rgba(0,0,0, > 0.22)` (Nimiq shadows are soft, low-alpha) |
+| underlined links | a body `<a>` with `text-decoration: underline` (links are bold, no underline) |
+| NIM address not in Fira Mono | a 4-char-grouped address rendered in a proportional font |
+| gold-tinted UI icon | a non-logo icon tinted gold (gold = brand mark only) |
+
+**Mobile (a second pass at 390px)**
+
+| Check | Threshold |
+|---|---|
+| horizontal overflow | `scrollWidth > viewport` by > 4px |
+| tap targets too small | a button / input / link-button under 30px (inline text links are exempt) |
+| text smaller than 12px | any text element below 12px at mobile width |
+
+The curated spacing scale (from `assets/css/modern/spacing.css`, desktop max of each step):
+`8 · 12 · 16 · 24 · 32 · 40 · 48 · 72 · 80 · 96 · 144 · 200`. Sub-8px is treated as optical
+nudging, not layout, and ignored. The radius scale: `3 · 4 · 6 · 8 · 10 · 12` plus full pills
+(500/999/9999) and circles (50%).
+
+---
+
+## Exceptions are part of the spec
+
+Calibration against real pages proved that a naive version of each rule flags Nimiq's own
+sites. The carve-outs are load-bearing, not afterthoughts:
+
+- **Social brand icons** — Discord/Telegram/X/YouTube/etc. colors are exempt from the palette
+  rule (you can't recolor a third-party logo). Reported separately as `exempt social-icon colors`.
+- **Blue-tinted neutrals** — Nimiq grays carry a deliberate violet spin, so "neutral" is tested
+  by *saturation relative to lightness*, not a flat channel spread.
+- **Secondary palette** — purple `#5F4B8B`, pink `#FA7268`, light-green `#88B04B`, brown
+  `#795548` (+ gradient starts) are brand colors, not violations.
+- **Abbreviations** — `p.a.`, `e.g.`, `U.S.` don't count as title periods (internal-dot guard).
+- **Translucent-only glass** — a near-opaque panel (≥85% bg) with a faint backdrop blur is a
+  solid surface, not glassmorphism. Only `10–85%` translucency + backdrop blur is flagged.
+- **Grey section eyebrows** — short grey uppercase labels ("THE APPS", "TRUSTED BY") are the
+  brand's own pattern; only *colored*, *>24-char*, or *pill* uppercase is flagged.
+- **Addresses & codes** — `NQ…` addresses and short alphanumeric codes (`L51C`) are uppercase by
+  nature and excluded from the eyebrow check.
+- **Own-surface contrast** — blue/navy text is judged against the element's *own* background
+  first, so blue text on a light card inside a dark section isn't a false error; gradient-filled
+  CTAs (white text) are never flagged.
+- **Inline links & nav triggers** — inline text links are exempt from the mobile tap-target check;
+  `nav`/`header` text buttons are exempt from the non-pill check.
+
+---
+
+## Calibration (measured, not invented)
+
+Thresholds were set by rendering real Nimiq pages at 1440px and measuring the envelope — the
+same "measure reality" method that proved the no-em-dash rule. Verified outcome:
+
+| Page | ERRORS | Note |
+|---|---|---|
+| nimiq.com home (reference) | **0** | the gate must never flag the brand's own site, even with the rule-20 contrast + depth/motion checks |
+| nimiq.com/about | 0 | — |
+| nimiq.tech | real findings | catches genuine em-dashes + a "Phase 2 · preview" colored eyebrow + 3 dense bands |
+| positive control | **2** | a deliberate `#0582CA`/`#265DD7`-on-navy page errors at 3.63/2.61:1; `#0CA6FE` + white pass |
+
+Re-run the calibration any time the rules change:
+`node bin/nq.js lint https://www.nimiq.com/` **must stay at 0 errors.** If a new rule flags the
+reference, the rule is wrong — fix the rule, not nimiq.com. (That principle just caught four
+over-strict rules during the 2026-06-20 hardening, including a blue-on-navy false error that the
+own-surface-bg fix resolved.)
+
+---
+
+## Exit codes & `--fix`
+
+- Exit `1` if any ERROR; `0` otherwise (warnings never affect exit). Wire the exit code into a
+  pre-commit hook or CI step to make it a real gate.
+- `--fix` (local files only) applies the safe **text** transforms — em/en dashes → comma,
+  strip trailing title periods — and reports what it changed. It never silently green-washes:
+  geometry fixes (measure width, spacing snap, glass → solid) are reported for a human/agent,
+  because rewriting layout unsupervised can break the page.
+
+---
+
+## Roadmap
+
+- **Render-mapped geometry autofix** — map a flagged rendered element back to its source line so
+  `--fix` can also constrain over-wide text and snap off-scale spacing, each behind a
+  re-render-and-verify check so a fix that breaks layout is rejected instead of shipped.
+- **Layer 3 — optional aesthetic judgment (BYO-key).** A cheap vision pass for the irreducible
+  residue the metrics can't see ("is this busyness *justified*? does it feel Nimiq or generic
+  SaaS?"). Off by default; the deterministic layers above stay free, offline, and keyless.
+- **`learnings.json` for lint** — same self-learning store as `nq audit`, so confirmed false
+  positives are remembered and suppressed across runs.

package/README.md

@@ -1,8 +1,10 @@
 # nimiq-branding-cli
 
 Scaffold **pixel-accurate Nimiq-branded UI components** into any project — Vue 3 SFCs or plain
-HTML/CSS — from a registry of 39 components where every one is pixel-diffed against the real
-Nimiq apps before it ships, plus the team's real asset library (logos, icons, flags, imagery).
+HTML/CSS — from a registry of 40 components (39 pixel-diffed against the real Nimiq apps before
+they ship, plus 1 original brand composition), plus the team's real asset library (logos, icons,
+flags, imagery). A weekly self-learning audit keeps it current with live Nimiq design — see
+[AUDIT.md](AUDIT.md).
 
 > Unofficial community project — see [NOTICE.md](NOTICE.md). All visuals are the Nimiq team's
 > real shipped files or faithful ports of their open-source components, never hand-drawn
@@ -29,18 +31,52 @@ ln -s "$PWD/bin/nq.js" ~/.local/bin/nq   # or: npm link
 ## Use
 
 ```
-nq list                     # browse the 39-component registry
+nq list                     # browse the 40-component registry
 nq init --style modern      # drop Nimiq design tokens into your project
 nq add amount-input         # copy a component (+ deps + CSS + real assets) into src/components
 nq add account-header --html   # plain HTML/CSS variant instead of Vue
 nq assets search wallet     # search 182 vendored files + 323 nimiq-icons + 422 hexagon flags
 nq assets add icon:logos-nimiq-horizontal flag:cr-hexagon world-map
 nq verify all               # (repo dev) re-run pixel verification against references
+nq audit                    # (repo dev) check the LIVE Nimiq upstreams for branding drift
+nq sync-skill               # (repo dev) regenerate the nimiq-ui skill block from index.json
 ```
 
 Open `showcase.html` for the full component gallery and `supporting-elements.html` for the
 wallet + marketing element demos.
 
+## Fleet stack alignment (`nq align` / `nq new-app` / `nq hooks`)
+
+Branding accuracy (`nq audit`/`nq verify`) keeps the UI matching Nimiq's design. `nq align`
+keeps a whole **app** on the canonical Nimiq fleet stack — same verdict vocabulary
+(`clean` / `safe-drift` / `risky-fail`).
+
+```
+nq new-app my-app           # scaffold a CANONICAL app: Bun+Hono+bun:sqlite+vanilla PWA+
+                            # @nimiq/style + inline rpc-block-scan settlement + Fly deploy
+                            # kit + ci.yml + a stamped nimiq-stack.json + /health. Aligns clean.
+nq new-app readonly --no-chain  # informational app (chainApp:false → skip settlement/styling parity)
+nq new-app pay --settlement rpc --deploy fly
+# (nq new <name> still scaffolds a UI registry component, unchanged)
+
+nq align                    # grade the app in cwd against the canonical fleet baseline
+nq align --all ~/Projects   # grade every app dir under a folder
+nq align --fix              # safe autofixes only (write/repair nimiq-stack.json)
+nq align --fail-on=settlement,styling   # nonzero exit for the pre-commit / CI gate
+
+nq hooks install            # git pre-commit gate + SessionStart banner + weekly GH Action
+```
+
+**The load-bearing axis is SETTLEMENT.** The `@nimiq/core` light client never reaches
+consensus on our hosts, so any `@nimiq/core/web` import or `Client.create(` /
+`waitForConsensusEstablished(` in `src/` is a **HARD FAIL**. Chain reads must use the
+rpc-block-scan path (the `nimiq-settlement` package). `@nimiq/core` is offline-crypto-only.
+
+Each app declares a root `nimiq-stack.json` (schema: `schemas/nimiq-stack.v1.json`); the
+canonical fleet baseline `nq align` grades against lives in `align/canonical.json`. Apps
+that are intentionally off-stack (e.g. nimiq.tech, nimiq-ads, gateflo) set `"exempt": true`
+and are reported but never failed.
+
 ## How pixel accuracy is enforced
 
 Every registry component carries:
@@ -65,7 +101,10 @@ disabled) and diffs it against `reference.png` with pixelmatch. Components whose
 | `onmax/nimiq-ui` | modern `nimiq-css` (oklch tokens, auto dark mode) |
 | `references/screenshots/` | captured reference screenshots of live Nimiq properties |
 
-Upstream clones live in `upstream/` (gitignored — re-clone with `git clone --depth 1`).
+Upstream clones live in `upstream/` (gitignored — re-clone with `git clone --depth 1`). The exact
+commits the registry was verified against are recorded in [`upstream-pins.json`](upstream-pins.json) —
+the committed source of truth for "what we are current with". `nq audit` watches the live tips against
+these pins; see [AUDIT.md](AUDIT.md).
 
 ## Repo layout
 
@@ -79,5 +118,9 @@ assets/
   css/legacy/          vendored @nimiq/style (nq-* classes)
   tokens.md            design-token quick reference
 scripts/verify.mjs     pixel-diff harness (playwright + pixelmatch)
+scripts/audit.mjs      live-upstream branding-drift engine (nq audit)
+scripts/sync-skill.mjs regenerates the nimiq-ui skill block from index.json
+upstream-pins.json     the upstream commits the registry is verified against
+audit/learnings.json   self-learning store: which upstream churn is benign vs branding
 references/screenshots side-by-side reference captures of live Nimiq UIs
 ```

package/align/canonical.json

@@ -0,0 +1,44 @@
+{
+  "description": "The CANONICAL Nimiq fleet baseline that `nq align` grades every app's nimiq-stack.json against. Derived from the proven shipping stack (SnapPOS RPC-settlement, nimiq-split reference manifest, TipJar/Beelink deploy kit). This file is the single committed source of truth for 'what a canonical chain app looks like'. Drift off these values is graded with the same vocabulary as nq audit: clean (matches), safe-drift (different but defensible — warn), risky-fail (load-bearing axis violated — fail).",
+  "canonicalVersion": "0.1.0",
+  "schemaVersion": 1,
+  "stack": {
+    "framework": "vanilla-pwa",
+    "server": "hono",
+    "runtime": "bun",
+    "build": "none",
+    "packageManager": "bun"
+  },
+  "styling": {
+    "source": "nimiq-ui"
+  },
+  "settlement": {
+    "pattern": "rpc-block-scan",
+    "lib": "nimiq-settlement",
+    "coreRole": "offline-crypto-only",
+    "acceptedPatterns": ["rpc-block-scan", "mock", "noop"],
+    "acceptedLibs": ["nimiq-settlement", "inline"],
+    "forbiddenPatterns": ["light-client"]
+  },
+  "deploy": {
+    "target": "fly",
+    "region": "ord",
+    "storage": "fly-volume",
+    "edge": {
+      "provider": "cloudflare",
+      "proxied": true
+    }
+  },
+  "config": {
+    "tsconfig": "local-strict",
+    "lint": "none",
+    "fileSizeGuard": 800,
+    "ci": true
+  },
+  "settlementPackage": "nimiq-settlement",
+  "lightClient": {
+    "forbiddenImports": ["@nimiq/core/web"],
+    "forbiddenCalls": ["Client.create(", "waitForConsensusEstablished("],
+    "reason": "The @nimiq/core light client never reaches consensus on our hosts (WASM addEventListener bug, hangs in Bun/Node through 2.7.0). Chain reads MUST use the rpc-block-scan path via the nimiq-settlement package; @nimiq/core is offline-crypto-only (key/tx signing)."
+  }
+}

package/audit/learnings.json

@@ -0,0 +1,51 @@
+{
+  "description": "Self-learning store for nq audit. Each rule classifies a changed upstream path (\"<repo>:<path>\", glob: ** = any incl. /, * = any excl. /) as `ignore` (benign churn — never affects our visual ports), `token` (design-framework/token change — review nq init + tokens), or `branding` (visual source change). SAFETY: a changed file that a component lists in meta.json `source.files` is ALWAYS escalated to risky BEFORE these rules run, so broad `ignore` rules cannot mask a real component change. Unmatched paths are `unknown` → surfaced for triage; resolving one means appending a rule here with seenCount++ (that is the learning).",
+  "rules": [
+    { "pattern": "*:**/*.spec.ts", "verdict": "ignore", "reason": "unit test", "seenCount": 0 },
+    { "pattern": "*:**/*.test.ts", "verdict": "ignore", "reason": "unit test", "seenCount": 0 },
+    { "pattern": "*:**/test/**", "verdict": "ignore", "reason": "test dir", "seenCount": 0 },
+    { "pattern": "*:**/tests/**", "verdict": "ignore", "reason": "test dir", "seenCount": 0 },
+    { "pattern": "*:**/__tests__/**", "verdict": "ignore", "reason": "test dir", "seenCount": 0 },
+    { "pattern": "*:**/__mocks__/**", "verdict": "ignore", "reason": "test mocks", "seenCount": 0 },
+    { "pattern": "*:**/*.stories.*", "verdict": "ignore", "reason": "storybook story", "seenCount": 0 },
+    { "pattern": "*:package.json", "verdict": "ignore", "reason": "dependency manifest", "seenCount": 0 },
+    { "pattern": "*:package-lock.json", "verdict": "ignore", "reason": "lockfile", "seenCount": 0 },
+    { "pattern": "*:yarn.lock", "verdict": "ignore", "reason": "lockfile", "seenCount": 0 },
+    { "pattern": "*:pnpm-lock.yaml", "verdict": "ignore", "reason": "lockfile", "seenCount": 0 },
+    { "pattern": "*:.github/**", "verdict": "ignore", "reason": "CI config", "seenCount": 0 },
+    { "pattern": "*:.husky/**", "verdict": "ignore", "reason": "git hooks", "seenCount": 0 },
+    { "pattern": "*:.vscode/**", "verdict": "ignore", "reason": "editor config", "seenCount": 0 },
+    { "pattern": "*:**/*.config.*", "verdict": "ignore", "reason": "build/tool config", "seenCount": 0 },
+    { "pattern": "*:tsconfig*", "verdict": "ignore", "reason": "ts config", "seenCount": 0 },
+    { "pattern": "*:README*", "verdict": "ignore", "reason": "docs", "seenCount": 0 },
+    { "pattern": "*:CHANGELOG*", "verdict": "ignore", "reason": "docs", "seenCount": 0 },
+    { "pattern": "*:**/*.md", "verdict": "ignore", "reason": "docs", "seenCount": 0 },
+    { "pattern": "*:**/i18n/**", "verdict": "ignore", "reason": "translations", "seenCount": 0 },
+    { "pattern": "*:**/*.po", "verdict": "ignore", "reason": "translations", "seenCount": 0 },
+    { "pattern": "*:src/i18n/**", "verdict": "ignore", "reason": "translations", "seenCount": 0 },
+    { "pattern": "*:src/lang/**", "verdict": "ignore", "reason": "translations", "seenCount": 0 },
+    { "pattern": "*:**/*Sentry*", "verdict": "ignore", "reason": "telemetry, not branding", "seenCount": 0 },
+    { "pattern": "*:**/*sentry*", "verdict": "ignore", "reason": "telemetry, not branding", "seenCount": 0 },
+    { "pattern": "*:src/stores/**", "verdict": "ignore", "reason": "app state — visual ports live in the .vue/.css files in provenance", "seenCount": 0 },
+    { "pattern": "*:src/lib/**", "verdict": "ignore", "reason": "app logic — not visual markup/style", "seenCount": 0 },
+    { "pattern": "*:src/electron/**", "verdict": "ignore", "reason": "desktop shell", "seenCount": 0 },
+    { "pattern": "*:src/composables/**", "verdict": "ignore", "reason": "app logic", "seenCount": 0 },
+
+    { "pattern": "*:src/views/**", "verdict": "ignore", "reason": "app-flow pages (compose shared components) — we port shared components from src/components, not full views", "seenCount": 1, "learnedAt": "2026-06-16", "learnedFrom": "hub drift 9e9b653→cf2ea419 (Bitcoin/Ledger swap success views)" },
+    { "pattern": "*:src/config/**", "verdict": "ignore", "reason": "network/app config", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:src/*.ts", "verdict": "ignore", "reason": "top-level entrypoint/logic (main/export/iframe/cashlink), not visual markup/style", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:types/**", "verdict": "ignore", "reason": "type declarations", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:patches/**", "verdict": "ignore", "reason": "dependency patches", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:public/**", "verdict": "ignore", "reason": "static/build assets (e.g. bundled bitcoin libs)", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:demos/**", "verdict": "ignore", "reason": "demo pages", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "hub:client/**", "verdict": "ignore", "reason": "hub client subpackage build", "seenCount": 1, "learnedAt": "2026-06-16" },
+    { "pattern": "*:bitcoinjs-parts.js", "verdict": "ignore", "reason": "vendored BTC lib build artifact", "seenCount": 1, "learnedAt": "2026-06-16" },
+
+    { "pattern": "nimiq-style:src/**", "verdict": "token", "reason": "design framework source — colors/typography/buttons/layout; review nq tokens + nq init", "seenCount": 0 },
+    { "pattern": "nimiq-style:nimiq-style.min.css", "verdict": "token", "reason": "compiled framework css that nq init/add ship", "seenCount": 0 },
+    { "pattern": "nimiq-ui:packages/nimiq-css/**", "verdict": "token", "reason": "modern @nimiq/css token source", "seenCount": 0 },
+    { "pattern": "*:**/themes.scss", "verdict": "token", "reason": "theme variables feeding component ports", "seenCount": 0 },
+    { "pattern": "*:**/variables.scss", "verdict": "token", "reason": "scss variables feeding component ports", "seenCount": 0 },
+    { "pattern": "*:src/scss/**", "verdict": "token", "reason": "shared scss (themes/variables/mixins) feeding component ports", "seenCount": 0 }
+  ]
+}

package/bin/nq.js

@@ -25,9 +25,31 @@ Usage:
   nq assets add <name...>       Copy official asset(s) into ./nimiq/assets/
                                 (icon:<name> extracts from nimiq-icons, flag:<cc> from nimiq-flags)
   nq principles                 Print the Nimiq design principles — the soul of this tool
-  nq new <name>                 Scaffold a new registry component with the principles
-                                checklist + verification contract embedded
+  nq new <name>                 Scaffold a new REGISTRY component (principles checklist +
+                                verification contract embedded)
+  nq new-app <name>             Scaffold a CANONICAL Nimiq fleet app (Bun+Hono+bun:sqlite+
+                                vanilla PWA + @nimiq/style + nimiq-settlement + Fly kit +
+                                a stamped nimiq-stack.json + /health). Starts clean on align.
+      --no-chain                chainApp:false (skip settlement + styling parity)
+      --settlement mock|rpc|noop    settlement client (default mock)
+      --deploy fly|none         deploy kit (default fly)
+  nq align [path]               Grade an app's stack vs the canonical fleet baseline.
+      --all <dir>               Grade every app dir under <dir>
+      --fix                     Safe autofixes only (write/repair nimiq-stack.json)
+      --fail-on settlement,styling   Nonzero exit if a listed axis is risky-fail (the gate)
+      --quiet                   One-line drift banner (SessionStart)  --json  machine output
+                                SETTLEMENT is load-bearing: any @nimiq/core/web import or
+                                Client.create( / waitForConsensusEstablished( in src HARD FAILS.
+  nq hooks install [repo]       Install the drift hooks: git pre-commit (align --fail-on),
+                                SessionStart banner, weekly GH Action (--write drops the workflow)
   nq verify <component|all>     Render the html variant and diff against the reference PNG
+  nq lint <file.html|url>       Render a page and enforce the brand rules + breathability.
+      --fix                     Auto-fix the safe text violations in a local file (dashes, title periods)
+      --json                    Machine-readable output
+                                ERRORS (off-brand slop) fail; WARNINGS (density) advise. See LINT.md
+  nq audit [--skip-verify]      Check the LIVE Nimiq upstreams for branding drift vs our
+                                pinned registry; attribute drift to components; write a report
+  nq sync-skill                 Regenerate the nimiq-ui skill's registry block from index.json
   nq help                       This message
 
 All visual assets are the team's real shipped files (nimiq.com, wallet, hub,
@@ -52,6 +74,19 @@ function parseFlags(args) {
     if (a === '--vue' || a === '--html') flags.variant = a.slice(2);
     else if (a === '--out') flags.out = args[++i];
     else if (a === '--style') flags.style = args[++i];
+    else if (a === '--fix') flags.fix = true;
+    else if (a === '--json') flags.json = true;
+    else if (a === '--quiet') flags.quiet = true;
+    else if (a === '--all') flags.all = (args[i + 1] && !args[i + 1].startsWith('--')) ? args[++i] : true;
+    else if (a === '--no-chain') flags.noChain = true;
+    else if (a.startsWith('--settlement=')) flags.settlement = a.slice('--settlement='.length);
+    else if (a === '--settlement') flags.settlement = args[++i];
+    else if (a.startsWith('--deploy=')) flags.deploy = a.slice('--deploy='.length);
+    else if (a === '--deploy') flags.deploy = args[++i];
+    else if (a.startsWith('--fail-on=')) flags.failOn = a.slice('--fail-on='.length);
+    else if (a === '--fail-on') flags.failOn = args[++i];
+    else if (a === '--check') flags.check = true;
+    else if (a === '--write') flags.write = true;
     else rest.push(a);
   }
   return { flags, rest };
@@ -259,10 +294,10 @@ const CHECKLIST = [
   'reproducible: plain HTML/CSS or standard Vue, passes nq verify',
 ];
 
-async function cmdNew(name, flags) {
-  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('nq new <kebab-case-name>');
+async function cmdNewComponent(name, flags) {
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('nq new-component <kebab-case-name>');
   if (ROOT.includes('node_modules') || ROOT.includes('_npx')) {
-    throw new Error('nq new scaffolds a component INTO the registry repo — clone it first:\n  git clone https://github.com/Andjroo111/nimiq-branding-cli\nthen run nq new from that checkout.');
+    throw new Error('nq new-component scaffolds a component INTO the registry repo — clone it first:\n  git clone https://github.com/Andjroo111/nimiq-branding-cli\nthen run nq new-component from that checkout.');
   }
   const dir = join(ROOT, 'registry', 'components', name);
   if (existsSync(dir)) throw new Error(`component "${name}" already exists`);
@@ -327,6 +362,37 @@ async function cmdNew(name, flags) {
 Read the soul of the tool first: nq principles`);
 }
 
+async function cmdNew(name, flags) {
+  const { scaffoldApp } = await import(join(ROOT, 'scripts', 'scaffold.mjs'));
+  const r = await scaffoldApp(name, { noChain: flags.noChain, settlement: flags.settlement, deploy: flags.deploy });
+  console.log(`+ scaffolded canonical Nimiq app → ${r.dir}`);
+  console.log(`  ${r.files.length} files · chainApp=${r.chain}${r.chain ? ` · settlement=${r.settlement}` : ''} · deploy=${r.deploy}`);
+  console.log(`\nNext:\n  cd ${name}\n  bun install\n  bun run dev      # http://localhost:3000  (try GET /health)\n  nq align         # should be clean on every axis\n  nq hooks install # add the pre-commit settlement/styling gate`);
+}
+
+async function cmdHooks(sub, flags) {
+  const { installHooks, SESSION_START, WEEKLY_WORKFLOW } = await import(join(ROOT, 'scripts', 'hooks.mjs'));
+  if (sub === 'install') {
+    const r = await installHooks(rest[1], { write: !!flags.write });
+    for (const p of r.wrote) console.log(`+ ${p}`);
+    for (const p of r.printed) console.log(`  ${p}`);
+    console.log(`\nSessionStart advisory — add to .claude/settings.json hooks.SessionStart:\n  ${SESSION_START.trim().split('\n').pop()}`);
+    console.log(`\nWeekly GH Action: copy hooks/stack-align.yml into .github/workflows/ (or re-run with --write).`);
+    return;
+  }
+  if (sub === 'show' || !sub) {
+    console.log('# git pre-commit (.git/hooks/pre-commit):\n');
+    const { PRE_COMMIT } = await import(join(ROOT, 'scripts', 'hooks.mjs'));
+    console.log(PRE_COMMIT);
+    console.log('# SessionStart advisory:\n');
+    console.log(SESSION_START);
+    console.log('# weekly GH Action (.github/workflows/stack-align.yml):\n');
+    console.log(WEEKLY_WORKFLOW);
+    return;
+  }
+  throw new Error(`nq hooks ${sub} — unknown (install | show)`);
+}
+
 async function cmdVerify(target) {
   const { verify } = await import(join(ROOT, 'scripts', 'verify.mjs'));
   const names = target === 'all' || !target
@@ -353,9 +419,25 @@ try {
     case 'init': await cmdInit(flags); break;
     case 'tokens': await cmdTokens(); break;
     case 'principles': await cmdPrinciples(); break;
-    case 'new': await cmdNew(rest[0], flags); break;
+    case 'new':
+    case 'new-component': await cmdNewComponent(rest[0], flags); break;
+    case 'new-app': await cmdNew(rest[0], flags); break;
+    case 'align': {
+      const { run } = await import(join(ROOT, 'scripts', 'align.mjs'));
+      await run(rest, flags);
+      break;
+    }
+    case 'hooks': await cmdHooks(rest[0], flags); break;
     case 'assets': await cmdAssets(rest[0], rest.slice(1), flags); break;
     case 'verify': await cmdVerify(rest[0]); break;
+    case 'lint': {
+      const { lint } = await import(join(ROOT, 'scripts', 'lint.mjs'));
+      const r = await lint(rest[0], { fix: flags.fix, json: flags.json });
+      if (r.errorCount) process.exitCode = 1;
+      break;
+    }
+    case 'audit': await import(join(ROOT, 'scripts', 'audit.mjs')); break;
+    case 'sync-skill': await import(join(ROOT, 'scripts', 'sync-skill.mjs')); break;
     default: console.log(HELP);
   }
 } catch (err) {