@marktiderman/genesis-config 0.0.0-stage → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +461 -2
  3. package/dist/blocks.d.ts +473 -0
  4. package/dist/blocks.js +5 -0
  5. package/dist/blocks.js.map +1 -0
  6. package/dist/chunk-B6WRD3WF.js +6 -0
  7. package/dist/chunk-B6WRD3WF.js.map +1 -0
  8. package/dist/chunk-HIOKZIZP.js +218 -0
  9. package/dist/chunk-HIOKZIZP.js.map +1 -0
  10. package/dist/chunk-M7IY6LUN.js +123 -0
  11. package/dist/chunk-M7IY6LUN.js.map +1 -0
  12. package/dist/chunk-OW46SL2G.js +10 -0
  13. package/dist/chunk-OW46SL2G.js.map +1 -0
  14. package/dist/chunk-SEFG2QV6.js +413 -0
  15. package/dist/chunk-SEFG2QV6.js.map +1 -0
  16. package/dist/chunk-UD7SPYZH.js +354 -0
  17. package/dist/chunk-UD7SPYZH.js.map +1 -0
  18. package/dist/chunk-VYUX7VAX.js +52 -0
  19. package/dist/chunk-VYUX7VAX.js.map +1 -0
  20. package/dist/chunk-Y7NUBTWA.js +494 -0
  21. package/dist/chunk-Y7NUBTWA.js.map +1 -0
  22. package/dist/gate-CNTkn-Fv.d.ts +202 -0
  23. package/dist/gate-react.d.ts +48 -0
  24. package/dist/gate-react.js +37 -0
  25. package/dist/gate-react.js.map +1 -0
  26. package/dist/gate.d.ts +18 -0
  27. package/dist/gate.js +5 -0
  28. package/dist/gate.js.map +1 -0
  29. package/dist/index.d.ts +128 -0
  30. package/dist/index.js +9 -0
  31. package/dist/index.js.map +1 -0
  32. package/dist/model-uON71G4u.d.ts +437 -0
  33. package/dist/node.d.ts +159 -0
  34. package/dist/node.js +486 -0
  35. package/dist/node.js.map +1 -0
  36. package/dist/packages-CWhdXtzS.d.ts +203 -0
  37. package/dist/platforms-NR0liM8L.d.ts +10 -0
  38. package/dist/react.d.ts +60 -0
  39. package/dist/react.js +236 -0
  40. package/dist/react.js.map +1 -0
  41. package/dist/settings-protocol.d.ts +515 -0
  42. package/dist/settings-protocol.js +4 -0
  43. package/dist/settings-protocol.js.map +1 -0
  44. package/dist/settings-react.d.ts +143 -0
  45. package/dist/settings-react.js +943 -0
  46. package/dist/settings-react.js.map +1 -0
  47. package/dist/settings.d.ts +373 -0
  48. package/dist/settings.js +3 -0
  49. package/dist/settings.js.map +1 -0
  50. package/dist/types-D4hs16bJ.d.ts +39 -0
  51. package/package.json +141 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mark Tiderman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,462 @@
1
- # Temporary Holding Version
1
+ # @marktiderman/genesis-config
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > Formerly `@marktiderman/genesis-features`, renamed in place (same source, same subpaths, same
4
+ > formats). The old name is a deprecated re-export for two minor versions
5
+ > ([packages/features-alias](../features-alias/README.md)); `genesis upgrade` moves an app's imports.
6
+
7
+ A repo's features in one typed code file that running code imports. Every other format (the
8
+ AGENTS.md pointer, `features.json`, an OpenFeature `flags.json`, the agent skill, a README
9
+ section, the admin page) is generated from it, and `genesis features check` fails CI when a
10
+ generated copy is stale or the registry and the code disagree.
11
+
12
+ Phase 1 is deliberately small: one flat file per repo. No database, no sync, no hierarchy.
13
+
14
+ ## The registry
15
+
16
+ ```ts
17
+ // src/features.ts
18
+ import { defineFeatures, type FeatureIdOf } from "@marktiderman/genesis-config";
19
+
20
+ export const features = defineFeatures({
21
+ tasks: {
22
+ name: "Tasks",
23
+ summary: "Coach and client both add and check off next steps.", // internal, one sentence
24
+ status: "live", // planned | building | beta | live | deprecated | retired
25
+ owner: "mark",
26
+ apps: ["web"],
27
+ audience: ["client", "coach"],
28
+ acceptance: ["A client can tick off a task their coach added."], // required on beta and live
29
+ visibility: "customer", // internal | customer | public | client:<name>
30
+ access: "all", // or { plan: "pro" }: the id is the entitlement's lookup key
31
+ reviewedAt: "2026-10-22",
32
+ links: { code: ["src/components/TasksPanel.tsx"], docs: ["docs/tasks.md"], issue: "#42" },
33
+ tagline: "Never lose a next step.", // with visibility "public": marketing output
34
+ category: "Coaching",
35
+ },
36
+ billing: { name: "Billing", summary: "…", status: "planned", horizon: "next", /* … */ },
37
+ });
38
+
39
+ export type FeatureId = FeatureIdOf<typeof features>;
40
+ ```
41
+
42
+ `defineFeatures` validates every entry with Zod and lists every problem at once:
43
+
44
+ - Unknown fields, bad dates and paths that leave the repo are errors.
45
+ - `planned` needs a `horizon` (now, next, later), and only planned or building features may have one. That's the roadmap, with no dates.
46
+ - `beta` and `live` need `acceptance`.
47
+ - `claimedBy` is only for `building`.
48
+ - Ids and `aliases` are unique.
49
+
50
+ It returns the same object, so code reads `features.tasks.status` directly. Name features by `FeatureId` everywhere, so a typo is a type error.
51
+
52
+ Ids are permanent. `check` and `build` refuse when an id recorded in `features.json` disappears. Retire a feature with `status: "retired"`, and rename one through `aliases`.
53
+
54
+ ## Flags
55
+
56
+ ```ts
57
+ import { defineFlags } from "@marktiderman/genesis-config";
58
+ import { features } from "./features";
59
+
60
+ export const flags = defineFlags(features, {
61
+ "tasks.v2": { feature: "tasks", kind: "release", owner: "mark", default: false, scopes: ["platform", "user"], expires: "2026-12-01" },
62
+ "tasks.kill": { feature: "tasks", kind: "ops", owner: "mark", default: true, scopes: ["platform"],
63
+ runbook: "docs/runbooks/tasks.md", splitReason: "a kill switch outlives the rollout" },
64
+ });
65
+ ```
66
+
67
+ - `feature` must be a `FeatureId`: an unknown one is a type error and a runtime error.
68
+ - Flags are grouped by feature, so a feature's second flag needs a `splitReason`.
69
+ - `release` and `experiment` flags need `expires`, and `ops` flags need a `runbook`.
70
+ - A `permission` flag fails `check`, because paid access is `access`, not a flag.
71
+ - `check` scans the code for flag reads through the accessors (default `useFlag(…)`, `getFlag(…)` and `<Flag name=…>`; set them with `flagAccessors`). It fails on:
72
+ - a computed key;
73
+ - a key that is read but not defined, or defined but never read;
74
+ - a flag past its `expires` date.
75
+
76
+ ## Generated output and the check
77
+
78
+ ```bash
79
+ genesis features build # AGENTS.md pointer, features.json, flags.json, the skill, the marketing block; @AGENTS.md in CLAUDE.md
80
+ genesis features check # CI. --labels "a,b" checks a PR's feature:<id> labels; --prs reads merged PRs with gh
81
+ genesis features check --summary # for a SessionStart hook: counts, stale output, expired flags, planned-but-shipped, claims
82
+ genesis features find <term> # search ids, aliases, names, summaries, flags and code paths
83
+ ```
84
+
85
+ **Errors fail the check:**
86
+
87
+ - Generated output is stale.
88
+ - A `links.code` path doesn't exist.
89
+ - A flag breaks one of the rules above.
90
+ - An id was removed.
91
+ - A feature tag names an unknown id: `@feat:<id>` in tests, `Features: <id>` in a changeset's body, or `feature:<id>` on a PR.
92
+ - CLAUDE.md has no `@AGENTS.md` line.
93
+
94
+ **Warnings don't fail it:**
95
+
96
+ - A review is due: `reviewedAt` is over 90 days old, or missing.
97
+ - A live feature has no test tagged with its `@feat:<id>`.
98
+ - A feature is still `planned`, but shipped work is tagged with it: a changeset with `Features: <id>`, or (with `--prs`) a merged PR labelled `feature:<id>`. The warning names each one, e.g. "billing is still planned, but .changeset/x.md and PR #123 shipped work for it". `--prs` asks `gh pr list --state merged --label feature:<id>` for each planned id and alias; when `gh` is missing or fails, you get one warning and only changesets count. From code, pass the PRs yourself as `checkFeatureOutputs({ …, evidence: { prs: { billing: [{ number, title }] } } })`.
99
+ - A route or server-function file isn't covered by any `links.code`.
100
+ - A docs path is missing.
101
+
102
+ The check only ever compares generated output with the generator, never two hand-written files.
103
+
104
+ The AGENTS.md block is a short pointer with counts, not the list. Agents run `find` and read the skill (`.claude/skills/features/SKILL.md`, which covers finding, adding, changing and retiring features, and says to remove the code before the flag).
105
+
106
+ ### Settings
107
+
108
+ The CLI reads settings from the `features` block of `genesis.config.json` (the app's one Genesis config, beside `doctor`), or from `"genesisFeatures"` in `package.json`. Command-line options win, then `genesis.config.json`.
109
+
110
+ ```json
111
+ "genesisFeatures": {
112
+ "registry": "src/features.ts",
113
+ "flagsFile": "src/lib/flags/registry.ts",
114
+ "command": "bun run features",
115
+ "marketing": "README.md",
116
+ "flagAccessors": ["useFlag", "flag", "<Flag name>"],
117
+ "coverage": ["src/routes/**/*.tsx", "**/*.functions.ts"]
118
+ }
119
+ ```
120
+
121
+ Other settings: `agents`, `claude`, `json`, `openfeature`, `skill` (each a path, or `false`), `scan`, `scanIgnore`, `tests`, `coverageIgnore`, `changesets`, `reviewDays`.
122
+
123
+ The flag scan ignores comments and test files. List the flags runtime itself (the files that define the accessors and read by variable) in `scanIgnore`; setting it replaces the default test globs, so include those too.
124
+
125
+ The CLI loads TypeScript itself, so the registry needs no build step. Keep its imports to packages, with no path aliases.
126
+
127
+ ## App settings
128
+
129
+ Every package declares its settings next to its `defineBlock`, and the app resolves them through
130
+ one resolver on the server, the web and phones (`@marktiderman/genesis-config/settings`, free of
131
+ zod; also on the root).
132
+
133
+ ```ts
134
+ import { defineSettings, resolveSettings, settingsCatalogue, withSettings } from "@marktiderman/genesis-config/settings";
135
+
136
+ export const supportSettings = defineSettings("support", {
137
+ messenger: { type: "boolean", default: { max: true, standard: true, min: false }, scope: "tenant", feature: "support-messenger" },
138
+ agentDesk: { type: "boolean", default: { max: true, standard: true, min: false }, requires: ["support.inbox"] },
139
+ inbox: { type: "boolean", default: true },
140
+ dumpRetentionDays: { type: "number", default: 90, min: 7, max: 365 },
141
+ githubRepo: { type: "string", default: null, needs: "secret:GITHUB_TOKEN", store: "edge", setup: "github.issues" },
142
+ sentryDsn: { type: "string", default: null, applies: "build" },
143
+ });
144
+
145
+ const catalogue = settingsCatalogue([supportSettings]);
146
+ const settings = resolveSettings(catalogue, { preset: "max", file, database, tenant, person });
147
+ settings.values["support.dumpRetentionDays"]; // 90
148
+ settings.sources["support.messenger"]; // { layer: "tenant" }
149
+ const ctx = withSettings({ platform: "web" }, catalogue, settings); // for featureOn
150
+ ```
151
+
152
+ Each key has a `type` (`boolean`, `number`, `string`, `list`, `object`) and a `default`, or one per
153
+ preset (`{ max, standard, min }`). `scope` (`app`, the default, `tenant` or `person`) is the lowest
154
+ layer that may change it; `applies` is `runtime` (the default) or `build` (a new binary or bundle).
155
+ `requires` links other keys, `min`, `max` and `options` bound the value, and `needs:
156
+ "secret:NAME"` names the secret it needs and `store` where it lives (`vault`, `edge`, `server-env`
157
+ or `ci`): never its value. `feature` and `flag` link the key to the gate. A number with
158
+ `integer: true` takes whole numbers only (in every layer, and in the database).
159
+
160
+ **The layers**, low to high. A later layer wins unless an earlier one locked the value
161
+ (`{ value, locked: true }`):
162
+
163
+ 1. **default**: the declared default (for a per-preset one, `max`'s);
164
+ 2. **preset**: `max` (Genesis's default: everything on), `standard` or `min`, chosen in
165
+ genesis.config.json (`"preset"`) but resolved as its own layer;
166
+ 3. **file**: genesis.config.json `settings` (`settingsLayerFromFile`), the only layer that sets a
167
+ build-time key;
168
+ 4. **database**: the app's `genesis_settings` table (genesis-supabase's `settings` block);
169
+ 5. **tenant**: only keys declared `scope: "tenant"`;
170
+ 6. **person**: only keys declared `scope: "person"`.
171
+
172
+ Which layers may set each scope is one table, `SCOPE_LAYERS`. A lock always holds: a locked entry
173
+ whose own value is bad keeps the value from below and still locks it. `null` ("not set") is a value
174
+ only for a key whose default is `null`.
175
+
176
+ `resolveSettings` never throws: it skips a bad entry and reports it in `problems` (an unknown
177
+ key, a value of the wrong type or out of bounds, a tenant or person value for a key without that
178
+ scope, a runtime layer setting a build-time key, a change to a locked value, a key on while one it
179
+ requires is off, an unknown preset, which resolves on `max`). Every map it returns has no prototype,
180
+ so a key such as `__proto__` or `constructor` is just an unknown key. `sources` says which layer set each value and which locked it.
181
+
182
+ **Reading a result.** `values`, `sources` and the maps `settingsGateContext` returns have no
183
+ prototype, so they have no `hasOwnProperty` (or `toString`) of their own: `values.hasOwnProperty(k)`
184
+ throws. Read a key directly (`values["support.messenger"]`), test it with `k in values` or
185
+ `Object.prototype.hasOwnProperty.call(values, k)`, and copy one with `{ ...values }` if you need an
186
+ ordinary object.
187
+
188
+ **The gate.** A boolean key linked with `feature` that resolves to `false` puts the feature in
189
+ `GateContext.settingsOff` (`featureOn` answers `reason: "setting"`), and a key linked with `flag`
190
+ gives the flag its value when the context has none (`withSettings`, `settingsGateContext`). A key the
191
+ app locked (genesis.config.json or the database, `APP_LOCK_LAYERS`) wins over the context: the
192
+ tenant's switch can't turn off a feature locked on, nor the context's flag change a locked flag. A
193
+ tenant or person lock only stops later settings layers; it never beats a platform flag, an
194
+ entitlement or (for a person) the tenant's switch. It is the same gate, with one more check.
195
+
196
+ **Two keys switching one feature.** Nothing stops two keys from naming the same `feature` (say a
197
+ package's `messenger` and `helpCenter` both linked to its help desk). Then either key resolving to
198
+ `false` switches the feature off: `off` is "any linked key is false", never "the last one wins". A
199
+ lock on either key keeps the tenant's switch from turning the feature off. Link one key per feature
200
+ unless "off when any of them is off" is what you mean.
201
+
202
+ **Packages without running them.** A package also lists its declaration in package.json
203
+ (`genesis.settings`: `{ "namespace": …, "keys": { … } }`, read with `settingsFromManifest`), so
204
+ `genesis doctor` checks an app's genesis.config.json against the installed packages
205
+ (`invalid-setting`, `setting-requires`, and `setup-incomplete` and `secret-missing` for keys with a
206
+ `setup` step or a secret they `needs`, checked by name only). `catalogueManifest` is the catalogue as the database checks values against it.
207
+
208
+ ### The Settings screen
209
+
210
+ One screen, two hosts: the localhost wizard (`genesis setup`) and the app's own platform-admin
211
+ page. `<GenesisSettings>` (`@marktiderman/genesis-config/settings/react`, Beta) draws it, and talks to its
212
+ host only through a `SettingsClient` (`@marktiderman/genesis-config/settings-protocol`, Beta, free of zod
213
+ and React).
214
+
215
+ **Beta.** The screen ships before the maintainer's design review: its look, copy keys and props may
216
+ change in a minor release.
217
+
218
+ ```tsx
219
+ import { APP_HOST_CAPABILITIES, createSettingsClient } from "@marktiderman/genesis-config/settings-protocol";
220
+ import { GenesisSettings } from "@marktiderman/genesis-config/settings/react";
221
+
222
+ declare const accessToken: () => string | null;
223
+
224
+ const client = createSettingsClient(fetch, { baseUrl: "/api/genesis/settings", token: accessToken });
225
+
226
+ export function PlatformSettings() {
227
+ return <GenesisSettings client={client} capabilities={APP_HOST_CAPABILITIES} />;
228
+ }
229
+ ```
230
+
231
+ **Tabs.** Values (every key grouped by package, with its value, the layer it came from and its
232
+ lock), Health (the doctor's findings, each with its fix), Secrets (each secret's name, store and
233
+ whether it is set: never its value), Upgrades (installed and latest versions, release notes) and
234
+ Audit (the history of changes, a page at a time).
235
+
236
+ **What it may write.** The host reports its `capabilities` (`writeFiles`, `writeDatabase`,
237
+ `setSecrets`, `runCli`, `agent`, and optionally `proposeChanges`), and the `capabilities` prop can
238
+ only narrow them: a key the prop leaves out doesn't narrow, only `false` does
239
+ (`intersectCapabilities`). `settingWritability` holds the rules for the screen and a host's
240
+ handler alike: a build-time key is written only in the file layer; the file layer needs
241
+ `writeFiles`, the database layer `writeDatabase`; a key a lower layer locked can't be changed above
242
+ it.
243
+
244
+ - **The CLI host** writes the file layer by default (`preferredWriteLayer`), since it is reviewed
245
+ like code; the database is an explicit choice in the edit sheet, except for a value that already
246
+ comes from the database, which opens on the database. Writing a layer below the one
247
+ the value comes from shows that the higher layer overrides it.
248
+ - **The app host** (`APP_HOST_CAPABILITIES`) edits runtime keys in the database layer only. A
249
+ build-time key, or one the file layer locked (the lock lives in the file), shows "Change in repo"
250
+ with the genesis.config.json change to commit (`settingFileSnippet`), or a pull request when the
251
+ host can open one (`proposeChanges`).
252
+ - **Secrets** are set per store: `setSecrets` is `true` (every store) or `{ vault?, edge?,
253
+ "server-env"?, ci? }` (`canSetSecret`). The app host may set and rotate Vault secrets only, when
254
+ the host itself reports `{ vault: true }` (`APP_HOST_CAPABILITIES` is a mask that allows it but
255
+ doesn't grant it): the `setSecret` op is write-only, the value is never returned, and the screen
256
+ drops it once sent. Other stores are set through `genesis setup`. The host side comes with the
257
+ app's settings handler.
258
+
259
+ **Fixes.** An automatic fix is planned first (`plan`): the screen shows the files it writes (with
260
+ a diff), the commands it runs, the settings layers it writes and the secrets it needs, asks to
261
+ confirm, then applies it with the plan's `hash` (`apply(fixId, expect)`). A host refuses a plan
262
+ that changed in between (`stale_plan`), and the screen offers to plan again. A plan needing more
263
+ than the host can do shows its `genesis fix <id>` command instead. The app host applies a fix only
264
+ when it writes the database layer and nothing else (`databaseOnly` on the fix, `layers` on the
265
+ plan). A guided fix opens its setup step (`onOpenStep`, or `genesis setup --step <id>`); a manual
266
+ fix shows its instructions. Links (`href`, `notesUrl`) are followed only when `http:`, `https:` or
267
+ on the same site (`safeHref`).
268
+
269
+ **What a host must redact.** The screen never draws a secret's value: the Secrets tab shows names
270
+ and status only, and the audit history draws `before` and `after` only for a `set` or `clear` of a
271
+ catalogue key that needs no secret (`auditValuesVisible`). Free text is drawn as given, so a host
272
+ redacts secrets from it: a finding's `message`, a plan's `summary`, `why`, diffs and command
273
+ `args`, an apply's `message`, and an audit entry's `summary`.
274
+
275
+ **Audit.** The history is drawn as rows, a page at a time through the protocol's cursor, not as a
276
+ `ResourceView`: a ResourceView needs a `GenesisProvider` with a data provider and pages through
277
+ it, and this screen has neither (the wizard host has no app around it). It moves to a ResourceView
278
+ over a client-side source when ResourceView can take a cursor-paged source without a provider.
279
+ When `state` carries no `audit`, the tab fetches the first page itself.
280
+
281
+ **The protocol.** One endpoint, `POST`, JSON only, a bearer token and no cookies
282
+ (`credentials: "omit"`), every request `{ v, op, … }` (`SETTINGS_PROTOCOL_VERSION`). The ops are
283
+ `state`, `setValue`, `clearValue`, `plan`, `apply`, `upgrades`, `audit`, `propose` and `setSecret`
284
+ (`SETTINGS_OPS`, answers in `SettingsResponses`). A failure is `{ error: { code, message } }`,
285
+ thrown by the client as a `SettingsProtocolError` whose `code` is `bad_request`, `unauthenticated`,
286
+ `forbidden`, `unsupported`, `locked`, `stale_plan`, `not_found`, `version` or `error`. A host
287
+ answers an op it doesn't know (one a newer screen sends) with `unsupported`, so the screen can tell
288
+ "not here" from a bad request. The client
289
+ gives up after `timeoutMs` (default 30 seconds), refuses a response that isn't JSON, and refuses a
290
+ `state` without its lists or capabilities. Its own messages are in `messages`
291
+ (`SETTINGS_CLIENT_MESSAGES`).
292
+
293
+ Every word on the screen is in `copy` (defaults: `GENESIS_SETTINGS_COPY`), accessible names
294
+ included; a host's error messages are shown as the host wrote them. Every element a test or an
295
+ agent drives has a `data-testid` under the `testID` prefix (default `genesis-settings`). Pass
296
+ `header={false}` when the host page owns the title (under `AppShellPageHeader`).
297
+
298
+ ## The gate
299
+
300
+ `featureOn(registry, context, id)` answers "is this feature on here?" the same way everywhere. Checks
301
+ run in a fixed order and the first "no" wins: **status** (beta, live or deprecated), **platform**, **setting**
302
+ (a setting switched it off, through `withSettings`), **tenant** (switched off), **flag** (each boolean release flag must be exactly `true`) and last **entitlement** (for
303
+ `access: { plan }`), so an upgrade prompt only appears when paying is the one thing missing. The answer
304
+ carries the reason, and for a paid feature the plan that unlocks it.
305
+
306
+ ```ts
307
+ import { featureOn, gateSnapshot, isSnapshotStale, requireFeature } from "@marktiderman/genesis-config/gate";
308
+
309
+ const context = { platform: "web", entitlements: ["form-webhook-delivery"], off: ["library"], flags: { "sms.release": true } };
310
+ featureOn({ features, flags }, context, "library"); // { on: false, reason: "tenant" }
311
+
312
+ // Server functions refuse whatever the reason: FeatureOff has status 402 (entitlement) or 403.
313
+ requireFeature({ features, flags }, context, "form-webhook-delivery");
314
+
315
+ // The server hands the client every shipped feature's answer: plain JSON with `at` (and `version`).
316
+ const snapshot = gateSnapshot({ features, flags }, context, { version: buildVersion });
317
+ // A client keeps it, and replaces it when stale, after sign-in or a tenant switch, or after a refusal.
318
+ if (isSnapshotStale(snapshot, 5 * 60_000)) refresh();
319
+ ```
320
+
321
+ `/gate` has no zod, React, Node built-ins or DOM globals, so it ships to browsers, extension service workers,
322
+ phones and edge functions. Context id sets are lists, Sets or functions (not iterators or strings). In React (web and React
323
+ Native), `/gate/react` reads the server's snapshot:
324
+
325
+ ```tsx
326
+ import { FeatureGate, FeatureGateProvider, useFeature } from "@marktiderman/genesis-config/gate/react";
327
+
328
+ <FeatureGateProvider snapshot={snapshot}>
329
+ <FeatureGate feature="form-webhook-delivery" upsell={({ unlock }) => <Upgrade plan={unlock.plan} />}>
330
+ <WebhookSettings />
331
+ </FeatureGate>
332
+ </FeatureGateProvider>;
333
+ ```
334
+
335
+ A feature that `requires` other features in the registry (a module's parts) is off while any of them is off,
336
+ with `via` naming the one that said no, so switching a module off or not paying for it turns its parts off
337
+ too. Ids outside the registry don't gate.
338
+
339
+ The gate doesn't check roles: "may this person" stays with roles and row security. Why it works this
340
+ way: [ADR 0001](../../docs/adr/0001-one-feature-gate.md).
341
+
342
+ ## Blocks
343
+
344
+ A block is a feature an app adds whole: account, push, observability, support, updates. It is
345
+ declared once, by its FeatureId, with what it needs and what it contributes. The app shell, the
346
+ navigation tree and Settings read the contributions by FeatureId; the app still decides where they
347
+ go. `@marktiderman/genesis-config/blocks` has no zod in it, so it ships to phones (the root
348
+ re-exports it).
349
+
350
+ ```ts
351
+ import { defineBlock, resolveBlocks } from "@marktiderman/genesis-config/blocks";
352
+ import type { FeatureId } from "./features";
353
+
354
+ export const supportBlock = defineBlock<FeatureId>({
355
+ id: "support",
356
+ requires: ["account"], // other blocks, or app features that aren't blocks
357
+ platforms: ["web", "native"], // default: everywhere
358
+ contributes: {
359
+ nav: [{ id: "help", label: "Help", path: "/help" }],
360
+ settings: [{ id: "contact-support", section: "about", title: "Contact support", href: "/support" }],
361
+ routes: [{ path: "/support", signedIn: true }],
362
+ slots: { fatal: SupportFatalScreen }, // fills the host shell's slots; the app's own slots win
363
+ migrations: [{ package: "@acme/support", file: "migrations/0001_support.sql" }],
364
+ skills: [".claude/skills/support/SKILL.md"],
365
+ privacy: { collects: [{ type: "email address", purposes: ["app functionality"], linked: true, tracking: false }] },
366
+ },
367
+ });
368
+
369
+ const blocks = resolveBlocks([accountBlock, supportBlock], enabledIds, { platform: "native", features });
370
+ blocks.nav; // [{ feature: "support", id: "help", … }]: place them in your nav tree
371
+ blocks.settings; // by `order`, then dependency order
372
+ blocks.dropped; // with { missing: "drop" }: what was left out and why
373
+ ```
374
+
375
+ `defineBlock` validates one block and freezes it. `resolveBlocks(blocks, enabled?, options?)`
376
+ takes the blocks that exist, the ids that are on (a list, a predicate, or every block when left
377
+ out) and returns the enabled ones in dependency order with their contributions merged, each tagged
378
+ with its `feature`. It throws a `BlockError` listing every problem at once:
379
+
380
+ - a bad id, a block requiring itself, an unknown contribution key, a duplicate id;
381
+ - a cycle through `requires` (the registry's own check, from `graph.ts`);
382
+ - with `features` (the registry), a block id or requirement that isn't a feature;
383
+ - an enabled block whose requirement is off, or doesn't run on `platform`. With `missing: "drop"` the
384
+ block (and everything needing it) is left out instead and listed in `dropped`: for switches that
385
+ change at run time, such as a tenant turning a feature off;
386
+ - two enabled blocks contributing the same nav entry, Settings row, route or slot, or (with `slots`)
387
+ a fill for a slot the host doesn't have.
388
+
389
+ A requirement that isn't one of the blocks is a feature the app owns: it is met only when
390
+ `enabled` lists it, so a block that was never passed is an error, not a silent pass. With `slots`
391
+ (the host's slot names), a fill for any other slot is an error too.
392
+
393
+ Blocks shipped so far: `createUpdates(…)` (`app-updates`, in `@marktiderman/genesis-native/updates`),
394
+ `accountBlock` and `tenantFeaturesBlock` (in `@marktiderman/genesis-supabase`).
395
+ `<GenesisNativeApp blocks={…}>` runs them; see that package's README.
396
+
397
+ ## Content packs
398
+
399
+ A content pack is versioned data that fills installed blocks: whatever those blocks hold (meeting types,
400
+ templates, checklists, forms) plus labels. Packs are code: the publishing package exports them, and an
401
+ installer copies them into a tenant's editable rows, keeping each row's source (pack, version, key) so an
402
+ update can tell what someone changed.
403
+
404
+ A pack's `sections` are keyed by the block that owns them. Genesis checks what every pack shares; what an
405
+ item holds is the block's business, checked by the validator it registers as `contributes.contentSection`:
406
+
407
+ ```ts
408
+ import { contentPackProblems, defineBlock, defineContentPack } from "@marktiderman/genesis-config/blocks";
409
+
410
+ export const meetingsBlock = defineBlock({
411
+ id: "meetings",
412
+ contributes: {
413
+ // Returns every problem with this block's items in a pack.
414
+ contentSection: (items) =>
415
+ (items as { key: string; minutes?: number }[]).filter((m) => !((m.minutes ?? 0) > 0)).map((m) => `${m.key}: minutes must be more than 0`),
416
+ },
417
+ });
418
+
419
+ export const weeklyTeamRhythm = defineContentPack(
420
+ {
421
+ id: "weekly-team-rhythm",
422
+ name: "Weekly team rhythm",
423
+ version: "1.0.0",
424
+ publisher: "@acme/content",
425
+ requires: ["meetings"],
426
+ labels: { "project.phase": "Stage" },
427
+ sections: { meetings: [{ key: "weekly", name: "Weekly meeting", minutes: 60 }] },
428
+ },
429
+ { blocks: [meetingsBlock] },
430
+ );
431
+
432
+ contentPackProblems(weeklyTeamRhythm, { installed: installedBlockIds, blocks: [meetingsBlock] }); // [] when it can be installed
433
+ ```
434
+
435
+ `defineContentPack` lists every problem at once: ids, semver versions, publisher, label keys, item keys
436
+ (unique per section, stable across versions), every block validator's problems, and any section whose
437
+ block `requires` doesn't list. `contentPackProblems(pack, installedBlockIds)` still takes the installed
438
+ blocks alone; `{ validators: { meetings: fn } }` gives validators by block id instead of blocks.
439
+
440
+ The typed sections packs had before (`sessionTypes`, `metricTemplates`, `fieldDefinitions`, `forms`,
441
+ `roadmapTemplates`) still work and are checked as before, but are deprecated: put that data in `sections`
442
+ under the block that owns it.
443
+
444
+ ## The page
445
+
446
+ ```tsx
447
+ import { FeatureList } from "@marktiderman/genesis-config/react";
448
+
449
+ <FeatureList features={features} flags={flags} pathHref={(p) => `https://github.com/acme/app/blob/main/${p}`} />
450
+ <FeatureList features={features} variant="marketing" title="What it does" />
451
+ ```
452
+
453
+ The default view is a genesis-ui `ResourcePage` over static data:
454
+
455
+ - A table, and in its grid view a board grouped by status (`KanbanBoard`).
456
+ - Status chips (`StatusBadge`), plus filters by app, audience and visibility.
457
+ - A detail panel with links, acceptance and flags.
458
+ - Planned work stays off the list and shows on the roadmap (Now, Next, Later) below it.
459
+
460
+ `variant="marketing"` shows public, shipped features that have a tagline, as cards: highlights first, then grouped by category.
461
+
462
+ genesis-ui (3.0.0 or later), React and lucide-react are optional peers, needed only by `/react` and `/settings/react`. Gate the route yourself; the component shows whatever it is given.