--- type: decision tldr: KBs exchange documents through an opt-in `share` module — a git channel per trust group with one append-only mailbox per KB; sends are packed self-contained, secret-scanned and confirmed; receives land in raw/inbox/ (untrusted) or raw/retractions/; the git author must own the mailbox; handled messages are recorded in a ledger in ckb.yaml. status: accepted decided_on: 2026-11-11 decided_by: Michał Kopeć affects: .agents/modules/share/, .agents/skills/ckb-ingest/SKILL.md, .agents/skills/ckb-ingest/scripts/dedup_inbox.py, .agents/skills/ckb-retract/SKILL.md, tests/smoke.sh, README.md, docs/MANUAL.md confidence: 0.7 quality: 0.8 last_updated: 2026-11-11 freshness_window_days: 365 retention: high --- # D-0018 — A share module: mailboxes in a git channel **Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć ## Context One KB often holds something another KB needs: a summary, a decision, an answer. Until now the options were `linked/`, which mounts a whole KB and needs local filesystem access, and the `mcp` module's `add_to_inbox`, which needs the receiver to run a server. A team wanted to prepare a document in one KB and drop it where another KB can pick it up, using only git. ## Decision 1. **An opt-in module** (D-0001 pattern), `share`, with one skill, `ckb-share`, and one stdlib script, `share.py`. Most KBs never send anything, so the base pays no context for it. 2. **The channel is a separate git repo per trust group**, with `CHANNEL.md`, `members.yaml` (KB name → owner emails) and `mail//`. Each KB writes only to its own mailbox and never edits or deletes a file there, so merge conflicts cannot happen. A new version or a retraction is a new file. The channel is cloned into `tmp/share//`, and creating the repo stays manual. 3. **Messages carry an envelope**: `type: share`, `kind` (`document`/`retraction`), a stable `share_id` (`/`), `version`, `from`, `to` (names or `*`), `sent_by`, `sent_on`, `untrusted: true`. 4. **Send packs a self-contained copy.** `` spans and `## Notes` are dropped. Local links become text. Sources and Crux paths are marked `:`, so the receiver's lint treats them as not checkable rather than broken. Only `outputs/documents/`, `outputs/answers/` and `wiki/` pages can be sent; `raw/archive/` needs an extra yes. Lint's secret patterns block the send. A dry run shows the `ABOUT.md` sensitivity section, and the user confirms every send. 5. **Receive never touches `wiki/`.** Documents go to `raw/inbox/`, with `submitted_by` set to the git author who added the message, so `ckb-retract`'s owner check works unchanged. A newer version points at the earlier one with `supersedes_source`, and ingest treats it as supersession. A retraction becomes one `raw/retractions/` request per held version. 6. **The sender is checked on receive.** The git author who added a message must be an owner of its mailbox in `members.yaml`. If not, the message is UNVERIFIED and is taken only when the user insists. Git cannot enforce per-folder writes; a git host's path protection can, and that is documented as optional hardening. 7. **What was handled is a ledger, not derived from files.** The plan was to derive "already taken" from `raw/inbox/` and `raw/archive/`, but `ckb-retract` deletes the archived file, so a retracted document would be offered again. The `received:` list in the `share:` block of `ckb.yaml` records every message taken, declined, filed or seen. The script owns the whole block. The plan's open questions were settled on their recommended answers: notes are dropped by default (`--keep-notes` to send them); documents, answers and wiki pages can be sent, raw sources only with a yes; declines live in committed `ckb.yaml`; a routine only reports what is waiting; channels are created by hand. ## Alternatives considered - **Sync one folder with a submodule or subtree.** Pinned commits, a detached HEAD and history mixed into the KB. Rejected for a separate clone in `tmp/`. - **One shared folder all KBs write to, deleting what they take.** Conflicts between writers, and one receiver's delete hides the file from the others. - **`linked/` to a shared KB.** Better for knowledge everyone keeps reading. Still available, but it doesn't fit handing one document over. - **`mcp` `add_to_inbox`.** Needs a running server at the receiver. Still the right tool when one exists. - **Read receipts written back to the channel.** Deferred: the receiver would write outside its own mailbox, or into it, which mixes roles. ## Consequences - Sent material stays in the channel's git history. Unsharing makes receivers unwind it, but it doesn't unpublish. - `ckb.yaml` grows by one line per message received. That is acceptable for years of use, and the ledger can be trimmed by hand once its messages are gone from the channel. - The Hub plan's git push transport (`raw/outbox/` to an inbound branch) can adopt this envelope instead of inventing its own. - Not done in this release: a lint check for `type: share` files, a `share: N waiting` line at session start, eval cases (a channel needs a git remote, which the eval fixtures don't provide yet), and a PowerShell check.