# ytLlive — Memory Map (schema)

This file defines how the repo stores durable, associative memory: context as
plain markdown files, versioned in git. It is the map of the map — the schema
that every other memory file follows. Read `ai.md` first; this file explains
*why* and *how*.

## Why markdown files, not a database

- Grep-able, diffable, portable, human-editable — no tooling lock-in.
- Git gives versioning and history for free; every stale fact is a `git log` away.
- Files form a graph: each file is a node, each relative link an edge. The map
  stays associative (like memory) rather than a rigid tree.

## File inventory

| File | Role | Entry point? |
|------|------|--------------|
| `README.md` | Human-facing intro: what the app is, how to run it, roadmap | no |
| `ai.md` | **AI guide + session handoff** — architecture, patterns, decisions, the cognitive map home | **yes — start here** |
| `TASKS.md` | Task queue + authoritative YouTube API research facts + task statuses | yes — for status |
| `schema.md` | This file: the conventions below | when in doubt |
| `<dir>/index.md` | Per-directory map (progressive disclosure): what lives there + links | when diving into code |
| `Views/` | Reserved for Views; currently empty | — |

## Conventions

1. **Semantic filenames.** A file's name says what it is (`YouTubeAuthService.cs`,
   `FocusPreservingListBox.cs`). No codes, no abbreviations. Naming beats search.
2. **One `index.md` per code directory.** The index is a Map of Content (MOC):
   it lists every file in that directory with a one-line purpose and links out to
   related directories. Details live in the files, never duplicated in the index.
3. **Links over hierarchy.** Prefer relative links between related files over
   deep nesting. Relationships that matter should be visible from `ai.md` or an
   `index.md`; a note that is unreachable from `ai.md` might as well not exist.
4. **Stale facts get FIXED, not appended.** A wrong map is worse than no map.
   When the code changes, update the memory file in the same change — no
   "TODO: update later" notes.
5. **Progressive disclosure.** Don't cram detail into `ai.md`. `ai.md` names
   concepts and points at files; the indexes and source are the detail. Each
   layer adds resolution only when you drill in.

## Reading order

1. `ai.md` — what this app is, how it's built, current state, open decisions.
2. `TASKS.md` — what's done, what's next, and the YouTube API constraints.
3. `<dir>/index.md` — to understand a directory before reading its files.
4. The source files themselves — always the authority over any memory file.

## Integration rule

Every feature change ships with its memory update: `ai.md` for architecture /
patterns, `TASKS.md` for status, index files when the layout changes. That is
what keeps the map accurate enough to trust next session.