Peter Steinberger be315dd311

docs: add clawdex.sh feature pages and Rolodex-themed site

Adds 14 per-feature docs pages under docs/ covering install, quickstart,
people, notes, timeline, search, avatars, imports, vCard export, git
sync, markdown storage, doctor, and config. Replaces the placeholder
landing page with a single-page Rolodex/index-card site that fetches and
renders the docs client-side via marked + highlight.js, with code syntax
highlighting and dark-mode support. .nojekyll keeps GitHub Pages serving
the markdown files raw to the SPA.

2026-05-08 16:50:41 +01:00

3.1 KiB

Raw Permalink Blame History

Git Sync

Your contacts data repo is just a Git repo. Clawdex doesn't run a sync daemon, doesn't talk to a clawdex.sh server, and doesn't store anything about you remotely. Backup and multi-device sync are 100% Git.

The default suggested remote is a private GitHub repo:

https://github.com/<you>/backup-clawdex.git

You set this once in Quickstart with:

clawdex config set git.remote https://github.com/<you>/backup-clawdex.git

`clawdex git` commands

All four commands run inside the data repo, not the clawdex source repo. They're thin wrappers around git so you don't have to cd constantly.

Status

clawdex git status

A wrapper for git -C <repo> status --short --branch. Same output, same exit codes. Use this before committing to see what an import or edit changed.

Commit

clawdex git commit
clawdex git commit -m "sync: import google contacts"

Stages everything modified under the data repo and commits with the provided message. The default message is sync: update clawdex contacts. Returns whether a commit was actually created — if there were no changes, committed: false.

Pull

clawdex git pull

Pulls from the configured remote on the configured branch. Resolve conflicts the way you'd resolve them in any other repo.

Push

clawdex git push

Pushes to the configured remote on the configured branch. The first push on a fresh repo also sets the upstream.

Choosing a remote

Anything Git-hostable works:

Private GitHub repo — recommended; integrates with GitHub Mobile if you want to read your notes on a phone.
Self-hosted — Forgejo, Gitea, sourcehut, a bare repo over SSH.
Local-only — leave git.remote unset and clawdex won't push. The repo is still version-controlled locally.

Whatever you pick, the remote should be private. The data is plain markdown — names, phone numbers, emails, conversation snippets. Treat it like a journal.

Multi-device

The flow on a second machine is the same as on the first:

brew install steipete/tap/clawdex
git clone https://github.com/<you>/backup-clawdex.git ~/.clawdex/contacts
clawdex config set repo_path ~/.clawdex/contacts
clawdex config set git.remote https://github.com/<you>/backup-clawdex.git
clawdex git pull
clawdex doctor

Day-to-day:

clawdex git pull
# ... edit, import, add notes ...
clawdex git commit -m "sync: ..."
clawdex git push

Conflicts are normal Git conflicts. Markdown frontmatter merges predictably; if a frontmatter merge ends up malformed, run clawdex doctor --repair to salvage it.

Encryption

vanilla clawdex git does not encrypt the repo. The data lives as plaintext markdown both locally and on the remote. If you need encryption at rest:

Use a private remote you trust.
Or layer git-crypt / age over the data repo manually.
Or back up encrypted snapshots out-of-band, alongside Git.

A built-in encrypted backup mode (à la gog backup) is on the roadmap but not shipped.

3.1 KiB Raw Permalink Blame History