@forhuman/flowmcp 0.1.0

package/cases/flowmcp.md

@@ -0,0 +1,79 @@
+# case: flowmcp
+
+**Target:** `flowmcp` itself (own repo, not a wrapped third party
+in the sense the rest of this file means it — see "contract origin" below).
+**Terrain:** mixed — a defined local contract (profiles, secrets, client
+config entries) plus a discovered remote one (Webflow's hosted MCP server
+OAuth surface).
+**Distribution:** npm (`@forhuman/flowmcp`), bash + Node/`npx`
+runtime, `bin` aliases `flowmcp` and `fmcp`. Chosen because the
+audience is JS-ecosystem developers/agencies already running Node for
+`npx mcp-remote` / `npx webflow-mcp-server` anyway — a compiled binary would
+have added packaging cost with no reachability gain for this audience.
+
+## Contract origin
+
+Mixed, not stated out loud at the time (should have been — this case entry
+is that admission). `lib/profiles.sh`/`lib/secrets.sh`/`lib/clients.sh` are
+defined: we own the shape of a profile and a client config entry. The OAuth
+surface against `mcp.webflow.com` was discovered: verified live (DCR
+registration + full PKCE exchange) rather than assumed from Webflow's classic
+Data API docs, which describe a different, client-secret-only flow.
+
+## What broke
+
+A test-org name collision overwrote a real client's entry in the user's real
+Claude Desktop config during manual testing of `rename` — recovered from the
+tool's own automatic `.bak`, no data lost. Full account in `friction.md`,
+folded in below.
+
+## Blocks adopted / rejected
+
+- **Adopted:** OS keychain via `security`/`secret-tool`, with a `chmod 600`
+  file fallback only when no keychain backend exists.
+- **Adopted, then replaced:** a hand-rolled PKCE + refresh + local-callback
+  OAuth flow, built and verified working, then thrown away for `mcp-remote`
+  (github.com/punkpeye/mcp-remote) once it was clear that package already
+  solves exactly this and is what the MCP ecosystem uses. What we kept
+  owning: per-org isolation via `MCP_REMOTE_CONFIG_DIR`.
+- **Rejected:** a manual OAuth-App-setup step (client_id/secret the user
+  creates by hand before `connect` works) — assumed necessary, disproven by
+  reading `mcp.webflow.com`'s own `.well-known/oauth-authorization-server`.
+
+## Agent-first checklist, applied to this build
+
+- `--json` + automatic JSON on non-TTY stdout: done, across every command
+  (read and write).
+- No prompt blocks a non-interactive run: `secret-set`/`rotate` refuse
+  outright without a real TTY rather than hanging.
+- `schema` command with a version field: added (`commands/schema.sh`,
+  `schema_version: 1`).
+- Exit codes: 0 success, 1 for both user error and failed check — not yet
+  split further; revisit if a caller needs to distinguish "org not found"
+  from "network unreachable" programmatically rather than reading `.error`.
+- Data on stdout, diagnostics on stderr: yes — `wfw_say_err/warn/hint` all
+  write to stderr, JSON payloads always to stdout.
+- Secrets never echo, never accept as an argument: enforced at the CLI
+  surface (`secret-set`/`rotate` read via `read -s`, no org's token is ever
+  interpolated into a printed string).
+- Trust ladder: sized to the actual damage. `install`/`remove`/`rename`
+  mutate real, shared, global client config files (Claude Code/Desktop/
+  Cursor) — that is the one place in this CLI where a wrong call has a real
+  blast radius (see "what broke" above), so those three now have `--dry-run`
+  and `remove` requires `--yes` with no interactive fallback. `add`/`connect`/
+  `list`/`inspect`/`test`/`debug` earn no gate: worst case is a wasted API
+  call or a duplicate profile you can `remove`.
+- Audit log: append-only, `~/.flowmcp/audit/<YYYY-MM>.jsonl`,
+  written after the action completes (not two-phase pending/final) since
+  none of the mutating commands here are async or long-running enough for a
+  killed-mid-flight state to matter the way it would for a payment API.
+- `nextSteps`: added to `inspect`/`test`/`debug`/`install`/`remove`/`rename`
+  JSON output as `next_steps: [string]`.
+
+## What I'd do differently
+
+Open `friction.md` on day one instead of reconstructing it after the fact.
+The rename/real-org collision is exactly the kind of finding the skill says
+gets rediscovered when nobody writes it down at the time — this build
+rediscovered a version of it we'd already have known to avoid if a prior
+case existed.

package/commands/add.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Usage: flowmcp add <org> [--label "Display Name"]
+# Registers profile metadata only, no token handling here. The suggested
+# next step is `flowmcp connect <org>` (browser OAuth, no token to copy);
+# `flowmcp secret-set <org>` is the fallback for headless environments with
+# no browser available.
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+org="${1:?Usage: flowmcp add <org> [--label \"Display Name\"]}"
+shift || true
+label="$org"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --label) label="$2"; shift 2 ;;
+    *) echo "error: unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+
+wfw_valid_org "$org" || {
+  wfw_say_err "$(wfw_t msg_invalid_org "$org")"
+  exit 1
+}
+
+if wfw_profile_exists "$org"; then
+  wfw_say_err "$(wfw_t msg_org_exists "$org")"
+  exit 1
+fi
+
+wfw_profile_write_new "$org" "$label"
+wfw_audit_log "add" "$org" "ok"
+
+backend="$(wfw_secret_backend)"
+wfw_say_ok "$(wfw_t msg_add_ok "$org" "$label" "$backend")"
+echo
+wfw_say_next "$(wfw_t msg_add_recommend "$org")"
+echo
+echo "    flowmcp connect $org"
+echo
+echo "$(wfw_t msg_add_no_browser)"
+echo
+echo "    flowmcp secret-set $org"
+echo
+echo "${WFW_C_DIM}$(wfw_t msg_add_explain1)"
+echo "$(wfw_t msg_add_explain2 "$backend")"
+echo "$(wfw_t msg_add_explain3)${WFW_C_RESET}"

package/commands/connect.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Usage: flowmcp connect <org> [--label "Name"]
+#
+# Human-friendly alternative to add + secret-set: opens a browser, the
+# client logs into their own Webflow account and approves access, and the
+# session is captured automatically — no copy/paste of a token by anyone,
+# ever, and no setup step required beforehand.
+#
+# Under the hood this runs `npx mcp-remote` against Webflow's own hosted
+# MCP server (mcp.webflow.com), which handles the full OAuth dance itself
+# (dynamic client registration, PKCE, browser open, token refresh) — we
+# just give each org an isolated storage directory so sessions never mix.
+# Must be run interactively (it opens a real browser and waits for you).
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+wfw_require_npx
+
+org="${1:?Usage: flowmcp connect <org> [--label \"Name\"]}"
+shift || true
+label="$org"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --label) label="$2"; shift 2 ;;
+    *) echo "error: unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+
+wfw_valid_org "$org" || {
+  wfw_say_err "$(wfw_t msg_invalid_org "$org")"
+  exit 1
+}
+
+if wfw_profile_exists "$org"; then
+  echo "${WFW_C_DIM}$(wfw_t msg_reconnecting "$org")${WFW_C_RESET}"
+else
+  wfw_profile_write_new "$org" "$label" "mcp-remote"
+fi
+
+remote_dir="$(wfw_mcp_remote_dir "$org")"
+mkdir -p "$remote_dir"
+
+wfw_t msg_connect_opening "$org"
+wfw_t msg_connect_ctrlc1
+wfw_t msg_connect_ctrlc2
+echo
+
+trap '' INT   # let mcp-remote (child) react to Ctrl+C; don't let it kill this script too
+MCP_REMOTE_CONFIG_DIR="$remote_dir" npx -y mcp-remote "$WFW_MCP_URL" --resource "$WFW_MCP_URL" || true
+trap - INT
+
+if wfw_mcp_remote_connected "$org"; then
+  wfw_profile_set_auth_method "$org" "mcp-remote"
+  wfw_audit_log "connect" "$org" "ok"
+  wfw_say_ok "$(wfw_t msg_connect_success "$org")"
+  wfw_say_next "$(wfw_t msg_connect_next "$org" "$org")"
+else
+  wfw_audit_log "connect" "$org" "fail" "no completed session found"
+  wfw_say_err "$(wfw_t msg_connect_fail "$org")"
+  wfw_say_hint "$(wfw_t msg_connect_fail_hint "$org")"
+  exit 1
+fi

package/commands/debug.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Usage: flowmcp debug <org> [--json]
+# Runs a battery of non-secret-leaking diagnostics and prints a summary.
+# JSON automatically when stdout isn't a real TTY (e.g. an agent's tool call).
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+org="${1:?Usage: flowmcp debug <org> [--json]}"
+shift || true
+json_flag=""
+[[ "${1:-}" == "--json" ]] && json_flag="1"
+
+WFW_CHECKS=()
+
+# wfw_check <name> <ok|fail|warn|note> <detail>
+wfw_check() {
+  local name="$1" level="$2" detail="$3"
+  WFW_CHECKS+=("$(jq -nc --arg n "$name" --arg l "$level" --arg d "$detail" '{name:$n, level:$l, detail:$d}')")
+  if ! wfw_json_mode "$json_flag"; then
+    case "$level" in
+      ok)   echo "ok: $detail" ;;
+      fail) echo "$(wfw_t dbg_level_fail): $detail" ;;
+      warn) echo "$(wfw_t dbg_level_warn): $detail" ;;
+      *)    echo "$(wfw_t dbg_level_note): $detail" ;;
+    esac
+  fi
+}
+
+wfw_section() {
+  wfw_json_mode "$json_flag" || echo "-- $1 --"
+}
+
+wfw_json_mode "$json_flag" || wfw_t dbg_header "$org"
+
+wfw_section "$(wfw_t dbg_sec_profile)"
+if wfw_profile_exists "$org"; then
+  wfw_check "profile" "ok" "profile exists at $(wfw_profile_path "$org")"
+else
+  wfw_check "profile" "fail" "no profile registered. Run: flowmcp add $org"
+  if wfw_json_mode "$json_flag"; then
+    jq -nc --arg org "$org" --argjson checks "$(printf '%s\n' "${WFW_CHECKS[@]}" | jq -sc '.')" \
+      '{org: $org, checks: $checks, next_steps: ["flowmcp add \($org)"]}'
+  fi
+  exit 1
+fi
+
+auth_method="$(jq -r '.auth_method // "pat"' <<<"$(wfw_profile_read "$org")")"
+wfw_section "$(wfw_t dbg_sec_auth "$auth_method")"
+
+if [[ "$auth_method" == "mcp-remote" ]]; then
+  if wfw_mcp_remote_connected "$org"; then
+    wfw_check "session" "ok" "a saved mcp-remote session exists for '$org'"
+  else
+    wfw_check "session" "fail" "no saved session. Run: flowmcp connect $org"
+  fi
+  wfw_section "$(wfw_t dbg_sec_mcpremote_avail)"
+  if command -v npx >/dev/null 2>&1; then
+    if ver="$(npm view mcp-remote version 2>/dev/null)"; then
+      wfw_check "mcp-remote" "ok" "reachable on npm (latest: $ver)"
+    else
+      wfw_check "mcp-remote" "warn" "could not reach npm registry to check mcp-remote (offline?)"
+    fi
+  else
+    wfw_check "mcp-remote" "fail" "npx not found — install Node.js"
+  fi
+else
+  backend="$(wfw_secret_backend)"
+  wfw_section "$(wfw_t dbg_sec_secret_backend "$backend")"
+  if wfw_secret_exists "$org"; then
+    wfw_check "secret" "ok" "a token is stored for '$org'"
+  else
+    wfw_check "secret" "fail" "no token stored. Run: flowmcp secret-set $org"
+  fi
+  wfw_section "$(wfw_t dbg_sec_wfmcp_avail)"
+  if command -v npx >/dev/null 2>&1; then
+    if ver="$(npm view webflow-mcp-server version 2>/dev/null)"; then
+      wfw_check "webflow-mcp-server" "ok" "reachable on npm (latest: $ver)"
+    else
+      wfw_check "webflow-mcp-server" "warn" "could not reach npm registry to check webflow-mcp-server (offline?)"
+    fi
+  else
+    wfw_check "webflow-mcp-server" "fail" "npx not found — install Node.js"
+  fi
+fi
+
+wfw_section "$(wfw_t dbg_sec_cred_check)"
+test_json="$("$WFW_COMMANDS_DIR/test.sh" "$org" --json 2>/dev/null || true)"
+test_status="$(jq -r '.status // "fail"' <<<"$test_json" 2>/dev/null || echo fail)"
+wfw_check "credentials" "$([[ "$test_status" == "ok" ]] && echo ok || echo fail)" "$(jq -r '.error // "valid"' <<<"$test_json" 2>/dev/null || echo "check failed")"
+if ! wfw_json_mode "$json_flag"; then
+  "$WFW_COMMANDS_DIR/test.sh" "$org" || true
+fi
+
+wfw_section "$(wfw_t dbg_sec_client_configs)"
+for spec in "claude-code:user" "claude-code:project" "claude-desktop:user" "cursor:user" "cursor:project"; do
+  client="${spec%%:*}"; scope="${spec#*:}"
+  path="$(wfw_client_config_path "$client" "$scope" 2>/dev/null || true)"
+  [[ -z "$path" ]] && continue
+  name="config:$spec"
+  if [[ -f "$path" ]]; then
+    if jq empty "$path" >/dev/null 2>&1; then
+      has_entry="$(jq -r --arg n "webflow-$org" '.mcpServers[$n] // empty' "$path")"
+      if [[ -n "$has_entry" ]]; then
+        wfw_check "$name" "ok" "$path has 'webflow-$org' entry"
+      else
+        wfw_check "$name" "note" "$path exists, valid JSON, no 'webflow-$org' entry"
+      fi
+    else
+      wfw_check "$name" "fail" "$path exists but is not valid JSON"
+    fi
+  else
+    wfw_check "$name" "note" "$path does not exist"
+  fi
+done
+
+if wfw_json_mode "$json_flag"; then
+  jq -nc --arg org "$org" --argjson checks "$(printf '%s\n' "${WFW_CHECKS[@]}" | jq -sc '.')" \
+    '{org: $org, checks: $checks,
+      next_steps: [$checks[] | select(.level == "fail") | .detail | select(startswith("Run: ") or test("flowmcp")) ] }'
+else
+  wfw_t dbg_done
+fi

package/commands/inspect.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Usage: flowmcp inspect <org> [--live] [--json]
+# Prints full profile metadata (no token). Add --live to also re-run test.
+# JSON automatically when stdout isn't a real TTY (e.g. an agent's tool call).
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+org="${1:?Usage: flowmcp inspect <org> [--live] [--json]}"
+shift || true
+live="" json_flag=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --live) live="1"; shift ;;
+    --json) json_flag="1"; shift ;;
+    *) echo "error: unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+
+wfw_profile_exists "$org" || {
+  echo "error: no org '$org' registered" >&2
+  exit 1
+}
+
+if [[ -n "$live" ]]; then
+  "$WFW_COMMANDS_DIR/test.sh" "$org" >/dev/null 2>&1 || true
+fi
+
+auth_method="$(jq -r '.auth_method // "pat"' <<<"$(wfw_profile_read "$org")")"
+if [[ "$auth_method" == "mcp-remote" ]]; then
+  wfw_mcp_remote_connected "$org" && connected="true" || connected="false"
+else
+  wfw_secret_exists "$org" && connected="true" || connected="false"
+fi
+
+if wfw_json_mode "$json_flag"; then
+  if [[ "$connected" == "false" ]]; then
+    if [[ "$auth_method" == "mcp-remote" ]]; then
+      next="[\"flowmcp connect $org\"]"
+    else
+      next="[\"flowmcp secret-set $org\"]"
+    fi
+  else
+    next="[\"flowmcp test $org\"]"
+  fi
+  jq --argjson connected "$connected" --argjson next "$next" \
+    '. + {connected: $connected, next_steps: $next}' "$(wfw_profile_path "$org")"
+  exit 0
+fi
+
+jq . "$(wfw_profile_path "$org")"
+echo
+if [[ "$connected" == "false" ]]; then
+  if [[ "$auth_method" == "mcp-remote" ]]; then
+    wfw_t msg_inspect_no_session "$org" "$org"
+  else
+    wfw_t msg_inspect_no_token "$org" "$org"
+  fi
+fi

package/commands/install.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Usage: flowmcp install <org> <client> [--scope user|project] [--force] [--dry-run] [--json]
+# client: claude-code | claude-desktop | cursor
+#
+# Writes an mcpServers entry that points at run-mcp.sh, so the token itself
+# never has to be written into the client's config file.
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+org="${1:?Usage: flowmcp install <org> <client> [--scope user|project] [--force] [--dry-run]}"
+client="${2:?Usage: flowmcp install <org> <client> [--scope user|project] [--force] [--dry-run]}"
+shift 2
+scope="user"
+force=""
+dry_run=""
+json_flag=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --scope) scope="$2"; shift 2 ;;
+    --force) force="--force"; shift ;;
+    --dry-run) dry_run="1"; shift ;;
+    --json) json_flag="1"; shift ;;
+    *) echo "error: unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+
+wfw_profile_exists "$org" || {
+  wfw_say_err "$(wfw_t msg_install_no_org "$org" "$org" "$org")"
+  exit 1
+}
+
+config_path="$(wfw_client_config_path "$client" "$scope")" || exit 1
+auth_method="$(jq -r '.auth_method // "pat"' <<<"$(wfw_profile_read "$org")")"
+server_name="webflow-$org"
+
+server_json="$(wfw_build_server_json "$org" "$auth_method")"
+if [[ "$auth_method" == "mcp-remote" ]]; then
+  note="$(wfw_t msg_install_note_mcpremote)"
+else
+  note="$(wfw_t msg_install_note_pat)"
+fi
+
+if [[ -n "$dry_run" ]]; then
+  if wfw_json_mode "$json_flag"; then
+    jq -nc --arg org "$org" --arg client "$client" --arg scope "$scope" --arg path "$config_path" \
+      --arg name "$server_name" --argjson entry "$server_json" \
+      '{ok: true, dry_run: true, org: $org, client: $client, scope: $scope, path: $path,
+        server_name: $name, entry: $entry, next_steps: ["flowmcp install \($org) \($client) --scope \($scope)"]}'
+  else
+    echo "${WFW_C_DIM}dry-run — would merge into $config_path:${WFW_C_RESET}"
+    jq -n --arg name "$server_name" --argjson entry "$server_json" '{mcpServers: {($name): $entry}}'
+  fi
+  exit 0
+fi
+
+wfw_client_merge_server "$config_path" "$server_name" "$server_json" "$force"
+wfw_audit_log "install" "$org" "ok" "client=$client scope=$scope path=$config_path auth=$auth_method"
+
+if wfw_json_mode "$json_flag"; then
+  jq -nc --arg org "$org" --arg client "$client" --arg scope "$scope" --arg path "$config_path" \
+    --arg name "$server_name" \
+    '{ok: true, dry_run: false, org: $org, client: $client, scope: $scope, path: $path, server_name: $name,
+      next_steps: ["restart \($client) to pick up the new server", "flowmcp test \($org)"]}'
+else
+  wfw_say_ok "$(wfw_t msg_install_ok "$server_name" "$config_path")"
+  echo "${WFW_C_DIM}($note — $(wfw_t msg_install_restart "$client"))${WFW_C_RESET}"
+fi

package/commands/lang.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Usage: flowmcp lang [en|es] [--json]
+# With no argument, prints the current language. With en/es, sets it —
+# this is how a human changes the choice made at first run (or an agent
+# sets it on their behalf; unlike secret-set/rotate, no token is involved
+# here, so there's no reason to gate this behind a TTY).
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+json_flag=""
+new_lang=""
+for arg in "$@"; do
+  case "$arg" in
+    --json) json_flag="1" ;;
+    en|es)  new_lang="$arg" ;;
+    *)
+      echo "error: unknown language '$arg' (supported: en, es)" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -n "$new_lang" ]]; then
+  echo "$new_lang" > "$WFW_LANG_FILE"
+  if wfw_json_mode "$json_flag"; then
+    jq -nc --arg lang "$new_lang" '{ok: true, lang: $lang}'
+  else
+    wfw_say_ok "$(wfw_t msg_lang_set "$new_lang")"
+  fi
+  exit 0
+fi
+
+current="$(wfw_lang)"
+if wfw_json_mode "$json_flag"; then
+  jq -nc --arg lang "$current" '{lang: $lang}'
+else
+  echo "$current"
+fi

package/commands/list.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Usage: flowmcp list [--json]
+# Lists registered orgs and their last test status. Never prints tokens.
+# JSON automatically when stdout isn't a real TTY (e.g. an agent's tool call).
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+json_flag=""
+[[ "${1:-}" == "--json" ]] && json_flag="1"
+
+orgs=($(wfw_profile_list))
+
+if wfw_json_mode "$json_flag"; then
+  if [[ ${#orgs[@]} -eq 0 ]]; then
+    echo "[]"
+    exit 0
+  fi
+  jq -sc '.' <(for org in "${orgs[@]}"; do wfw_profile_read "$org"; done)
+  exit 0
+fi
+
+if [[ ${#orgs[@]} -eq 0 ]]; then
+  wfw_t msg_no_orgs
+  exit 0
+fi
+
+printf "${WFW_C_DIM}%-20s %-24s %-16s %-10s %s${WFW_C_RESET}\n" "ORG" "LABEL" "BACKEND" "LAST TEST" "TESTED AT"
+for org in "${orgs[@]}"; do
+  p="$(wfw_profile_read "$org")"
+  label="$(jq -r '.label' <<<"$p")"
+  backend="$(jq -r '.secret_backend' <<<"$p")"
+  status="$(jq -r '.last_test.status // "never"' <<<"$p")"
+  ts="$(jq -r '.last_test.timestamp // "-"' <<<"$p")"
+  printf "%-20s %-24s %-16s %s %s\n" "$org" "$label" "$backend" "$(wfw_status_color_padded "$status" 10)" "$ts"
+done

package/commands/remove.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Usage: flowmcp remove <org> --yes [--from client:scope ...] [--dry-run] [--json]
+# Destructive: deletes the profile and the stored secret. Requires --yes.
+# Optionally also strips the entry from named client configs, e.g.:
+#   flowmcp remove acme --yes --from claude-code:user --from cursor:project
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../lib/bootstrap.sh"
+
+org="${1:?Usage: flowmcp remove <org> --yes [--from client:scope]... [--dry-run]}"
+shift || true
+confirmed=""
+dry_run=""
+json_flag=""
+froms=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --yes) confirmed="1"; shift ;;
+    --from) froms+=("$2"); shift 2 ;;
+    --dry-run) dry_run="1"; shift ;;
+    --json) json_flag="1"; shift ;;
+    *) echo "error: unknown option '$1'" >&2; exit 1 ;;
+  esac
+done
+
+wfw_profile_exists "$org" || {
+  wfw_say_err "$(wfw_t msg_org_not_found "$org")"
+  exit 1
+}
+
+if [[ -n "$dry_run" ]]; then
+  targets=()
+  for spec in "${froms[@]:-}"; do
+    [[ -z "$spec" ]] && continue
+    client="${spec%%:*}"; scope="${spec#*:}"
+    config_path="$(wfw_client_config_path "$client" "$scope" 2>/dev/null || true)"
+    [[ -n "$config_path" && -f "$config_path" ]] && targets+=("$config_path")
+  done
+  if wfw_json_mode "$json_flag"; then
+    jq -nc --arg org "$org" --argjson targets "$(printf '%s\n' "${targets[@]:-}" | jq -R . | jq -sc 'map(select(length>0))')" \
+      '{ok: true, dry_run: true, org: $org, would_delete: ["profile", "stored credentials"], would_strip_from: $targets}'
+  else
+    echo "${WFW_C_DIM}dry-run — would delete profile + stored credentials for '$org'${WFW_C_RESET}"
+    for t in "${targets[@]:-}"; do echo "${WFW_C_DIM}would strip 'webflow-$org' from $t${WFW_C_RESET}"; done
+  fi
+  exit 0
+fi
+
+if [[ -z "$confirmed" ]]; then
+  if wfw_json_mode "$json_flag"; then
+    jq -nc --arg org "$org" '{ok: false, error: "confirmation required", next_steps: ["flowmcp remove \($org) --yes"]}'
+  else
+    wfw_say_err "$(wfw_t msg_remove_confirm_needed "$org")"
+    wfw_say_hint "$(wfw_t msg_remove_confirm_hint)"
+    echo "${WFW_C_DIM}exit 1 · refused by a gate · nothing was deleted${WFW_C_RESET}" >&2
+  fi
+  exit 1
+fi
+
+removed_from=()
+for spec in "${froms[@]:-}"; do
+  [[ -z "$spec" ]] && continue
+  client="${spec%%:*}"
+  scope="${spec#*:}"
+  config_path="$(wfw_client_config_path "$client" "$scope" 2>/dev/null || true)"
+  if [[ -n "$config_path" && -f "$config_path" ]]; then
+    wfw_client_remove_server "$config_path" "webflow-$org"
+    removed_from+=("$config_path")
+    wfw_json_mode "$json_flag" || wfw_say_ok "$(wfw_t msg_remove_stripped "$org" "$config_path")"
+  fi
+done
+
+wfw_secret_delete "$org"
+rm -rf "$(wfw_mcp_remote_dir "$org")"
+wfw_profile_delete "$org"
+wfw_audit_log "remove" "$org" "ok"
+
+if wfw_json_mode "$json_flag"; then
+  jq -nc --arg org "$org" --argjson removed "$(printf '%s\n' "${removed_from[@]:-}" | jq -R . | jq -sc 'map(select(length>0))')" \
+    '{ok: true, dry_run: false, org: $org, removed_from: $removed}'
+else
+  wfw_say_ok "$(wfw_t msg_remove_ok "$org")"
+fi