create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/.claude/skills/summon/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: summon
+description: "Design and launch a persistent agent (a spirit) that runs on a schedule or watches for conditions, via adaptive questioning that produces a reviewable spec before launch."
+---
+
+# /summon — Design and Launch a Persistent Agent Process
+
+Summon a spirit — a persistent agent that runs on a schedule or watches for conditions. Unlike `/loop` (dumb scheduler), `/summon` designs the process through adaptive questioning, produces a reviewable spec, then launches it.
+
+## When to invoke
+
+**Trigger phrases**: "summon", "create a loop", "set up a recurring", "watch for", "monitor", "keep an eye on", "babysit", "run something every", "I want an agent that"
+
+**Not this command**:
+- Quick one-shot schedule → `/loop` directly (user already knows what they want)
+- One-time task → just do it, no spirit needed
+
+## Mode detection
+
+```bash
+MODE=$(jq -r '.mode // "connected"' egregore.json 2>/dev/null)
+```
+
+**Local mode** (`mode === "local"`): Skip ALL `bin/graph.sh`, `bin/graph-batch.sh`, and `bin/notify.sh` calls — do NOT run them. Do NOT show any graph-related messaging.
+
+Local-mode adjustments:
+- **Phase 1**: Skip the graph scan. Generate options from conversation context, `memory/quests/` files, and `.spirits/` directory instead of the graph.
+- **Phase 5**: Skip Spirit node creation in Neo4j. Write the spec file to `.spirits/{name}.json` and create the CronCreate schedule — these work without the graph.
+- **Phase 6**: Skip LoopReport creation in Neo4j. The TUI report still renders, but the graph artifact is not created.
+- **Managing Spirits**: Read from `.spirits/` directory instead of querying the graph. Suspend/resume only uses CronDelete/CronCreate, not graph updates.
+
+## Instructions
+
+### Phase 1: Intent Discovery
+
+Start with one open question via AskUserQuestion:
+
+```
+What should this spirit do?
+```
+
+**Connected mode:** Options should be derived from current graph context — not hardcoded. Before asking, run a lightweight graph scan to understand what's happening:
+
+```bash
+# Get active quests, recent sessions, health signals
+CONTEXT=$(bash bin/graph-batch.sh '[
+  {"statement": "MATCH (q:Quest) WHERE q.status IN [\"active\", \"in-progress\"] RETURN q.id, q.title LIMIT 10", "parameters": {}},
+  {"statement": "MATCH (s:Session)-[:BY]->(p:Person) RETURN s.topic, p.name, toString(s.date) AS date ORDER BY s.date DESC LIMIT 5", "parameters": {}},
+  {"statement": "MATCH (s:Spirit) RETURN s.name, s.type, s.status LIMIT 10", "parameters": {}}
+]')
+```
+
+Use this context to generate options that are relevant — e.g. if there are dormant quests, offer "reconcile dormant work"; if there's a PR-heavy period, offer "watch PRs". Always include a free-text option.
+
+**Local mode:** Skip the graph scan. Instead, derive options from:
+- Active quests in `memory/quests/` (parse frontmatter for status)
+- Recent handoffs in `memory/handoffs/index.md`
+- Existing spirits in `.spirits/` directory
+- Conversation context
+Always include a free-text option.
+
+The agent has full discretion to decide what context is relevant given the user's stated intent.
+
+### Phase 2: Adaptive Convergence
+
+Ask questions iteratively. Each round is informed by previous answers AND graph context. The questioning is non-linear — the agent decides what to ask based on where the interesting tension is, not a fixed script.
+
+**Dimensions to explore** (not necessarily in order — the agent picks what matters):
+
+- **Scope**: What exactly does the spirit observe? What can it act on? What's off-limits?
+- **Cadence**: How often? Time-driven (cron) or condition-driven (watchdog)? Or both?
+- **Boundaries**: What should it never do? What requires human approval vs auto-action?
+- **Reporting**: What does the user want to see? Metrics? Narrative? Diffs? Alerts only?
+- **Failure modes**: What happens when the spirit finds something it can't handle?
+- **Evolution**: Should the spirit's behavior change as it learns? How?
+
+**Convergence signal**: When the user's answers start narrowing to specifics (concrete conditions, specific quests, named thresholds), propose the spec. Don't ask more than 6 rounds unless the user is actively expanding scope.
+
+**For watchdog spirits** (event-driven):
+- Define the condition to watch for (as a Cypher query or graph pattern)
+- Define the action on trigger (notify, auto-fix, flag, escalate)
+- Cadence is polling interval (cron-based for now, hookable later)
+
+### Phase 3: Spec Generation
+
+Produce a spirit spec as JSON. Write to `.spirits/{name}.json`:
+
+```json
+{
+  "name": "graph-gardener",
+  "type": "recurring",
+  "purpose": "Maintain knowledge graph health — fix structural issues, infer new relationships, report drift",
+  "cadence": "0 3 * * *",
+  "cadence_human": "Daily at 3:03 AM",
+  "scope": {
+    "reads": ["Quest", "Artifact", "Session", "Person"],
+    "writes": ["Artifact", "Quest"],
+    "relationships": ["PART_OF", "RELATES_TO", "BUILDS_ON"],
+    "off_limits": ["Person deletion", "Quest deletion"]
+  },
+  "actions": {
+    "auto": ["resolve stale handoffs", "migrate date types", "mark dormant quests", "link artifacts by topic"],
+    "suggest": ["merge duplicate persons", "link disconnected artifacts"],
+    "flag": ["ghost artifacts", "orphaned sessions"]
+  },
+  "reporting": {
+    "tui": true,
+    "graph_artifact": true,
+    "notify": false
+  },
+  "watchdog": null,
+  "created_by": "cem",
+  "created_at": "2026-03-09T10:00:00Z",
+  "version": 1
+}
+```
+
+For watchdog spirits, the `watchdog` field contains:
+
+```json
+{
+  "condition": "MATCH (s:Session) WHERE s.date > date() - duration('P1D') AND s.handoffStatus = 'pending' RETURN count(s) > 3",
+  "action": "notify",
+  "message_template": "{{count}} handoffs piling up — someone should triage"
+}
+```
+
+### Phase 4: Review
+
+Present the spec as a TUI box:
+
+```
+┌ Spirit: graph-gardener ───────────────────────────┐
+│                                                    │
+│  Purpose:  Maintain knowledge graph health         │
+│  Type:     Recurring                               │
+│  Cadence:  Daily at 3:03 AM                        │
+│                                                    │
+│  Auto-fix: stale handoffs, date types,             │
+│            dormant quests, topic links              │
+│  Suggest:  duplicate persons, disconnected arts     │
+│  Flag:     ghosts, orphans                         │
+│                                                    │
+│  Reporting: TUI + Graph artifact each cycle        │
+│  Boundaries: No person/quest deletion              │
+│                                                    │
+└────────────────────────────────────────────────────┘
+```
+
+Ask: "Launch this spirit?" with options: Launch, Edit (back to questioning), Cancel.
+
+### Phase 5: Launch
+
+1. **Write spec file**: `.spirits/{name}.json`
+2. **Create Spirit node in graph** — **CONNECTED MODE ONLY**:
+   **Skip this step in local mode.** Do not run `bin/graph.sh`.
+   ```bash
+   bash bin/graph.sh query "
+     MERGE (sp:Spirit {name: \$name})
+     SET sp.type = \$type, sp.purpose = \$purpose, sp.cadence = \$cadence,
+         sp.status = 'active', sp.createdAt = datetime(), sp.createdBy = \$author,
+         sp.version = 1
+     RETURN sp.name
+   " '{"name":"...","type":"...","purpose":"...","cadence":"...","author":"..."}'
+   ```
+3. **Schedule via CronCreate**:
+   - Prompt is the spirit's execution prompt (constructed from spec)
+   - For recurring: standard cron
+   - For watchdog: polling cron + condition check prefix
+4. **Confirm**: Show job ID, how to cancel, 3-day auto-expiry note.
+
+### Phase 6: Cycle Reporting (attached to each execution)
+
+When a spirit runs (via `/loop` invoking its prompt), each cycle MUST:
+
+1. **Run the work** defined in the spec
+2. **Produce TUI report**:
+   ```
+   ┌ graph-gardener · Cycle 4 · 2026-03-09 ─────────┐
+   │                                                   │
+   │  ✦ Fixed: 3 stale handoffs resolved              │
+   │  ✦ Fixed: 12 date types migrated                 │
+   │  ◇ Inferred: 8 new RELATES_TO edges              │
+   │  ⚠ Flagged: 2 ghost artifacts                    │
+   │                                                   │
+   │  Health: 412 nodes · 891 edges · 1.2% orphan     │
+   │  Delta:  +15 edges since last cycle               │
+   │  Drift:  dormant quest count stable (26)          │
+   │                                                   │
+   │  Insight: "3 artifacts about 'governance' appeared│
+   │  this week but aren't linked to any quest —       │
+   │  emerging theme?"                                 │
+   │                                                   │
+   └───────────────────────────────────────────────────┘
+   ```
+
+3. **Write LoopReport to graph** — **CONNECTED MODE ONLY**:
+   **Skip this step in local mode.** Do not run `bin/graph.sh`. The TUI report still renders but is not persisted to the graph.
+   ```bash
+   bash bin/graph.sh query "
+     MATCH (sp:Spirit {name: \$name})
+     CREATE (lr:Artifact {
+       id: \$id, type: 'loop-report', title: \$title,
+       created: date(), origin: 'spirit',
+       metrics: \$metrics
+     })
+     CREATE (lr)-[:GENERATED_BY]->(sp)
+     RETURN lr.id
+   " '{"name":"...","id":"...","title":"...","metrics":"..."}'
+   ```
+
+4. **Insights**: The report should include one model-generated insight per cycle — a pattern, question, or observation that emerges from the data but wasn't explicitly programmed. This is the inferential layer growing.
+
+### Telemetry
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"summon"}' 2>/dev/null &
+```
+
+## Managing Spirits
+
+**Connected mode:**
+- **List active**: `bash bin/graph.sh query "MATCH (sp:Spirit {status: 'active'}) RETURN sp.name, sp.type, sp.cadence"`
+- **Suspend**: Set `sp.status = 'suspended'` + CronDelete
+- **Resume**: Set `sp.status = 'active'` + CronCreate
+- **View history**: `MATCH (lr:Artifact {origin: 'spirit'})-[:GENERATED_BY]->(sp:Spirit {name: $name}) RETURN lr ORDER BY lr.created DESC`
+
+**Local mode:**
+- **List active**: Read `.spirits/*.json` files, filter by `"status": "active"`. Display name, type, cadence from each spec file.
+- **Suspend**: Update spec file `"status": "suspended"` + CronDelete
+- **Resume**: Update spec file `"status": "active"` + CronCreate
+- **View history**: Not available in local mode (no graph artifact storage). Show: `Spirit history requires connected mode.`
+
+## Design Principles
+
+1. **Bitter lesson**: The agent decides what context is relevant, not a fixed query set. More compute, less hand-engineering.
+2. **Adaptive convergence**: Questions stop when the spec is clear, not after N rounds.
+3. **Specs are forkable**: `.spirits/` is git-tracked. Fork the egregore, inherit its spirits.
+4. **Spirits compound**: Each cycle's LoopReport feeds future cycles. The spirit gets smarter about what to surface.
+5. **Watchdogs are deferred hooks**: Poll-on-cron now, proper event-driven hooks when infrastructure exists.

package/runtime/claude/.claude/skills/sync-repos/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: sync-repos
+description: "Smart sync of all Egregore repos (memory + managed repos + current repo) — fetches first, only pulls if behind. Use for /sync-repos or 'sync all repos'."
+---
+
+Smart sync of all Egregore repos. Fetches first, only pulls if behind.
+
+## When to invoke
+
+User says: "/sync-repos", "sync all repos", "sync everything", "get every repo up to date"
+
+## Execution boundary
+
+This is deterministic multi-repository sync. Run it inline with bounded
+parallel fetches; do not spend a Loom/model-routing call or delegate it to
+another agent.
+
+## Repos to sync
+
+- `../$MEMORY_DIR` — shared knowledge (derived from `memory_repo` in `egregore.json`)
+- Any repos listed in the `repos` array in `egregore.json` (as sibling directories `../{repo}`)
+- Current repo (egregore-core)
+
+**Read `egregore.json` first** to get the dynamic list:
+```bash
+# Memory repo directory
+MEMORY_DIR=$(basename "$(jq -r '.memory_repo' egregore.json)" .git)
+
+# Managed repos
+REPOS=$(jq -r '.repos[]? // empty' egregore.json)
+```
+
+## Execution
+
+For each repo, run these commands:
+
+```bash
+# 1. Fetch (always)
+git -C /path/to/repo fetch origin --quiet
+
+# 2. Compare local vs remote
+LOCAL=$(git -C /path/to/repo rev-parse HEAD)
+REMOTE=$(git -C /path/to/repo rev-parse origin/main)
+
+# 3. Only pull if different
+if [ "$LOCAL" != "$REMOTE" ]; then
+  git -C /path/to/repo pull origin main --quiet
+  # Count commits behind
+  BEHIND=$(git -C /path/to/repo rev-list HEAD..origin/main --count)
+fi
+```
+
+**For the current repo (egregore-core)**: sync the `develop` branch instead of main:
+```bash
+# Update local develop ref without switching branches (safe for concurrent sessions)
+git fetch origin develop:develop --quiet
+# If on dev/* branch, rebase onto develop
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" == dev/* ]]; then
+  git rebase develop --quiet || (git rebase --abort && git merge develop -m "Sync with develop")
+fi
+```
+
+Use absolute paths with `git -C` to avoid permission prompts.
+
+## Output format
+
+```
+Syncing Egregore repos...
+
+  {memory-dir}       ↓ 3 commits → pulled
+  {repo-1}           ✓ up to date
+  {repo-2}           ✓ up to date
+  egregore-core      ↓ 1 commit → pulled
+```
+
+## Rules
+
+- Use `git -C /absolute/path` — no `cd` commands
+- Fetch ALL repos first (parallel if possible), then compare/pull
+- Show commit count when pulling
+- Skip repos that don't exist (no error)

package/runtime/claude/.claude/skills/teams-connect/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: teams-connect
+description: "Set up Microsoft Teams as a notification channel for your Egregore — registers an Azure bot, uploads the app, and binds a channel. Use for /teams-connect, 'connect teams', or 'set up teams notifications'."
+---
+
+Set up Microsoft Teams as a notification channel for your Egregore.
+
+Arguments: $ARGUMENTS (none expected)
+
+## When to invoke
+
+**Trigger phrases:**
+- "set up teams", "connect teams", "teams-connect", "microsoft teams"
+- "add teams notifications", "teams channel", "notify us on teams"
+
+**Disambiguation:**
+- "set up telegram" → `/telegram-connect`
+- "send a message to teams" → NOT this — use the separate notification
+  consent protocol in `.claude/context/notification-consent.md`
+
+## What this does
+
+Registers a bot in the org's own Microsoft tenant, installs it in their Teams,
+and binds one channel to Egregore notifications. After this, everything that
+plans a group notification may also resolve Teams as a receiving channel; all
+resolved channels are shown before separate dispatch approval.
+
+You (the agent) run all the Azure work via `az` after one browser login. The
+human does exactly three things: one login, two portal clicks, one paste.
+
+## OSS tier — visible, gated, honest
+
+This skill ships to every Egregore, but Teams notifications run on the
+Connected tier. **Before anything else**, detect the tier:
+
+```bash
+MODE=$(jq -r '.mode // empty' egregore.json 2>/dev/null)
+API_URL=$(jq -r '.api_url // empty' egregore.json 2>/dev/null)
+```
+
+The tier predicate is exactly the canonical `_detect_mode` truth table
+(`bin/lib/config.sh`): the instance is on the **local (OSS) tier** when
+`MODE` is `local` **or** `API_URL` is empty. (A hand-set `mode: "connected"`
+without an `api_url` is still local — never treat it as an unlock.)
+
+On the local tier, deliver exactly this message, then the question — do not
+paraphrase the message:
+
+> You can expand your knowledge base with connections to Notion, Google Drive, Docs, Sheets, and many more. Upgrade to Connected Tier to accelerate.
+
+AskUserQuestion:
+- **Upgrade to Connected Tier** — tell them the one sanctioned path: run
+  `egregore connect` in a terminal (the launcher walks the whole upgrade:
+  registers your org with the platform, provisions the key, replays your
+  graph). Teams notifications unlock once Connect is active.
+- **Not now** — respect it and stop. Do not improvise config edits,
+  api_url values, or partial flows.
+
+Only continue past this section on a connected instance.
+
+## Step 0: Prerequisites (check before touching anything)
+
+Ask, or verify where possible. All three must be true:
+
+1. **A Microsoft 365 tenant with Teams** (work tenant, not personal Teams).
+2. **The person here is admin** of that tenant (Entra + Teams admin center).
+3. **An Azure subscription** in that tenant — the bot resource is free (F0) but must live in a subscription.
+
+`az` CLI must be installed: `which az` — if missing, `brew install azure-cli`
+(macOS) or point at https://aka.ms/azure-cli for their OS.
+
+## Step 1: Login (human, ~1 min)
+
+Ask them to run in the prompt:
+```
+! az login
+```
+Then verify tenant + user:
+```bash
+az account show --query "{tenant:tenantId, user:user.name, state:state}" -o json
+```
+
+**Verify Teams is actually licensed** (the #1 silent dead-end — an Azure-only
+tenant has no Teams and the Teams admin center errors with a cryptic
+"can't find the tenant region for …" / PLS message):
+```bash
+az rest --method get --url "https://graph.microsoft.com/v1.0/subscribedSkus" \
+  --query "value[].skuPartNumber" -o json
+```
+- `[]` or no Teams-bearing SKU → they need a license first. Guide: M365
+  admin center → Marketplace → **Microsoft 365 Business Basic (Trial)**.
+  **EEA trap:** every SKU marked "(no Teams)" literally excludes Teams
+  (EU unbundling) — pick the plain variant, or add "Microsoft Teams EEA"
+  separately. After purchase, assign the license (set `usageLocation` on the
+  user first — `assignLicense` fails without it, and racing the two calls
+  fails too: PATCH usageLocation, then assign in a separate call).
+- Graph 403 `AADSTS530035` (security defaults) → `az logout && az login` fresh.
+
+## Step 2: Azure infrastructure (agent, ~2 min)
+
+Run these; capture every id/secret as you go:
+
+```bash
+# 1. App registration (single-tenant — deliberate; Microsoft is deprecating new multi-tenant bots)
+az ad app create --display-name "Egregore Notifications" --sign-in-audience AzureADMyOrg \
+  --query "{appId:appId}" -o json
+
+# 2. Client secret (2 years)
+az ad app credential reset --id <APP_ID> --display-name "teams-notify" --years 2 -o json
+
+# 3. Service principal — az ad app create does NOT make one; skipping this
+#    yields token 401 AADSTS7000229 later
+az ad sp create --id <APP_ID>
+
+# 4. Resource group + free Azure Bot + Teams channel
+az group create -n egregore-bots -l <their-region, e.g. westeurope>
+az bot create --resource-group egregore-bots --name egregore-notifications \
+  --app-type SingleTenant --appid <APP_ID> --tenant-id <TENANT_ID> --sku F0
+az bot msteams create --name egregore-notifications --resource-group egregore-bots
+```
+
+Save to the instance `.env` (gitignored — never commit):
+```
+TEAMS_APP_ID=…
+TEAMS_APP_SECRET=…
+TEAMS_TENANT_ID=…
+```
+
+Smoke the token before proceeding (catches AADSTS7000229 immediately):
+```bash
+curl -sS -X POST "https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token" \
+  -d grant_type=client_credentials -d "client_id=<APP_ID>" \
+  -d "client_secret=<SECRET>" -d "scope=https://api.botframework.com/.default"
+```
+
+## Step 3: App package + catalog upload (human, 2 clicks)
+
+Build and reveal the zip:
+```bash
+bash teams-app/build-package.sh <APP_ID> && open teams-app/build/
+```
+(If this instance doesn't carry `teams-app/`, fetch it from the framework repo.)
+
+Guide them: **https://admin.teams.microsoft.com/policies/manage-apps** →
+**Actions → Upload new app** → pick `egregore-teams-app.zip`.
+
+Traps:
+- Fresh tenants show "setting up your new app management experience… up to
+  30 minutes" with the upload button greyed out. It's provisioning — wait, refresh.
+- Re-uploading the same app id via "Upload new app" is rejected — updates go
+  through the app's **detail page → Upload file to update**.
+
+## Step 4: Add the bot to the team (human, 1 click)
+
+In **Teams — the work account** (trap: the desktop app may silently be the
+consumer client — "Build your community" UI, no org catalog; use
+teams.microsoft.com if in doubt): **Apps → Built for your org → Egregore →
+▾ → Add to a team** → pick the channel → **Set up a bot**.
+
+Without this, sends fail `403 BotNotInConversationRoster`.
+
+## Step 5: Channel binding (human pastes, agent decodes)
+
+Ask for the channel link (channel → ⋯ → Get link to channel), then decode:
+```bash
+python3 -c "import sys,urllib.parse,re; m=re.search(r'(19%3a[^/?]+|19:[^/?]+)', sys.argv[1]); print(urllib.parse.unquote(m.group(1)))" "<PASTED_LINK>"
+```
+Result must look like `19:…@thread.tacv2`.
+
+## Step 6: Persist
+
+```bash
+API_URL=$(jq -r '.api_url' egregore.json)
+KEY=$(grep '^EGREGORE_API_KEY=' .env | cut -d= -f2-)
+curl -sS -X POST "$API_URL/api/org/teams" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"conversation_id":"<CONV_ID>","app_id":"<APP_ID>","app_secret":"<SECRET>","tenant_id":"<TENANT_ID>"}'
+```
+Expect `{"status":"connected", …}`. The per-org creds matter: a single-tenant
+bot only works in its home tenant, so each org brings its own registration.
+
+Non-default region: their bot's service URL may differ from the EMEA default —
+pass `"service_url"` too (Azure portal → the bot → Channels → Teams shows it).
+
+## Step 7: Verify with separate exact notification consent
+
+Follow `.claude/context/notification-consent.md`. Connecting Teams is not
+consent to send a test message. Prepare after configuration is final:
+```bash
+PLAN_JSON=$(bash bin/notify.sh plan group "Teams channel connected — this message reached you through Egregore.")
+```
+
+Show every resolved receiving channel—potentially both Telegram and Teams—and
+the exact message in a dedicated Send / Edit / Cancel checkpoint. Only dispatch
+after Send is selected for that preview. Card avatar may show a generic icon
+for a few hours (Teams caches
+app icons) — cosmetic, self-heals.
+
+## Troubleshooting quick table
+
+| Symptom | Cause → fix |
+|---|---|
+| "can't find the tenant region" (PLS) in Teams admin center | No M365/Teams license on the tenant → Step 1 licensing |
+| Token 401 `AADSTS7000229` | Missing service principal → `az ad sp create --id <APP_ID>` |
+| Send 403 `BotNotInConversationRoster` | Bot not added to the team → Step 4 |
+| Send 404 | Wrong conversation id or wrong `service_url` region |
+| "already an app with the same app ID" on upload | Use the app detail page → Upload file to update |
+| No Apps rail / no org catalog in Teams | Consumer Teams client → work account at teams.microsoft.com |
+| Upload button greyed out | Tenant still provisioning app management (≤30 min) |
+
+## After
+
+Emit telemetry (fire-and-forget):
+```bash
+bash bin/telemetry.sh emit "teams-connect" '{"command":"teams-connect"}' 2>/dev/null &
+```

package/runtime/claude/.claude/skills/telegram-connect/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: telegram-connect
+description: "Set up Telegram as a notification center for your Egregore — creates the group, links the bot, and stores the chat ID. Use for /telegram-connect, 'connect telegram', or 'set up telegram notifications'."
+---
+
+Set up Telegram as a notification center for your Egregore.
+
+Arguments: $ARGUMENTS (none expected)
+
+## When to invoke
+
+**Trigger phrases:**
+- "set up telegram", "connect telegram", "add notifications", "telegram-connect"
+- "telegram group", "add telegram", "enable telegram", "link telegram"
+- "notification setup", "set up notifications"
+
+**Disambiguation:**
+- "send a message on telegram" → NOT this — use the separate notification
+  consent protocol in `.claude/context/notification-consent.md`
+- "announce something" → NOT this — use `/announce`
+
+## Step 1: Check current state
+
+Check for existing `telegram_chat_id` — it lives in `.egregore-state.json` (preferred) or `egregore.json` (legacy):
+
+```bash
+jq -r '.telegram_chat_id // empty' .egregore-state.json 2>/dev/null || jq -r '.telegram_chat_id // empty' egregore.json 2>/dev/null
+```
+
+If already set, show:
+```
+Telegram is already connected.
+
+  Chat ID: {chat_id}
+  Group link: {group_link}
+
+To update it, remove `telegram_chat_id` from .egregore-state.json and run `/telegram-connect` again.
+```
+And stop.
+
+## Step 2: Guide setup
+
+Read the org slug from `egregore.json`:
+```bash
+jq -r '.slug // empty' egregore.json 2>/dev/null
+```
+
+If slug is set, generate the deep link with it: `https://t.me/Egregore_clbot?startgroup=org_{slug}`
+If slug is empty, fall back to: `https://t.me/Egregore_clbot?startgroup=true`
+
+Show:
+```
+To set up Telegram notifications:
+
+  1. Create a Telegram group for your team
+  2. Add the bot: {deep_link}
+  3. The bot will respond with your Chat ID — copy it
+  4. Get the invite link: group name → Edit → Invite Links → Copy
+  5. Paste both below
+```
+
+Then use AskUserQuestion to ask for the chat ID:
+```
+Chat ID (from the bot's message in your group):
+```
+
+Validate: must be a negative number (e.g., `-1001234567890`) — reject anything else with "That doesn't look like a Telegram chat ID. It should be a negative number like -1001234567890."
+
+Then use AskUserQuestion to ask for the group invite link:
+```
+Group invite link:
+```
+
+Validate: must start with `https://t.me/` — reject anything else with "That doesn't look like a Telegram invite link."
+
+## Step 3: Store and test
+
+Read `.egregore-state.json`, add `telegram_chat_id` and `telegram_group_link` fields, write it back.
+
+**Important:** Write to `.egregore-state.json`, NOT `egregore.json`. The state file is symlinked across worktrees so the config propagates everywhere. No branch, commit, or push is needed — it's an untracked local file.
+
+Offer an optional test through the separate exact notification consent flow in
+`.claude/context/notification-consent.md`. Saving the Telegram configuration is
+not consent to send. Prepare without sending:
+```bash
+PLAN_JSON=$(bash bin/notify.sh plan group "Telegram connected! 🎉")
+```
+
+Show the organization, group/channel, and exact message in a dedicated Send /
+Edit / Cancel checkpoint. If approved and dispatched, show:
+```
+Telegram connected — test message sent to your group.
+```
+
+If cancelled, show `Telegram connected — no test message sent.` If planning or
+dispatch fails, show the error and suggest checking the chat ID.
+
+## Step 4: Telemetry
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"telegram-connect"}' 2>/dev/null &
+```
+
+## Rules
+
+- Never expose credentials in tool output
+- The bot username is `@Egregore_clbot` — NOT `@egregore_bot`
+- Only store the group invite link and chat ID, not bot tokens (those live on the API server)
+- Store in `.egregore-state.json` (symlinked, untracked) — NOT `egregore.json` (tracked, branch-specific)
+- No commit/push needed — state file is local and shared via symlinks