From 0b2d459b7b425a7671d9c09164fa2a38ff384955 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 19 Jul 2026 17:25:34 +0000
Subject: [PATCH] docs(skills): teach the real feature-flags surface, not a
 fake defineStack key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Feature Flags example in skills/objectstack-platform/SKILL.md authored
`defineStack({ featureFlags: [...] })` — a key that does not exist on
ObjectStackDefinitionSchema (strict parsing silently strips it; consumers
copying it hit TS2353), and `environment: ['production']` is the wrong shape
(scalar enum) and an out-of-enum value ('prod' is correct).

Rewritten against the surface that actually exists:
- `FeatureFlag.create()` from `@objectstack/spec/kernel` for compile-checked
  flag values;
- the flags' one protocol home, the runtime capabilities descriptor
  (`ObjectStackCapabilities.system.features`);
- an explicit warning that this is NOT a defineStack key;
- pointers to the live toggle surfaces readers may actually want (the
  `feature_flags` settings manifest and `requiresFeature` auth gates).

Re-tagged the block with `<!-- os:check -->` so check:skill-examples covers
it going forward (gate passes: 20 marked examples).

Closes #3248

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011omKdw59exYDNh3GekqFZq
---
 skills/objectstack-platform/SKILL.md | 58 ++++++++++++++++++----------
 1 file changed, 38 insertions(+), 20 deletions(-)

diff --git a/skills/objectstack-platform/SKILL.md b/skills/objectstack-platform/SKILL.md
index 50c04a323f..1ede6cf76b 100644
--- a/skills/objectstack-platform/SKILL.md
+++ b/skills/objectstack-platform/SKILL.md
@@ -1033,32 +1033,50 @@ const metrics = kernel.getPluginMetrics();
 
 ## Feature Flags
 
-```typescript
-import { defineStack } from '@objectstack/spec';
+Feature flags are a **protocol shape, not a config key**. `FeatureFlagSchema` (from
+`@objectstack/spec/kernel`) defines the flag document; in the protocol it appears only on
+the runtime capabilities descriptor (`ObjectStackCapabilities.system.features`) that a
+platform serves for introspection. There is **no `featureFlags:` / `features:` key on
+`defineStack`** — strict parsing silently strips unknown keys, so such config would be a
+no-op.
 
-export default defineStack({
-  featureFlags: [
-    {
-      name: 'experimental_ai_copilot',
-      label: 'AI Copilot',
-      enabled: true,
-      strategy: 'percentage',
-      conditions: { percentage: 25 },   // 25% of users
-      environment: ['production'],
-    },
-    {
-      name: 'beta_kanban_view',
-      label: 'Kanban View',
-      enabled: true,
-      strategy: 'group',
-      conditions: { groups: ['beta_testers'] },
-    },
-  ],
+<!-- os:check -->
+```typescript
+import { FeatureFlag } from '@objectstack/spec/kernel';
+import type { ObjectStackCapabilities } from '@objectstack/spec';
+
+// FeatureFlag.create() gives you a compile-checked flag value:
+const aiCopilot = FeatureFlag.create({
+  name: 'experimental_ai_copilot',
+  label: 'AI Copilot',
+  enabled: true,
+  strategy: 'percentage',
+  conditions: { percentage: 25 },   // 25% of users
+  environment: 'prod',              // 'dev' | 'staging' | 'prod' | 'all' (default 'all')
 });
+
+// Where flags live in the protocol — the runtime capabilities descriptor:
+type SystemFeatures = NonNullable<ObjectStackCapabilities['system']['features']>;
+const features: SystemFeatures = [
+  aiCopilot,
+  {
+    name: 'beta_kanban_view',
+    label: 'Kanban View',
+    enabled: true,
+    strategy: 'group',
+    conditions: { groups: ['beta_testers'] },
+    environment: 'all',
+  },
+];
 ```
 
 Strategies: `boolean` | `percentage` | `user_list` | `group` | `custom`
 
+Looking for live, resolvable toggles today? Those are different surfaces, not
+`FeatureFlagSchema`: the `feature_flags` settings manifest
+(`@objectstack/service-settings`, env-overridable via `OS_FEATURE_FLAGS_*`) and auth
+capability gates (`requiresFeature` → `PUBLIC_AUTH_FEATURES`).
+
 ---
 ---