docs(schema): add schema/telegram.toml — platform source of truth

[chaodu-agent]

Summary

Adds schema/telegram.toml as the machine-readable, single source of truth for Telegram platform capabilities in OpenAB. Aligned with the three-layer trust architecture from ADR #1291.

Structure

schema/
└── telegram.toml    ← first platform schema; others follow same format

Three sections (per #1295 design discussion):

1. Trust layers — L1 (platform auth), L2 (scope control), L3 (identity gate) with config fields, defaults, and decision semantics
2. Platform capabilities — message limits, thread model, reactions, bot behavior, rate limits, attachment sizes
3. OpenAB feature support — per-feature status (implemented/partial/not_implemented) with symbol references (not line numbers — symbols survive refactors)
4. Quirks & findings — dated log of platform edge cases with official doc links

Why TOML (not markdown)?

• Consistent with project (config.toml)
• Machine-parseable → enables CI conformance checks
• Typed fields (booleans, numbers, not "Norway problem")
• Sections map naturally to Rust structs
• git diff schema/telegram.toml shows exactly what changed

Trust alignment (ADR #1291)

• Phase 3 (deny-all default) is live on main
• L1: secret_token + trusted_source_only (IP subnet check)
• L2: scope control, default OPEN (not a security boundary)
• L3: allow_all_users = false + allowed_users whitelist (THE security gate)

Future

• CI conformance tests validating symbol refs exist in source
• Additional platform schemas (discord.toml, slack.toml, line.toml, ...)
• Optional docs generation from schema

Ref

• docs(adr): revise identity-trust-none — three-layer architecture #1291 (trust ADR — three-layer architecture)
• docs(platforms): schema-driven platform facts knowledge base with CI conformance #1295 (platform knowledge base — content that informed this schema)
• Proposal: docs/platforms/ — schema-driven platform knowledge base (3 versioned schemas, one page per platform) #1294 (original proposal discussion)

Discussion: https://discord.com/channels/1491295327620169908/1491365158868619404/1523034521807618289

[chaodu-agent]

LGTM ✅ — Well-structured platform schema establishing the first machine-readable source of truth for Telegram capabilities.

What This PR Does

Adds schema/telegram.toml as a machine-readable, single source of truth for the Telegram platform adapter — covering trust layers, message capabilities, feature inventory, and platform quirks. Establishes the pattern for future platform schemas (discord.toml, slack.toml, etc.).

How It Works

Four-section TOML structure:

1. Trust layers (L1/L2/L3) — aligned with ADR docs(adr): revise identity-trust-none — three-layer architecture #1291 three-layer architecture; documents config fields, defaults, and decision semantics
2. Platform capabilities — message limits, thread model, reactions, bot behavior, rate limits
3. Feature support — [[openab_features]] array-of-tables with status enum (implemented/partial/workaround/not_implemented) and symbol references (not line numbers)
4. Quirks & findings — dated log of platform edge cases with official doc links

Findings

#	Severity	Finding	Location
1	🟢	Trust-layer documentation is clear and actionable — L1→L2→L3 flow with explicit rationale for keeping L2 open	[trust.*]
2	🟢	Feature inventory is comprehensive — 16 features with honest status reporting (including not_implemented and partial)	[[openab_features]]
3	🟢	Symbol references as stable code pointers avoid fragile line-number coupling	various
4	🟢	Quirks section prevents rediscovery of known platform edge cases	[[quirks]]
5	🟢	TOML syntax valid throughout; good use of array-of-tables for extensibility	whole file
6	🟢	Telegram API data verified accurate (4096 char limit, 20MB getFile cap, single-reaction semantics, IP subnets, rate limits)	various

Baseline Check

• PR opened: 2026-07-06
• Main already has: Telegram adapter implementation (crates/openab-gateway/src/adapters/telegram.rs, ~38KB)
• Main does NOT have: schema/ directory — this is fully net-new
• Net-new value: Machine-readable platform knowledge base enabling CI conformance checks and cross-platform comparison

What's Good (🟢)

• TOML choice is consistent with project conventions and enables typed CI validation
• Three-layer trust documentation matches ADR docs(adr): revise identity-trust-none — three-layer architecture #1291 precisely
• Honest "unverified" caveat on rich_message 32768 limit shows appropriate uncertainty
• [[quirks]] with dates creates an evolving knowledge log
• Status enum covers the full spectrum without ambiguity
• Symbol-based source references survive refactors

[chaodu-agent]

LGTM ✅ — Well-structured platform schema establishing machine-readable source of truth for Telegram capabilities.

What This PR Does

Introduces schema/telegram.toml as the first platform schema file, documenting Telegram's trust layers, message capabilities, feature support status, and platform quirks in a machine-parseable format aligned with ADR #1291.

How It Works

Single TOML file organized into sections: platform identity, trust layers (L1/L2/L3), message capabilities, thread model, interactions, bot behavior, OpenAB feature support matrix (with symbol references), and dated quirks log. Designed to be the canonical reference for CI conformance checks and future multi-platform schemas.

Findings

#	Severity	Finding	Location
1	🟢	Trust layer documentation precisely matches ADR #1291 three-layer model	schema/telegram.toml:17-49
2	🟢	Symbol references instead of line numbers — survives refactors	schema/telegram.toml:100-195
3	🟢	Quirks section includes dates and official doc references for traceability	schema/telegram.toml:199-266
4	🟢	TOML structure maps cleanly to Rust structs for future CI validation	—

Finding Details

🟢 F1: Trust layer alignment

All three layers (L1 platform auth, L2 scope control, L3 identity gate) correctly documented with config fields, defaults, and decision semantics matching the ADR #1291 architecture.

🟢 F2: Symbol references over line numbers

openab_features entries use source = "symbol_name" instead of file:line — these survive refactors and can be validated by future CI conformance tests.

🟢 F3: Quirks traceability

Each quirk entry has a date and official Telegram docs reference link, making it easy to verify against upstream changes.

🟢 F4: TOML format choice

Consistent with project convention (config.toml), avoids the "Norway problem" with typed fields, and sections map naturally to Rust structs for programmatic access.

Baseline Check

• PR opened: 2026-07-06
• Main already has: docs/telegram.md, docs/adr/telegram-rich-messages.md, crates/openab-gateway/src/schema.rs (unrelated CRD schema)
• Net-new value: First machine-parseable platform schema file; schema/ directory is entirely new. No overlap with existing docs — this is structured data complementing the prose documentation.

What's Good (🟢)

• Clean separation of concerns: trust → capabilities → features → quirks
• openab_features status enum (implemented/partial/workaround/not_implemented/n_a) provides clear feature matrix
• Feature entries include both symbol refs and human-readable descriptions
• Rate limit documentation captures per-chat, bulk, and per-group limits
• Thread detection logic documented (message_thread_id presence)
• Quirks capture real operational findings (single-slot reactions, getFile 20MB cap, privacy mode behavior)