Skip to content

setup-guide.md

Latest commit

 

History

History
151 lines (120 loc) · 6.82 KB

setup-guide.md

File metadata and controls

151 lines (120 loc) · 6.82 KB
Raw

Set up your union in an afternoon

A practical, no-jargon walkthrough for an organizer. By the end you'll have an encrypted case on your own device, captured media with RFC 3161 tokens, a second organizer synced peer-to-peer, and a technically verified review packet. Authority trust requires an accepted certificate anchor, and no court/inspector usefulness has been validated. Nothing leaves your devices as plaintext, and there is no account to create.

Alpha software. habitable works end to end, but it is not yet proven for real legal matters. Practice with the steps below before relying on it, and read Honest limits.

0. What you need (15 min)

  • A laptop (or two) per organizer. Phones come later via the app.
  • uv installed. The right Python (3.14) is fetched for you.
  • A strong passphrase per device, written down somewhere safe. If you lose it with no backup, the data is gone — by design, no one can recover it for you.
$ git clone https://github.com/ChelseaKR/habitable && cd habitable
$ uv sync
$ uv run habitable --help

1. See it work first (5 min)

$ uv run habitable demo

This fabricates a couple of photos, captures them as evidence, builds a packet (with location stripped from the shared copies), and verifies it — all offline, with no real data. The demo explicitly pins its synthetic RFC 3161 certificate; when all three claims read intact, trusted, and READY, the synthetic toolchain is healthy. That synthetic certificate is not a production trust decision.

2. Create a case (10 min)

$ export HABITABLE_PASSPHRASE='choose-a-strong-one'   # or you'll be prompted
$ uv run habitable init ./case-4B --case bldg-12 --unit 4B
$ uv run habitable id --vault ./case-4B               # note your fingerprint + public-id

Two IDs print here. Your fingerprint is a short code for this device — the same value the app shows under Device ID. Your public-id is the address another organizer uses to sync with you. Write both down.

Open ./case-4B/config.toml to set the wording for your area ([packet_template]) and confirm the sharing defaults (location is removed from shared copies by default).

3. Document an issue (30 min)

$ uv run habitable issue   --vault ./case-4B --category mold --room bathroom --title "Black mold"
$ uv run habitable capture ./photos/ceiling.jpg --vault ./case-4B --issue <issue-id>
$ uv run habitable timeline --vault ./case-4B --issue <issue-id> \
    --type notice_sent --occurred-at 2026-01-02 --source message \
    --text "Emailed landlord requesting repair"
$ uv run habitable status   --vault ./case-4B

Offline is fine. Each capture is sealed and fingerprinted right away, and a timestamp token is queued for when you have a connection. Once you're back online, run habitable resolve --vault ./case-4B to add the waiting tokens. Recipients must still verify each token against an authority certificate they trust.

Prefer a screen? Run the local app (accessible, English/Español) and use a laptop or desktop browser on the same machine. In the app:

  1. choose or add a condition under Rooms + conditions;
  2. add a Photo, What happened entry, or Document;
  3. compare Reported (the date someone says it happened) with Secured (when Habitable added the record);
  4. open Check this entry to see what is asserted and what can be checked;
  5. use What happened next? to add notice, response, repair, or recurrence; and
  6. choose Prepare a copy only when you are ready to review what would leave the device.

The CLI keeps the established issue, capture, and timeline command names; the app groups those records into a condition-first Repair Trail. The alpha has no supported phone package; do not expose this unlocked server over a LAN (see docs/mobile.md):

$ uv run habitable app --vault ./case-4B

4. Sync with another organizer (20 min)

Each organizer runs habitable id and shares their public-id. First, read your fingerprints to each other another way — by phone or in person — and check that they match. Pair the devices for this exact case, then sync over a shared folder (USB or a cloud drive) or through a relay.

# Create signed, recipient-sealed pairing material; the peer accepts the file:
$ uv run habitable sync-pair-create --vault ./case-4B --peer <their-public-id> --out ./peer.hpair
$ uv run habitable sync-pair-accept --vault ./case-4B --in ./peer.hpair
# Folder transport (no server):
$ uv run habitable sync --vault ./case-4B --peer <their-public-id> --channel 4B-room --dir /path/to/shared
# Or run your own relay. It only ever sees scrambled data — never your photos or text:
$ uv run habitable relay --host 0.0.0.0 --port 8787
$ uv run habitable sync --vault ./case-4B --peer <their-public-id> --channel 4B-room --relay http://<host>:8787

Both sides end up with the same case, and no edits are lost. The relay can read nothing.

No network at all? Hand the case over on a USB stick or SD card:

# Write an encrypted delta sealed to your peer onto the stick:
$ uv run habitable sync-export --vault ./case-4B --peer <their-public-id> --out /Volumes/USB/delta.hsync
# The recipient merges everything on the stick (a folder glob works too):
$ uv run habitable sync-import --vault ./case-4B /Volumes/USB/*.hsync

No relay, no data plan; a lost stick leaks nothing. See docs/sneakernet-sync.md for the full walkthrough.

5. Export and verify a packet (15 min)

$ uv run habitable export --vault ./case-4B --out ./4B-packet
$ uv run habitable verify ./4B-packet --trusted-cert ./independently-obtained-tsa-root.pem
habitable: integrity: intact; timestamp authority: trusted (N/N items); evidence readiness: READY

Hand the recipient ./4B-packet (the bundle.json, the media/, and packet.pdf). Anyone — including the opposing side — can run habitable verify to confirm nothing was altered. The recipient must obtain and assess the timestamp authority certificate independently; without it, Habitable can confirm token mechanics but reports authority trust and evidence readiness as false. The shared copies carry no location; the sealed originals stay encrypted in your vault.

Good habits

  • Keep an encrypted backup of each vault, and write down the recovery passphrase.
  • Check each other's fingerprint another way — by phone or in person — before you sync.
  • Re-export and re-verify before any court filing. The packet format and the way it is checked are versioned, so old packets keep verifying.
  • This produces documentation, not legal advice. Work with your tenant attorney or legal-aid group on what to file and when.