docs: capture JSON vs text output contract in architecture guide

[rianjs]

Decision

Golden rule: JSON output preserves upstream API semantics. Text/table output may interpret.

Context

Issue #143 fixed text/table rendering for Slack messages whose readable content lives in blocks, attachments, or files while the upstream Slack text field is empty.

Follow-up user feedback noted that --output json still shows text: "" for block-only messages. That is intentional when Slack returned text: "".

Rationale

Default JSON output should remain transport-shaped Slack data, or a subset of it. If slck overwrites text with rendered block content, scripts can no longer distinguish Slack-provided fallback text from CLI-derived rendering.

Renderer-derived content belongs in text/table output, not default JSON.

Rule To Document

• JSON output must not overwrite upstream fields with rendered or derived content.
• JSON output may be a subset of upstream data, but included fields should keep their upstream meaning.
• JSON output should preserve upstream readable surfaces when modeled, such as blocks, attachments, and files.
• Text/table output may be opinionated: flatten Slack blocks, dedupe fallback text, resolve mentions, truncate for density.
• Renderer-derived fields do not belong in default JSON output.

Concrete #143 Implication

For block-only Slack messages:

• --output text should show rendered block content.
• --output json should keep text: "" if Slack returned an empty text field.
• Missing blocks in JSON would be a fidelity bug.

Follow-Up

After the planned harness engineering work emits an ARCHITECTURE.md, fold this decision into an output-contract section and link it from contributor/agent-facing docs.

Related: #143, #144