first commit

docs/foundation/data/packer-browser/src/flags/flags.md

@@ -0,0 +1,76 @@
+# `flags`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`flags.ts` resolves the `@suaveplan/feature-flags` `FlagProvider` used
+by `PackedResourceManager` to gate Cluster B / C features. Cluster A
+registers no live flags, but the provider slot exists so adopters can
+wire a `MemoryProvider` (or any other `FlagProvider`) without an API
+churn later. The default is an empty `MemoryProvider` — every
+`isEnabled` query falls through to the strategy default because no
+`FlagDefinition` is registered.
+
+## Features
+
+- `resolveFlagsProvider(opts)` — single-call helper that returns
+  either the caller-supplied provider or a fresh empty
+  `MemoryProvider` from `@suaveplan/feature-flags`.
+- Zero startup cost in the default path — no flag definitions are
+  registered, no IO happens, no `setInterval` is set.
+- Composes cleanly with the rest of the manager's option bundle:
+  `PackedResourceManagerOptions.flags?: FlagProvider` flows straight
+  through.
+
+## Usage: Basic
+
+```ts
+import { resolveFlagsProvider } from "@suaveplan/packer-browser";
+
+const provider = resolveFlagsProvider();
+const result = await provider.evaluate({ key: "anything" }, {});
+// result.value === false (no flag defined)
+```
+
+## Usage: Advanced
+
+```ts
+import { MemoryProvider } from "@suaveplan/feature-flags";
+import { createPackedResourceManager } from "@suaveplan/packer-browser";
+
+const provider = new MemoryProvider([
+    {
+        key: "packer-browser.progressive-streaming",
+        type: "boolean",
+        defaultValue: false,
+        strategies: [],
+    },
+]);
+
+const manager = createPackedResourceManager({ flags: provider });
+const sameProvider = manager.getFlagProvider();
+// sameProvider === provider — caller-supplied instance is preserved
+```
+
+## API Reference
+
+- `resolveFlagsProvider(opts?: FlagsOptions): FlagProvider` — returns
+  `opts.flags ?? new MemoryProvider([])`.
+- `FlagsOptions` — `{ flags?: FlagProvider }`.
+- Re-export: `FlagProvider` (alias of
+  `@suaveplan/feature-flags`'s).
+
+## Implementation Notes
+
+The slot is intentionally minimal in Cluster A. The reason it ships
+now, even though no feature consumes it, is that adding a top-level
+option to a manager constructor later forces every adopter to update
+their type signatures — wiring it in once at first delivery means
+Cluster B can flip `progressive-streaming` on with a one-line config
+change. The default uses `MemoryProvider([])` rather than a null
+provider so caller code can call `provider.evaluate(...)` without
+guard checks: an empty `MemoryProvider` returns `defaultValue` for
+every unknown flag.