cam/USAGE.md

# 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.