ckb/.agents/modules/share
Michał Kopeć 8dc3445b27 Template 1.28.0: share module — mailboxes in a git channel (D-0018)
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>
2026-11-11 13:31:51 +01:00
..
fragments Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
skills/ckb-share Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
module.yaml Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
README.md Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
README.pl.md Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00

share module

Read this in: English | Polski

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

---
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