diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 99aa2712..f1aa3ead 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -22,11 +22,30 @@ npm run test:e2e       # E2E tests (optional, requires a live test repo)
 
 ### Running your local build
 
+Work in the **CLI clone**, not as `teamai init .`.
+
 ```bash
-npm link
-teamai --version
+npm run build && npm link
+teamai init https://github.com/teamai-hub/teamai-cli-dev --scope project --role dev
+teamai pull
+git status   # nothing under .teamai/ or tool dirs should be staged for this repo
 ```
 
+Documented pitfalls:
+
+- Init the **canonical hub URL**, not a personal fork. `teamai init <url>` treats that URL as the team repo; a fork diverges immediately, and GitHub push/PR today targets the configured remote (no fork-to-upstream flow).
+- Do **not** run `teamai init .`. That is single-repo mode: it turns the CLI source tree into the team repo and writes scaffolding at the repo root (easy to commit by mistake).
+- `Push failed (you can push manually later)` on member registration is **expected** without write access. Local config is still saved; `teamai pull` still works.
+
+`digest` / `dashboard` read `stats/`, `sessions/`, and `members/` from the team repo. Those files are written via git, so **no write ⇒ not in team stats**. Giving every internet contributor write on the hub repo is not acceptable.
+
+| Who | Hub repo access | Required setup | In team digest |
+| --- | --- | --- | --- |
+| Contributors | read | `init` + `pull` | no |
+| Collaborators (after a few PRs) | write, `main` protected | full, including reports | yes |
+
+`git status` after init does not imply committing TeamAI local files into `teamai-cli`. Do not stage `.teamai/` or tool dirs.
+
 ## Project Layout
 
 ```
@@ -43,7 +62,7 @@ See [docs/providers.md](../docs/providers.md) for how to add a new git provider.
 
 ## Making a Change
 
-1. Fork the repo and create a feature branch from `master`.
+1. Fork the repo and create a feature branch from the latest `origin/main`. Prefer a git worktree for code changes.
 2. Write tests for your change (we target 80%+ coverage).
 3. Run `npx vitest run` and `npx tsc --noEmit` — both must pass.
 4. Use conventional commits where possible: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`.