Getting started

Download the Community Legibility Spec packet from https://github.com/HoustonBloom/cls-packet as a zip, unzip it into a folder on this computer, and tell me the folder's path. Then open SETUP.md in it.

Required

For offline file sending and viewing

Optional

The setup prompt

Open your agent in <your folder>, then paste this, with your name, your email and the packet's path filled in:

Set me up with the Community Legibility Spec packet at <packet>.
My name is <Your Name> and my email is <you@example.org>.
Follow <packet>/SETUP.md steps 1 to 9 in this folder, in order, using the By hand commands.
After each step, check the output against "You should see" and stop if it differs.
Do not send anything anywhere. When you are done, show me my dashboard and tell me where my card is.

You should see: your agent works through the steps and ends with your dashboard open and the path to your card, per_<your-name>.vcf.

Or set it up yourself

1. Check Node.js

Check that Node.js 18 or later is installed.

You should see: v18 or higher, such as v24.13.0. If not, install the LTS version from nodejs.org and open a new terminal.

Only if you will send ZIM files. A ZIM is one file that opens offline in Kiwix. Making one needs Python 3 and the libzim package; Pillow is optional and adds the small icon Kiwix shows. Skip this if you will only send HTML.

Check that Python 3 is installed, install libzim (and Pillow), then check that libzim imports.

You should see: Python 3. and a version, then libzim ok.

2. Make your folder

Make 00_inbox, 00_contacts and notes in this folder.

You should see: three empty folders. 00_inbox is where you drop anything you want captured: a contact card, a note about someone, an export. 00_contacts is where your people are kept. notes is for things you make. They are yours: an update to the packet never touches them.

3. Keep a note of where this came from

PACKET.md is a one-page note: this packet, from Houston Bloom. A copy goes in your folder so step 7 can log it as the first thing you received. The tools themselves stay in the packet.

Copy <packet>/PACKET.md here.

You should see: PACKET.md in your folder.

4. Copy the skills and tell them your folders

Copy <packet>/skills into .claude/skills here, then write .claude/cls.json naming my folders:
contacts, tools, manifest, spec, skills and inbox, as SETUP.md step 4 shows.

You should see: .claude/skills holding capture-connection, contacts, map, share, and .claude/cls.json with six paths. Every skill reads its folders from that file; to move a folder, change one line there.

5. Add yourself

Add me as the owner of my contacts folder: <Your Name>, <you@example.org>.

You should see:

per_your-name is the owner of this folder ("me" in intake notes).
filed    me.json: 1 people, 0 organizations, 0 exchanges

6. Make your card

Make my contact card from my record and put it in this folder.

You should see: 1 cards written to ..., and per_your-name.vcf in your folder. It is your own contact card: open it on your phone, or send it to anyone.

7. Start your manifest

/map Start my manifest: log PACKET.md as received from Houston Bloom, then map 00_contacts and notes.

You should see:

received from Houston Bloom: id 3f9a1c22
full id: 3f9a1c22...
mapped 00_contacts: private, id bb2e07e6
mapped notes: private, id 7050a4ec

The ids are random, so yours differ. The first row of your manifest is this packet, received today. It stays on your machine.

8. Add your first person

/capture-connection Sam Lee, sam.lee@example.org. Runs workshops for founders. We are working on First project together.

You should see:

filed    sam-lee.json: 1 people, 0 organizations, 0 exchanges
note     new project "First project" (prj_...); rename it in projects.json

9. Open your dashboard

Check my contacts folder, build my dashboard and my activity view, then open them.

You should see: PASS · 7 schemas describe every field and pass their own examples · 2 people ..., then 2 people · 0 organizations · 0 exchanges ..., then wrote activity.html · ..., and the dashboard with you and Sam on it. 00_contacts/activity.html is your activity: everything that passed between you and people, and everything you mapped, made, shared and got back, newest first. Rebuild it any time with the same command.

10. Share something

Log a file you made and sent. This logs the send; it sends nothing.

/share I made notes/for-sam.md for First project and sent it to Sam Lee. Log the make and the send, and record it against Sam.

You should see:

made: for-sam.md, private, id 9ebdc246
full id: 9ebdc246...
sent for-sam.md: now Sam Lee, id 9ebdc246
full id: 9ebdc246...
filed    sent-to-sam.json: 0 people, 0 organizations, 1 exchanges

and the dashboard shows the exchange with Sam.

Sending it as a ZIM instead? Only if you did the ZIM check in step 1. Pack a page, then log and send the .zim:

/share Pack notes/for-sam.html as a ZIM for Sam Lee, then log and send the .zim.

You should see: OK, the .zim path, its bytes and sha256. A FAIL line names what to fix in the page; nothing is written.

11. End a session

/map End of session: check my manifest.

You should see:

checked 4 · changed 0 · missing 0
offer a transformation note: PACKET.md, id 3f9a1c22, from Houston Bloom
offer a transformation note: for-sam.md, id 9ebdc246, sent to Sam Lee

Updating

Your folders (00_contacts, 00_inbox, manifest, notes) are yours; the packet holds only tools. To update:

Update the CLS packet at <packet> with git pull, then copy <packet>/skills into .claude/skills again.

You should see: git list the files it changed, or Already up to date. Nothing in your own folders changes.

Later

• Anything in 00_inbox. Ask: /capture-connection whatever is in 00_inbox. A contact card (.vcf) can also go straight into 00_contacts/inbox/ and be filed with node "<packet>/contacts-tools/_build/intake.mjs".
• An impact report for a person. Ask: Draft an impact report for Sam Lee. By hand: node "<packet>/contacts-tools/_build/impact.mjs" per_sam-lee. It writes to 00_contacts/reports/.
• A copy for a person. Ask: /map Make Sam Lee's redacted copy. By hand: node .claude/skills/map/map.mjs redact --to "Sam Lee" --person per_sam-lee. You should see: copy for Sam Lee: 1 times you were active together, ....
• A transformation note. Ask: /share Write the transformation note for for-sam.md. By hand: copy .claude/skills/share/transformation.md to notes/for-sam-note.md, fill it in, then node .claude/skills/map/map.mjs note notes/for-sam.md notes/for-sam-note.md.

Not built yet

• Reading from your email. Needs an email connector in your agent.
• Your activity, from your own AI history. The activity view shows what your contacts and manifest record. Adding your ChatGPT or Claude history to it is coming: the Personal Data Transformer already writes it as dated lines (evidence.jsonl).
• The community side of the dual ledger. Only a person's redacted copy runs.
• Local Assembly.