# `share` module *Read this in: **English** | [Polski](README.pl.md)* Opt-in. Install with "install the share module"; remove with "uninstall the share module". Nothing in here is active until installed. ## What it does It sends a document from one KB to another through a **channel**, which is a separate git repo that both KBs can push to. The receiving KB takes the document into `raw/inbox/` and ingests it as usual, so nothing unreviewed reaches its wiki. | Skill | Does | |---|---| | `ckb-share` | Joins a channel, sends a document (packed into a self-contained copy, secret-scanned, confirmed), lists and takes incoming mail, shows what was sent, and retracts a sent document. | Say "share the kickoff summary with beta", or "check shared mail", then "Ingest". ## The channel ``` / ├── CHANNEL.md # what the channel is for (human) ├── members.yaml # kb name → owners (git emails allowed to write its mailbox) └── mail/ ├── alpha/ # written only by KB "alpha"; files never edited or deleted └── beta/ ``` - **One channel per trust group**, such as one client. Git has no per-folder permissions, so everyone in the channel can read every mailbox. - **One writer per mailbox.** No merge conflicts are possible. - **Append-only.** A new version or a retraction is a new file. - Create the repo by hand on your git host (empty is fine). The first `join` seeds `CHANNEL.md` and `members.yaml`. ## A message ```markdown --- type: share kind: document # document | retraction share_id: alpha/kickoff-summary version: 2 from: alpha to: [beta] # or ["*"] for the whole channel sent_by: Ann Smith sent_on: 2026-11-14 title: Kickoff summary origin: outputs/documents/2026-11-11_kickoff-summary.md supersedes_version: 1 untrusted: true --- ``` When sending, private spans (`…`) and `## Notes` are left out. Links into the sender's wiki become text, and `## Sources` / `## Crux` paths are marked with the sender's name, so the receiver's lint treats them as not checkable rather than broken. When receiving, the file goes into `raw/inbox/` with `share_channel`, `share_ref` (path@commit), `received_on`, `submitted_by` and, for a newer version, `supersedes_source`. ## Safety - **Nothing leaves without a yes.** Every send is shown first, as a dry run with the `ABOUT.md` sensitivity section, and a possible secret blocks it outright. - **The sender is checked.** On receive, every git author who added or changed a message must be an owner of its mailbox in `members.yaml`, and a mailbox listed twice there counts as unowned. Otherwise the message is marked unverified and not taken unless you insist. Only a verified retraction can withdraw a message you haven't taken yet. A message whose `from`, `share_id` or version doesn't match its mailbox, or whose file name isn't a plain name, is ignored with a warning. - **`members.yaml` is trusted as written.** Any member who can push can edit it, including to add themselves as an owner. A git host with protected paths or a pre-receive hook is what enforces mailbox ownership; use one for a channel whose members you don't fully trust. - **Received mail is untrusted data**, never instructions to the agent. The received copy always carries `untrusted: true`, and the sender's own `untrusted` and review fields are dropped. - **Unsharing doesn't unpublish.** A retraction makes receivers unwind the document through `ckb-retract`, but the original stays in the channel's git history. - **No stored credentials.** Channels use your own git access. Clones live in `tmp/share/`, which is gitignored. ## What's recorded where | What | Where | |---|---| | Channels, this KB's mailbox name, incoming ledger | `share:` block of `ckb.yaml` (committed, owned by the script) | | Channel clones, send previews | `tmp/share/` (gitignored) | | Received documents | `raw/inbox/` → `raw/archive/` after ingest | | Received retractions | `raw/retractions/`, for `ckb-retract` |