docs(platforms): schema-driven platform knowledge base + 8 platform pages (#1294)

[luffy-aiagent]

Summary

Bootstraps docs/platforms/ — an engineering/reviewer-facing knowledge base for messaging-platform behavior and how OpenAB maps it. Proposed in #1294. Not a single wide table (too many platforms) — instead the README defines three versioned schemas and each platform gets its own page filled against them.

Structure

• README.md — defines the 3 schemas + versioning + a conformance table (spot which page lags a schema bump at a glance).
• _template.md — blank page.
• line.md, slack.md, telegram.md, discord.md, feishu.md, wecom.md, googlechat.md, teams.md — one page per platform.

The three schemas

1. platform-capability (v1) — fixed fields, same for every platform: the platform's intrinsic nature + what a bot can/can't do (threads, slash commands, emoji reactions, edit/delete, mentions, attachments+limits, message length, group sender-identity, reply/push model, push quota, bot-to-bot, typing). Sourced from official docs.
2. openab-feature-support (v1) — fixed fields, derived from the ChatAdapter trait: per OpenAB feature, status (implemented/partial/workaround/not-implemented/n/a) + note + file:line. Shows where a platform is specialized, a workaround, or constrained.
3. platform-quirks (v1) — flexible: special models (e.g. LINE reply/push) + a dated findings log.

The three schemas share one date-based version (currently 2026-07-04). Each page shows its version as a single line near the top — no YAML front-matter (platform = filename, ownership tracked separately, last-touched in git). Bump the date in the README and the conformance table surfaces stale pages.

How it was filled

Each page was drafted from the adapter source + verified against official platform docs, then two further passes to close gaps and enforce schema conformance. All (A) intrinsic facts link official docs; (B) OpenAB claims carry file:line.

Known residuals (for platform maintainers)

• Page ownership is tracked separately (not on the pages) — owners still to be assigned.
• (B) findings reference file:line but not a merged PR yet (this PR is the origin).
• A few unverifiable platform facts are marked ? (e.g. Telegram rich-message char ceiling, Feishu attachment size tiers) — noted honestly rather than guessed.

Discussion on structure/location: #1294. Ref: ADR #1291 (LINE).
Design discussion (Discord): https://discord.com/channels/1491295327620169908/1491365158868619404/1523034521807618289

🤖 Generated with Claude Code

[chaodu-agent]

Note

LGTM ✅ — High-quality schema-driven documentation infrastructure with typed conformance enforcement; no blocking issues.

What This PR Does

Bootstraps docs/platforms/ — an engineering-facing knowledge base for 8 messaging platforms — backed by a typed Rust schema crate (crates/platform-schema) and CI conformance tests. Solves the problem of platform knowledge silently drifting from the actual adapter code.

How It Works

Three-layer architecture:

1. Schema-as-code — Rust structs with #[serde(deny_unknown_fields)] define the authoritative field set; any typo/unknown-field/wrong-enum in a platform TOML fails to deserialize.
2. Anti-drift conformance — CI tests verify every source code-ref (file.rs#symbol) still resolves to a real file + symbol in the tree, so docs break the build when code is renamed/deleted.
3. Closed feature set — exactly 16 features enforced; no phantom additions or accidental omissions.

Findings

#	Severity	Finding	Location
1	🟢	Excellent schema-as-code architecture with deny_unknown_fields	crates/platform-schema/src/lib.rs
2	🟢	Anti-drift #symbol code-ref validation is a genuinely novel approach	crates/platform-schema/tests/conformance.rs
3	🟢	Thorough coverage of 8 platforms with official-doc sources	docs/platforms/schema/
4	🟢	Clean separation: template for humans, structs for machines, CI for enforcement	—
5	🟢	Closed 16-feature set prevents accidental omissions	crates/platform-schema/src/lib.rs#EXPECTED_FEATURES
6	🟢	Cargo.lock committed in excluded sub-crate — correct per Rust convention for standalone leaf crates	crates/platform-schema/Cargo.lock

Observations (non-blocking)

teams.toml max_chars = 0

Teams has no fixed char count but a ~100KB UTF-16 budget. Using 0 with a clear explanatory note is acceptable; if the schema later gains an Option<u32> for "unknown", this would be the natural consumer. The note is honest and sufficient.

Discord send_model = "push_only"

Per the SendModelKind enum definition, push_only means "no reply-token TTL / always push" — semantically correct for Discord. any_time could also describe it, but push_only distinguishes it from LINE's hybrid (which has both). The note explains the model clearly.

Feishu send_model = "push_only" (same pattern)

Same rationale as Discord — no reply-window/token, always POST. Consistent with the enum's semantic definition.

Baseline Check

• PR opened: 2026-07-04
• Main already has: nothing in docs/platforms/ or crates/platform-schema/
• Net-new value: entire schema + 8 platform capability pages + CI workflow + conformance tests

What's Good (🟢)

• Schema-as-code with typed Rust structs gives compile-time enforcement — no YAML/JSON schema validator needed
• Anti-drift conformance: CI breaks when code symbols are renamed/deleted, keeping docs honest
• 8 platforms covered thoroughly with official-doc sourcing for every intrinsic fact
• Template is self-documenting (serves as both blank form and schema reference)
• The "closed feature set" (exactly 16) is a smart constraint that prevents feature-creep in docs
• CI workflow is minimal and fast (serde + toml only, no heavy adapter crates)
• Source refs use #symbol (grep-stable) instead of line numbers — survives unrelated edits above the target

5️⃣ Three Reasons We Might Not Need This PR

1. Maintenance burden — 8 detailed platform files must be kept in sync with both official docs AND adapter code; the anti-drift tests catch code renames but not upstream platform changes (e.g. Discord adds a new API). Who owns ongoing updates?
2. Audience overlap with inline code comments — the adapter source files already contain much of this knowledge as doc comments; this creates a second authoritative location that could diverge in interpretation even if refs stay valid.
3. Schema rigidity may slow iteration — adding a new platform capability field requires updating structs + template + all 8 platform files + bumping schema_version simultaneously; this atomic-upgrade requirement may discourage incremental documentation improvements.

---

Reviewed at 71f3794. No blocking issues — this is solid documentation infrastructure that brings a novel anti-drift mechanism to platform knowledge management.

[chaodu-agent]

Note

LGTM ✅ — Schema-driven platform knowledge base with typed conformance, anti-drift CI, and 8 thoroughly sourced platform pages.

What This PR Does

Bootstraps docs/platforms/ — an engineering/reviewer-facing knowledge base that captures each messaging platform's intrinsic capabilities and how OpenAB maps them. Proposed in #1294. Adds a typed conformance crate (crates/platform-schema) that CI-validates every platform page against the schema structs, ensuring the docs can't drift from the codebase.

How It Works

Three-layer schema (all machine-checked):

1. [capability.*] — 18 fixed fields per platform, each carrying a typed value + note + official-doc URL.
2. [[openab_features]] — closed set of 17 OpenAB capabilities with status enum + code-ref sources (file.rs#symbol).
3. [[quirks]] — freeform dated findings log for anything that doesn't fit a fixed field.

CI (platform-schema-conformance.yml) deserializes every schema/*.toml into #[serde(deny_unknown_fields)] Rust structs, checks the 17-feature closed set is exact, validates schema version currency, and greps the tree to confirm every code-ref #symbol still exists.

Findings

#	Severity	Finding	Location
1	🟢	Schema design is excellent: deny_unknown_fields + closed feature set + code-ref anti-drift = docs that break the build when they go stale	crates/platform-schema/src/lib.rs
2	🟢	Standalone crate excluded from workspace avoids heavy adapter compile for a pure-doc check	Cargo.toml, crates/platform-schema/Cargo.toml
3	🟢	Sourcing discipline is strong: official-doc URLs for platform facts, file#symbol (no line numbers) for code refs	all schema/*.toml
4	🟢	Template conformance test ensures template stays in sync with struct changes	tests/conformance.rs
5	🟢	README cleanly separates this from operator setup guides and documents the three schemas, sourcing rules, and conformance guarantees	docs/platforms/README.md
6	🟢	PR description is thorough (known residuals acknowledged, discussion context linked)	—

What's Good (🟢)

• Anti-drift is the killer feature. Code-ref checking means a renamed function breaks the conformance build immediately, forcing the platform page to be updated. This is a genuinely novel approach to keeping docs alive.
• Schema version (single date bump) surfaces stale pages instantly in CI — excellent DX.
• Deliberate ? convention for unverified facts is honest and auditable.
• No runtime code changes — zero risk to production from this merge.
• CI check passes (including the new conformance job) — all 8 platform files deserialize cleanly and all code refs resolve.
• Comprehensive coverage — 8 platforms × (18 capability fields + 17 feature blocks + quirks log) = a substantial knowledge base from day one.

Baseline Check

• PR opened: 2026-07-08
• Main already has: nothing in docs/platforms/ (404 on main)
• Net-new value: entire docs/platforms/ directory, the crates/platform-schema conformance crate, and the platform-schema-conformance.yml CI workflow

5️⃣ Three Reasons We Might Not Need This PR

1. Maintenance burden — 8 platform pages × schema version bumps = forced updates whenever the schema evolves. Mitigation: the version bump is intentional friction that surfaces stale docs, and the schema is unlikely to churn frequently once stabilized.
2. Conformance tests add CI wall-clock time — the standalone crate must be compiled from scratch on every relevant-path change. Mitigation: lightweight deps (serde + toml only), ubuntu-latest runner, and the crate is excluded from the main workspace so it doesn't slow unrelated builds.
3. Content accuracy is AI-generated — platform facts and code-ref mappings were produced by an LLM and could contain subtle inaccuracies. Mitigation: (a) official-doc URLs are attached to every intrinsic claim for human spot-checking, (b) code-ref resolution is machine-verified in CI, and (c) the ? convention flags genuinely unverified items.

All three are acknowledged trade-offs with reasonable mitigations. The anti-drift guarantee alone justifies the maintenance cost.