super-ux 0.36.1 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## 0.38.0 — 2026-08-12
+
+Four practices for developer products, from a measured reading of a live
+developer landing page (`zernio.com`, 2026-08-12) rather than from a survey.
+
+### Added
+
+- **BP-207..210, a new catalog band: "Developer products — the landing, the
+  capability page, the first run."** A developer product is evaluated from the
+  code sample and the reference, not from the benefit statement, and these are
+  the composition consequences:
+  - **BP-207 — the hero is the call, not a screenshot.** The focal element of the
+    first viewport is a runnable request with its filename and language; it
+    scrolls horizontally and never reflows or shrinks below body size, and the
+    fold is allowed to crop it. A wrapped sample stops being evidence, which is
+    the failure mode of pasting code into a hero without its own scroll
+    container.
+  - **BP-208 — one measure per content role, not one container width.** A ladder
+    tied to what the content *is*: the argument in a narrow reading measure,
+    proof one step wider, logo walls widest, the whole ladder collapsing on a
+    phone. A single width forces one compromise on every content type — prose
+    past the 45–75-character measure BP-087 requires, grids cramped.
+  - **BP-209 — the setup checklist arrives already partly complete.** Steps
+    satisfied by signing up arrive ticked and the list opens on the first
+    outstanding one, which is the endowed-progress effect. Carries its own
+    honesty condition: pre-ticking a step the user has *not* completed spends the
+    trust the pattern runs on, and every step keeps a postpone link that names
+    the consequence, so the list never becomes a gate (BP-206).
+  - **BP-210 — a capability page answers one question per heading.** Every `h2`
+    is a question a buyer asks, every `h3` one capability in one sentence, the
+    endpoint beside the capability. Search, answer engines and a scanning
+    developer all want the same shape; a features grid serves none of them,
+    because a grid cell cannot be quoted as an answer.
+- **Three routing rows** in `practice-selection.md`: developer landing,
+  capability page, first-run checklist — the new entries are reachable from the
+  surfaces that need them, not only from the catalog.
+- **`visual-identity.md` routes the `manpage` pack** for developer products whose
+  hero is a code sample, alongside the existing pack choices, and points at
+  BP-207..210 for what goes where on such a page.
+
+### Fixed
+
+- `best-practices.md`'s section heading read **`Verbal identity (BP-182..205)`**
+  while BP-206 had been sitting inside it since 0.37.0. Section-heading spans are
+  not covered by the id, routing or index gates — only `practice-selection.md`'s
+  header span is checked — so this one drifted silently. Corrected to BP-182..206.
+- `README.md` said **206 proven practices** against a catalog of 210.
+
+### Changed
+
+- `test/floors.json`: `validate.py` 3160 → 3236 — four entries, their field and
+  tag checks, and three routing rows.
+
+
+## 0.37.0 — 2026-08-12
+
+The last five findings from the R-14 run — the ones that needed a **decision**
+rather than a correction. In every case the fresh-context agent had already
+improvised the right answer, said out loud that it was deviating, and explained
+why. The answer was accepted rather than re-invented.
+
+### Added
+
+- **A declared branch for "we know almost nothing".** The Design workflow read
+  *per story* and built its practice profile from `foundation.md`, while the
+  commonest real brief has neither — and nothing said what to do. Step 0 now
+  requires three things instead of silent improvisation: a **provisional
+  profile** where every dimension names its provenance (`brief` / `inferred` /
+  `assumed`, and an assumed dimension that decides the flow's shape is called
+  out), `Traces:` as an **unbacked provisional job** in the user's words, and an
+  **open decisions** list saying what each would change. A flow built this way is
+  honest input; built without the three blocks it is invented personas with a
+  diagram on top.
+- **A granularity rule for the practice pass, because "every practice" does not
+  scale.** A mobile subscription product pulls roughly **150 practices for one
+  flow**; the worked example has four rows. Per-practice verdicts for the artifact
+  row and anything the artifact touches; **one band verdict, with its reason**,
+  per remaining set. A band with no reason is a silent skip wearing a table row.
+- **`blocked` joins the screen status enum** — designed, complete, and unsafe to
+  build because a decision outside UX would change it. Name the decision and its
+  owner on the same line. That state used to live in prose, where no linter and no
+  next agent reliably finds it, and `designed` quietly read as ready.
+- **A state is not a screen, with a test.** One `SCR-ID` per place the user can
+  be; split only when a variation owns distinct copy, distinct elements **and** its
+  own primary action. A confirm dialog with its own words is a screen; a table with
+  no rows is a state. Two agents given the same app produced incompatible
+  `screens.md` files for exactly this.
+- **The platform-permits rule, generalised out of BP-123.** Where a step belongs
+  to the OS or a store — store billing, a permission prompt, a share sheet,
+  biometrics — two non-design questions decide the diagram: can the app perform
+  the action at all, and does it learn the outcome synchronously. A "no" to the
+  second is a **third branch**. Drawing only success and failure there ships a flow
+  that cannot be built.
+
 ## 0.36.1 — 2026-08-12
 
 Four of the R-14 run's findings actioned, and a defect class ported from the

package/README.md

@@ -230,7 +230,7 @@ The contracts every skill reads:
 | [ux_doctor.py](plugins/super-ux/scripts/ux_doctor.py) | Contract doctor — reports mixed or stale contract versions across a project's artifacts, files the tooling cannot find under their contract names, and audits produced against a base that is not there. `/ux-lint` checks a chain against itself; this checks it against the contract. Installed as `docs/ux/doctor.py`, read-only unless `--fix` |
 | [best-practices-index.md](plugins/super-ux/skills/references/best-practices-index.md) | Generated tag index over the catalog — tag → ids, id → title. Read it to decide which entries to open; regenerated by `plugins/super-ux/scripts/bp_index.py` and checked for drift by the validator |
 | [ux-design-principles.md](plugins/super-ux/skills/references/ux-design-principles.md) | How the agent thinks: the design pipeline (forward and backwards), task analysis, flow rules, heuristics PRN-01..24, the improvement procedure, anti-patterns |
-| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 206 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, growth loops and referral mechanics, empty states, authentication (NIST SP 800-63B rev 4) and form recovery, motion craft and perceived quality, the defaults that make an interface read as generated, interface state, locale and platform surfaces (Web Interface Guidelines), visual craft, Figma structure |
+| [best-practices.md](plugins/super-ux/skills/references/best-practices.md) | Living, tag-indexed catalog of 210 proven practices — subscription-app laws, mobile/web/voice guidance (Apple HIG 2025, M3 Expressive, NN/g, Baymard, WCAG 2.2), monetization economics (RevenueCat/PLG 2025 benchmarks, ASO, freemium boundaries), web funnels end to end (landing, pricing, checkout, dunning, cancel) and web2app (paid handoff, deferred deep links, storefront rules), motion and page weight (HTTP Archive field data, W3C sustainability), accessibility as it actually fails (WebAIM Million, EAA/ADA exposure), frustration telemetry, gamification and trend governance, growth loops and referral mechanics, empty states, authentication (NIST SP 800-63B rev 4) and form recovery, motion craft and perceived quality, the defaults that make an interface read as generated, interface state, locale and platform surfaces (Web Interface Guidelines), visual craft, Figma structure |
 | [practice-selection.md](plugins/super-ux/skills/references/practice-selection.md) | The deterministic bridge: product profile → mandatory consideration sets → per-artifact checklists → a compliance table where every pulled practice gets a verdict. No silent skips, no cargo cult |
 | [component-guidelines.md](plugins/super-ux/skills/references/component-guidelines.md) | Which control for which job (radios/select/switch, sheet/alert, modal/disclosure, combobox, nav bar/rail, FAB, dates, toasts) and the platform rules — Apple HIG, Material 3, W3C ARIA APG, GOV.UK |
 | [visual-identity.md](plugins/super-ux/skills/references/visual-identity.md) | The visual layer and its owner: one style pack for the whole product, where it's recorded, how it meets Figma and code, and the division of labor with the craft floors |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.36.1",
+  "version": "0.38.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"