docs: add feature flag contributor guide for gating new features

[bobbravo2]

Summary

• Adds docs/internal/developer/adding-a-feature.md — a step-by-step walkthrough for contributors to gate new features behind feature flags (naming, registration in flags.json, backend/frontend gating, visibility choice, and testing)
• Adds a feature-flag requirement to CONTRIBUTING.md in both the "Make Your Changes" workflow and the "Before Submitting" PR checklist
• Links the new guide from docs/internal/developer/README.md alongside the existing feature-flags docs and ADR-0007
• Adds a "Feature Flags" section to BOOKMARKS.md for discoverability

Closes the gap between ADR-0007's mandate ("all new features must be flag-gated") and the contributor-facing docs, which previously never mentioned feature flags.

Test plan

• Verify all relative links resolve correctly in a local docs build or GitHub rendering
• Confirm flags.json path referenced in the guide matches the actual file location
• Review code examples against current handlers/featureflags.go and @/lib/feature-flags APIs

Made with Cursor

Summary by CodeRabbit

• Documentation
  • Added comprehensive feature flags documentation including implementation guides, overview, and fail-modes reference
  • Updated contributing guidelines to require gating new user-facing features behind feature flags
  • Documented end-to-end developer workflow for implementing feature-gated functionality

[coderabbitai]

📝 Walkthrough

Walkthrough

PR adds comprehensive feature flag documentation and establishes requirements for gating new user-facing features behind flags. Includes a detailed step-by-step guide for developers, architecture references, and updates contributing guidelines to mandate feature flag usage.

Changes

Cohort / File(s)	Summary
Documentation Index Updates BOOKMARKS.md, docs/internal/developer/README.md	Added "Feature Flags" sections linking to step-by-step guides, overview documentation, and architecture decision records (ADR-0007) on Unleash feature flags.
Contribution Requirements CONTRIBUTING.md	Explicitly mandates gating all new user-facing features behind feature flags in branch workflow and PR checklist, with link to implementation guide.
Feature Flag Implementation Guide docs/internal/developer/adding-a-feature.md	New comprehensive developer guide covering flag naming conventions (<component>.<feature>.<aspect>), registration in flags.json and models.json, startup sync via cmd/sync_flags.go, backend gating patterns in handlers/featureflags.go, frontend gating via Unleash React SDK and workspace-scoped evaluation, flag visibility scoping, local testing, and evaluation precedence rules.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title follows Conventional Commits format (docs: ...) and clearly describes the main change: adding feature flag documentation for contributors.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Performance And Algorithmic Complexity	✅ Passed	PR contains only markdown documentation files with no code changes, algorithms, or performance-critical operations.
Security And Secret Handling	✅ Passed	Documentation-only PR with no hardcoded secrets, credentials, or injection vulnerabilities; references to sensitive terms are educational best practices and environment variable documentation.
Kubernetes Resource Safety	✅ Passed	Kubernetes Resource Safety check not applicable; PR contains only documentation changes without Kubernetes manifest modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/feature-flag-contributor-guide

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/feature-flag-contributor-guide

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/internal/developer/adding-a-feature.md`:
- Line 32: The docs reference a non-existent Make target deploy-unleash-kind;
either add a Makefile target named deploy-unleash-kind that runs the appropriate
Kind deployment steps to apply the manifests under
components/manifests/base/core (including flags.json and models.json), or update
the documentation to point to the actual existing Make target that performs the
same Kind deployment. Modify the Makefile to include a deploy-unleash-kind
recipe that executes the cluster creation/apply sequence for the Unleash
manifests, or change the doc line referencing deploy-unleash-kind to the correct
target name and include any required flags/notes to deploy to a Kind cluster.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5730ce82-eb0d-4598-b73a-bc8f5eed5c16

📥 Commits

Reviewing files that changed from the base of the PR and between 4b12c81 and 9230bff.

📒 Files selected for processing (4)

• BOOKMARKS.md
• CONTRIBUTING.md
• docs/internal/developer/README.md
• docs/internal/developer/adding-a-feature.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify manifest files and Make targets exist

# Check flags.json
if [[ -f "components/manifests/base/core/flags.json" ]]; then
  echo "✓ components/manifests/base/core/flags.json exists"
else
  echo "✗ components/manifests/base/core/flags.json NOT FOUND"
fi

# Check models.json
if [[ -f "components/manifests/base/core/models.json" ]]; then
  echo "✓ components/manifests/base/core/models.json exists"
else
  echo "✗ components/manifests/base/core/models.json NOT FOUND"
fi

# Check Make targets
if grep -q "^deploy-unleash-kind:" Makefile; then
  echo "✓ Make target 'deploy-unleash-kind' found"
else
  echo "✗ Make target 'deploy-unleash-kind' NOT FOUND"
fi

if grep -q "^unleash-port-forward:" Makefile; then
  echo "✓ Make target 'unleash-port-forward' found"
else
  echo "✗ Make target 'unleash-port-forward' NOT FOUND"
fi

Repository: ambient-code/platform

Length of output: 256

---

🏁 Script executed:

cat -n docs/internal/developer/adding-a-feature.md | sed -n '25,65p'

Repository: ambient-code/platform

Length of output: 1663

---

🏁 Script executed:

grep -n "deploy-unleash-kind\|unleash-port-forward" docs/internal/developer/adding-a-feature.md

Repository: ambient-code/platform

Length of output: 195

---

🏁 Script executed:

cat -n docs/internal/developer/adding-a-feature.md | sed -n '150,165p'

Repository: ambient-code/platform

Length of output: 671

---

make deploy-unleash-kind target missing.

The guide references make deploy-unleash-kind at line 158 to deploy Unleash to a Kind cluster, but this Make target does not exist. The manifest files referenced (components/manifests/base/core/flags.json and models.json) are correct and present. Add the missing Make target or update the documentation with the correct deployment command.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/internal/developer/adding-a-feature.md` at line 32, The docs reference a
non-existent Make target deploy-unleash-kind; either add a Makefile target named
deploy-unleash-kind that runs the appropriate Kind deployment steps to apply the
manifests under components/manifests/base/core (including flags.json and
models.json), or update the documentation to point to the actual existing Make
target that performs the same Kind deployment. Modify the Makefile to include a
deploy-unleash-kind recipe that executes the cluster creation/apply sequence for
the Unleash manifests, or change the doc line referencing deploy-unleash-kind to
the correct target name and include any required flags/notes to deploy to a Kind
cluster.