docs(telegram): document bridge family and implementation status

guides/bridge-examples.md

@@ -15,6 +15,7 @@ families are grouped by external protocol or adapter contract, not by transport.
 | BotBinary/BinaryBot | `optionx_cpp/bridges/bot_binary.hpp` | `BotBinaryBridgeConfig` | `examples/bot_binary_bridge_smoke.cpp` | Compatibility intake for BotBinary `request=...` HTTP URLs and file-signal filenames. |
 | BotBinary command helper | `optionx_cpp/bridges/bot_binary.hpp` | none | `examples/bot_binary_command_builder_smoke.cpp` | Formatter/parser helper for legacy BotBinary command strings. |
 | Legacy trading pipe | `optionx_cpp/bridges/legacy_trading.hpp` | `LegacyTradingBridgeConfig` | `examples/named_pipe_bridge_smoke.cpp` | Compatibility bridge for the older named-pipe JSON trading protocol. |
+| Telegram signal bridge | `optionx_cpp/bridges/telegram.hpp` | `TelegramSignalBridgeConfig` | `examples/telegram_signal_bridge_smoke.cpp` | Deterministic parser, source boundary, signal callback, duplicate report, and shutdown lifecycle without Telegram credentials. |
 
 ## Choosing A Bridge
 
@@ -29,6 +30,10 @@ families are grouped by external protocol or adapter contract, not by transport.
   BotBinary command string or file-signal filename.
 - Use the legacy trading pipe only for old clients that already speak that
   named-pipe JSON format.
+- Use the Telegram signal bridge when a user-client source must turn channel
+  messages into normalized signals. The production source is expected to be a
+  `tg-client-stdio` adapter; the parser and bridge can be tested independently
+  with a fake source.
 
 Compatibility bridges should convert their external payload into `TradeSignal`
 callbacks and reports. They do not need to expose Bridge Protocol v1 endpoints

guides/bridge-taxonomy.md

@@ -28,11 +28,18 @@ OptionX protocol together.
 | TradingView extension | `optionx_cpp/bridges/trading_view.hpp` | Adapter for payloads emitted by `browser_extensions/tradingview-alert-extension`. | HTTP. |
 | BinaryBot/BotBinary | `optionx_cpp/bridges/bot_binary.hpp` | Compatibility bridge and formatter/parser helpers for observed BinaryBot-compatible command strings. | HTTP `request=...`, file-signal name. |
 | Legacy trading pipe | `optionx_cpp/bridges/legacy_trading.hpp` | Compatibility bridge for the older named-pipe JSON trading protocol. | Named pipe. |
+| Telegram signal bridge | `optionx_cpp/bridges/telegram.hpp` | User-client message parser and live signal adapter. The Telegram worker/session remains an external source boundary. | stdio worker source, with source adapters kept outside the parser. |
 
 All families converge internally on OptionX DTOs such as `TradeSignal`,
 `TradeRequest`, account snapshots and bridge callbacks. The public wire format
 does not need to be the same for every family.
 
+Telegram is a source adapter family rather than a transport-only family. The
+public bridge consumes `TelegramMessageSource` callbacks, while authorization,
+proxy handling, dialog discovery and historical export belong to the
+`tg-client-stdio` worker/supervisor layer. Historical export remains a separate
+archive capability and is not added to `BaseBridge`.
+
 For practical embedding of the native HTTP/WebSocket server bridge, see
 `guides/protocol-v1-bridge-runtime.md`. For runnable bridge entry points, see
 `examples/README.md`.

guides/telegram-bridge-design.md

@@ -1,7 +1,8 @@
 # Telegram Bridge Design
 
-This document captures the intended direction for a future Telegram signal
-bridge. It is a design note, not a committed public API.
+This document captures the architecture and current boundaries of the Telegram
+signal bridge. The public C++ DTO/parser/bridge layer is implemented, while
+the authorized Telegram worker adapter remains a separate integration step.
 
 ## Problem Shape
 
@@ -53,6 +54,12 @@ newline-delimited JSON over stdin/stdout. Keep the protocol versioned so a
 framed transport can replace JSONL later if media bytes ever need to cross the
 stdio boundary.
 
+The current OptionX bridge does not own a Telethon process. It consumes the
+`TelegramMessageSource` interface, so fake sources can exercise parsing and
+lifecycle without credentials. The concrete source adapter will bind that
+interface to `tg-client-stdio::WorkerClient` after the worker repository's
+supervisor and typed archive API are merged and pinned by OptionX.
+
 ## Stdio Protocol Envelope
 
 Every JSONL record should use an envelope so responses, long-running exports,
@@ -107,7 +114,7 @@ Keep the live bridge, archive export, and parsing separate.
 
 ### Worker Client
 
-`TelegramWorkerClient` owns the process/session protocol. It should expose
+`tg-client-stdio::WorkerClient` owns the process/session protocol. It exposes
 operations such as:
 
 - `auth.status`;
@@ -131,6 +138,11 @@ message events into `TradeSignal` callbacks and signal reports.
 It should not expose historical export through `BaseBridge::run()` or
 `process()`. Bridge lifecycle remains live-intake lifecycle.
 
+The current bridge also applies a bounded identity-based dedupe cache. Parser
+diagnostics, duplicate messages, allocator failures and callback failures are
+reported through `BridgeSignalReport`; they do not silently become accepted
+signals.
+
 ### Archive Source
 
 Historical export is a separate capability. The first implementation can be
@@ -308,17 +320,26 @@ Proxy config should support at least SOCKS5 and HTTP where the underlying
 Telegram client library supports them. Proxy failures must be distinct from
 authorization failures.
 
-## First PR Sequence
+## Implementation Status And Next Steps
+
+Completed without an authorized Telegram session:
+
+1. `tg-client-stdio` worker protocol for dialogs, streaming export,
+   live listen/stop, auth status/code/2FA and HTTP/SOCKS proxy configuration.
+2. C++ worker supervisor and typed raw-message export DTOs in the standalone
+   worker repository.
+3. OptionX raw/parsed Telegram DTOs, deterministic regex parser and
+   source-independent `TelegramSignalBridge`.
+4. Fake-source unit coverage and a runnable no-credentials bridge example.
+
+Next steps:
 
-1. Refactor `telegram-monitoring-tool` into a non-interactive worker command
-   with the JSONL envelope above, preserving the current interactive CLI as a
-   thin wrapper if needed.
-2. Add worker operations for `dialogs.list`, `messages.export` and
-   `messages.listen`.
-3. Add C++ protocol DTOs and a small worker client/supervisor in OptionX.
-4. Add `TelegramSignalParser` with pure text fixture tests.
-5. Add `TelegramSignalBridge` live intake using the parser.
-6. Add archive/parser example for historical backtest fixture generation.
+1. Merge and pin the worker repository's supervisor/archive PRs.
+2. Add `TelegramMessageSource` adapter code around `WorkerClient` and test it
+   against the mock worker process.
+3. Add a historical archive/parser fixture example.
+4. Perform the first real authorization, proxy and live-channel check with an
+   operator-provided Telegram session.
 
-Keep the first OptionX PR focused on DTOs, parser and docs if the worker is not
-ready yet.
+OCR/vision remains a separate optional provider and should not block the text
+parser or the first authorized-session test.