gramps
804b1d2f5f
ai.md is the mandatory read every session; at 2,702 lines / ~64k tokens it costs the whole subsystem history even when the task never touches it. This is a verbatim move, not a compression - nothing is deleted and each stub is written from the moved text. - docs/ai/frame-pipeline.md: 'Frame cadence', 'Per-element composite timing + scene dump', 'What the first instrumented take said', 'Render budget', 'Scene compositor' and 'Live frame pipeline', byte-identical, plus a short 'Related in ai.md' footer and two stale 'below' pointers corrected. - ai.md keeps two stubs carrying the invariants that must not be missed (overlay on every render path, VideoFrame.Epoch, StripPool threads, Release-only render numbers; arrival-stamped rawvideo, non-blocking submit, stop order, burned _outputIndex judge) and links the new file. - docs/ai/index.md + docs/index.md route the split; schema.md inventory lists the new tier. - 4 index-row references and 2 TASKS.md anchors repointed; ai.md's Services row too. Measured: ai.md 63.6k -> 47.1k tokens, 2,702 -> 1,975 lines. Progressive disclosure per schema.md convention 5. No source touched; no push.
62 lines
3.9 KiB
Markdown
62 lines
3.9 KiB
Markdown
# 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? |
|
|
|------|------|--------------|
|
|
| `AGENTS.md` | Auto-read on-ramp for AI sessions — points to the map and the working rules | **always read first** |
|
|
| `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` | **Catalog/index** for the task queue. The actual task files live in [`TASKS/`](TASKS/) (one file per task); `TASKS.md` carries the status table, open items, and research facts pointer. Read this for queue state; open task files for full detail. | yes — for status |
|
|
| `HANDOFF.md` | Current operational state: what's in flight, landmines, next step, secret/DB/port locations | yes — trust it as current state |
|
|
| `MyMistakes.md` | Per-task failure log **+ RECIPES REGISTRY** (derived-solution rule): one-off solutions / how-tos get recorded here the same session, then grepp'd before ever re-deriving them (see `AGENTS.md` 🔬) | grep first on any "did this before?" wall |
|
|
| `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 |
|
|
| `docs/ai/*.md` | **Split-out subsystems** of `ai.md` — verbatim moves (from 2026-10-26); `ai.md` keeps a short invariant stub + link, and [`docs/ai/index.md`](docs/ai/index.md) routes | when the task touches a moved subsystem |
|
|
| `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. `AGENTS.md` — auto-read on-ramp; it points you here.
|
|
2. `ai.md` — what this app is, how it's built, current state, open decisions.
|
|
3. `TASKS.md` — what's done, what's next, and the YouTube API constraints.
|
|
4. `<dir>/index.md` — to understand a directory before reading its files.
|
|
5. The source files themselves — always the authority over any memory file.
|
|
|
|
## Integration rule
|
|
|
|
Every feature change ships with its memory update **in the same commit**:
|
|
`ai.md` for architecture / patterns, `TASKS.md` for status, index files when
|
|
the layout changes. No code commit without its docs — a follow-up "docs
|
|
backfill" commit is a broken rule, not a style. That is what keeps the map
|
|
accurate enough to trust next session.
|