# ATVM Workspace Conventions

## File Roles
- `guide.md`
  - authoritative workflow rules, defaults, and checklists
- `examples.md`
  - reusable command examples only
- `run-learnings.md`
  - dated lessons captured only when a run produced a new lasting insight
- `inventory/*.md`
  - durable environment reference and listings
- `archive/imported-notes/*.md`
  - preserved source material kept for completeness and traceability

## Update Policy
- Update `docs/setup/guide.md` when setup/bootstrap workflow behavior changes.
- Update `docs/automation/guide.md` when automation workflow behavior changes.
- Update `docs/automation/examples.md` when a reusable example pattern changes.
- Update `run-learnings.md` files only when a run created a new lesson worth preserving.
- Keep inventory details in `inventory/` rather than mixing them into workflow guides.

## Path Conventions
- Prefer actual repo paths under `/home/aw/code/cds/atvm/...` in documentation.
- Keep top-level navigation in `README.md` and `AGENTS.md`.
- Keep executable assets under `scripts/`.

## Archive Policy
- Preserve imported long-form notes under `archive/imported-notes/`.
- Do not rely on archived notes as the primary operational runbook when a current guide exists.
- Keep detailed listings available; reorganization should improve navigation, not remove information.