Swarm Structure and File-Type Policy¶
The canonical layout contract for swarm folders. Where references, recordings, and experiments live, and what file types each accepts.
flowchart LR
ref[references/ · durable sources] --- rec[recordings/ · run logs]
rec --- exp[experiments/ · executable outputs]
ref --> readme[README + .gitkeep allowed everywhere]Read next
- Map — the canonical visual of the layout
- Human's guide — what to read first
- How to swarm — operational guide
- Patterns — writing conventions
Layout contract — referenced by maintenance and validation tooling.
This file is the canonical layout contract for swarm folders that hold reusable references and run recordings.
Intent¶
- Keep durable source references separate from run artifacts.
- Keep recordings reproducible without storing heavy raw media in git.
- Make file-type expectations explicit so maintenance can validate them.
Folder Roles¶
references/: curated external-source notes, citations, and structured reference metadata.recordings/: session/run transcripts, observation logs, and pointer metadata for non-text captures.experiments/: executable experiment outputs and result artifacts.
Allowed File Types¶
references/:.md,.json,.txt,.csv,.tsv,.bib,.yml,.yamlrecordings/:.md,.json,.txt,.csv,.tsv,.log,.yml,.yaml- Shared exceptions:
README.md,.gitkeep
Any other extension in these folders should be treated as out-of-policy and flagged by maintenance.
Naming Guidance¶
- Use stable, searchable names:
<topic>-s<session>.<ext>when tied to a swarm session. - Use date-prefixed names for chronological recordings:
<yyyy-mm-dd>-<topic>-s<session>.<ext>. - Keep topic slugs lowercase with hyphens.
Raw Media Handling¶
- Do not commit large raw audio/video captures into
recordings/. - Store raw media outside the repo and commit a small pointer record (
.mdor.json) with: - capture date/time
- source location (path/URL)
- checksum if available
- short interpretation notes