@norskvideo/ctl-dev-kit 0.1.14 → 0.1.16

package/build/flake.nix

@@ -21,9 +21,15 @@
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/d233902339c02a9c334e7e593de68855ad26c4cb"; # nixpkgs-unstable 2026-05-15, bun 1.3.13
+    # Biome must match the version pinned in package.json (@biomejs/biome 2.5.5)
+    # exactly: 2.4.x can't parse this repo's biome.json (`rules.preset` is a
+    # 2.5 key) and any other 2.5.x emits a version-mismatch info that breaks the
+    # "0 diagnostics" bar. The main nixpkgs pin only ships 2.4.14, so biome
+    # comes from its own pin -- bump this one whenever package.json's biome moves.
+    nixpkgs-biome.url = "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e"; # biome 2.5.5
   };
 
-  outputs = { self, nixpkgs }:
+  outputs = { self, nixpkgs, nixpkgs-biome }:
     let
       systems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
       forAllSystems = f: builtins.listToAttrs (map (s: { name = s; value = f s; }) systems);
@@ -72,7 +78,14 @@
       devShells = forAllSystems (system:
         let
           pkgs = import nixpkgs { inherit system; };
+          # Biome from its own pin so `bun run lint` works on NixOS: the
+          # node_modules @biomejs/biome binary is glibc-linked and can't run
+          # here. Each shell exports BIOME_BINARY so the npm wrapper execs this
+          # nix build instead -- no patchelf, no per-command env var. Keep the
+          # pin in step with package.json's @biomejs/biome version.
+          biome = (import nixpkgs-biome { inherit system; }).biome;
           buildTools = [
+            biome
             pkgs.bun
             pkgs.cargo # builds the native product-signer addon (probe/native)
             pkgs.rustc
@@ -83,14 +96,17 @@
           # Everyday dev shell — build tools + the pinned norsk-ctl daemon.
           # `nix develop` and `nix develop .#dev` are equivalent.
           default = pkgs.mkShell {
+            BIOME_BINARY = "${biome}/bin/biome";
             buildInputs = buildTools ++ [ (mkCtl system) ];
           };
           dev = pkgs.mkShell {
+            BIOME_BINARY = "${biome}/bin/biome";
             buildInputs = buildTools ++ [ (mkCtl system) ];
           };
           # Lean shell for CI (build-image / integration) — no ctl fetch, so
           # image builds never depend on the ctl binary channel.
           build = pkgs.mkShell {
+            BIOME_BINARY = "${biome}/bin/biome";
             buildInputs = buildTools;
           };
         });

package/conventions/CLAUDE.core.md

@@ -65,5 +65,16 @@
   (`norsk-ctl-product-playout`, `-commentary`) or beside the code they guard
   (`-probe`, `-turnkey-funke-pegasus`) is the repo's choice — the contract is
   the IDs and the guard, not the layout.
+- **Know who reads it — name the persona before writing docs or a
+  persona-facing surface.** Every Norsk ctl product writes for the same four
+  reader personas — Evaluator, Builder, Integrator, Operator (SRE) — defined in
+  `@norskvideo/ctl-dev-kit/conventions/personas.md`, with this product's own
+  audiences mapped onto them in its `docs/personas.md`. Before writing or
+  restructuring docs, a configure/dashboard surface, onboarding material, or any
+  copy a persona will read, name that reader and honour the ownership handoff
+  (Evaluator/Builder -> product repo, Operator -> ctl, Integrator -> both).
+  Runtime actors (the roles people play in the deployed product) are NOT
+  doc-reader personas: the operator who runs it is the Builder; guests who are
+  invited in receive onboarding kit, they don't read the manual.
 
 <!-- END ctl-shared-conventions v1 -->

package/conventions/personas.md

@@ -0,0 +1,127 @@
+# Documentation personas (shared across all Norsk ctl product repos)
+
+The shared reader vocabulary. Every Norsk ctl product — probe, commentary,
+playout, the turnkeys — writes docs for the same four personas, so a reader who
+learns one product's docs knows how to navigate the next. Read this before
+writing or restructuring a product's `docs/`; then keep the product's own
+`docs/personas.md`, which maps *this* product's named audiences and runtime
+roles onto the four below.
+
+This is a **shipped reference**, not a drift-gated copy: you consume it from
+`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md`, you do not copy
+it into the repo. The per-product mapping legitimately differs product to
+product, so there is nothing byte-identical to gate — the shared thing is the
+vocabulary, not the mapping.
+
+## The four personas
+
+Two extremes (casual / deep-tech) miss the two middle personas that most docs
+actually serve. Each persona has a fixed sub-structure — Skills / Wants / Doc
+needs / Failure mode — so a product can fill it in the same shape.
+
+### 1. Evaluator
+
+Just heard about the product. A developer, a PM at a broadcaster, a technical
+founder — or a **sales engineer demoing it on their behalf**. Wants to know
+"does this do what I need?" in 15 minutes.
+
+- **Skills**: variable — assume no Docker / ffmpeg / transport-protocol knowledge.
+- **Wants**: a result on screen within a few minutes; clarity on what just
+  happened; confidence they won't hit a wall going further. A demo-driver also
+  wants it to read as credible and legible live on a shared screen.
+- **Doc needs**: one quick start, zero-to-running. Happy path only, no flags. A
+  gallery that shows the product's range at a glance.
+- **Failure mode**: opens a page with twelve sidebar entries (or a dense form),
+  bounces.
+
+### 2. Builder
+
+Building or standing up a real deployment *with* the product. A developer or a
+technical producer/operator. Wants it to work; does not want to become a DevOps
+expert, and does not want to hand-write config/graph YAML.
+
+- **Skills**: can run commands, knows what a container is. May be deeply fluent
+  in the product's *domain* (broadcast transports, say) while still not wanting
+  ctl/Docker internals — a product refines this in its own mapping.
+- **Wants**: task-oriented hand-holding; a UI that exposes everything; good
+  errors with fix hints; sensible defaults.
+- **Doc needs**: task guides ("how to do X") with screenshots. A troubleshooting
+  checklist. Not compose YAML, not env vars, not architecture diagrams.
+- **Failure mode**: hits an error, can't tell if it's their fault or a bug,
+  gives up.
+- **Usually the most underserved persona**, and usually the product's sweet
+  spot — the Integrator has generated reference, the Evaluator has zero-to-hero,
+  the Operator is largely ctl's; the Builder's task guides are the product's own
+  work and the thing most worth investing in.
+
+### 3. Integrator
+
+Automating against the product or wiring it into a larger system. Scripted
+launches, CI/CD, programmatic control.
+
+- **Skills**: comfortable with CLIs, API calls, shell; trusts tools, reads flags.
+- **Wants**: reference that matches reality; copy-pastable invocations; scripting
+  examples; clear error codes; idempotent operations for CI.
+- **Doc needs**: CLI reference (generated), API reference (from OpenAPI), a
+  config-file/schema reference, a short recipes page.
+- **Failure mode**: the reference has drifted from the tool; trust is lost; they
+  read the source instead.
+
+### 4. Operator (SRE)
+
+Running the product in production. Responsible for uptime, cost, security.
+
+- **Skills**: deep Docker, nginx/networking/TLS; reads source when docs are thin.
+- **Wants**: what the platform does to the host — ports bound, files touched,
+  where state lives, secrets, crash/restart, backup/restore, upgrade/DR.
+- **Doc needs**: an honest architecture doc, a production deployment guide, a
+  security reference.
+- **Failure mode**: docs are too happy-path, omit failure modes; can't tell if
+  the thing is production-ready.
+
+### On decision-makers
+
+CFO / commercial personas are a marketing concern, not a docs one. The useful
+middle is a **decision-maker evaluating for their team** — "should we build on
+this?" — served by one honest overview page (scale, maintenance, lock-in, CI),
+no marketing copy. Don't build a separate doc track for it.
+
+## Ownership: the persona handoff
+
+The persona a page serves decides which repo owns it, once products are split
+out of ctl:
+
+| Persona    | Owner repo    |
+| ---------- | ------------- |
+| Evaluator  | **product**   |
+| Builder    | **product**   |
+| Integrator | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
+| Operator   | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's |
+
+The test: **if the answer changes when you swap products, it's product docs; if
+it changes when you upgrade ctl, it's ctl docs.** Ownership is not presentation —
+a single rendered site can still interleave both (see norsk-ctl's
+`_planning/docs-after-the-split.md`).
+
+## Runtime actors are not doc-reader personas
+
+A deployed product has **runtime actors** — the roles people play in the running
+system (an operator at a console, a guest who joins, an analyst who reads a
+report). These are *not* a fifth, sixth, seventh persona, and indexing docs by
+them is the most common way a product's docs sprawl.
+
+Reconcile them like this:
+
+- The actor who **sets the deployment up and runs it** is the **Builder** (and,
+  live, the Operator in the ctl sense) — the same human, wearing hats. Their
+  material is the Builder task guides.
+- Actors who are **invited into** the running deployment (a guest, a
+  contributor) rarely read the manual at all — they receive a link, and maybe an
+  onboarding message. Material authored *for* them but *handed out by* the
+  Builder — join-page guides, onboarding email templates — is **distribution /
+  onboarding kit**, indexed separately from the Builder's own task guides, not
+  as manual chapters.
+
+Map each product's named audiences (from its `PRODUCT.md`) onto the four
+personas above; don't invent a parallel scheme. Keep the per-product mapping in
+the product's `docs/personas.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",