diff --git a/CHANGELOG.md b/CHANGELOG.md index 779fd9e..4468ab9 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index b970527..78f885b 100644 --- a/README.md +++ b/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 diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..b11f6f6 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,181 @@ +# CAM Usage Workflow + +Step-by-step order for moving Cursor agent context between workstations. + +**Repository:** +**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 " +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 . Context was exported from workstation . +``` + +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.