From 6d4bcc971e1ef3e29fd913e81346df8a2d6661cb Mon Sep 17 00:00:00 2001
From: Hrithik-Gavankar <hgavanka@redhat.com>
Date: Wed, 9 Sep 2026 01:21:55 +0530
Subject: [PATCH 1/2] fix(team-brain): sanity before workshop

---
 .gitignore                                    |  10 +-
 README.md                                     |  22 +-
 core/scripts/team-brain-admin-setup.sh        | 164 +++++++++++++
 core/scripts/team-brain-api.sh                |   8 +-
 core/scripts/team-brain-bootstrap.sh          |  58 ++++-
 core/scripts/team-brain-member-setup.sh       | 229 ++++++++++++++++++
 core/scripts/team-brain-realtime.py           |   2 +-
 core/scripts/team-brain-secret-utils.sh       |  45 ++++
 core/team/JIRA_ATTACH.md                      |   2 +-
 core/team/TEAM_COMMANDS.md                    |  44 ++--
 core/team/team.yaml.example                   |   4 +-
 docs/engineer-brain-onboarding.md             |   2 +-
 docs/faq.md                                   |   4 +-
 docs/scopes.md                                |   2 +-
 docs/team-brain-demo.md                       |  28 +--
 docs/team-brain-memory.md                     |  16 +-
 docs/team-brain-onboarding.md                 |  84 +++----
 docs/team-brain-tutorial.md                   |   4 +-
 docs/team-brain.md                            |  24 +-
 mcp/team-brain/README.md                      |  10 +-
 mcp/team-brain/server.py                      |   2 +-
 platforms/cursor/README.md                    |  10 +-
 platforms/cursor/rules/team-brain.mdc         |  10 +-
 .../skills/engineer-brain/ONBOARDING.md       |   2 +-
 platforms/cursor/skills/team-brain/SKILL.md   |  12 +-
 supabase/README.md                            |  18 +-
 website/docs/platforms/cursor.md              |  12 +-
 website/docs/quick-start.md                   |   6 +-
 28 files changed, 663 insertions(+), 171 deletions(-)
 create mode 100755 core/scripts/team-brain-admin-setup.sh
 create mode 100755 core/scripts/team-brain-member-setup.sh
 create mode 100644 core/scripts/team-brain-secret-utils.sh

diff --git a/.gitignore b/.gitignore
index ff08a1d..8d4bdc0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,9 +23,17 @@ website/.docusaurus/
 # Team Brain secrets (per-workspace only — do not blanket-ignore all of .team-brain/)
 .team-brain/credentials.json
 .team-brain/**/credentials.json
+.team-brain/team.yaml
+.team-brain/**/team.yaml
+.team-brain/share-bundle.txt
+.team-brain/**/share-bundle.txt
+.team-brain/cache/
+.team-brain/**/cache/
+.team-brain/sync/
+.team-brain/**/sync/
 !.team-brain/**/.gitkeep
 # Commit-safe pin (.team-brain/project.json) SHOULD be committed — never put anon/api_key/invite there.
-# team.yaml often holds URL+anon for local use — prefer env / project.public.env; do not commit anon.
+# team.yaml holds URL+anon locally — gitignored above; prefer supabase/project.public.env.
 supabase/project.public.env
 
 # Bootstrap-generated combined SQL (may be large; never commit crew secrets beside it)
diff --git a/README.md b/README.md
index c58f876..5c850d6 100644
--- a/README.md
+++ b/README.md
@@ -160,7 +160,7 @@ Shared AI memory for crews working on the same Jira initiative. When one enginee
 
 ```mermaid
 flowchart LR
-    subgraph Crew["Crew on AAP-81423"]
+    subgraph Crew["Crew on YOU_JIRA_TICKET_HERE"]
         A1[Alice's Agent]
         A2[Bob's Agent]
         A3[Carol's Agent]
@@ -172,7 +172,7 @@ flowchart LR
     end
 
     subgraph Local["Each Engineer"]
-        CACHE["cache/AAP-81423.json"]
+        CACHE["cache/YOU_JIRA_TICKET_HERE.json"]
         MCP[MCP Tools]
     end
 
@@ -199,10 +199,10 @@ flowchart LR
 ### How It Works
 
 1. **Admin creates team** — `register "Team Atlas" "Alice"` → Supabase project + invite code
-2. **Teammates join** — `onboard <invite> "Bob" AAP-81423` → credentials + Jira key
-3. **Start sync mode** — "I'm starting on AAP-81423 — start Team Brain sync"
+2. **Teammates join** — `onboard <invite> "Bob" YOU_JIRA_TICKET_HERE` → credentials + Jira key
+3. **Start sync mode** — "I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync"
 4. **Agents collaborate** — `remember` findings → peers get realtime push → `recall` when needed
-5. **Generate artifacts** — `breakdown AAP-81423` → story/spike draft from crew memory
+5. **Generate artifacts** — `breakdown YOU_JIRA_TICKET_HERE` → story/spike draft from crew memory
 
 ```
 Alice researches auth options → remember "prefer OAuth2 over SAML for SSO"
@@ -411,10 +411,10 @@ bash install.sh continue-dev ~/my-workspace
 "team-brain register …"                → admin creates team once
 
 # Sync mode (Cursor chat — one line to start crew work):
-"I'm starting on AAP-81423 — start Team Brain sync."
-"Wake Team Brain sync for AAP-81423 and continue."
-"Stop Team Brain sync for AAP-81423."
-"Breakdown AAP-81423 from Team Brain memory."
+"I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync."
+"Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue."
+"Stop Team Brain sync for YOU_JIRA_TICKET_HERE."
+"Breakdown YOU_JIRA_TICKET_HERE from Team Brain memory."
 ```
 
 
@@ -424,9 +424,9 @@ bash install.sh continue-dev ~/my-workspace
 bash install.sh cursor ~/my-workspace
 # Personal: /engineer-brain sync
 # Admin once: bash core/scripts/team-brain-api.sh register "Team Atlas" "You"
-# Teammate:   bash core/scripts/team-brain-api.sh onboard <INVITE> "Name" AAP-81423
+# Teammate:   bash core/scripts/team-brain-api.sh onboard <INVITE> "Name" YOU_JIRA_TICKET_HERE
 # (Admin: own Supabase project → fill local project.public.env; joiners get URL+anon+invite)
-# Then in Cursor: I'm starting on AAP-81423 — start Team Brain sync.
+# Then in Cursor: I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ---
diff --git a/core/scripts/team-brain-admin-setup.sh b/core/scripts/team-brain-admin-setup.sh
new file mode 100755
index 0000000..c9b5d65
--- /dev/null
+++ b/core/scripts/team-brain-admin-setup.sh
@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# Team Brain — one-shot ADMIN setup
+#
+# Creates the crew (register → admin role). Colleagues use team-brain-member-setup.sh.
+#
+# DEMO DEFAULTS (Brainstack Day 0 workshop only — change for your crew):
+#   Epic: KAN-4 · Crew: Workshop Crew
+#   Override: --jira YOUR-EPIC --team "Your Crew" --jira-site https://your-org.atlassian.net
+#   Or env: TEAM_BRAIN_DEMO_JIRA_KEY, TEAM_BRAIN_DEMO_TEAM_NAME, TEAM_BRAIN_DEMO_JIRA_SITE
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+BOOTSTRAP="$SCRIPT_DIR/team-brain-bootstrap.sh"
+API="$SCRIPT_DIR/team-brain-api.sh"
+
+# shellcheck source=team-brain-secret-utils.sh
+source "$SCRIPT_DIR/team-brain-secret-utils.sh"
+
+# --- demo defaults (override for production crews) ---
+DEFAULT_JIRA_KEY="${TEAM_BRAIN_DEMO_JIRA_KEY:-KAN-4}"
+DEFAULT_JIRA_TITLE="${TEAM_BRAIN_DEMO_JIRA_TITLE:-Brainstack context layer — workshop spike}"
+DEFAULT_JIRA_SITE="${TEAM_BRAIN_DEMO_JIRA_SITE:-https://brainstack-org.atlassian.net}"
+DEFAULT_TEAM_NAME="${TEAM_BRAIN_DEMO_TEAM_NAME:-Workshop Crew}"
+
+ADMIN_NAME="${TEAM_BRAIN_ADMIN_NAME:-}"
+TEAM_NAME="$DEFAULT_TEAM_NAME"
+JIRA_KEY="$DEFAULT_JIRA_KEY"
+JIRA_TITLE="$DEFAULT_JIRA_TITLE"
+JIRA_SITE="$DEFAULT_JIRA_SITE"
+SKIP_START=0
+DRY_RUN=0
+BOOTSTRAP_ARGS=()
+
+die() { echo "error: $*" >&2; exit 1; }
+info() { echo "→ $*" >&2; }
+ok() { echo "✓ $*" >&2; }
+warn() { echo "⚠ $*" >&2; }
+
+print_demo_notice() {
+  cat >&2 <<EOF
+
+──────────────────────────────────────────────────────────────────
+ Demo defaults (workshop): epic ${JIRA_KEY} · crew "${TEAM_NAME}"
+ For your own crew, pass --jira YOUR-EPIC --team "Your Crew"
+ (and --jira-site if not brainstack-org). See docs/workshop-brainstack-day0.md
+──────────────────────────────────────────────────────────────────
+
+EOF
+}
+
+usage() {
+  cat <<EOF
+Team Brain — one-shot ADMIN setup
+
+  bash core/scripts/team-brain-admin-setup.sh --admin "Your Name" [options]
+
+Required:
+  --admin, -a "Name"        Admin display name (creates crew + admin role)
+
+Demo defaults (override for your epic):
+  --jira KEY                Default: $DEFAULT_JIRA_KEY (demo only)
+  --team NAME               Default: $DEFAULT_TEAM_NAME (demo only)
+  --jira-site URL           Default: $DEFAULT_JIRA_SITE
+
+Bootstrap options (passed through):
+  --url URL  --anon KEY  --db-url URL  --local  --skip-migrations  --dry-run
+
+Colleagues then run:
+  bash core/scripts/team-brain-member-setup.sh --invite <CODE> --name "Bob" --role member
+
+See: docs/workshop-brainstack-day0.md
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --admin|-a) ADMIN_NAME="${2:-}"; shift 2 ;;
+    --team) TEAM_NAME="${2:-}"; shift 2 ;;
+    --jira) JIRA_KEY="${2:-}"; shift 2 ;;
+    --jira-site) JIRA_SITE="${2:-}"; shift 2 ;;
+    --jira-title) JIRA_TITLE="${2:-}"; shift 2 ;;
+    --skip-start) SKIP_START=1; shift ;;
+    --dry-run) DRY_RUN=1; BOOTSTRAP_ARGS+=(--dry-run); shift ;;
+    --help|-h) usage; exit 0 ;;
+    --url|--anon|--db-url)
+      [ $# -ge 2 ] || die "$1 requires a value"
+      BOOTSTRAP_ARGS+=("$1" "$2"); shift 2 ;;
+    --local|--skip-migrations)
+      BOOTSTRAP_ARGS+=("$1"); shift ;;
+    *)
+      die "unknown option: $1 (colleagues use team-brain-member-setup.sh)"
+      ;;
+  esac
+done
+
+[ -n "$ADMIN_NAME" ] || die "--admin \"Your Name\" is required (see --help)"
+[ -f "$BOOTSTRAP" ] || die "bootstrap script not found: $BOOTSTRAP"
+
+JIRA_KEY=$(echo "$JIRA_KEY" | tr '[:lower:]' '[:upper:]')
+print_demo_notice
+
+cd "$REPO_ROOT"
+export TEAM_BRAIN_DIR="${TEAM_BRAIN_DIR:-$REPO_ROOT/.team-brain}"
+
+bash "$BOOTSTRAP" \
+  --team "$TEAM_NAME" \
+  --admin "$ADMIN_NAME" \
+  --jira "$JIRA_KEY" \
+  --jira-title "$JIRA_TITLE" \
+  --jira-site "$JIRA_SITE" \
+  --write-env \
+  "${BOOTSTRAP_ARGS[@]}"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  info "Dry run — would run pin set, doctor, start $JIRA_KEY"
+  exit 0
+fi
+
+info "Setting commit-safe pin"
+bash "$API" pin set --jira "$JIRA_KEY" --team-name "$TEAM_NAME" | jq '{pinned, default_jira_key, team_name, path}' 2>/dev/null \
+  || bash "$API" pin set --jira "$JIRA_KEY" --team-name "$TEAM_NAME"
+
+info "Doctor check"
+bash "$API" doctor || warn "doctor reported issues — fix migrations before going live"
+
+if [ "$SKIP_START" -eq 0 ]; then
+  info "Starting sync mode ($JIRA_KEY)"
+  bash "$API" start "$JIRA_KEY"
+  bash "$API" sync-status "$JIRA_KEY" | jq '{jira_key, mode}' 2>/dev/null \
+    || bash "$API" sync-status "$JIRA_KEY"
+fi
+
+invite=""
+invite=$(bash "$API" whoami 2>/dev/null | jq -r '.invite_code // empty' || true)
+
+invite_mask=""
+if [ -n "$invite" ]; then
+  invite_mask=$(tb_mask_secret "$invite")
+fi
+bundle_path=$(tb_share_bundle_path)
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo " Admin setup complete"
+echo "═══════════════════════════════════════════════════════════════"
+echo " Role:     admin"
+echo " Epic:     $JIRA_KEY — $JIRA_TITLE"
+if [ -n "$invite" ]; then
+  echo " Invite:   $invite_mask"
+  echo " Full invite + anon: $bundle_path (gitignored — share via DM only)"
+else
+  echo " Invite:   (run: bash core/scripts/team-brain-api.sh whoami)"
+  echo " Full bundle: $bundle_path (if bootstrap wrote it)"
+fi
+echo ""
+echo " Colleague (member) — use invite from $bundle_path or credentials.json:"
+echo "   bash core/scripts/team-brain-member-setup.sh --invite <INVITE> --name \"Bob\" --role member"
+echo ""
+echo " Do NOT paste invite/anon into git, PRs, or public Slack."
+echo " (Demo used KAN-4 / Workshop Crew — pass --jira / --team for your epic.)"
+echo "═══════════════════════════════════════════════════════════════"
+tb_print_no_paste_warning
diff --git a/core/scripts/team-brain-api.sh b/core/scripts/team-brain-api.sh
index 92c5517..ca921b3 100755
--- a/core/scripts/team-brain-api.sh
+++ b/core/scripts/team-brain-api.sh
@@ -40,6 +40,9 @@ CRED_FILE="${TEAM_BRAIN_CREDENTIALS:-$TEAM_DIR/credentials.json}"
 CONFIG_YAML="${TEAM_BRAIN_CONFIG:-$TEAM_DIR/team.yaml}"
 PIN_FILE="${TEAM_BRAIN_PIN:-$TEAM_DIR/project.json}"
 
+# shellcheck source=team-brain-secret-utils.sh
+source "$SCRIPT_DIR/team-brain-secret-utils.sh"
+
 die() { echo "error: $*" >&2; exit 1; }
 
 # Commit-safe pin (#39). Never put anon / api_key / invite here.
@@ -439,7 +442,10 @@ save_credentials() {
   chmod 600 "$CRED_FILE" 2>/dev/null || true
   echo "Wrote credentials → $CRED_FILE" >&2
   if jq -e '.role == "admin" and (.invite_code // null) != null and .invite_code != ""' >/dev/null 2>&1 <<<"$json"; then
-    echo "Invite code (share with teammates; keep private from the public internet): $(jq -r .invite_code <<<"$json")" >&2
+    local invite_raw invite_mask
+    invite_raw=$(jq -r .invite_code <<<"$json")
+    invite_mask=$(tb_mask_secret "$invite_raw")
+    echo "Invite code (full value in $CRED_FILE and .team-brain/share-bundle.txt — share via DM only): $invite_mask" >&2
   fi
   echo "API key saved (keep private)." >&2
 }
diff --git a/core/scripts/team-brain-bootstrap.sh b/core/scripts/team-brain-bootstrap.sh
index 92783b6..40638f4 100755
--- a/core/scripts/team-brain-bootstrap.sh
+++ b/core/scripts/team-brain-bootstrap.sh
@@ -17,6 +17,9 @@ PUBLIC_ENV="${TEAM_BRAIN_PUBLIC_ENV:-$REPO_ROOT/supabase/project.public.env}"
 MIGRATIONS_DIR="$REPO_ROOT/supabase/migrations"
 SUPABASE_DIR="$REPO_ROOT/supabase"
 
+# shellcheck source=team-brain-secret-utils.sh
+source "$SCRIPT_DIR/team-brain-secret-utils.sh"
+
 die() { echo "error: $*" >&2; exit 1; }
 info() { echo "→ $*" >&2; }
 ok() { echo "✓ $*" >&2; }
@@ -60,7 +63,7 @@ Migration strategy (first match wins):
 
 Examples:
   # Hosted project you already filled in project.public.env + linked CLI:
-  bash core/scripts/team-brain-bootstrap.sh --team "Spike Crew" --admin "Alice" --jira AAP-81423
+  bash core/scripts/team-brain-bootstrap.sh --team "Spike Crew" --admin "Alice" --jira YOU_JIRA_TICKET_HERE
 
   # Pass URL/anon + DB URL for migrations:
   bash core/scripts/team-brain-bootstrap.sh --team "Spike Crew" --admin "Alice" \\
@@ -314,6 +317,39 @@ print_share_bundle() {
   local anon="$4"
   local jira="$5"
   local site="${6:-https://your-org.atlassian.net}"
+  local jira_key="${jira:-JIRA-KEY}"
+  local invite_mask anon_mask bundle_path full_bundle
+
+  invite_mask=$(tb_mask_secret "$invite")
+  anon_mask=$(tb_mask_secret "$anon")
+  export TEAM_BRAIN_DIR="${TEAM_BRAIN_DIR:-$REPO_ROOT/.team-brain}"
+
+  full_bundle=$(cat <<EOF
+Team Brain — share bundle (admin → crew) — FULL SECRETS — gitignored local file
+Generated: $(date -u +"%Y-%m-%dT%H:%M:%SZ") UTC
+
+Team:     ${team}
+Invite:   ${invite}
+URL:      ${url}
+Anon:     ${anon}
+Jira key: ${jira:-"(give teammates the ticket key)"}
+Jira:     ${site}
+
+Joiner (one shot):
+  bash core/scripts/team-brain-member-setup.sh \\
+    --invite ${invite} \\
+    --name "Their Name" \\
+    --url "${url}" \\
+    --anon "${anon}" \\
+    --role member
+
+Or set supabase/project.public.env (gitignored) with URL + anon, then:
+  bash core/scripts/team-brain-member-setup.sh --invite ${invite} --name "Their Name" --role member
+
+Do NOT commit this file or paste into public chat / PRs.
+EOF
+)
+  bundle_path=$(tb_write_share_bundle_file "$full_bundle")
 
   cat <<EOF
 
@@ -322,24 +358,25 @@ print_share_bundle() {
 ╚══════════════════════════════════════════════════════════════════╝
 
 Team:     ${team}
-Invite:   ${invite}
+Invite:   ${invite_mask}
 URL:      ${url}
-Anon:     ${anon}
+Anon:     ${anon_mask}
 Jira key: ${jira:-"(give teammates the ticket key)"}
 Jira:     ${site}
 
+Full invite + anon (for DM to joiners only):
+  → ${bundle_path}
+
 Joiner checklist (no Supabase account needed):
   1. Clone brainstack (or use installed skills)
-  2. Put URL + anon in local supabase/project.public.env (or .team-brain/team.yaml / env)
-  3. Admin assigns role (member = contributor, viewer = read-only), then run:
-       bash core/scripts/team-brain-api.sh onboard ${invite} "Their Name" ${jira:-JIRA-KEY} --role member
-     # or: ... --role viewer
-  4. Start sync:
-       bash core/scripts/team-brain-api.sh start ${jira:-JIRA-KEY}
+  2. Admin sends joiner the file above (or URL + anon + invite via DM — never public Slack/PR)
+  3. Joiner runs:
+       bash core/scripts/team-brain-member-setup.sh --invite <INVITE> --name "Their Name" --role member
+     (Use values from ${bundle_path})
 
 Admin after bootstrap:
   bash core/scripts/team-brain-api.sh list-members
-  bash core/scripts/team-brain-api.sh pending list ${jira:-JIRA-KEY}   # review queued overrides (#67)
+  bash core/scripts/team-brain-api.sh pending list ${jira_key}   # review queued overrides (#67)
   bash core/scripts/team-brain-api.sh doctor
 
 Do NOT commit live URL/anon/invite to a public fork.
@@ -347,6 +384,7 @@ Do NOT share service_role or member api_key in chat logs that get committed.
 
 Admin credentials saved under .team-brain/credentials.json (gitignored).
 EOF
+  tb_print_no_paste_warning
 }
 
 # ----- main -----
diff --git a/core/scripts/team-brain-member-setup.sh b/core/scripts/team-brain-member-setup.sh
new file mode 100755
index 0000000..2884d94
--- /dev/null
+++ b/core/scripts/team-brain-member-setup.sh
@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# Team Brain — one-shot MEMBER setup
+#
+# Colleagues with an admin invite → member or viewer only.
+# Admin runs team-brain-admin-setup.sh first — NOT this script.
+#
+# DEMO DEFAULTS (Brainstack Day 0 workshop only — change for your crew):
+#   Epic: KAN-4 · Crew: Workshop Crew
+#   Override: --jira YOUR-EPIC
+#   Or env: TEAM_BRAIN_DEMO_JIRA_KEY, TEAM_BRAIN_DEMO_JIRA_SITE
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+API="$SCRIPT_DIR/team-brain-api.sh"
+PUBLIC_ENV="${TEAM_BRAIN_PUBLIC_ENV:-$REPO_ROOT/supabase/project.public.env}"
+PUBLIC_ENV_EXAMPLE="$REPO_ROOT/supabase/project.public.env.example"
+
+# --- demo defaults (override for production crews) ---
+DEFAULT_JIRA_KEY="${TEAM_BRAIN_DEMO_JIRA_KEY:-KAN-4}"
+DEFAULT_JIRA_TITLE="${TEAM_BRAIN_DEMO_JIRA_TITLE:-Brainstack context layer — workshop spike}"
+DEFAULT_JIRA_SITE="${TEAM_BRAIN_DEMO_JIRA_SITE:-https://brainstack-org.atlassian.net}"
+DEFAULT_TEAM_NAME="${TEAM_BRAIN_DEMO_TEAM_NAME:-Workshop Crew}"
+DEFAULT_ROLE="member"
+
+INVITE="${TEAM_BRAIN_INVITE:-}"
+DISPLAY_NAME="${TEAM_BRAIN_DISPLAY_NAME:-}"
+SUPABASE_URL="${TEAM_BRAIN_SUPABASE_URL:-}"
+ANON_KEY="${TEAM_BRAIN_SUPABASE_ANON_KEY:-}"
+JIRA_KEY="$DEFAULT_JIRA_KEY"
+JIRA_TITLE="$DEFAULT_JIRA_TITLE"
+JIRA_SITE="$DEFAULT_JIRA_SITE"
+ROLE="$DEFAULT_ROLE"
+INTERACTIVE=1
+SKIP_START=0
+DRY_RUN=0
+
+STEP=0
+TOTAL_STEPS=7
+
+die() { echo "error: $*" >&2; exit 1; }
+info() { echo "→ $*" >&2; }
+ok() { echo "✓ $*" >&2; }
+step() {
+  STEP=$((STEP + 1))
+  echo "" >&2
+  echo "[$STEP/$TOTAL_STEPS] $*" >&2
+}
+
+print_demo_notice() {
+  cat >&2 <<EOF
+
+──────────────────────────────────────────────────────────────────
+ Demo defaults (workshop): epic ${JIRA_KEY} · crew "${DEFAULT_TEAM_NAME}"
+ For your own crew, pass --jira YOUR-EPIC (must match admin's epic).
+ See docs/workshop-brainstack-day0.md
+──────────────────────────────────────────────────────────────────
+
+EOF
+}
+
+usage() {
+  cat <<EOF
+Team Brain — one-shot MEMBER setup (not admin)
+
+  bash core/scripts/team-brain-member-setup.sh [options]
+
+Options:
+  --invite, -i CODE       Invite from admin (required)
+  --name, -n "Your Name"  Display name (unique on crew)
+  --role ROLE             member (default) or viewer
+  --url URL  --anon KEY   Supabase (or use project.public.env)
+  --jira KEY              Default: $DEFAULT_JIRA_KEY (demo — use your epic)
+  --non-interactive  --skip-start  --dry-run  -h
+
+Admin? team-brain-admin-setup.sh first.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --invite|-i) INVITE="${2:-}"; shift 2 ;;
+    --name|-n) DISPLAY_NAME="${2:-}"; shift 2 ;;
+    --role) ROLE="${2:-}"; shift 2 ;;
+    --url) SUPABASE_URL="${2:-}"; shift 2 ;;
+    --anon) ANON_KEY="${2:-}"; shift 2 ;;
+    --jira) JIRA_KEY="${2:-}"; shift 2 ;;
+    --non-interactive) INTERACTIVE=0; shift ;;
+    --skip-start) SKIP_START=1; shift ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown option: $1 (try --help)" ;;
+  esac
+done
+
+JIRA_KEY=$(echo "$JIRA_KEY" | tr '[:lower:]' '[:upper:]')
+ROLE=$(echo "$ROLE" | tr '[:upper:]' '[:lower:]')
+print_demo_notice
+
+prompt() {
+  local var_name="$1" prompt_text="$2" default="${3:-}" value=""
+  [ "$INTERACTIVE" -eq 1 ] || return 1
+  if [ -n "$default" ]; then
+    read -r -p "$prompt_text [$default]: " value || true
+    value="${value:-$default}"
+  else
+    read -r -p "$prompt_text: " value || true
+  fi
+  printf -v "$var_name" '%s' "$value"
+}
+
+is_placeholder() {
+  case "${1:-}" in ""|*YOUR_PROJECT*|*your-project*|*example.supabase*) return 0 ;; esac
+  case "${2:-}" in ""|your-anon-key|YOUR_ANON*|replace-me*|changeme*) return 0 ;; esac
+  return 1
+}
+
+write_public_env() {
+  mkdir -p "$(dirname "$PUBLIC_ENV")"
+  cat >"$PUBLIC_ENV" <<EOF
+# Generated by team-brain-member-setup.sh — gitignored; do not commit live keys.
+TEAM_BRAIN_SUPABASE_URL=$1
+TEAM_BRAIN_SUPABASE_ANON_KEY=$2
+TEAM_BRAIN_JIRA_SITE=$JIRA_SITE
+EOF
+  chmod 600 "$PUBLIC_ENV" 2>/dev/null || true
+  ok "Wrote $PUBLIC_ENV"
+}
+
+load_public_env_file() {
+  [ -f "$PUBLIC_ENV" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      TEAM_BRAIN_SUPABASE_URL=*) [ -n "$SUPABASE_URL" ] || SUPABASE_URL="${line#TEAM_BRAIN_SUPABASE_URL=}" ;;
+      TEAM_BRAIN_SUPABASE_ANON_KEY=*) [ -n "$ANON_KEY" ] || ANON_KEY="${line#TEAM_BRAIN_SUPABASE_ANON_KEY=}" ;;
+    esac
+  done <"$PUBLIC_ENV"
+}
+
+write_demo_pin() {
+  local path="$1"
+  mkdir -p "$(dirname "$path")"
+  jq -n \
+    --arg team "$DEFAULT_TEAM_NAME" \
+    --arg key "$JIRA_KEY" \
+    --arg notes "Demo pin from member-setup. Replace default_jira_key with YOUR epic for non-demo crews." \
+    '{version:1, team_name:$team, default_jira_key:$key, jira_keys:[$key], supabase_project_ref:null, notes:$notes}' \
+    >"$path"
+}
+
+step "Checking dependencies"
+need_cmd() { command -v "$1" >/dev/null 2>&1 || die "missing dependency: $1"; }
+need_cmd curl
+need_cmd jq
+[ -f "$API" ] || die "team-brain-api.sh not found at $API"
+ok "curl, jq, team-brain-api.sh"
+
+step "Validating Supabase config"
+cd "$REPO_ROOT"
+export TEAM_BRAIN_DIR="${TEAM_BRAIN_DIR:-$REPO_ROOT/.team-brain}"
+load_public_env_file
+
+if is_placeholder "$SUPABASE_URL" "$ANON_KEY" && [ "$INTERACTIVE" -eq 1 ]; then
+  info "Ask admin for URL + anon from the share bundle."
+  [ ! -f "$PUBLIC_ENV" ] && [ -f "$PUBLIC_ENV_EXAMPLE" ] && cp "$PUBLIC_ENV_EXAMPLE" "$PUBLIC_ENV"
+  prompt SUPABASE_URL "Supabase project URL" ""
+  prompt ANON_KEY "Supabase anon key" ""
+fi
+
+is_placeholder "$SUPABASE_URL" "$ANON_KEY" && \
+  die "Supabase URL/anon missing. Set $PUBLIC_ENV or pass --url / --anon."
+
+if [ "$DRY_RUN" -eq 0 ]; then write_public_env "$SUPABASE_URL" "$ANON_KEY"
+else info "Dry run — would write $PUBLIC_ENV"; fi
+export TEAM_BRAIN_SUPABASE_URL="$SUPABASE_URL"
+export TEAM_BRAIN_SUPABASE_ANON_KEY="$ANON_KEY"
+export TEAM_BRAIN_JIRA_SITE="$JIRA_SITE"
+export TEAM_BRAIN_PUBLIC_ENV="$PUBLIC_ENV"
+ok "Supabase configured"
+
+step "Installing crew pin ($JIRA_KEY)"
+PIN_PATH="$TEAM_BRAIN_DIR/project.json"
+if [ "$DRY_RUN" -eq 1 ]; then
+  info "Dry run — would write pin at $PIN_PATH"
+elif [ ! -f "$PIN_PATH" ]; then
+  write_demo_pin "$PIN_PATH"
+  ok "Wrote demo pin ($JIRA_KEY)"
+else
+  ok "Pin exists: $PIN_PATH"
+fi
+
+step "Collecting join credentials"
+[ -n "$INVITE" ] || prompt INVITE "Invite code from admin" "" || die "missing --invite"
+[ -n "$DISPLAY_NAME" ] || prompt DISPLAY_NAME "Your display name" "" || die "missing --name"
+
+case "$ROLE" in
+  member|viewer) ;;
+  admin) die "use team-brain-admin-setup.sh for admin" ;;
+  *) die "role must be member or viewer" ;;
+esac
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  echo "Dry run: onboard → verify → start $JIRA_KEY"
+  exit 0
+fi
+
+step "Joining crew (onboard)"
+bash "$API" onboard "$INVITE" "$DISPLAY_NAME" "$JIRA_KEY" --role "$ROLE"
+ok "Onboard complete"
+
+step "Verifying connection"
+bash "$API" whoami | jq '{display_name, role, team_name}'
+bash "$API" pin show | jq '{default_jira_key: (.default_jira_key // .jira_key), team_name}' 2>/dev/null || true
+bash "$API" status >/dev/null
+ok "Verified"
+
+if [ "$SKIP_START" -eq 0 ]; then
+  step "Starting sync ($JIRA_KEY)"
+  bash "$API" start "$JIRA_KEY"
+  bash "$API" sync-status "$JIRA_KEY" | jq '{jira_key, mode}' 2>/dev/null || bash "$API" sync-status "$JIRA_KEY"
+fi
+
+echo ""
+echo "═══════════════════════════════════════════════════════════════"
+echo " Member setup complete · epic $JIRA_KEY"
+echo " Cursor: I'm starting on $JIRA_KEY — start Team Brain sync, summarize crew memory, then help me."
+echo " (Demo defaults — pass --jira YOUR-EPIC for your own initiative.)"
+echo "═══════════════════════════════════════════════════════════════"
diff --git a/core/scripts/team-brain-realtime.py b/core/scripts/team-brain-realtime.py
index a2cc739..30d4de7 100755
--- a/core/scripts/team-brain-realtime.py
+++ b/core/scripts/team-brain-realtime.py
@@ -358,7 +358,7 @@ def next_ref() -> str:
 
 def main() -> None:
     parser = argparse.ArgumentParser(description="Team Brain Realtime Broadcast listener")
-    parser.add_argument("jira_key", help="Jira key (e.g. AAP-81423)")
+    parser.add_argument("jira_key", help="Jira key (e.g. YOU_JIRA_TICKET_HERE)")
     parser.add_argument(
         "--topic",
         default="",
diff --git a/core/scripts/team-brain-secret-utils.sh b/core/scripts/team-brain-secret-utils.sh
new file mode 100644
index 0000000..369b23d
--- /dev/null
+++ b/core/scripts/team-brain-secret-utils.sh
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Shared helpers — mask secrets in terminal output; write full share bundle locally only.
+# Source from team-brain-bootstrap.sh / team-brain-admin-setup.sh / team-brain-api.sh
+
+tb_mask_secret() {
+  local s="${1:-}"
+  local n=${#s}
+  if [ -z "$s" ]; then
+    echo "(empty)"
+    return 0
+  fi
+  if [ "$n" -le 8 ]; then
+    echo "(redacted, ${n} chars)"
+    return 0
+  fi
+  printf '%s…%s (%s chars)\n' "${s:0:4}" "${s:n-4:4}" "$n"
+}
+
+tb_share_bundle_path() {
+  local team_dir="${TEAM_BRAIN_DIR:-${TB_SHARE_BUNDLE_DIR:-}}"
+  if [ -z "$team_dir" ]; then
+    team_dir="$(pwd)/.team-brain"
+  fi
+  printf '%s/share-bundle.txt' "$team_dir"
+}
+
+tb_write_share_bundle_file() {
+  local path content
+  path=$(tb_share_bundle_path)
+  content="$1"
+  mkdir -p "$(dirname "$path")"
+  printf '%s\n' "$content" >"$path"
+  chmod 600 "$path" 2>/dev/null || true
+  echo "$path"
+}
+
+tb_print_no_paste_warning() {
+  cat <<'EOF'
+
+⚠  SECRETS — DO NOT paste this terminal output into git commits, PRs, Slack threads,
+   or screen recordings. Full values are in .team-brain/share-bundle.txt (gitignored, chmod 600).
+   Share URL + anon + invite with joiners via DM only.
+
+EOF
+}
diff --git a/core/team/JIRA_ATTACH.md b/core/team/JIRA_ATTACH.md
index 2b94f00..7ea2d5f 100644
--- a/core/team/JIRA_ATTACH.md
+++ b/core/team/JIRA_ATTACH.md
@@ -5,7 +5,7 @@ Used by the `team-brain` skill when running `/team-brain attach <JIRA-KEY>`.
 ## Steps for the agent
 
 1. **Resolve Jira** (preferred: Atlassian MCP `getJiraIssue` with cloudId + key):
-   - `key` (e.g. `AAP-81423`)
+   - `key` (e.g. `YOU_JIRA_TICKET_HERE`)
    - `fields.summary`
    - `fields.status.name`
    - Browse URL: `{jira.site}/browse/{key}` from `.team-brain/team.yaml`
diff --git a/core/team/TEAM_COMMANDS.md b/core/team/TEAM_COMMANDS.md
index a1bebfc..a4863d5 100644
--- a/core/team/TEAM_COMMANDS.md
+++ b/core/team/TEAM_COMMANDS.md
@@ -14,11 +14,11 @@ Onboarding: [docs/team-brain-onboarding.md](../../docs/team-brain-onboarding.md)
 ├── credentials.json       # api_key — gitignored, never commit
 ├── TEAM.md                # one per team
 ├── cache/
-│   └── AAP-81423.json     # agent SoT (written on start/sync/remember)
+│   └── YOU_JIRA_TICKET_HERE.json     # agent SoT (written on start/sync/remember)
 ├── sync/
-│   └── AAP-81423.json     # sync mode session (active | sleep | stopped)
+│   └── YOU_JIRA_TICKET_HERE.json     # sync mode session (active | sleep | stopped)
 └── initiatives/
-    └── AAP-81423.md       # optional human/git export
+    └── YOU_JIRA_TICKET_HERE.md       # optional human/git export
 ```
 
 ## Sync model
@@ -37,7 +37,7 @@ Jira = initiative **identity**. Memories = Supabase (+ cache).
 **New teammate:**
 
 ```bash
-bash core/scripts/team-brain-api.sh onboard INVITECODE "Bob" AAP-81423 --role member
+bash core/scripts/team-brain-api.sh onboard INVITECODE "Bob" YOU_JIRA_TICKET_HERE --role member
 ```
 
 **Admin (once) — preferred:**
@@ -47,7 +47,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --team "Crew" --admin "Alice" \
   --url "https://….supabase.co" --anon "eyJ…" \
   --db-url "postgresql://postgres:…@db….supabase.co:5432/postgres" \
-  --jira AAP-81423 --write-env
+  --jira YOU_JIRA_TICKET_HERE --write-env
 # prints share bundle (invite + URL + anon + joiner checklist)
 ```
 
@@ -62,39 +62,39 @@ bash core/scripts/team-brain-api.sh register "Crew" "Alice"   # share invite_cod
 In Cursor / any agent chat:
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ```text
-/team-brain start AAP-81423
+/team-brain start YOU_JIRA_TICKET_HERE
 ```
 
 CLI:
 
 ```bash
-bash core/scripts/team-brain-api.sh start AAP-81423
-bash core/scripts/team-brain-api.sh sync-status AAP-81423   # includes compliance
-bash core/scripts/team-brain-api.sh compliance AAP-81423    # soft MCP-first gate
+bash core/scripts/team-brain-api.sh start YOU_JIRA_TICKET_HERE
+bash core/scripts/team-brain-api.sh sync-status YOU_JIRA_TICKET_HERE   # includes compliance
+bash core/scripts/team-brain-api.sh compliance YOU_JIRA_TICKET_HERE    # soft MCP-first gate
 ```
 
 | Chat example | Effect |
 |--------------|--------|
-| `I'm starting on AAP-81423 — start Team Brain sync.` | Enter sync mode + load crew memory |
-| `Wake Team Brain sync for AAP-81423 and continue.` | Resume after idle sleep |
-| `Stop Team Brain sync for AAP-81423.` | Leave sync mode |
-| `Breakdown AAP-81423 from Team Brain memory.` | Draft stories from recall |
+| `I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.` | Enter sync mode + load crew memory |
+| `Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.` | Resume after idle sleep |
+| `Stop Team Brain sync for YOU_JIRA_TICKET_HERE.` | Leave sync mode |
+| `Breakdown YOU_JIRA_TICKET_HERE from Team Brain memory.` | Draft stories from recall |
 
 **Day to day (while sync active):**
 
 ```bash
-bash core/scripts/team-brain-api.sh remember AAP-81423 research --source-ref "AAP-81423#cli" "Finding…"
-bash core/scripts/team-brain-api.sh recall AAP-81423 "decision environment"
-bash core/scripts/team-brain-api.sh touch AAP-81423    # keep awake
-bash core/scripts/team-brain-api.sh stop AAP-81423     # done
-bash core/scripts/team-brain-api.sh wake AAP-81423     # after sleep
+bash core/scripts/team-brain-api.sh remember YOU_JIRA_TICKET_HERE research --source-ref "YOU_JIRA_TICKET_HERE#cli" "Finding…"
+bash core/scripts/team-brain-api.sh recall YOU_JIRA_TICKET_HERE "decision environment"
+bash core/scripts/team-brain-api.sh touch YOU_JIRA_TICKET_HERE    # keep awake
+bash core/scripts/team-brain-api.sh stop YOU_JIRA_TICKET_HERE     # done
+bash core/scripts/team-brain-api.sh wake YOU_JIRA_TICKET_HERE     # after sleep
 
 # Human correction (update same source_ref + optional learning)
-bash core/scripts/team-brain-api.sh correct AAP-81423 --source-ref "AAP-81423#cli" \
+bash core/scripts/team-brain-api.sh correct YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli" \
   --was "Claimed schema was in tox-ansible" \
   --learning "Was wrong: schema in tox-ansible. Prefer: packages/ansible-language-server." \
   "EE schema path lives in packages/ansible-language-server."
@@ -148,8 +148,8 @@ On `source_ref` update, the prior body is **archived** (`archived_revision`); us
 Memory bodies: natural prefer/avoid prose — not TODO/NO-TODO dumps.
 
 ```bash
-bash core/scripts/team-brain-api.sh history AAP-81423 --source-ref "AAP-81423#cli"
-bash core/scripts/team-brain-api.sh restore AAP-81423 --source-ref "AAP-81423#cli" --revision 1
+bash core/scripts/team-brain-api.sh history YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli"
+bash core/scripts/team-brain-api.sh restore YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli" --revision 1
 ```
 
 Apply migrations `…_sync_mode.sql`, `…_learning_kind.sql`, and `…_memory_history.sql` on the Supabase project.
diff --git a/core/team/team.yaml.example b/core/team/team.yaml.example
index 3990c3d..701b174 100644
--- a/core/team/team.yaml.example
+++ b/core/team/team.yaml.example
@@ -19,10 +19,10 @@ repos:
 
 # One markdown file per initiative under initiatives/<id>.md
 initiatives:
-  - id: AAP-81423
+  - id: YOU_JIRA_TICKET_HERE
     title: "Port and improve Ansible Tox integration"
     status: active
-    file: initiatives/AAP-81423.md
+    file: initiatives/YOU_JIRA_TICKET_HERE.md
 
 sync:
   # supabase = multi-engineer memory sync | local = files/git only
diff --git a/docs/engineer-brain-onboarding.md b/docs/engineer-brain-onboarding.md
index d0d6018..a33fb2d 100644
--- a/docs/engineer-brain-onboarding.md
+++ b/docs/engineer-brain-onboarding.md
@@ -75,7 +75,7 @@ The plugin registers MCP namespace `plugin-atlassian-atlassian` and points at At
 
 First-time site install may require a user who has access to the Jira projects you use; after that, other crew members can authorize individually.
 
-> **Example (Red Hat):** `you@redhat.com` on `redhat.atlassian.net`, project keys like `AAP-xxxxx`.
+> **Example (Red Hat):** `you@redhat.com` on `redhat.atlassian.net`, project keys like `YOU_JIRA_TICKET_HERE`.
 
 #### 3.3 Verify
 
diff --git a/docs/faq.md b/docs/faq.md
index f03f8e6..4d4d8f0 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -182,7 +182,7 @@ The **team / initiative scope** of Brain. Crews share collaborative AI memory on
 Use **bootstrap** (configure → migrations → register → share bundle):
 
 ```bash
-bash core/scripts/team-brain-api.sh bootstrap --team "Crew" --admin "Alice" --url … --anon … --db-url … --jira AAP-81423
+bash core/scripts/team-brain-api.sh bootstrap --team "Crew" --admin "Alice" --url … --anon … --db-url … --jira YOU_JIRA_TICKET_HERE
 ```
 
 See [supabase/README.md](../supabase/README.md). Joiners still use `onboard` and do **not** need a Supabase account.
@@ -192,7 +192,7 @@ See [supabase/README.md](../supabase/README.md). Joiners still use `onboard` and
 Ask your admin for an **invite code**, **Jira key**, and the crew’s **Supabase URL + anon key**. Put URL/anon in local `supabase/project.public.env` (or `team.yaml` / env), then:
 
 ```bash
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" AAP-81423
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" YOU_JIRA_TICKET_HERE
 ```
 
 You do **not** need your own Supabase account. Step-by-step: [team-brain-onboarding.md](team-brain-onboarding.md). Admin setup: [supabase/README.md](../supabase/README.md).
diff --git a/docs/scopes.md b/docs/scopes.md
index 8126bda..61dc424 100644
--- a/docs/scopes.md
+++ b/docs/scopes.md
@@ -43,7 +43,7 @@ flowchart TB
 
 1. Admin: `bootstrap --team "Spike Crew" --admin "Alice" …` (or manual migrate + `register`) — see [supabase/README.md](../supabase/README.md)
 2. Admin: share the printed invite + URL + anon bundle
-3. Teammate: put crew URL/anon locally → `onboard <invite> "Name" AAP-81423`
+3. Teammate: put crew URL/anon locally → `onboard <invite> "Name" YOU_JIRA_TICKET_HERE`
 4. Agents/`remember` / `recall` / `breakdown` (or MCP tools)
 5. Optional: wire [mcp/team-brain](../mcp/team-brain/README.md); Cursor installs `team-brain.mdc` always-on rule
 6. `/engineer-brain sync` still personal-only
diff --git a/docs/team-brain-demo.md b/docs/team-brain-demo.md
index 028da8a..395fa60 100644
--- a/docs/team-brain-demo.md
+++ b/docs/team-brain-demo.md
@@ -29,7 +29,7 @@ With Team Brain, knowledge compounds:
 
 ```bash
 # In Cursor chat:
-"I'm starting on AAP-81423 — start Team Brain sync."
+"I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync."
 ```
 
 What happens:
@@ -41,8 +41,8 @@ What happens:
 
 ```bash
 # AI finds something useful:
-bash core/scripts/team-brain-api.sh remember AAP-81423 research \
-  --source-ref "AAP-81423#cli-entrypoint" \
+bash core/scripts/team-brain-api.sh remember YOU_JIRA_TICKET_HERE research \
+  --source-ref "YOU_JIRA_TICKET_HERE#cli-entrypoint" \
   "CLI entrypoint is in pkg/scaffold — start here for EE schema."
 ```
 
@@ -53,7 +53,7 @@ bash core/scripts/team-brain-api.sh remember AAP-81423 research \
 
 ```bash
 # Bob's AI pulls the knowledge:
-bash core/scripts/team-brain-api.sh recall AAP-81423 "scaffold"
+bash core/scripts/team-brain-api.sh recall YOU_JIRA_TICKET_HERE "scaffold"
 ```
 
 Result:
@@ -63,7 +63,7 @@ Result:
   "memories": [{
     "author": "Alice",
     "body": "CLI entrypoint is in pkg/scaffold — start here for EE schema.",
-    "source_ref": "AAP-81423#cli-entrypoint"
+    "source_ref": "YOU_JIRA_TICKET_HERE#cli-entrypoint"
   }]
 }
 ```
@@ -71,7 +71,7 @@ Result:
 ### 4. Breakdown into stories
 
 ```bash
-bash core/scripts/team-brain-api.sh breakdown AAP-81423
+bash core/scripts/team-brain-api.sh breakdown YOU_JIRA_TICKET_HERE
 ```
 
 Generates a draft epic breakdown from shared memory — stories, spikes, implementation hints.
@@ -124,27 +124,27 @@ Generates a draft epic breakdown from shared memory — stories, spikes, impleme
 bash core/scripts/team-brain-api.sh bootstrap \
   --team "Spike Crew" --admin "Alice" \
   --url "https://….supabase.co" --anon "eyJ…" \
-  --db-url "postgresql://…" --jira AAP-81423 --write-env
+  --db-url "postgresql://…" --jira YOU_JIRA_TICKET_HERE --write-env
 ```
 
 **Teammate (admin assigns role):**
 ```bash
 # Contributor (read + write + delete):
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Bob" AAP-81423 --role member
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Bob" YOU_JIRA_TICKET_HERE --role member
 
 # Read-only observer:
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Carol" AAP-81423 --role viewer
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Carol" YOU_JIRA_TICKET_HERE --role viewer
 ```
 
 **Admin audit crew permissions:**
 ```bash
 bash core/scripts/team-brain-api.sh list-members
-bash core/scripts/team-brain-api.sh pending list AAP-81423   # review queued overrides (#67)
+bash core/scripts/team-brain-api.sh pending list YOU_JIRA_TICKET_HERE   # review queued overrides (#67)
 ```
 
 **Work session:**
 ```
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ---
@@ -191,9 +191,9 @@ bash core/scripts/team-brain-api.sh remember DEMO-1 research \
 ### Cursor Chat Demo
 
 ```
-User: I'm starting on AAP-81423 — start Team Brain sync.
+User: I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 
-AI: ✓ Loaded 3 crew memories for AAP-81423.
+AI: ✓ Loaded 3 crew memories for YOU_JIRA_TICKET_HERE.
 
 Summary:
 • CLI entrypoint in pkg/scaffold (Alice)
@@ -235,7 +235,7 @@ Ready to dig in. What would you like to work on?
 
 2. **Why not just share BRAIN.md?**
    - `BRAIN.md` is personal (career, growth).
-   - Team Brain is initiative-scoped (AAP-81423 work only).
+   - Team Brain is initiative-scoped (YOU_JIRA_TICKET_HERE work only).
 
 3. **What about privacy?**
    - Each crew runs their own Supabase project.
diff --git a/docs/team-brain-memory.md b/docs/team-brain-memory.md
index af56dac..19fa62b 100644
--- a/docs/team-brain-memory.md
+++ b/docs/team-brain-memory.md
@@ -48,7 +48,7 @@ Engineer A agent                    Supabase                         Engineer B
 
 | Layer | Role |
 |-------|------|
-| **Jira** | Initiative spine (`AAP-81423`) |
+| **Jira** | Initiative spine (`YOU_JIRA_TICKET_HERE`) |
 | **Supabase** | Source of truth for memories + membership + realtime |
 | **Local cache** | `.team-brain/cache/<KEY>.json` for agents (fast read) |
 | **Markdown export** | Optional human/git mirror — **not** the sync bus |
@@ -141,10 +141,10 @@ bash core/scripts/team-brain-api.sh enable-semantic openai   # or: enable-semant
 export TEAM_BRAIN_EMBED_API_KEY=sk-...                        # openai only — never persisted to team.yaml
 bash core/scripts/team-brain-api.sh enable-semantic openai   # re-run to verify: prints vector dims on success
 
-bash core/scripts/team-brain-api.sh remember AAP-81423 research "EE schema path lives in …"
-bash core/scripts/team-brain-api.sh recall AAP-81423 "where is decision_environment scaffolded"
+bash core/scripts/team-brain-api.sh remember YOU_JIRA_TICKET_HERE research "EE schema path lives in …"
+bash core/scripts/team-brain-api.sh recall YOU_JIRA_TICKET_HERE "where is decision_environment scaffolded"
 # → stderr: "recall mode: vector (openai)"; response body: "mode": "vector"
-bash core/scripts/team-brain-api.sh reembed AAP-81423        # backfill memories written before opt-in
+bash core/scripts/team-brain-api.sh reembed YOU_JIRA_TICKET_HERE        # backfill memories written before opt-in
 ```
 
 Manual/legacy path (still works, e.g. for one-off scripting): export `TEAM_BRAIN_EMBED_PROVIDER` / `_MODEL` / `_BASE_URL` directly — `enable-semantic` is just a documented, persisted shortcut for the same env vars.
@@ -188,9 +188,9 @@ Humans can still run CLI manually; **agents must not skip the loop**.
 - [x] Team aggregation metrics (#35) — coverage + reuse via `metrics --team` / `aggregate` (collab graph deferred)
 
 ```bash
-bash core/scripts/team-brain-api.sh breakdown AAP-81423
-bash core/scripts/team-brain-api.sh metrics AAP-81423
-# → initiatives/AAP-81423-breakdown.md + metrics.json (gitignored)
+bash core/scripts/team-brain-api.sh breakdown YOU_JIRA_TICKET_HERE
+bash core/scripts/team-brain-api.sh metrics YOU_JIRA_TICKET_HERE
+# → initiatives/YOU_JIRA_TICKET_HERE-breakdown.md + metrics.json (gitignored)
 bash core/scripts/team-brain-api.sh metrics --team   # crew coverage + reuse (#35)
 ```
 
@@ -266,7 +266,7 @@ When poisoned or stale team context must be removed (not just corrected), **memb
 
 ```bash
 # Tombstone (member/admin)
-bash core/scripts/team-brain-api.sh delete AAP-81423 --source-ref "AAP-81423#bad-claim"
+bash core/scripts/team-brain-api.sh delete YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#bad-claim"
 
 # Admin audit crew tiers
 bash core/scripts/team-brain-api.sh list-members
diff --git a/docs/team-brain-onboarding.md b/docs/team-brain-onboarding.md
index f6fbd3f..6dfde48 100644
--- a/docs/team-brain-onboarding.md
+++ b/docs/team-brain-onboarding.md
@@ -5,11 +5,13 @@
 **You do not need:** your own Supabase account, a `service_role` key, or Docker.  
 **You do need from your admin:** invite code, Jira key, and the crew’s Supabase **project URL + anon key** (placeholders ship in the repo — not a live project).
 
+> **Workshop demo scripts:** [workshop-brainstack-day0.md](workshop-brainstack-day0.md) uses **`team-brain-admin-setup.sh`** / **`team-brain-member-setup.sh`** with demo epic **`KAN-4`** only. Everything below uses **`YOU_JIRA_TICKET_HERE`** (replace with your ticket key).
+
 ---
 
 ## What is Team Brain? (30 seconds)
 
-You and your teammates work on the **same Jira ticket** (for example `AAP-81423`).
+You and your teammates work on the **same Jira ticket** (for example `YOU_JIRA_TICKET_HERE`).
 
 Without Team Brain, each person’s AI starts cold and re-researches the same things.
 
@@ -46,7 +48,7 @@ Ask a teammate (crew admin) for **secrets** (Slack/chat is fine). The **Jira key
 |---------|---------|--------|
 | **Invite code** | 16 hex chars | From admin’s `register` / `rotate-invite` — never in git |
 | **Supabase URL + anon key** | `https://….supabase.co` + anon JWT | Crew’s project — local env / `project.public.env` only |
-| **Jira key** (if no pin) | `AAP-81423` | Or pull `.team-brain/project.json` from the product repo (#39) |
+| **Jira key** (if no pin) | `YOU_JIRA_TICKET_HERE` | Or pull `.team-brain/project.json` from the product repo (#39) |
 | **Role** (required) | `member` (read+write+delete) or `viewer` (read-only) | Admin tells you which; pass `--role` on onboard |
 
 Also make sure you have:
@@ -70,11 +72,11 @@ Many crews commit **only** `.team-brain/project.json` (Jira key + team name —
 ```bash
 # In the product workspace (example shape):
 cat .team-brain/project.json
-# { "default_jira_key": "AAP-81423", "team_name": "Spike Crew", … }
+# { "default_jira_key": "YOU_JIRA_TICKET_HERE", "team_name": "Spike Crew", … }
 ```
 
 Example fixture: [examples/team-spike-crew/project.json](../examples/team-spike-crew/project.json).  
-Admin creates/updates the pin with: `bash core/scripts/team-brain-api.sh pin set --jira AAP-81423 --team-name "Spike Crew"`.
+Admin creates/updates the pin with: `bash core/scripts/team-brain-api.sh pin set --jira YOU_JIRA_TICKET_HERE --team-name "Spike Crew"`.
 
 ### Step 1 — Open a terminal in the right place
 
@@ -95,7 +97,7 @@ Edit `supabase/project.public.env` (or export env / fill `.team-brain/team.yaml`
 bash core/scripts/team-brain-api.sh onboard INVITE_CODE "Your Name" --role member
 
 # Or explicit Jira + contributor role:
-bash core/scripts/team-brain-api.sh onboard INVITE_CODE "Your Name" AAP-81423 --role member
+bash core/scripts/team-brain-api.sh onboard INVITE_CODE "Your Name" YOU_JIRA_TICKET_HERE --role member
 
 # Read-only viewer:
 bash core/scripts/team-brain-api.sh onboard INVITE_CODE "Your Name" --role viewer
@@ -104,7 +106,7 @@ bash core/scripts/team-brain-api.sh onboard INVITE_CODE "Your Name" --role viewe
 **Real example:**
 
 ```bash
-bash core/scripts/team-brain-api.sh onboard 9F7AC910 "Ada Junior" AAP-81423 --role member
+bash core/scripts/team-brain-api.sh onboard 9F7AC910 "Ada Junior" YOU_JIRA_TICKET_HERE --role member
 ```
 
 Tips:
@@ -145,9 +147,9 @@ Team Brain created a folder next to your work (often the parent workspace), for
 ├── credentials.json    ← YOUR secret — never commit or paste in Slack
 ├── team.yaml           ← often has URL+anon locally — do not commit anon
 ├── cache/
-│   └── AAP-81423.json  ← what agents should read
+│   └── YOU_JIRA_TICKET_HERE.json  ← what agents should read
 └── initiatives/
-    └── AAP-81423.md    ← optional human-readable export
+    └── YOU_JIRA_TICKET_HERE.md    ← optional human-readable export
 ```
 
 **Safety rule:** never commit `credentials.json`. Never share your `api_key`. Sharing the **invite code** with a new teammate is OK.
@@ -161,12 +163,12 @@ Use the **same Jira key** your crew is on.
 ### 1) Start sync (the only manual step before work)
 
 ```bash
-bash core/scripts/team-brain-api.sh start AAP-81423
+bash core/scripts/team-brain-api.sh start YOU_JIRA_TICKET_HERE
 ```
 
 This:
 
-- Loads crew memories into `.team-brain/cache/AAP-81423.json`
+- Loads crew memories into `.team-brain/cache/YOU_JIRA_TICKET_HERE.json`
 - Starts **background sync** (merge-safe pull)
 - Stays awake while you/`touch`/`remember`/`recall` stay active
 - **Sleeps after 1 hour** of no local activity (warning ~5 min before)
@@ -174,13 +176,13 @@ This:
 Check:
 
 ```bash
-bash core/scripts/team-brain-api.sh sync-status AAP-81423
+bash core/scripts/team-brain-api.sh sync-status YOU_JIRA_TICKET_HERE
 ```
 
 Optional topic search anytime:
 
 ```bash
-bash core/scripts/team-brain-api.sh recall AAP-81423 "scaffold"
+bash core/scripts/team-brain-api.sh recall YOU_JIRA_TICKET_HERE "scaffold"
 ```
 
 ### 2) Save something useful you learned
@@ -188,7 +190,7 @@ bash core/scripts/team-brain-api.sh recall AAP-81423 "scaffold"
 Keep it short and professional (a teammate’s AI will see this). Prefer a stable `--source-ref`:
 
 ```bash
-bash core/scripts/team-brain-api.sh remember AAP-81423 research --source-ref "AAP-81423#cli-entrypoint" "Found CLI entrypoint in pkg/scaffold — start there for EE schema."
+bash core/scripts/team-brain-api.sh remember YOU_JIRA_TICKET_HERE research --source-ref "YOU_JIRA_TICKET_HERE#cli-entrypoint" "Found CLI entrypoint in pkg/scaffold — start there for EE schema."
 ```
 
 | Kind | When to use |
@@ -206,19 +208,19 @@ Merge rules:
 ### 3) Draft stories / stop when done
 
 ```bash
-bash core/scripts/team-brain-api.sh breakdown AAP-81423
-bash core/scripts/team-brain-api.sh stop AAP-81423
+bash core/scripts/team-brain-api.sh breakdown YOU_JIRA_TICKET_HERE
+bash core/scripts/team-brain-api.sh stop YOU_JIRA_TICKET_HERE
 ```
 
-If sync slept: `wake AAP-81423` (or `start` again).
+If sync slept: `wake YOU_JIRA_TICKET_HERE` (or `start` again).
 
 ### Optional — background `watch` on long spikes
 
 Sync mode already pulls while active, but during a **long** research session you can keep the cache warmer without waiting for idle sleep or the next `start`:
 
 ```bash
-bash core/scripts/team-brain-api.sh watch AAP-81423 &
-# or with Realtime push (full content, encrypted; falls back to signal+pull without `cryptography`): watch AAP-81423 --push &
+bash core/scripts/team-brain-api.sh watch YOU_JIRA_TICKET_HERE &
+# or with Realtime push (full content, encrypted; falls back to signal+pull without `cryptography`): watch YOU_JIRA_TICKET_HERE --push &
 ```
 
 Run it **once** when the spike gets long — not every command. Cursor agents also refresh via periodic `recall` (see the team-brain skill); `watch` is the human/CLI companion. If sync **slept**, use `wake` (or `start`) — `watch` does not replace sleep/wake.
@@ -257,7 +259,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --team "Team Name" --admin "Your Name" \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env
 ```
 
@@ -280,7 +282,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
   --db-url "postgresql://postgres:YOUR_DB_PASSWORD@db.YOUR_REF.supabase.co:5432/postgres" \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env
 ```
 
@@ -295,7 +297,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --team "Team Name" --admin "Your Name" \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env \
   --skip-migrations
 ```
@@ -313,7 +315,7 @@ When members hit overlapping research, they can **`remember … --queue`**. You
 bash core/scripts/team-brain-api.sh list-members
 
 # Review pending overrides for an initiative
-bash core/scripts/team-brain-api.sh pending list AAP-81423
+bash core/scripts/team-brain-api.sh pending list YOU_JIRA_TICKET_HERE
 
 # Keep the improved finding (promotes to live memory)
 bash core/scripts/team-brain-api.sh pending approve <pending-id> --note "Supersedes prior auth note"
@@ -333,7 +335,7 @@ Verify migrations: `bash core/scripts/team-brain-api.sh doctor` should report `p
 
 ```bash
 bash core/scripts/team-brain-api.sh register "Team Name" "Your Name"
-bash core/scripts/team-brain-api.sh attach AAP-81423 "Short title" "active" "https://your-org.atlassian.net/browse/AAP-81423"
+bash core/scripts/team-brain-api.sh attach YOU_JIRA_TICKET_HERE "Short title" "active" "https://your-org.atlassian.net/browse/YOU_JIRA_TICKET_HERE"
 ```
 
 > **Note:** New teams get 16-character invite codes. Only admins see the invite via `register` / `whoami` / bootstrap share bundle — joiners’ `credentials.json` does not store it.
@@ -355,7 +357,7 @@ bash core/scripts/team-brain-api.sh attach AAP-81423 "Short title" "active" "htt
 | **Peer push while sync/`watch` active** | ✅ Signal Broadcast (#31) + poll fallback; needs `start` or `watch` once |
 | **Push into open chat with zero `start`** | ❌ Still needs you (or the agent) to enter sync mode once |
 
-**Cursor:** say *“I’m starting on AAP-81423 — start Team Brain sync.”*  
+**Cursor:** say *“I’m starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.”*  
 The always-on rule expects `start` → summarize cache → work → `remember` / `touch`.
 
 ## Daily habits (keep it simple)
@@ -379,7 +381,7 @@ The always-on rule expects `start` → summarize cache → work → `remember` /
 Agents can be wrong. When you paste a correction, the AI should **update** the matching memory (same `source_ref`) — not leave a stale row and not invent a second topic slug.
 
 ```bash
-bash core/scripts/team-brain-api.sh correct AAP-81423 --source-ref "AAP-81423#cli-schema" \
+bash core/scripts/team-brain-api.sh correct YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli-schema" \
   --was "Claimed schema lived in tox-ansible" \
   "EE schema path lives in packages/ansible-language-server."
 ```
@@ -390,8 +392,8 @@ Memory bodies should be natural prefer/avoid guidance — not TODO/NO-TODO lists
 Each `source_ref` update **archives** the prior body. Inspect or soft-rollback:
 
 ```bash
-bash core/scripts/team-brain-api.sh history AAP-81423 --source-ref "AAP-81423#cli-schema"
-bash core/scripts/team-brain-api.sh restore AAP-81423 --source-ref "AAP-81423#cli-schema" --revision 1
+bash core/scripts/team-brain-api.sh history YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli-schema"
+bash core/scripts/team-brain-api.sh restore YOU_JIRA_TICKET_HERE --source-ref "YOU_JIRA_TICKET_HERE#cli-schema" --revision 1
 ```
 
 `restore` keeps the audit trail (current body is archived before rollback).
@@ -399,11 +401,11 @@ bash core/scripts/team-brain-api.sh restore AAP-81423 --source-ref "AAP-81423#cl
 In Cursor you can say:
 
 ```text
-Correct Team Brain for AAP-81423#cli-schema — the schema is in packages/ansible-language-server, not tox-ansible.
+Correct Team Brain for YOU_JIRA_TICKET_HERE#cli-schema — the schema is in packages/ansible-language-server, not tox-ansible.
 ```
 
 ```text
-Show Team Brain history for AAP-81423#cli-schema and restore revision 1 if needed.
+Show Team Brain history for YOU_JIRA_TICKET_HERE#cli-schema and restore revision 1 if needed.
 ```
 
 Apply once on the crew Supabase project:
@@ -431,27 +433,27 @@ That installs:
 Paste into Cursor chat / Composer (pick one):
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
 ```
 
 ```text
-/team-brain start AAP-81423
+/team-brain start YOU_JIRA_TICKET_HERE
 ```
 
 Other useful lines:
 
 | When | Say this |
 |------|----------|
-| Keep working after a break | `Wake Team Brain sync for AAP-81423 and continue.` |
-| Done for the day | `Stop Team Brain sync for AAP-81423.` |
-| Check state | `What's my Team Brain sync-status for AAP-81423?` |
-| Compliance | `What's Team Brain compliance for AAP-81423?` |
-| Plan stories | `Breakdown AAP-81423 from Team Brain memory.` |
-| Fix bad research | `Correct Team Brain for AAP-81423#<slug> — …` |
+| Keep working after a break | `Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.` |
+| Done for the day | `Stop Team Brain sync for YOU_JIRA_TICKET_HERE.` |
+| Check state | `What's my Team Brain sync-status for YOU_JIRA_TICKET_HERE?` |
+| Compliance | `What's Team Brain compliance for YOU_JIRA_TICKET_HERE?` |
+| Plan stories | `Breakdown YOU_JIRA_TICKET_HERE from Team Brain memory.` |
+| Fix bad research | `Correct Team Brain for YOU_JIRA_TICKET_HERE#<slug> — …` |
 
 Then work. After findings the AI should `remember` (and `touch`) without you asking.  
 If `compliance.agent_action` is set, the agent should follow it before deep research.  
@@ -524,9 +526,9 @@ bash core/scripts/team-brain-api.sh metrics <JIRA-KEY>
 bash core/scripts/team-brain-api.sh metrics --team   # crew coverage + reuse (#35)
 
 # Or in Cursor chat:
-#   I'm starting on AAP-81423 — start Team Brain sync.
-#   Wake Team Brain sync for AAP-81423 and continue.
-#   Stop Team Brain sync for AAP-81423.
+#   I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
+#   Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
+#   Stop Team Brain sync for YOU_JIRA_TICKET_HERE.
 ```
 
 ---
diff --git a/docs/team-brain-tutorial.md b/docs/team-brain-tutorial.md
index b337399..b430a37 100644
--- a/docs/team-brain-tutorial.md
+++ b/docs/team-brain-tutorial.md
@@ -525,10 +525,10 @@ bash core/scripts/team-brain-api.sh sync-status <JIRA-KEY>
 bash core/scripts/team-brain-api.sh metrics <JIRA-KEY>
 
 # Cursor chat
-"I'm starting on AAP-81423 — start Team Brain sync."
+"I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync."
 "Remember: CLI entrypoint is in pkg/scaffold."
 "What does Team Brain know about scaffold?"
-"Breakdown AAP-81423 from Team Brain memory."
+"Breakdown YOU_JIRA_TICKET_HERE from Team Brain memory."
 ```
 
 ---
diff --git a/docs/team-brain.md b/docs/team-brain.md
index 58ccc30..a13a4a3 100644
--- a/docs/team-brain.md
+++ b/docs/team-brain.md
@@ -19,11 +19,11 @@ Part of **Brainstack** alongside [engineer-brain](scopes.md). See also [#2](http
 ├── credentials.json          # gitignored — from register / join / onboard
 ├── TEAM.md                   # one per team (norms, members)
 ├── cache/
-│   └── AAP-81423.json        # agent-facing snapshot (written on attach/remember/recall)
+│   └── YOU_JIRA_TICKET_HERE.json        # agent-facing snapshot (written on attach/remember/recall)
 ├── metrics.json              # gitignored — local reuse stats
 └── initiatives/
-    ├── AAP-81423.md          # optional human/git export
-    └── AAP-81423-breakdown.md
+    ├── YOU_JIRA_TICKET_HERE.md          # optional human/git export
+    └── YOU_JIRA_TICKET_HERE-breakdown.md
 ```
 
 ## Sync model
@@ -56,7 +56,7 @@ Admin provisions **their own** Supabase project (see [supabase/README.md](../sup
 Share with joiners: **invite code + project URL + anon key + Jira key** (not via public git).
 
 ```bash
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Bob" AAP-81423
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Bob" YOU_JIRA_TICKET_HERE
 ```
 
 Admin once: create project → migrations → `register "Team Atlas" "Alice"` → share invite (16 hex chars).
@@ -68,26 +68,26 @@ One manual step when you start team work on a ticket.
 **In Cursor / chat (preferred):**
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
 ```
 
 ```text
-/team-brain start AAP-81423
+/team-brain start YOU_JIRA_TICKET_HERE
 ```
 
 | Later | Say |
 |-------|-----|
-| After idle sleep | `Wake Team Brain sync for AAP-81423 and continue.` |
-| Done | `Stop Team Brain sync for AAP-81423.` |
+| After idle sleep | `Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.` |
+| Done | `Stop Team Brain sync for YOU_JIRA_TICKET_HERE.` |
 
 **CLI equivalent:**
 
 ```bash
-bash core/scripts/team-brain-api.sh start AAP-81423
+bash core/scripts/team-brain-api.sh start YOU_JIRA_TICKET_HERE
 ```
 
 | While active | Behavior |
@@ -108,8 +108,8 @@ Cursor rule/skill: summarize cache after `start`; prompt user if mode is `sleep`
 4. `breakdown` / `metrics` when planning; `metrics --team` for crew coverage + reuse (#35).
 
 ```bash
-bash core/scripts/team-brain-api.sh breakdown AAP-81423
-bash core/scripts/team-brain-api.sh metrics AAP-81423
+bash core/scripts/team-brain-api.sh breakdown YOU_JIRA_TICKET_HERE
+bash core/scripts/team-brain-api.sh metrics YOU_JIRA_TICKET_HERE
 bash core/scripts/team-brain-api.sh metrics --team
 ```
 
diff --git a/mcp/team-brain/README.md b/mcp/team-brain/README.md
index 36dca06..ffa9e01 100644
--- a/mcp/team-brain/README.md
+++ b/mcp/team-brain/README.md
@@ -115,11 +115,11 @@ Commit `.team-brain/project.json` for repo pin (#39); `start`/`attach` accept an
 ### Chat examples (Cursor)
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
-Wake Team Brain sync for AAP-81423 and continue.
-Stop Team Brain sync for AAP-81423.
-Breakdown AAP-81423 from Team Brain memory.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
+Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
+Stop Team Brain sync for YOU_JIRA_TICKET_HERE.
+Breakdown YOU_JIRA_TICKET_HERE from Team Brain memory.
 ```
 
 Cursor ships always-on rule `platforms/cursor/rules/team-brain.mdc` + skill.
diff --git a/mcp/team-brain/server.py b/mcp/team-brain/server.py
index 36bb539..adb26b1 100644
--- a/mcp/team-brain/server.py
+++ b/mcp/team-brain/server.py
@@ -326,7 +326,7 @@ def remember(
     """Save a finding for the crew — call IMMEDIATELY after durable research (do not wait).
 
     kind: research | decision | note | learning.
-    Always pass source_ref (e.g. AAP-81423#cli-schema).
+    Always pass source_ref (e.g. YOU_JIRA_TICKET_HERE#cli-schema).
     Identical body → deduped=true. Same source_ref + new body → updated=true (merge);
     prior body is archived (archived_revision) when the history migration is applied.
     Near-duplicate or cross-author conflict → redundant_candidate=true (not stored).
diff --git a/platforms/cursor/README.md b/platforms/cursor/README.md
index 10cca5a..b7a2205 100644
--- a/platforms/cursor/README.md
+++ b/platforms/cursor/README.md
@@ -75,21 +75,21 @@ local — never commit it back to this repository.
 `team-brain.mdc` is installed with Cursor rules. **One chat line to start:**
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
 ```
 
 ```text
-/team-brain start AAP-81423
+/team-brain start YOU_JIRA_TICKET_HERE
 ```
 
 | Later | Say |
 |-------|-----|
-| After idle sleep | `Wake Team Brain sync for AAP-81423 and continue.` |
-| Done | `Stop Team Brain sync for AAP-81423.` |
+| After idle sleep | `Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.` |
+| Done | `Stop Team Brain sync for YOU_JIRA_TICKET_HERE.` |
 
 While active the agent should summarize cache, `touch` each turn, and `remember` findings (`source_ref`).
 
diff --git a/platforms/cursor/rules/team-brain.mdc b/platforms/cursor/rules/team-brain.mdc
index f61361d..27d0749 100644
--- a/platforms/cursor/rules/team-brain.mdc
+++ b/platforms/cursor/rules/team-brain.mdc
@@ -37,11 +37,11 @@ bash <brainstack>/core/scripts/team-brain-api.sh sync-status <JIRA-KEY>
 When the user starts team work on a ticket — including phrases like:
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
-/team-brain start AAP-81423
-Wake Team Brain sync for AAP-81423 and continue.
-Stop Team Brain sync for AAP-81423.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
+/team-brain start YOU_JIRA_TICKET_HERE
+Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
+Stop Team Brain sync for YOU_JIRA_TICKET_HERE.
 ```
 
 …run the matching command (`start` / `wake` / `stop`):
diff --git a/platforms/cursor/skills/engineer-brain/ONBOARDING.md b/platforms/cursor/skills/engineer-brain/ONBOARDING.md
index d0d6018..a33fb2d 100644
--- a/platforms/cursor/skills/engineer-brain/ONBOARDING.md
+++ b/platforms/cursor/skills/engineer-brain/ONBOARDING.md
@@ -75,7 +75,7 @@ The plugin registers MCP namespace `plugin-atlassian-atlassian` and points at At
 
 First-time site install may require a user who has access to the Jira projects you use; after that, other crew members can authorize individually.
 
-> **Example (Red Hat):** `you@redhat.com` on `redhat.atlassian.net`, project keys like `AAP-xxxxx`.
+> **Example (Red Hat):** `you@redhat.com` on `redhat.atlassian.net`, project keys like `YOU_JIRA_TICKET_HERE`.
 
 #### 3.3 Verify
 
diff --git a/platforms/cursor/skills/team-brain/SKILL.md b/platforms/cursor/skills/team-brain/SKILL.md
index 947d0cd..17becb7 100644
--- a/platforms/cursor/skills/team-brain/SKILL.md
+++ b/platforms/cursor/skills/team-brain/SKILL.md
@@ -81,11 +81,11 @@ API="${SKILL_DIR}/scripts/team-brain-api.sh"
 User will often say things like:
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
-/team-brain start AAP-81423
-Wake Team Brain sync for AAP-81423 and continue.
-Stop Team Brain sync for AAP-81423.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
+/team-brain start YOU_JIRA_TICKET_HERE
+Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
+Stop Team Brain sync for YOU_JIRA_TICKET_HERE.
 ```
 
 Run:
@@ -165,7 +165,7 @@ That research is wrong — the schema lives in packages/ansible-language-server,
 ```
 
 ```text
-Correct Team Brain memory for AAP-81423#cli-schema — prefer …
+Correct Team Brain memory for YOU_JIRA_TICKET_HERE#cli-schema — prefer …
 ```
 
 Then:
diff --git a/supabase/README.md b/supabase/README.md
index e99ef65..37b68de 100644
--- a/supabase/README.md
+++ b/supabase/README.md
@@ -4,7 +4,7 @@ Collaborative **AI memory** for a crew on the same Jira initiative:
 
 | Layer | Role |
 |-------|------|
-| **Jira** | Initiative identity (`AAP-81423`, …) |
+| **Jira** | Initiative identity (`YOU_JIRA_TICKET_HERE`, …) |
 | **Supabase** | Membership + shared memories (SoT) |
 | **Local cache** | `.team-brain/cache/<KEY>.json` for agents |
 | **Markdown** | Optional export under `initiatives/<KEY>.md` |
@@ -62,7 +62,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --team "Spike Crew" --admin "Alice" \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env
 
 # Step 2 — after pasting supabase/.bootstrap-migrations.combined.sql in SQL Editor:
@@ -70,7 +70,7 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --team "Spike Crew" --admin "Alice" \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env \
   --skip-migrations
 
@@ -80,11 +80,11 @@ bash core/scripts/team-brain-api.sh bootstrap \
   --url "https://YOUR_REF.supabase.co" \
   --anon "eyJ..." \
   --db-url "postgresql://postgres:YOUR_DB_PASSWORD@db.YOUR_REF.supabase.co:5432/postgres" \
-  --jira AAP-81423 \
+  --jira YOU_JIRA_TICKET_HERE \
   --write-env
 
 # Linked Supabase CLI:
-bash core/scripts/team-brain-api.sh bootstrap --team "Spike Crew" --admin "Alice" --jira AAP-81423
+bash core/scripts/team-brain-api.sh bootstrap --team "Spike Crew" --admin "Alice" --jira YOU_JIRA_TICKET_HERE
 
 # Local Docker demo:
 bash core/scripts/team-brain-api.sh bootstrap --team "Local Crew" --admin "Alice" --local --jira DEMO-1
@@ -110,15 +110,15 @@ Ask your admin for: **invite code**, **Jira key**, and the crew’s **Supabase U
 
 ```bash
 cd brainstack
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" AAP-81423
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" YOU_JIRA_TICKET_HERE
 ```
 
 **Day to day**
 
 ```bash
-bash core/scripts/team-brain-api.sh remember AAP-81423 research "What I learned…"
-bash core/scripts/team-brain-api.sh recall AAP-81423
-bash core/scripts/team-brain-api.sh breakdown AAP-81423
+bash core/scripts/team-brain-api.sh remember YOU_JIRA_TICKET_HERE research "What I learned…"
+bash core/scripts/team-brain-api.sh recall YOU_JIRA_TICKET_HERE
+bash core/scripts/team-brain-api.sh breakdown YOU_JIRA_TICKET_HERE
 ```
 
 ---
diff --git a/website/docs/platforms/cursor.md b/website/docs/platforms/cursor.md
index 3bb9b48..7fa2a54 100644
--- a/website/docs/platforms/cursor.md
+++ b/website/docs/platforms/cursor.md
@@ -31,18 +31,18 @@ In any Cursor chat or Composer session:
 /engineer-brain reflect
 
 /team-brain onboard <invite> Name KEY
-/team-brain start AAP-81423
+/team-brain start YOU_JIRA_TICKET_HERE
 /team-brain remember / recall
-/team-brain breakdown AAP-81423
+/team-brain breakdown YOU_JIRA_TICKET_HERE
 ```
 
 **Start crew work (natural language):**
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
-Wake Team Brain sync for AAP-81423 and continue.
-Stop Team Brain sync for AAP-81423.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
+Wake Team Brain sync for YOU_JIRA_TICKET_HERE and continue.
+Stop Team Brain sync for YOU_JIRA_TICKET_HERE.
 ```
 
 Personal context loads automatically. Team Brain sync mode loads crew memory first, then the agent remembers durable findings.
diff --git a/website/docs/quick-start.md b/website/docs/quick-start.md
index f8b91ea..01b6f09 100644
--- a/website/docs/quick-start.md
+++ b/website/docs/quick-start.md
@@ -65,17 +65,17 @@ This scans your git history and auto-populates BRAIN.md with your expertise, pat
 If your crew shared an invite code, Jira key, and Supabase URL + anon (fill local `project.public.env`):
 
 ```bash
-bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" AAP-81423
+bash core/scripts/team-brain-api.sh onboard <INVITE> "Your Name" YOU_JIRA_TICKET_HERE
 ```
 
 Then in Cursor (one line to start crew work):
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync.
 ```
 
 ```text
-I'm starting on AAP-81423 — start Team Brain sync, summarize crew memory, then help me.
+I'm starting on YOU_JIRA_TICKET_HERE — start Team Brain sync, summarize crew memory, then help me.
 ```
 
 Junior guide: [team-brain-onboarding.md](https://github.com/Hrithik-Gavankar/brainstack/blob/main/docs/team-brain-onboarding.md).

From 12fd2f97ee14dd6a86ddffca7bc40b89265a02c0 Mon Sep 17 00:00:00 2001
From: Hrithik-Gavankar <hgavanka@redhat.com>
Date: Wed, 9 Sep 2026 01:25:04 +0530
Subject: [PATCH 2/2] fix(team-brain): clarify local workshop doc reference and
 ignore in link checker

---
 .github/mlc_config.json       | 3 +++
 docs/team-brain-onboarding.md | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/.github/mlc_config.json b/.github/mlc_config.json
index a95db3f..72177e0 100644
--- a/.github/mlc_config.json
+++ b/.github/mlc_config.json
@@ -8,6 +8,9 @@
     },
     {
       "pattern": "^https://engineer-brain.dev"
+    },
+    {
+      "pattern": "workshop-brainstack-day0\\.md"
     }
   ],
   "timeout": "10000",
diff --git a/docs/team-brain-onboarding.md b/docs/team-brain-onboarding.md
index 6dfde48..46a0aef 100644
--- a/docs/team-brain-onboarding.md
+++ b/docs/team-brain-onboarding.md
@@ -5,7 +5,7 @@
 **You do not need:** your own Supabase account, a `service_role` key, or Docker.  
 **You do need from your admin:** invite code, Jira key, and the crew’s Supabase **project URL + anon key** (placeholders ship in the repo — not a live project).
 
-> **Workshop demo scripts:** [workshop-brainstack-day0.md](workshop-brainstack-day0.md) uses **`team-brain-admin-setup.sh`** / **`team-brain-member-setup.sh`** with demo epic **`KAN-4`** only. Everything below uses **`YOU_JIRA_TICKET_HERE`** (replace with your ticket key).
+> **Workshop demo scripts:** `docs/workshop-brainstack-day0.md` (local workshop copy — not in the public repo) documents **`team-brain-admin-setup.sh`** / **`team-brain-member-setup.sh`** with demo epic **`KAN-4`**. Everything below uses **`YOU_JIRA_TICKET_HERE`** (replace with your ticket key).
 
 ---