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

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

2. Workstation config

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

Required fields:

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

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

---

Before leaving a workstation

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

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

---

On a new workstation

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

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

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.