# CAM Usage Workflow

Step-by-step order for moving Cursor agent context between workstations.

**Repository:** <https://git.p7net.ru/tools/cam.git>  
**Version:** 0.1.0 (in development)

---

## Context codes (readable names)

Each agent session gets a **context code** stored in `registry.yaml`:

| Code type | Example | Meaning |
|-----------|---------|---------|
| Auto main | `w1-1`, `w2-110` | `{workstation.index}-{seq}` |
| Auto subagent | `w1-11.1` | `{parent}.{seq}` |
| Manual | `w1.git.001`, `sync-crm3` | Assigned by operator |

Markdown files use readable names for Cursor `@`:

```
docs/cursor_agents/markdown/w1-11--Из-исходной-базы-в-целевую.md
docs/cursor_agents/markdown/w1.git.001--sync-analysis.md
```

**Re-export updates the same file** for a given code (consolidated/enriched context overwrites in place).

In a new Cursor chat:

```
@docs/cursor_agents/markdown/w1-11--Из-исходной-базы-в-целевую.md
```

or reference by code:

```
Context w1-11 — continue transfer of customer orders.
```

---

## One-time setup (each workstation)

### 1. Clone CAM

```bash
git clone https://git.p7net.ru/tools/cam.git tools/cam
pip install -r tools/cam/requirements.txt
```

### 2. Workstation config

```bash
cp tools/cam/config/workstations/macos.example.yml tools/cam/config/workstations/local.yml
```

Required fields:

```yaml
workstation:
  id: "nt-041"
  index: "w1"          # w1, w2, … — prefix for auto codes

context:
  prefix_workstation: true    # w1-1 (true) or 1 (false)
  auto_format: "{ws}-{seq}"
  subagent_format: "{parent}.{seq}"

registry:
  file: "registry.yaml"
```

### 3. Verify

```bash
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml paths
```

---

## Before leaving a workstation

```bash
# all contexts
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export

# one context
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export --context w1-11

# by mask
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml export --mask 'w1-*'
```

Commit project archive:

```bash
git add docs/cursor_agents/
git commit -m "Export Cursor agent contexts (w1)"
git push
```

---

## On a new workstation

```bash
git pull
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
# or selective:
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml import --mask 'w1-*'
```

Close Cursor before import. For new agent work, prefer `@markdown/w1-11--….md`.

---

## Manual context codes

```bash
# list all codes
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code list

# rename w1-11 → thematic code
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code set w1-11 w1.git.zakaz

# show details
python tools/cam/cam.py -c tools/cam/config/workstations/local.yml code show w1.git.zakaz
```

Rules for manual codes: letters, digits, `.`, `-`, `_` (e.g. `w1.git.001`, `sync-crm3`).

To drop workstation prefix in **new** auto codes only:

```yaml
context:
  prefix_workstation: false
  auto_format: "{seq}"
```

Existing codes in `registry.yaml` are not renamed automatically.

---

## Command reference

| Command | Description |
|---------|-------------|
| `export` | Cursor → project archive |
| `import` | project archive → Cursor |
| `list` | List contexts in archive |
| `code list` | List codes from registry |
| `code set TARGET NEW` | Assign/rename code |
| `code show CODE` | Show context record |
| `paths` | Resolved paths |

Flags: `--context CODE`, `--mask PATTERN` (glob: `w1-*`, `*.git.*`).

---

## Archive layout (0.1.0)

```
docs/cursor_agents/
├── registry.yaml          # codes ↔ session UUID ↔ file paths
├── INDEX.md
├── manifest.json
├── raw/                   # JSONL by session UUID (for Cursor import)
└── markdown/
    ├── w1-1--topic.md     # @-friendly names
    └── subagents/
        └── w1-1.1--topic.md
```

---

## Security

Do not commit workstation `local.yml` with secrets to public repos.  
Agent transcripts may contain business data — keep `docs/cursor_agents/` in your private project repo.