# sharedoc — notes for agents

`sharedoc` is the CLI for share-doc (https://sharedoc.brightmotion.io). It is designed to be driven by you, not by a human
at a prompt.

- **Always pass `--json`.** stdout is then exactly one JSON document — successes and errors alike.
- **Scope first:** `sharedoc whoami --json` tells you the user, the workspaces, the projects and
  the server. Then use `--workspace <slug>` / `--project <slug>`.
- **Read before you write:** `files list`, `files cat`, `files history`, `events tail`.
- **Headless auth:** set `SHAREDOC_TOKEN` (plus `SHAREDOC_HTTP` for a non-default host). Env
  beats the stored config. Never print a token.
- **Attribution:** `--as-agent claude-code --as-model opus-5` (or `SHAREDOC_AGENT` /
  `SHAREDOC_MODEL`) records the write as "Justin · via claude-code (opus-5)". Pass the model you
  are actually running. You act as the human; permissions are theirs.
- **Every project's `sharedoc-instructions.md` is its manual.** Read it before working in a
  project; after a `sync add` / `connect`, add the pairing (repo, folder, command) to its
  "Where this project is synced" table with `files put --base`, so the next clone knows.

Exit codes:

| Code | Name | Meaning |
|---|---|---|
| 0 | `ok` | success |
| 1 | `usage` | bad arguments/flags |
| 2 | `auth` | not logged in, token revoked, or write scope required |
| 3 | `not_found` | workspace/project/file/thread not found |
| 4 | `conflict` | overlapping edits under --strict, or a stale --if-version (412) — nothing was written; re-read and retry |
| 5 | `rate_limited` | slow down; retry after the hinted seconds |
| 6 | `server` | server or network error |
| 7 | `timeout` | --wait ran out with the draft set still open — ask again later |

Full skill (copy into `~/.claude/skills/sharedoc/SKILL.md`): https://sharedoc.brightmotion.io/skill.md
Setting share-doc up for a repo, start to finish: https://sharedoc.brightmotion.io/setup.md
Command reference: https://sharedoc.brightmotion.io/docs/cli · live contract: https://sharedoc.brightmotion.io/api/v1/schema