@ultimat3/flags 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -118,7 +118,12 @@ what lets `policy` (tier 2) call it from inside a predicate.
 ## Open
 
 - Nothing calls `flagsReport()` yet. It is the projection an `x flags [--json]` command and an MCP
-  `flags.list` tool should read; neither exists.
+  `flags.list` tool should read; neither exists. `projection.ts`'s own header said the opposite
+  until 12.0.0 — it named the CLI, the MCP tool and the manifest as readers — and the manifest was
+  never a candidate: it is derived from SOURCE, while `allFlags()` is runtime state an app's imports
+  fill, so a manifest build would publish an empty list. That is `@ultimat3/http`'s `appErrorStatus()`,
+  deleted for the same reason. A CLI command is the one reachable consumer, because `loadApp` runs
+  first.
 
 ## Commands
 

package/README.md

@@ -162,8 +162,12 @@ up muted and the debt invisible again. `configureFlags({ clock, reportEveryMs })
 ## Projection
 
 `flagsReport()` returns every declared flag with its kind, expiry, owner and whether it is expired,
-sorted by key, plus the expired keys lifted out. It is the one shape `x flags --json`, an MCP tool
-and the manifest should all read, so none of them recomputes "expired".
+sorted by key, plus the expired keys lifted out.
+
+**Offered, not published.** Nothing reads it yet: there is no `x flags` command, no `flags` section
+in the manifest and no MCP tool, and this file claimed all three until 12.0.0. The manifest is not a
+consumer it can ever have — a manifest is derived from source and this reads a registry an app's own
+imports fill at runtime — so the one reachable surface is a CLI command, which loads the app first.
 
 ## What it owns
 
@@ -176,7 +180,7 @@ and the manifest should all read, so none of them recomputes "expired".
 | `src/registry.ts` | `defineFlag`, key → flag, `applyFlagSnapshot` |
 | `src/runtime.ts` | the clock and the per-flag report rate limit over core's `reportError` |
 | `src/evaluate.ts` | `isEnabled()` — the one way to ask |
-| `src/projection.ts` | `flagsReport()` for the CLI, MCP and the manifest |
+| `src/projection.ts` | `flagsReport()` — the shape a CLI command would print; nothing reads it yet |
 | `src/errors.ts` | this package's X_* codes |
 
 ## Boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/flags",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.2.0"
+    "@ultimat3/core": "12.0.0"
   }
 }

package/src/projection.ts

@@ -1,6 +1,20 @@
-// Single responsibility: the declared flags as data — one JSON-safe shape for `x flags --json`,
-// the MCP tool and the manifest, so all three answer "what is expired?" identically instead of
-// each computing it. Same rule as `listErrorCodes()`: the projection lives with the registry.
+// Single responsibility: the declared flags as data — one JSON-safe shape, so no surface has to
+// compute "what is expired?" for itself. Same rule as `listErrorCodes()`: the projection lives
+// with the registry.
+//
+// OFFERED, not published (`As of 2026-08-24`). This header used to state that `x flags --json`,
+// an MCP tool and the manifest all read it. **None of the three exists**: there is no `x flags`
+// command, `ARRAY_SECTIONS` in `@ultimat3/manifest` has no `flags` section, no MCP tool names one,
+// and `flagsReport` has zero callers outside this package's own test. `packages/flags/CLAUDE.md`
+// has always said so; only this file stated the plan as fact, which is the shape
+// `@ultimat3/ai`'s `agent-facts.ts` names — the SHAPE a surface would publish, never a row any
+// surface carries.
+//
+// And one of the three could never have been the consumer it named: a manifest is a build artefact
+// derived from SOURCE, while `allFlags()` is process-global runtime state filled by the app's own
+// imports — so in a CLI process that has not loaded the app this answers `{ flags: [], expired: []
+// }`, which is `@ultimat3/http`'s deleted `appErrorStatus()` exactly. A CLI command is the reachable
+// consumer, because `loadApp` imports the app's modules before the command runs.
 
 import type { FlagKind } from './flag';
 import { allFlags } from './registry';