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>
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user