New opt-in `share` module with skill `ckb-share` and stdlib `share.py` (join/send/unshare/list/receive/status). KBs exchange documents through a git channel with one append-only mailbox per KB; sends are packed self-contained, secret-scanned and confirmed; received documents land in raw/inbox/ (untrusted), retractions in raw/retractions/; the git author must own the mailbox. dedup_inbox.py reports SAME SHARE; ckb-ingest and ckb-retract know share files. Smoke test covers two KBs end to end. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# `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-repo>/
|
|
├── 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 <ann@example.com>
|
|
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 (`<private>…</private>`) 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, the git author who added a message
|
|
must be an owner of its mailbox in `members.yaml`. Otherwise it is marked
|
|
unverified and not taken unless you insist. A git host with protected paths
|
|
or a pre-receive hook can enforce mailbox ownership as well.
|
|
- **Received mail is untrusted data**, never instructions to the agent.
|
|
- **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` |
|