Improve Telegram control-plane operator gates

control-plane/AGENTS.md

@@ -1,107 +1,77 @@
 # Telegram Control-Plane Rules
 
-- This directory is the local Telegram control-plane, not a Telegram runtime repo.
-- Default operation is read-only toward external Telegram components.
-- Do not move repos, refresh plugin cache, sync skill-index, rewrite LaunchAgents,
-  start mirror jobs, or copy sessions from here without an explicit later plan.
-- `generated/` may be rewritten by local doctor/status commands.
-- The first milestone is allowed to fail closed on known defects.
-
-## Agent Entry (read this first)
-
-### Codex (live read — hot path)
-
-Do **not** load the full telegram skill for «что нового / прочитай чат за сегодня».
-
-1. `telegram://docs/routing` **or** `tg read today <chat> --limit 30 --json`
-2. Fallback: `bin/telegram-fast-read-today` → MCP `telegram_read` `mode="fast"`
-3. Forbidden until read fails: mcporter, tool_search, plugin README, doctor, launchd
+This directory is the local Telegram control-plane, not a Telegram runtime repo.
+Default operation is direct full-surface local MCP for the owner's Telegram accounts.
 
-`tg` on PATH: `./bin/telegram-kit --local`
+## First calls
 
-### All hosts
+- Use the native MCP tools first. `telegram-main` is the main account on port
+  `8799`; `telegram-pl` is the second account on port `8800`.
+- Run `./bin/telegram-status` or `./bin/telegram-doctor --json` only when MCP
+  calls fail or you are doing maintenance.
+- `./bin/tgc commands --json` — machine-readable registry of every command
+  (purpose, level, safety, example). Same data as `tests/test_command_registry.py`
+  enforces, so it cannot drift from `bin/`.
 
-For live Telegram work, read MCP resources first (smaller than the full skill):
+## Intent → command
 
-- `telegram://docs/routing`, `telegram://docs/tools`, `telegram://docs/sources`
-
-Full skill: `$HOME/.agents/skills/telegram` (symlink to
-`generated/telegram-plugin-package/skills/telegram`). Do not improvise Telethon
-calls or browse `telegram-mcp` unless debugging.
-
-### Speed path (low-stakes "что нового / за сегодня")
-
-1. Classify: current/today/recent → **live only** (never mirror/archive).
-2. On this host, run first:
-   `tg read today <chat> --limit 30 --json` (or `bin/telegram-fast-read-today` alias).
-3. If that fails, call MCP `telegram_read` with `mode="fast"`, not legacy
-   `read_today_dialog` (not on default allowlist).
-4. Skip `mcporter list`, doctor, launchd, and plugin README until a real failure.
-
-### Quality path (complete / media / send)
-
-| User intent | Tool | Notes |
+| Intent | Command | Notes |
 | --- | --- | --- |
-| Keyword in dialog | `telegram_search` | Then fetch context only for hits |
-| Full today, nothing missed | `telegram_read` `mode="full"` + page | Report `truncated` / `has_more_before` |
-| Draft reply | `telegram_prepare_reply` | No send without explicit user text |
-| Send | `telegram_confirmed_send` | Fresh `confirmation_token` from preview |
-| Photos/video | `telegram_inspect_media` / downloads | Never answer from captions only |
+| Что нового / прочитай чат за сегодня | `tg read today <chat> --limit 30 --json` | Live only; never mirror/archive. Fallback: MCP `telegram_read` `mode="fast"` |
+| Keyword in dialog | MCP `telegram_search` | Then fetch context only for hits |
+| Full today, nothing missed | MCP `telegram_read` `mode="full"` + page | Report `truncated` / `has_more_before` |
+| Draft reply | MCP `telegram_prepare_reply` | No send without explicit user text |
+| Send | MCP `telegram_send` or `send_message` | Direct one-call send on the selected local account |
+| Edit/delete/forward/react/pin | MCP `edit_message`, `delete_messages`, `forward_messages`, `send_reaction`, `set_message_pinned` | Use exact chat/message ids |
+| Photos/video | MCP `telegram_inspect_media` / downloads | Never answer from captions only |
 | Historical (allowlist) | `telegram-local-mirror` skill | Not for today/latest |
+| Mirror status/read/search | `./bin/telegram-mirror-fast …` | Local exports only; promotion is maintenance |
+| Control-plane health | `./bin/telegram-status`, `./bin/telegram-doctor --json` | Core profile, fails closed |
+| Low-stakes today smoke | `./bin/telegram-fast-read-today me --limit 1` | Read-only fast path |
+| Anything else | `./bin/tgc commands` | Pick by level/safety from the registry |
 
-### Default MCP surface (16 tools)
-
-Only these are exposed to agents via plugin allowlist: `telegram_read`,
-`telegram_search`, `telegram_prepare_reply`, `telegram_confirmed_send`,
-`telegram_inspect_media`, `telegram_export_members`, `resolve_dialog`,
-`find_dialog`, `collect_dialog_context`, `collect_context`, `download_media`,
-`download_media_batch`, `download_dialog_media`, `prepare_media_inspection_manifest`,
-`get_me`, `doctor_check`. Legacy aliases (`read_today_dialog`, `prepare_dialog_reply`,
-`draft_reply`, `search_dialog_messages`, …) and raw `send_dialog_message` /
-`reply_in_dialog` are **not** on the default surface (full/admin profile only).
+Avoid `mcporter` and broad doctor checks on the hot path. `tg` on PATH:
+`./bin/telegram-kit --local`. Do not improvise raw Telethon calls unless
+debugging the MCP server itself.
 
-### Doc sync (skill ↔ MCP resources)
+## Hard rules
 
-Edit `generated/telegram-plugin-package/skills/telegram/references/`, then:
-
-```bash
-./bin/telegram-agent-docs-sync
-```
-
-Restarts local MCP HTTP daemons automatically after sync. CI uses `--check --no-restart`.
-`build-plugin-package` runs the same sync automatically. Manifest:
-`skills/telegram/agent-docs/manifest.json`.
-
-### Telemetry (local)
-
-- Daily JSONL: `~/telegram-mcp/telemetry/daily/YYYY-MM-DD.jsonl` (30-day retention).
-- Symlink: `~/telegram-mcp/telemetry.jsonl` → today’s file.
-- Snapshot: `~/telegram-mcp/telemetry-stats.json` (runtime_stats + scheduler, ~60s).
-- Prometheus: `http://127.0.0.1:9109/metrics` (set `TELEGRAM_TELEMETRY_METRICS_PORT`; use `9110` for PL profile).
-- Policy: `policy/telemetry/` (Prometheus scrape, alert rules, Grafana dashboard JSON).
-- Summarize: `./bin/telegram-telemetry-status --json` or MCP `bin/telemetry-summary --json`.
-- Event `source`: `mcp_tool`, `fast_read_cli`, `mcp_server` — only paths through MCP/fast-read are tracked.
-- `doctor_check` includes `telemetry_summary` for the last 24h.
+- Do not move repos, refresh plugin cache, sync skill-index, rewrite LaunchAgents,
+  start mirror jobs, or copy sessions from here without an explicit later plan.
+- `generated/` may be rewritten by local doctor/status commands.
+- Blocking doctor findings mean the selected MCP account is not healthy. Fix
+  the failing component directly; `telegram-repair-plan` is optional
+  maintenance context, not a required preflight.
+- Maintenance/release commands (`telegram-maintenance-doctor`,
+  `telegram-release-gate`, plugin cache materialization, adapter installs,
+  docs sync) are outside the normal agent hot path.
+
+## Deep docs (read on demand)
+
+- Doctor warn triage and command levels: `docs/agents/doctor-triage.md`
+- Full MCP surface and release-gate naming: `docs/agents/mcp-surface.md`
+- System map and verification order: `docs/agents/system-map.md`
+- Telemetry locations and thresholds: `docs/agents/telemetry.md`
+- Doc sync skill ↔ MCP resources: `docs/agents/doc-sync.md`
+- Human map: `MAP.md`; roadmap: `TELEGRAM_AGENT_KIT_ROADMAP.md`
+- Live MCP backend location: `policy/managed-systems.json` → `telegram-mcp`
+- Portable plugin: `generated/telegram-plugin-package`
 
-### Verification on this host
+## Verification on this host
 
 ```bash
-./bin/telegram-fast-read-today me --limit 1
-./bin/telegram-golden-read-smoke --json
-./bin/telegram-mcp-surface --json
+tg read today me --limit 1 --json   # payload.data_source == "live_telegram"
+./bin/tgc next
 ./bin/telegram-doctor --json
-./bin/telegram-telemetry-status --json
+./bin/telegram-operator-status
 ```
 
-Fast read must return `payload.data_source == "live_telegram"`, not
-`Unknown tool`. Golden smoke covers five dialogs in `policy/golden-dialogs.json`
-(me, Конспекты, three DMs). Use `TELEGRAM_GOLDEN_READ_SKIP=1` only in CI/offline.
-
-### Runtime locations
-
-- Live MCP backend: `policy/managed-systems.json` → `telegram-mcp`
-- Portable plugin: `generated/telegram-plugin-package`
-- Human map: `MAP.md`, roadmap: `TELEGRAM_AGENT_KIT_ROADMAP.md`
+Use `./bin/telegram-golden-read-smoke --json` only for release or live-smoke
+verification (five dialogs from `policy/golden-dialogs.json`).
+For a full post-change verification run, use
+`./bin/telegram-regression-loop --include-live --json`; it keeps live smoke
+sequential and avoids racing runtime tests.
+`TELEGRAM_GOLDEN_READ_SKIP=1` is CI/offline only.
 
 ## Agent skills
 
@@ -115,4 +85,4 @@ Five canonical triage roles (`needs-triage`, `needs-info`, `ready-for-agent`, `r
 
 ### Domain docs
 
-Single-context layout: `CONTEXT.md` at the repo root and `docs/adr/` for decisions. See `docs/agents/domain.md`.
+Single-context layout: `CONTEXT.md` at the repo root and `docs/adr/` for decisions. See `docs/agents/domain.md`.

control-plane/CONTEXT.md

@@ -17,14 +17,19 @@ allowlist parity, and checks control-plane docs for stale surface claims.
 _Avoid_: Allowlist file, tool list in Python
 
 **Default MCP surface**:
-The restricted tool profile agents see through the installed plugin and local MCP
-facade — read/search/prepare/confirmed-send only, never raw send/reply on default.
-_Avoid_: Full MCP, admin profile (when meaning default)
+The owner-local full MCP surface exposed on this single-user machine. The active
+contract is `policy/surface-contract.json` with `owner_local_full_mcp`, so local
+agents may use reads, writes, media, contacts, groups, reactions, pins, polls,
+stories, privacy and profile tools directly when the task and safety rules allow
+it.
+_Avoid_: Legacy facade allowlist, restricted profile (when meaning the current
+owner-local default)
 
 **Confirmed write**:
-A facade tool that may mutate Telegram only after an explicit preview token
-(`telegram_confirmed_send`), not raw `send_*` / `reply_*` on the default surface.
-_Avoid_: Write tool, send helper
+A legacy facade write path that may mutate Telegram only after an explicit
+preview token (`telegram_confirmed_send`). It remains relevant for compatibility
+and tests, but it is not the current owner-local full-surface boundary.
+_Avoid_: Treating confirmed-send facade rules as the full owner-local MCP surface
 
 **Live MCP**:
 The `telegram-mcp` backend used for current/today/recent reads — not mirror or
@@ -65,4 +70,4 @@ _Avoid_: Inspecting LaunchAgents and session trees ad hoc per task
 **AuditRemediation**:
 The repair-plan catalog (`policy/audit-remediation.json` + `audit_remediation.py`)
 that links findings to ordered dry-run steps and keeps apply paths fail-closed.
-_Avoid_: Ad-hoc cleanup commands without `telegram-repair-plan`
+_Avoid_: Ad-hoc cleanup commands without `telegram-repair-plan`

control-plane/PLAN.md

@@ -44,25 +44,28 @@ Roadmap milestones 1–7 are implemented in code and gates:
 
 ## Verification
 
-Run these before calling the control-plane healthy:
+For day-to-day health, use:
 
 ```bash
-./bin/telegram-release-gate
+./bin/telegram-status
 ./bin/telegram-doctor --json
-python3 -m pytest -q -m integration
+./bin/telegram-mirror-fast status --json
 ```
 
 Expected current shape:
 
-- `telegram-release-gate`: exit `0`
-- `telegram-managed-systems`: `ok`
-- `telegram-mcp-surface`: `ok`
-- `telegram-docs-audit`: `ok`
-- `telegram-doctor`: `warn` with `0` blocking findings
-- known warnings only for `telegram-mirror` recovery state and telecrawl archive
-  gaps
+- `telegram-doctor`: fast core profile only
+- core covers live Telegram routing/surface safety, fast read, minimal live
+  runtime state, and lightweight mirror status
+- mirror fast path reads existing local exports with
+  `telegram-mirror-fast read/search`; it does not start watchers or backfills
+- release/archive/telemetry/plugin/mirror-promotion checks are not core
+
+For release/maintenance work, run `./bin/telegram-maintenance-doctor --json` or
+`./bin/telegram-release-gate`. Use component audits such as
+`telegram-mcp-surface`, `telegram-docs-audit`, or `telegram-telemetry-status`
+only as drill-down from doctor findings.
 
 ## karpathy-kb
 
 Canonical entity: `research/karpathy-kb/wiki/entities/telegram-control-plane.md`
-

control-plane/PROTECTION.md

@@ -1,37 +1,9 @@
 # Telegram Protection Contract
 
-This directory is the canonical index for local Telegram tooling. It protects
-systems by registering where they live; it does not absorb their private state.
+Single-owner local rule:
 
-## Deletion Rule
+Do not delete Telegram session directories, the MCP `.env`, or mirror runtime
+state without explicit user approval and a recoverable backup or safe-trash
+path.
 
-Do not delete, move, archive, or rewrite Telegram-related paths directly.
-
-Before any cleanup:
-
-1. Run `./bin/telegram-managed-systems --json`.
-2. Run `./bin/telegram-doctor --json`.
-3. Produce a dry-run repair or cleanup plan listing touched paths.
-4. Use recoverable safe-trash or a timestamped backup path.
-5. Get explicit user approval for the stateful action.
-
-## Managed Inventory
-
-`policy/managed-systems.json` is the source of truth for Telegram-related
-source repos, plugin/skill surfaces, runtime data roots, and archive tools.
-
-If a blocking-protected path disappears, `telegram-doctor` must fail closed.
-
-This is a control-plane guard, not an operating-system lock. A direct destructive
-shell command can still remove files. For stateful cleanup, the required safety
-mechanism is the workflow above: inventory first, dry-run plan second,
-recoverable backup/safe-trash third, explicit approval last.
-
-## What Must Not Live Here
-
-- Telegram session strings
-- Telegram Desktop `tdata`
-- raw media payloads
-- subscriber exports
-- unredacted archive databases
-- secrets or private env files
+The protected paths are listed in `policy/managed-systems.json`.