docs: generalize doc standard to all crates and config sections

[bglusman]

Summary

Broadens the documentation standard from "channels only" to a project-wide gold standard that applies to all user-facing config, public library APIs, and user-facing features across every crate.

The two mechanisms

Library crates (secrets-client, adversary-detector, clashd, mcp-server, paste-server, security-proxy): native Rust doctests in /// comments — cargo test --doc -p <crate> compiles and runs them.

Binary crates (calciforge, host-agent): include_str! + unit tests that load markdown files, extract fenced TOML blocks, and parse them against the live config schema. The channel tests in config.rs are the canonical reference implementation.

What's defined

• Which config sections need docs and where they live (docs/agents.md, docs/routing.md, docs/model-gateway.md, etc.)
• Five-section structure every setup guide must follow (architecture, prerequisites, config, identity/routing, verify)
• Explicit rules for adding fields, config sections, and public functions
• Hard rule: no new channel, config section, or public API without tested docs

What this doesn't do

Doesn't add the missing docs yet — that's the next body of work. This PR establishes the standard so any agent or contributor knows exactly what's required when they touch any part of the codebase.

Merge order

Can merge independently of PR #82 (channel setup guides) or after — the standard references the channel tests as the canonical example.

Generated with Claude Code

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[greptile-apps]

Greptile Summary

This PR establishes a project-wide documentation standard, adds four channel setup guides (telegram.md, matrix.md, signal.md, whatsapp.md), and introduces a config.rs test harness that uses include_str! to parse every fenced TOML block in those docs against the live config schema. The docs/index.md is updated with navigation links to the new guides.

Confidence Score: 5/5

Safe to merge; only one P2 documentation nit about a non-existent function name in an example snippet.

All findings are P2. The test infrastructure is correct and well-structured, the four channel docs are complete and match their inline test fixtures, and the standard itself is clearly written. The single issue (AGENTS.md example referencing doc_blocks_with/parse_as_config which don't exist) is a documentation clarity nit that won't break builds or mislead runtime behaviour.

AGENTS.md — example snippet uses non-existent helper function names

Important Files Changed

Filename	Overview
AGENTS.md	Adds comprehensive documentation standard section; example snippet uses doc_blocks_with/parse_as_config which don't exist in the codebase
crates/calciforge/src/config.rs	Adds test helpers (extract_toml_blocks, channel_blocks_from_doc, parse_channel_block) and 8 tests covering inline TOML and doc-file TOML blocks for all four channels; implementation is clean and correct
docs/channels/telegram.md	New Telegram setup guide with all five required sections; channel TOML block matches the inline test in config.rs
docs/channels/matrix.md	New Matrix setup guide; includes E2EE-not-supported warning, all required sections, and TOML example verified by tests
docs/channels/signal.md	New Signal setup guide; ZeroClaw config block correctly uses [channels_config.signal] so it isn't accidentally caught by the channel-block filter in tests
docs/channels/whatsapp.md	New WhatsApp setup guide; detailed webhook payload, reply API, and HMAC verification sections; TOML examples verified by tests
docs/index.md	Adds navigation links to the four new channel setup guides under the channels section

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["docs/channels/*.md\n(Markdown with fenced TOML blocks)"] --> B["include_str! at compile time\n(config.rs test module)"]
    B --> C["extract_toml_blocks(markdown)\nreturns all fenced toml blocks"]
    C --> D["channel_blocks_from_doc(markdown)\nfilters for blocks containing [[channels]]"]
    D --> E["parse_channel_block(block)\nwraps in [calciforge] envelope\nand calls toml::from_str"]
    E --> F{Parse OK?}
    F -->|yes| G["assert cfg.channels[0].kind == expected"]
    F -->|no| H["panic with block content + error\n(test fails, CI blocks merge)"]
    G --> I["test passes"]

Loading

_{Reviews (2): Last reviewed commit: "fix(docs): fix SecretsClient example in ..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Expands Calciforge’s documentation approach by adding compile-tested channel setup guides and codifying a project-wide “tested docs” standard for user-facing config and public APIs.

Changes:

• Adds new channel setup guides under docs/channels/ (Telegram, Matrix, Signal, WhatsApp) with TOML examples intended to stay schema-correct.
• Updates crates/calciforge/src/config.rs tests to include_str! the channel docs and parse fenced [[channels]] TOML blocks against the live CalciforgeConfig schema.
• Updates AGENTS.md to define the repo-wide documentation/testing standard and links channel guides from docs/index.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/index.md	Links to the new per-channel setup guides from the main docs index.
docs/channels/whatsapp.md	Adds a WhatsApp webhook + ZeroClaw/OpenClaw setup guide with config examples.
docs/channels/telegram.md	Adds a Telegram long-poll setup guide with config examples.
docs/channels/signal.md	Adds a Signal webhook + ZeroClaw/OpenClaw setup guide with config examples.
docs/channels/matrix.md	Adds a Matrix /sync long-poll setup guide (explicitly notes no E2EE) with config examples.
crates/calciforge/src/config.rs	Adds tests that parse channel-doc TOML blocks to prevent schema drift.
AGENTS.md	Documents the “tested docs” gold standard and how to implement it for crates/config sections.

[bglusman]

Closing as superseded by the current docs-test direction and #89. The integration branch includes the relevant docs expansion on top of latest main without the stale conflicts.