docs(skills): teach the real feature-flags surface, not a fake defineStack key

[os-zhuang]

Summary

Fixes the ## Feature Flags section of skills/objectstack-platform/SKILL.md, which taught defineStack({ featureFlags: [...] }) — an authoring surface that does not exist. The block was deliberately left untagged by the check:skill-examples gate (#3224) because the fix was structural, not a rename.

Closes#3248

What was wrong (verified against the spec)

1. featureFlags is not a key on ObjectStackDefinitionSchema (packages/spec/src/stack.zod.ts — none of its 42 top-level keys is featureFlags or features). defineStack strict parsing silently strips unknown keys, so the example config was a no-op at runtime and TS2353 at compile time for consumers.
2. The only place FeatureFlagSchema[] appears in the protocol is KernelCapabilitiesSchema.features → ObjectStackCapabilities.system.features — the runtime capabilities descriptor (an introspection/read surface), never referenced by the definition schema. Feature flags have no authoring home in objectstack.config.ts; nothing in the codebase produces or evaluates them at runtime (the schema's only consumers are its own unit tests). Adding a top-level authoring key was therefore deliberately not done here — that's a spec/product decision for the surface owner (per the issue), and it would ship authored-but-inert config.
3. environment: ['production'] was the wrong shape and value: FeatureFlagSchema.environment is a scalar z.enum(['dev','staging','prod','all']) (default 'all').

The rewrite

• Teaches the surface that actually exists: FeatureFlag.create() from @objectstack/spec/kernel (compile-checked flag values) and the flags' protocol home, ObjectStackCapabilities.system.features.
• States explicitly that this is not a defineStack key and why authored featureFlags: is a silent no-op.
• Points readers who want live, resolvable toggles to the real surfaces: the feature_flags settings manifest (@objectstack/service-settings, OS_FEATURE_FLAGS_* env overrides) and auth capability gates (requiresFeature → PUBLIC_AUTH_FEATURES) — explicitly distinct from FeatureFlagSchema.
• Re-tags the block with <!-- os:check --> per the issue's definition of done, so the gate covers it from now on.

Verification

pnpm --filter @objectstack/spec build
pnpm --filter @objectstack/spec run check:skill-examples
# ✅ 20 skill examples type-check against @objectstack/spec
# (was 19 — the new block at skills/objectstack-platform/SKILL.md:1045 is now covered)

🤖 Generated with Claude Code

https://claude.ai/code/session_011omKdw59exYDNh3GekqFZq

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Building	Preview, Comment	Jul 19, 2026 5:26pm