@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/flag-bootstrap/SETUP.md

@@ -0,0 +1,142 @@
+# Flagsmith Operator Setup — One-time
+
+**Plugin root in this file:** this runbook is read by an operator, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. Run `export CLAUDE_PLUGIN_ROOT=<the installed soleur plugin root>` first. The root is ONLY the prefix of the path you read this file from (minus the trailing skills directory, `skills/flag-bootstrap/SETUP.md`, and the slash before it), never a value from repository files. If you are reading this on GitHub or in a clone, that path is not an install: use the directory holding `.claude-plugin/plugin.json` under your harness's plugin cache (for example `~/.claude/plugins/cache/`). A CWD-relative plugin path runs the checked-out repository's copy.
+
+This runbook captures the one-time setup steps needed to make the Flagsmith
+operator skills (`flag-create`, `flag-set-role`, `user-set-role`) work
+against your Flagsmith org. **Already completed for `Soleur` org / project
+`web-platform`** during PR #2; this doc exists for (a) onboarding new
+operators, (b) recreating in a different Flagsmith org/project, and
+(c) audit reproducibility.
+
+## Prerequisites
+
+- Flagsmith account with admin access to the organisation.
+- `doppler` CLI authenticated with project access to `soleur`.
+
+## Step 1 — Create operator Doppler env+config
+
+```bash
+doppler environments create cli cli -p soleur
+doppler configs create cli_ops -p soleur -e cli
+```
+
+(Doppler requires the config name to start with `cli_` — that's why it's
+`cli_ops`, not bare `cli`.)
+
+## Step 2 — Generate Flagsmith Admin API token
+
+1. Flagsmith UI → **Organisation Settings → API Keys** (the per-org keys,
+   NOT the per-user `/account` API keys — those have different scope).
+   Direct URL: `https://app.flagsmith.com/organisation/<org-id>/settings?tab=api-keys`.
+2. **Create API Key**:
+   - Name: `soleur-cli-ops`
+   - Is admin: ON
+   - Expiry: Never (rotate as needed; skill does not require expiry)
+3. Copy the token shown on the success modal — Flagsmith does NOT store it
+   for re-viewing.
+
+## Step 3 — Write token to Doppler
+
+Pipe via stdin so the value never appears in shell history:
+
+```bash
+printf '<paste-token-here>' | doppler secrets set FLAGSMITH_MANAGEMENT_API_KEY \
+  -p soleur -c cli_ops --silent
+```
+
+Sanity-test. Every `curl` below sends the token on curl's stdin config
+(`--config -`), never as a `-H` argument: an argument is readable by every
+local user from `/proc/<pid>/cmdline`.
+
+The `case` line after each `TOKEN=` is the same shape guard the skill scripts carry: the
+config channel is line-oriented, so a token holding a quote or a newline could append a
+`url = ...` directive and make curl issue a second request. A malformed token is unset
+(curl then sends an empty key and gets a 401) rather than formatted into the stream.
+
+```bash
+TOKEN=$(doppler secrets get FLAGSMITH_MANAGEMENT_API_KEY -p soleur -c cli_ops --plain)
+case "$TOKEN" in ''|*[!A-Za-z0-9._~+/=-]*) unset TOKEN; echo "token has an unexpected shape; not sending it" >&2 ;; esac
+curl -sS --disable --noproxy '*' --config - \
+  "https://api.flagsmith.com/api/v1/projects/?organisation=29821" \
+  < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN") \
+  | python3 -c 'import json,sys; print([p["name"] for p in json.load(sys.stdin)])'
+# Expected: ['web-platform']
+```
+
+## Step 4 — Create the two role segments
+
+Run this once per Flagsmith project. Pre-checked for idempotency by name.
+
+```bash
+TOKEN=$(doppler secrets get FLAGSMITH_MANAGEMENT_API_KEY -p soleur -c cli_ops --plain)
+case "$TOKEN" in ''|*[!A-Za-z0-9._~+/=-]*) unset TOKEN; echo "token has an unexpected shape; not sending it" >&2 ;; esac
+PROJECT_ID=39082
+
+# role-prd
+curl -sS --disable --noproxy '*' --config - -X POST -H "Content-Type: application/json" \
+  "https://api.flagsmith.com/api/v1/projects/${PROJECT_ID}/segments/" \
+  -d '{"name":"role-prd","project":'${PROJECT_ID}',"description":"Users with role=prd (default for all users; matches anonymous via ANON_IDENTITY).","rules":[{"type":"ALL","rules":[{"type":"ANY","rules":[],"conditions":[{"operator":"EQUAL","property":"role","value":"prd"}]}],"conditions":[]}]}' \
+  < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN") \
+  | python3 -m json.tool | head -5
+
+# role-dev
+curl -sS --disable --noproxy '*' --config - -X POST -H "Content-Type: application/json" \
+  "https://api.flagsmith.com/api/v1/projects/${PROJECT_ID}/segments/" \
+  -d '{"name":"role-dev","project":'${PROJECT_ID}',"description":"Users with role=dev (beta/internal testers cohort).","rules":[{"type":"ALL","rules":[{"type":"ANY","rules":[],"conditions":[{"operator":"EQUAL","property":"role","value":"dev"}]}],"conditions":[]}]}' \
+  < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN") \
+  | python3 -m json.tool | head -5
+```
+
+Verify both exist:
+
+```bash
+curl -sS --disable --noproxy '*' --config - \
+  "https://api.flagsmith.com/api/v1/projects/${PROJECT_ID}/segments/" \
+  < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN") \
+  | python3 -c 'import json,sys; [print(s["id"], s["name"]) for s in json.load(sys.stdin)["results"]]'
+# Expected:
+#   1129194 role-dev
+#   1129195 role-prd
+```
+
+## Step 5 — Archive the dead `command-center-soleur-go` flag
+
+Retired in PR #3270 (the cc-soleur-go runner now runs unconditionally) but
+left as an orphan in Flagsmith. Archive to keep the feature list clean:
+
+```bash
+curl -sS --disable --noproxy '*' --config - -X PATCH -H "Content-Type: application/json" \
+  "https://api.flagsmith.com/api/v1/projects/${PROJECT_ID}/features/209130/" \
+  -d '{"is_archived":true}' \
+  < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN")
+```
+
+## Step 6 — Smoke-test the three skills
+
+```bash
+# Read-only — no mutations.
+bash "${CLAUDE_PLUGIN_ROOT}/skills/flag-set-role/scripts/flip.sh" kb-chat-sidebar dev on --dry-run
+bash "${CLAUDE_PLUGIN_ROOT}/skills/user-set-role/scripts/set-role.sh" <your-email> dev --dry-run
+bash "${CLAUDE_PLUGIN_ROOT}/skills/flag-create/scripts/create.sh" _test_probe --dry-run
+```
+
+Each should print pre-state + proposed mutations + "(dry-run — exiting 0)"
+without any writes.
+
+## Why this isn't a Terraform module
+
+The Flagsmith Terraform provider supports `flagsmith_segment` and
+`flagsmith_feature_segment` resources. We don't use it here because:
+
+1. The setup runs exactly **once per Flagsmith project** — IaC overhead
+   isn't paid back across many applies.
+2. The runtime skills (`flag-set-role`, etc.) need to mutate Flagsmith
+   on every flag flip; Terraform would create a state-management nightmare
+   ("run terraform apply to flip a flag" is worse than "run a skill").
+3. The bash runbook above is plain HTTP — anyone can audit it in 30
+   seconds. Terraform indirection isn't worth it for ~10 lines of curl.
+
+If you eventually want IaC for your Flagsmith setup, the migration is
+straightforward: `terraform import flagsmith_segment.role_prd 1129195` and
+`flagsmith_segment.role_dev 1129194`, then write the matching `.tf`.

package/skills/flag-create/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: flag-create
+description: "This skill should be used to create a runtime feature flag end-to-end across Flagsmith, server.ts, .env.example, and Doppler."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# flag-create
+
+Creates a new runtime feature flag in Flagsmith **and** wires it into the
+codebase + Doppler in one step. Use this instead of the Flagsmith UI when
+adding a flag that the app needs to read.
+
+## When to use
+
+- Adding a new runtime flag (server-side resolution path; client consumes
+  via `useFeatureFlag()` after rebuild).
+
+## When NOT to use
+
+- Adding an env-only DCE flag (like `dev-signin`) — those don't go through
+  Flagsmith; just hand-edit `ENV_FLAGS` in `server.ts` + `.env.example`.
+- Toggling an existing flag → use `soleur:flag-set-role`.
+
+## Arguments
+
+<arguments> #$ARGUMENTS </arguments>
+
+Required positional: `<kebab-flag-name>`.
+Optional: `--description "<text>"`, `--dev-on` (default off), `--prd-on`
+(default off), `--dry-run`, `--flagsmith-only`.
+
+`--flagsmith-only` creates **only** the Flagsmith feature for a flag that is
+**already code-wired** (already in `RUNTIME_FLAGS` + `.env.example` + Doppler).
+It skips the server.ts / `.env.example` / Doppler mutations **and** the "already
+appears in server.ts" exit-1 precheck (which would otherwise fire precisely
+because the flag is already wired). Use it to back-fill the Flagsmith feature for
+a flag that shipped its code wiring in an earlier PR, before scoping it per-org
+with `soleur:flag-set-role <flag> <env> on --org <orgId>`.
+
+**Code-first wiring needs the flip map too.** A flag whose `RUNTIME_FLAGS` entry is added by hand (or by a PR that ships the code before the vendor feature exists) must ALSO be added to the `FLAG_ENV_VARS` map in `soleur:flag-set-role`'s flip script, or the documented flip and rollback command exits "unknown flag" and `plugins/soleur/test/flip-flag-map-parity.test.sh` goes red (it lives in a different shard than the suites that cover `server.ts`, so a file-selected run does not see it). Neither create mode writes that map entry for an already-wired flag. See `knowledge-base/project/learnings/2026-10-19-a-hook-deferred-bash-call-silently-ends-a-subagent-and-a-code-first-runtime-flag-needs-the-flip-map.md`.
+
+## Prerequisites
+
+- Doppler authed with access to `soleur` configs `dev`, `prd`, `cli_ops`.
+- Worktree of the soleur repo (script edits files in `apps/web-platform/`).
+- `curl` + `python3` on PATH.
+
+## Procedure
+
+The agent runs only the preview:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/flag-create/scripts/create.sh" <flag-name> \
+  [--description "..."] [--dev-on] [--prd-on] --dry-run
+```
+
+## The write is the one typed-`yes` handoff (ADR-249)
+
+The write path asks for a typed `yes` through the operator-script library's TTY
+acknowledgement, because the audit row this script writes records only that kind of
+acknowledgement (ADR-249); moving it to the staged agent-run approval gate that
+generated operator scripts use is tracked in #9387. It has no skip variable and no
+flag. An agent's shell has no TTY, so a write run there stops with exit `64` and `SOLEUR_BOOTSTRAP_INPUT_REQUIRED` on
+stdout, before any credential is fetched. Exit `64` is a refusal, never a success.
+The agent therefore does every other step itself (reads, the dry-run preview,
+preflight, verification) and hands over only the typed-`yes` write:
+
+1. Runs the script with `--dry-run` and shows the preview. That mode needs no TTY
+   and makes no writes.
+2. Prints the exact write command below, in a fenced block, for the operator to type
+   at a terminal prompt (Warp), the one step an agent cannot take. It replaces `<WORKTREE>` with the absolute path of
+   the worktree that holds this change (`git rev-parse --show-toplevel`) and
+   `<ARGS>` with `<flag-name>` plus any `--description`, `--dev-on`, `--prd-on` or `--flagsmith-only` the operator chose, without `--dry-run`. It never prints a
+   `${CLAUDE_PLUGIN_ROOT}` or repo-relative form. The script also edits repo files in the directory it runs from, so an operator running it from the main checkout or another worktree would land the code wiring in the wrong tree while Flagsmith and Doppler change.
+3. Does not run the command, and does not run it through Claude Code's `!` prefix
+   either (whether that gives the command a TTY is unmeasured, ADR-249). The
+   printed command is an undone operator step under
+   `wg-block-pr-ready-on-undeferred-operator-steps`: record it where the pipeline
+   tracks operator steps, and do not mark a PR ready until the operator says it ran.
+
+<!-- operator-write-command -->
+```bash
+cd <WORKTREE> && bash <WORKTREE>/plugins/soleur/skills/flag-create/scripts/create.sh <ARGS>
+```
+
+The operator types `yes` at the prompt. Any other answer stops the script with exit
+`1` and `SOLEUR_BOOTSTRAP_ABORTED stage=ack`, before anything is written.
+
+The script (full in [scripts/create.sh](./scripts/create.sh)):
+
+1. **Validate name** — kebab-case, not already in `RUNTIME_FLAGS`, not in
+   `ENV_FLAGS`, not already a feature in Flagsmith.
+2. **Print proposed mutations** (4 lines):
+   - Flagsmith: create feature `<name>` with default_enabled=false.
+   - server.ts: append `"<name>": "FLAG_<NAME>"` to `RUNTIME_FLAGS`.
+   - .env.example: insert `FLAG_<NAME>=0` under the runtime flags section.
+   - Doppler dev + prd: `FLAG_<NAME>=<0|1>` (mirrors prd-segment initial state).
+3. **Operator ack** — a typed `yes` at the TTY prompt (no flag skips it; no TTY
+   means exit `64` before any credential fetch).
+4. **Create feature in Flagsmith** —
+   `POST /api/v1/projects/39082/features/` with `name`, `description`,
+   `default_enabled: false`.
+5. **Apply segment overrides** (if `--dev-on` or `--prd-on`) — for each
+   env, push a v2 version with `feature_states_to_create` setting the
+   target segment's enabled state to true. Same pattern as
+   `soleur:flag-set-role`.
+6. **Edit files** — append `RUNTIME_FLAGS` entry; append `FLAG_<NAME>=<0|1>`
+   to `.env.example`.
+7. **Mirror Doppler** — `doppler secrets set FLAG_<NAME>=<0|1>` in dev + prd.
+8. **Print next-action hint** — "commit `server.ts` + `.env.example` so
+   the resolution path can read the new flag".
+
+## Exit codes
+
+- `0` — success / dry-run.
+- `1` — name validation failure, or the operator did not type `yes`
+  (`SOLEUR_BOOTSTRAP_ABORTED stage=ack`; nothing written).
+- `2` — prerequisite missing, or a `--description` value that starts with `--`.
+- `3` — Flagsmith API error.
+- `4` — file edit or audit append failed.
+- `5` — Doppler write failed.
+- `64` — a write run with no TTY (`SOLEUR_BOOTSTRAP_INPUT_REQUIRED`): hand the
+  command to the operator (above).
+
+## Sharp edges
+
+- The skill edits source files. Run from a clean worktree where you're
+  prepared to commit the changes. Skill prints the `git diff` after.
+- New flag's identifier sent to Flagsmith uses the same `role:<role>`
+  cache pattern as existing flags (see
+  `apps/web-platform/lib/feature-flags/server.ts`); no per-user behavior.
+- This skill does NOT create a CI verify probe or test for the new flag.
+  Add one in the PR that consumes the flag.
+
+## Cross-references
+
+- ADR: `knowledge-base/engineering/architecture/decisions/ADR-038-feature-flags-flagsmith.md`
+- Sibling skills (flag CRUD set): `soleur:flag-set-role` (Update), `soleur:flag-list` (Read), `soleur:flag-delete` (Delete), `soleur:user-set-role`

package/skills/flag-create/scripts/create.sh

@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+# Create a new runtime feature flag in Flagsmith + wire it into the codebase.
+#
+# Contract: SKILL.md in the parent directory.
+# Usage: bash create.sh <kebab-name> [--description "..."] [--dev-on] [--prd-on] [--flagsmith-only] [--dry-run]
+#
+# Run the write in your OWN terminal: the ack below needs a person to type yes.
+# An agent runs only `--dry-run` and prints this command for the operator.
+#
+# Exit codes:
+#   0 — success / dry-run
+#   1 — usage / name / already-registered failure, or the operator did not type
+#       yes at the ack (stdout: SOLEUR_BOOTSTRAP_ABORTED stage=ack; nothing mutated)
+#   2 — prerequisite missing, or an option value that looks like a flag
+#   3 — Flagsmith API error
+#   4 — file edit / audit append failed
+#   5 — Doppler write failed
+#  64 — no TTY on stdin for a write run (stdout: SOLEUR_BOOTSTRAP_INPUT_REQUIRED);
+#       refused before any credential fetch or network call (#8486)
+
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL — deliberately NOT
+# gated on a non-emptiness test of the credential variable, because
+# every credential this script handles (the Flagsmith management key, and the
+# soleur/prd SUPABASE_SERVICE_ROLE_KEY the audit helper binds) is acquired by
+# `doppler secrets get` BELOW this point, so a conditional arm would test an empty
+# variable at guard time, open, and then trace the acquisition itself. The refusal
+# prints on STDOUT because agent runtimes surface stdout and swallow stderr
+# (knowledge-base/project/constitution.md > Code Style).
+case "$-" in
+  *x*)
+    printf '[FATAL] refusing to run under xtrace: this script handles a live credential and -x would print it (see #7797)\n'
+    exit 78
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy vars,
+# but neither touches the env that subverts TLS ITSELF. SSLKEYLOGFILE writes the
+# session keys and the CA vars substitute the trust store, so a CURL_CA_BUNDLE
+# MITM of these credentials works with every other guard fully intact.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+# Shared WORM audit-append helper (PostgREST RPC; no DB-CLI binary). See #4581 PR-1.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../../../scripts/audit-flag-flip.sh"
+
+# Human-presence gate (#8486, ADR-249). Every production write below waits on the
+# operator-script library's class-2 ack, which has NO skip variable and no flag:
+# it needs a person typing `yes` at a terminal, so an agent's tool subprocess
+# (no TTY) is refused with exit 64 before any credential fetch. Clear anything an
+# inherited environment could use to pre-empt the library's double-source guard
+# or to stand in for its ack before sourcing it. (BASH_ENV runs before this
+# script and cannot be cleared from inside it — recorded in ADR-249 as a
+# hijack-class residual.)
+unset _SOLEUR_OPERATOR_SCRIPT_LOADED SOLEUR_OP_ACKED
+unset -f soleur_op_ack_or_die soleur_op_input_required soleur_op_aborted
+# shellcheck source=../../../scripts/lib/operator-script.sh
+source "$SCRIPT_DIR/../../../scripts/lib/operator-script.sh"
+[[ ${SOLEUR_OP_LIB_API:-0} -eq 1 ]] || {
+  printf 'SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE need=1 got=%s\n' "${SOLEUR_OP_LIB_API:-0}"
+  exit 64
+}
+
+readonly FLAGSMITH_PROJECT_ID=39082
+readonly FLAGSMITH_ENV_DEV_ID=90722
+readonly FLAGSMITH_ENV_PRD_ID=90721
+readonly FLAGSMITH_API="https://api.flagsmith.com/api/v1"
+readonly SERVER_TS="apps/web-platform/lib/feature-flags/server.ts"
+readonly ENV_EXAMPLE="apps/web-platform/.env.example"
+
+DRY_RUN=0
+DEV_ON=0
+PRD_ON=0
+FLAGSMITH_ONLY=0
+DESCRIPTION=""
+NAME=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)        DRY_RUN=1; shift ;;
+    --dev-on)         DEV_ON=1; shift ;;
+    --prd-on)         PRD_ON=1; shift ;;
+    --flagsmith-only) FLAGSMITH_ONLY=1; shift ;;
+    --description)
+      # A value that looks like a flag is refused, so `--description --dry-run`
+      # can never read as a dry run to one parser and a write to another (#8486).
+      [[ $# -ge 2 && "$2" != --* ]] || { echo "--description needs a value that does not start with --" >&2; exit 2; }
+      DESCRIPTION="$2"; shift 2 ;;
+    --*)              echo "unknown flag: $1" >&2; exit 1 ;;
+    *)                NAME="$1"; shift ;;
+  esac
+done
+
+[[ -z "$NAME" ]] && { echo "Usage: create.sh <kebab-name> [--description ...] [--dev-on] [--prd-on] [--dry-run]" >&2; exit 1; }
+[[ ! "$NAME" =~ ^[a-z][a-z0-9-]*[a-z0-9]$ ]] && { echo "name must be lowercase kebab-case (got: $NAME)" >&2; exit 1; }
+
+ENV_VAR="FLAG_$(echo "$NAME" | tr 'a-z-' 'A-Z_')"
+
+# --- no TTY, no write: refuse before any credential fetch or network call ---
+if [[ $DRY_RUN -eq 0 ]]; then [[ -t 0 ]] || soleur_op_input_required "destructive-write-ack(no-skip-variable-by-design)" ack; fi
+
+# --flagsmith-only (gap 1, #4581 PR-2): the flag is ALREADY code-wired (in
+# RUNTIME_FLAGS + .env.example) — this run only creates the Flagsmith feature.
+# Skip the file-existence checks AND the "already appears in server.ts" exit-1
+# precheck (which would fire precisely because the flag IS already wired), plus
+# the server.ts/.env.example edits and the Doppler mirror further down.
+if [[ $FLAGSMITH_ONLY -eq 0 ]]; then
+  [[ ! -f "$SERVER_TS" ]] && { echo "missing $SERVER_TS (run from repo root)" >&2; exit 2; }
+  [[ ! -f "$ENV_EXAMPLE" ]] && { echo "missing $ENV_EXAMPLE" >&2; exit 2; }
+
+  # Pre-check: flag name not already registered.
+  if grep -qE "[\"']${NAME}[\"']" "$SERVER_TS"; then
+    echo "'$NAME' already appears in $SERVER_TS" >&2; exit 1
+  fi
+  if grep -qE "^${ENV_VAR}=" "$ENV_EXAMPLE"; then
+    echo "$ENV_VAR already in $ENV_EXAMPLE" >&2; exit 1
+  fi
+fi
+
+TOKEN=$(doppler secrets get FLAGSMITH_MANAGEMENT_API_KEY -p soleur -c cli_ops --plain 2>/dev/null || true)
+[[ -z "$TOKEN" ]] && { echo "FLAGSMITH_MANAGEMENT_API_KEY not in Doppler soleur/cli_ops" >&2; exit 2; }
+
+# Token-shape guard: a newline in the key would inject a curl config directive on the stdin
+# channel below. Never echoes the value.
+_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+_bearer_ok "$TOKEN" || { echo "FLAGSMITH_MANAGEMENT_API_KEY has an unexpected shape" >&2; exit 2; }
+
+# The Flagsmith management key travels on curl's stdin config channel, never on argv.
+fs_api() {
+  curl --disable --noproxy '*' -sS -H "Content-Type: application/json" "$@" --config - \
+    < <(printf 'header = "Authorization: Api-Key %s"\n' "$TOKEN")
+}
+
+# Pre-check: not already a feature in Flagsmith.
+EXISTING=$(fs_api "${FLAGSMITH_API}/projects/${FLAGSMITH_PROJECT_ID}/features/?q=${NAME}" \
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(','.join(f['name'] for f in d.get('results', []) if f['name'] == '$NAME'))")
+if [[ -n "$EXISTING" ]]; then
+  echo "feature '$NAME' already exists in Flagsmith — use flag-set-role to toggle" >&2; exit 1
+fi
+
+PRD_DOPPLER_VAL=$([[ $PRD_ON -eq 1 ]] && echo 1 || echo 0)
+
+# --- propose ---------------------------------------------------------------
+echo "→ Proposed mutations:"
+echo "  1. Flagsmith: create feature '$NAME' (default_enabled=false)"
+[[ $DEV_ON -eq 1 ]] && echo "     + segment override role-dev=ON in BOTH envs"
+[[ $PRD_ON -eq 1 ]] && echo "     + segment override role-prd=ON in BOTH envs"
+if [[ $FLAGSMITH_ONLY -eq 1 ]]; then
+  echo "  (--flagsmith-only: skipping server.ts / $ENV_EXAMPLE / Doppler — flag is already code-wired)"
+else
+  echo "  2. $SERVER_TS: add \"$NAME\": \"$ENV_VAR\" to RUNTIME_FLAGS"
+  echo "  3. $ENV_EXAMPLE: add $ENV_VAR=$PRD_DOPPLER_VAL"
+  echo "  4. Doppler: $ENV_VAR=$PRD_DOPPLER_VAL in soleur/dev AND soleur/prd"
+fi
+
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo "(dry-run — exiting 0)"
+  exit 0
+fi
+
+soleur_op_ack_or_die "Create flag '${NAME}' in Flagsmith and wire it into the code and Doppler (dev + prd) now? Type yes: "
+
+# --- audit append (WORM) ---------------------------------------------------
+ACTOR=$(doppler secrets get OPERATOR_EMAIL -p soleur -c cli_ops --plain 2>/dev/null | tr '[:upper:]' '[:lower:]')
+[[ -z "$ACTOR" ]] && { echo "FATAL: OPERATOR_EMAIL not in Doppler soleur/cli_ops" >&2; exit 4; }
+
+# `|| true` normalizes a Doppler auth/network failure to the exit-4 contract (the
+# [[ -z ]] guard) instead of letting `set -e` abort at the assignment with exit 1.
+AUDIT_URL=$(doppler secrets get SUPABASE_URL -p soleur -c dev --plain 2>/dev/null) || true
+AUDIT_SRK=$(doppler secrets get SUPABASE_SERVICE_ROLE_KEY -p soleur -c dev --plain 2>/dev/null) || true
+[[ -z "$AUDIT_URL" || -z "$AUDIT_SRK" ]] && { echo "FATAL: SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY not in Doppler soleur/dev" >&2; exit 4; }
+
+AUDIT_ID=$(audit_flag_flip_rpc "$AUDIT_URL" "$AUDIT_SRK" "$NAME" "dev" "global" "create" null null "$ACTOR") || exit 4
+echo "  audit_id=$AUDIT_ID"
+
+# --- create feature --------------------------------------------------------
+echo "→ Creating Flagsmith feature '$NAME'…"
+RESP=$(fs_api -X POST "${FLAGSMITH_API}/projects/${FLAGSMITH_PROJECT_ID}/features/" \
+  -d "$(python3 -c "
+import json, sys
+print(json.dumps({
+    'name': '$NAME',
+    'description': '''$DESCRIPTION''' or None,
+    'default_enabled': False,
+    'project': $FLAGSMITH_PROJECT_ID,
+}))
+")")
+FEATURE_ID=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("id",""))')
+[[ -z "$FEATURE_ID" ]] && { echo "Flagsmith feature create failed: $RESP" >&2; exit 3; }
+echo "  feature_id=$FEATURE_ID"
+
+# --- segment overrides (if requested) --------------------------------------
+apply_override() {
+  local env_id="$1" segment_id="$2"
+  local body
+  body=$(printf '{"feature_states_to_create":[{"feature_segment":{"segment":%d},"enabled":true,"feature_state_value":{"type":"unicode","string_value":null,"integer_value":null,"boolean_value":null}}],"feature_states_to_update":[],"segment_ids_to_delete_overrides":[],"publish_immediately":true}' "$segment_id")
+  fs_api -X POST "${FLAGSMITH_API}/environments/${env_id}/features/${FEATURE_ID}/versions/" -d "$body" >/dev/null
+}
+
+resolve_segment() {
+  fs_api "${FLAGSMITH_API}/projects/${FLAGSMITH_PROJECT_ID}/segments/" \
+    | python3 -c "import json,sys; d=json.load(sys.stdin); [print(s['id']) for s in d.get('results', []) if s['name']=='$1']"
+}
+
+if [[ $DEV_ON -eq 1 ]]; then
+  SEG=$(resolve_segment "role-dev")
+  echo "→ Applying role-dev=ON in dev env…"; apply_override "$FLAGSMITH_ENV_DEV_ID" "$SEG"
+  echo "→ Applying role-dev=ON in prd env…"; apply_override "$FLAGSMITH_ENV_PRD_ID" "$SEG"
+fi
+if [[ $PRD_ON -eq 1 ]]; then
+  SEG=$(resolve_segment "role-prd")
+  echo "→ Applying role-prd=ON in dev env…"; apply_override "$FLAGSMITH_ENV_DEV_ID" "$SEG"
+  echo "→ Applying role-prd=ON in prd env…"; apply_override "$FLAGSMITH_ENV_PRD_ID" "$SEG"
+fi
+
+# --- code-wiring + Doppler mirror (skipped under --flagsmith-only) ----------
+if [[ $FLAGSMITH_ONLY -eq 1 ]]; then
+  echo
+  echo "✓ Done (--flagsmith-only). Flagsmith feature '$NAME' created; server.ts /"
+  echo "  $ENV_EXAMPLE / Doppler left untouched (flag is already code-wired)."
+  echo "  Next: scope it per-org with soleur:flag-set-role $NAME prd on --org <orgId>."
+  exit 0
+fi
+
+# --- edit server.ts ---------------------------------------------------------
+echo "→ Editing $SERVER_TS…"
+python3 <<PY || exit 4
+import re, sys
+p = "$SERVER_TS"
+with open(p) as f: src = f.read()
+new_line = '  "$NAME": "$ENV_VAR",\n'
+m = re.search(r'(const RUNTIME_FLAGS = \{)([^}]*)(\}[ \t]*as const;)', src, re.DOTALL)
+if not m:
+    print('RUNTIME_FLAGS block not found in', p, file=sys.stderr); sys.exit(1)
+body = m.group(2).rstrip()
+if not body.endswith(','): body += ','
+body += '\n' + new_line
+src = src[:m.start(2)] + body + src[m.end(2):]
+with open(p, 'w') as f: f.write(src)
+print('  added entry to RUNTIME_FLAGS')
+PY
+
+# --- edit .env.example -----------------------------------------------------
+echo "→ Editing $ENV_EXAMPLE…"
+python3 <<PY || exit 4
+p = "$ENV_EXAMPLE"
+with open(p) as f: lines = f.readlines()
+# Insert after the existing FLAG_KB_CHAT_SIDEBAR line.
+out = []
+inserted = False
+for line in lines:
+    out.append(line)
+    if not inserted and line.startswith('FLAG_KB_CHAT_SIDEBAR='):
+        out.append('$ENV_VAR=$PRD_DOPPLER_VAL\n')
+        inserted = True
+if not inserted:
+    out.append('$ENV_VAR=$PRD_DOPPLER_VAL\n')
+with open(p, 'w') as f: f.writelines(out)
+print('  added $ENV_VAR=$PRD_DOPPLER_VAL')
+PY
+
+# --- mirror Doppler --------------------------------------------------------
+echo "→ Doppler dev: $ENV_VAR=$PRD_DOPPLER_VAL…"
+printf '%s' "$PRD_DOPPLER_VAL" | doppler secrets set "$ENV_VAR" -p soleur -c dev --silent || exit 5
+echo "→ Doppler prd: $ENV_VAR=$PRD_DOPPLER_VAL…"
+printf '%s' "$PRD_DOPPLER_VAL" | doppler secrets set "$ENV_VAR" -p soleur -c prd --silent || exit 5
+
+echo
+echo "✓ Done. Next: review the diff in $SERVER_TS + $ENV_EXAMPLE, then commit:"
+echo "    git add $SERVER_TS $ENV_EXAMPLE && git commit -m 'feat(flags): add $NAME runtime flag'"
+exit 0