Add USAGE.md with step-by-step workflow for workstation handoff.

Link from README; document export/import cycle and troubleshooting.

Co-authored-by: Cursor <cursoragent@cursor.com>

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to **CAM (Cursor Agents Manager)** are documented in this fi
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+### Added
+
+- `USAGE.md` — step-by-step workflow (setup, export, import, daily sync between workstations)
+
 ## [0.0.1] - 2026-07-10
 
 ### Status

README.md

@@ -28,6 +28,8 @@ pip install -r requirements.txt
 
 ## Quick start
 
+See **[USAGE.md](USAGE.md)** for the full step-by-step workflow (setup, export before leaving a workstation, import on a new machine).
+
 ### 1. Clone CAM into your project
 
 ```bash

USAGE.md

@@ -0,0 +1,181 @@
+# CAM Usage Workflow
+
+Step-by-step order for moving Cursor agent context between workstations.
+
+**Repository:** <https://git.p7net.ru/tools/cam.git>  
+**Version:** 0.0.1 (in development)
+
+---
+
+## One-time setup (each workstation)
+
+### 1. Clone CAM into the project
+
+From the **consumer project root** (e.g. `crm3-migration`):
+
+```bash
+git clone https://git.p7net.ru/tools/cam.git tools/cam
+cd tools/cam
+pip install -r requirements.txt
+```
+
+### 2. Create a local workstation config
+
+```bash
+cp config/workstations/macos.example.yml config/workstations/local.yml
+# Windows: cp config/workstations/windows.example.yml config/workstations/local.yml
+```
+
+Edit `config/workstations/local.yml`:
+
+| Key | Set to |
+|-----|--------|
+| `workstation.id` | Short ID for this PC (e.g. `nt-041`, `office-pc`) |
+| `project.root` | **Absolute** path to the project opened in Cursor |
+| `export.output_dir` | Usually `docs/cursor_agents` |
+| `export.index_language` | `en` or `ru` |
+
+`local.yml` is **gitignored** — never commit real paths to the public CAM repo.
+
+### 3. Verify paths
+
+```bash
+python cam.py -c config/workstations/local.yml paths
+```
+
+Check `transcripts_dir` points to your Cursor `agent-transcripts` folder.
+
+---
+
+## Before leaving a workstation (save context)
+
+Run from the **project root**:
+
+```bash
+source .venv-nt-041/bin/activate   # or your project venv
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export
+```
+
+This updates in the project:
+
+- `docs/cursor_agents/raw/` — JSONL transcripts
+- `docs/cursor_agents/markdown/` — readable exports
+- `docs/cursor_agents/manifest.json`, `INDEX.md`
+
+Commit and push the **consumer project** repository:
+
+```bash
+git add docs/cursor_agents/
+git commit -m "Export Cursor agent history from <workstation-id>"
+git push
+```
+
+---
+
+## On a new workstation (restore context)
+
+### 1. Clone the consumer project
+
+```bash
+git clone https://git.p7net.ru/rhana/crm3-migration.git crm3-26
+cd crm3-26
+```
+
+See the project’s `docs/meta/REPOSITORIES.md` for other required clones (configs, `tools/run_bsl`, etc.).
+
+### 2. Set up CAM (one-time on this PC)
+
+```bash
+git clone https://git.p7net.ru/tools/cam.git tools/cam
+cp tools/cam/config/workstations/macos.example.yml tools/cam/config/workstations/local.yml
+# edit project.root to this machine’s absolute path
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml paths
+```
+
+### 3. Import into Cursor (optional — chat sidebar)
+
+**Close Cursor completely**, then:
+
+```bash
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import --dry-run
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import
+```
+
+Re-open Cursor. Existing local files are **not** overwritten unless `import.overwrite_existing: true` in config.
+
+### 4. Continue work with the agent (recommended)
+
+In a new Cursor Agent chat:
+
+```
+@docs/cursor_agents/INDEX.md
+Continue work on <topic>. Context was exported from workstation <id>.
+```
+
+This works reliably across machines; UI import is best-effort.
+
+---
+
+## Daily cycle (two-way sync)
+
+```
+Workstation A                          Workstation B
+─────────────                          ─────────────
+  export                                 git pull
+  git commit + push          ──────►    import (optional)
+                                         work…
+  git pull                   ◄──────    export
+  import (optional)                    git commit + push
+  work…
+  export …
+```
+
+| Step | Command | Direction |
+|------|---------|-----------|
+| **export** | `python tools/cam/cam.py -c …/local.yml export` | Cursor local → project archive |
+| **import** | `python tools/cam/cam.py -c …/local.yml import` | project archive → Cursor local |
+
+---
+
+## Command reference
+
+All commands use `-c` **before** the subcommand:
+
+```bash
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml paths
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml list
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import --dry-run
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import
+```
+
+---
+
+## CRM3-26 / crm3-migration example
+
+```bash
+# nt-041 (macOS) — template
+cp tools/cam/config/workstations/nt-041.example.yml tools/cam/config/workstations/local.yml
+# set project.root: /Users/you/projects/crm3-26
+
+python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export
+git add docs/cursor_agents/ && git commit -m "Export Cursor agent history" && git push
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Check |
+|---------|--------|
+| `Transcripts folder not found` | Open project in Cursor once; run `paths`; fix `project.root` |
+| Wrong slug / empty transcripts | `project.root` must match the path Cursor uses exactly |
+| Import skips files | Set `import.overwrite_existing: true` or delete old local transcripts |
+| Chats not in sidebar after import | Use `@docs/cursor_agents/INDEX.md` — UI restore is not guaranteed |
+
+---
+
+## Security
+
+- Do not commit workstation configs with secrets to `cam.git`.
+- Agent transcripts may contain business data — treat `docs/cursor_agents/` like project documentation in your private migration repo.