# Set up share-doc — a runbook for agents

You are setting up [share-doc](https://sharedoc.brightmotion.io) for your human: the CLI installed and logged in, a project,
this repo's `docs/` folder paired with it and kept live by a background service. Follow the steps in
order; each one says how to check it worked. Pass `--json` to every `sharedoc` command: stdout is
then exactly one JSON document, errors included, and the exit code means something.

## 1. Ask first, in one message

Before you run anything, ask your human these together, so they answer once. Skip any they already
answered.

1. **Workspace** — which share-doc workspace this belongs in (they tick it on the login page).
2. **Project** — an existing one (its slug, from the address bar: `/p/<slug>`) or a new one: its name, *private* (only people they add) or *workspace* (everyone in the workspace), and whether it gets its own chat channel.
3. **Folder** — default `<repo>/docs`. Never the repo root: it would upload the README and the source.
4. **Keep it running?** — the sync as a background service (recommended: starts at login, restarts if it dies) or a one-off `connect` in a terminal.
5. **Chat mirror?** — every channel they can see, written read-only to `~/sharedoc/chat/` as markdown, so you can read the discussion.

Say what you will do with the answers, then go. Everything below is yours to run; the only thing
they do is approve the login in their browser.

## 2. Install the CLI

```bash
curl -fsSL https://sharedoc.brightmotion.io/install.sh | sh                     # macOS / Linux (installs Bun too if missing)
powershell -c "irm https://sharedoc.brightmotion.io/install.ps1 | iex"          # Windows — then open a new shell for PATH
sharedoc --version
```

Already installed? `sharedoc update` brings it current.

## 3. Log in — you run it, they approve

```bash
sharedoc whoami --json                 # exit 0 with a login for the workspace: skip to step 4
sharedoc login --no-wait --json        # → { url, codeTtlSeconds, next }
```

Send your human the `url` and tell them: *open it, tick the workspace, choose
**Write**, press Authorize, and paste me the code it shows.* The code starts with `sd_code_` and is
good for 5 minutes. Then:

```bash
sharedoc login --code <sd_code_…> --json
sharedoc whoami --json                 # the workspace is there, scope write
```

- Expired or mistyped code: run `sharedoc login --no-wait --json` again for a fresh link.
- *already logged in*: `whoami` shows what is there. If it is the right workspace with write
  scope, keep it. If not, add `--force` to both login commands (the old tokens are revoked once
  the new ones arrive).
- If your shell can keep a process running and write to its stdin later,
  `sharedoc login --no-browser --json` does the same in one command: it prints the URL on stderr
  and waits for the code on stdin.
- Only if you can do neither, ask the human to run `sharedoc login` in their own terminal.
- Never print, log or commit a token, and never invent one.

## 4. The project

```bash
sharedoc projects list --workspace <workspace> --json
```

Use the slug they named. For a new one:

```bash
sharedoc projects create "<name>" --workspace <workspace> --json                 # whole workspace, with a channel
sharedoc projects create "<name>" --workspace <workspace> --private --no-channel --json
```

`project.slug` and `project.url` in the reply are what you use from here on.

Read the project's manual before you change anything in it — it may already record how this repo
is paired:

```bash
sharedoc files cat <project> sharedoc-instructions.md
```

## 5. Pair the folder

An empty or missing folder is filled from the project; a folder with files pushes what the project
doesn't have yet, **straight away**. So look first:

```bash
find <repo>/docs -type f -not -path '*/.*' | wc -l
du -sh <repo>/docs
```

Over 50 files or 20 MB: show your human what is there, folder by folder, and offer to keep some of it
local with a `<repo>/docs/.sharedocignore` (gitignore syntax; the sync does not read `.gitignore`,
and it already skips dotfiles, lockfiles and build output). Pair once they agree to what goes up:

```bash
sharedoc sync add <project> <repo>/docs --workspace <workspace> --json
```

It prints the files it sends on stderr; `firstPush` in the reply counts them. If the reply has an
`approval`, the workspace has large files turned off and holds a push that big until someone
approves it: tell your human, and run `approval.command` only on their say-so (or they approve at
`approval.url`). Adding `--yes` to `sync add` sends it at once instead — again, only once they
agreed to the list.

## 6. Make the repo agree

`docs/` now lives in share-doc, not in git. Follow the repo's own workflow for this change (a branch
and a pull request, if that is how the repo works):

1. Add to `.gitignore`:

   ```gitignore
   # docs/ lives in share-doc (synced by the sharedoc CLI), not in git
   /docs/
   ```

2. If git already tracks `docs/`, untrack it — after the first sync succeeded, never before:
   `git rm -r --cached docs`. The files stay on disk.

3. Paste this section into the repo's `CLAUDE.md` or `AGENTS.md` (the copy in the project's
   `sharedoc-instructions.md`, under *Make the repo agree*, has the channel filled in — prefer it):

````markdown
## `docs/` is synced, not committed

`docs/` is a share-doc folder paired with the `<project>` project (https://sharedoc.brightmotion.io). It is gitignored
on purpose: a background daemon (`sharedoc sync run`) pushes local edits up and pulls remote edits
down within seconds. Edit files under `docs/` normally — no commit, no push. Re-read a file right
before editing it; it changes under you when someone edits it in the web app. Leave
`docs/.share-doc/` alone. How this repo is paired: `docs/sharedoc-instructions.md`.

The chat about the project is mirrored read-only under `~/sharedoc/chat/` (`sharedoc sync add --channels`).
Post with `sharedoc channel post <channel> --project <project> --body "…"`, answer a post with
`sharedoc thread reply <thread-id>`, and add `--as-agent <agent> --as-model <model>` to every write.
Etiquette: https://sharedoc.brightmotion.io/skill.md.
````

## 7. Keep it running

```bash
sharedoc sync install --json           # launchd on macOS, systemd --user on Linux
sharedoc sync status --json            # every pair says live, no lastError
```

- One-off instead (they said no service): `sharedoc connect <project> <repo>/docs`, which runs until
  stopped. Never run both on the same folder.
- On Windows there is no service yet: `sharedoc sync run` in a terminal that stays open.
- Chat mirror, if they wanted it: `sharedoc sync add --channels --workspace <workspace> --json`, then
  `sharedoc sync status --json` again.

Save the skill where you keep skills, so the next session knows the etiquette (reading before
writing, threads, drafts). For Claude Code:

```bash
mkdir -p ~/.claude/skills/sharedoc && curl -fsSL https://sharedoc.brightmotion.io/skill.md > ~/.claude/skills/sharedoc/SKILL.md
```

## 8. Record the pairing, then report

Add a row to the *Where this project is synced* table in `sharedoc-instructions.md`: the repo, the
folder relative to the clone (`docs/`), the exact `sync add` command, who and when. With the
service running, edit `<repo>/docs/sharedoc-instructions.md` in place (re-read it first). Otherwise:

```bash
sharedoc files list <project> --json     # the manual's current version
sharedoc files put <project> sharedoc-instructions.md --from <edited copy> --base <version> --message "record pairing: <repo>/docs" --as-agent <agent> --as-model <model> --json
```

Then tell your human what you did, in a few lines: the project and its URL
(`https://sharedoc.brightmotion.io/p/<project>`), the folder and how many files went up, whether the service and the chat mirror
are on, and the repo change you made (or the pull request). Say plainly if a step failed or was
skipped, and why.

---

Day-to-day use (reading, commenting, chat, drafts): https://sharedoc.brightmotion.io/skill.md · Command reference: https://sharedoc.brightmotion.io/docs/cli