convert pdf to md, add OVERVIEW and docs

worker-toolkit-stocks-in-the-future/repo/docs/map/AGENTS.md

@@ -0,0 +1,50 @@
+# Stocks in the Future — system map
+
+An edit map of this Rails app: what the nouns are, how they move, and what else moves
+when you change one. **The app tree is the source of truth** — cards cite `path:line`
+and never restate behaviour. Read a card, then read the source it points at.
+
+Built on ICM: folders carry sequencing, hierarchy carries context, files carry state.
+
+## Where things live
+
+| Folder | What it holds |
+|---|---|
+| `objects/` | one card per noun, clustered by how an editor asks |
+| `processes/` | the six movements that actually run |
+| `effects/` | change-impact index — "changing X? open these cards" |
+| `_meta/` | schema: the closed set of node types and labels |
+| `_templates/` | blank object/process cards — a new card is a copy |
+
+## Route by what you are doing
+
+| If you are… | Go to | Then stop at |
+|---|---|---|
+| orienting cold | `CONTEXT.md` | universes + traps, then one card |
+| asking "what is X?" | `objects/_index.md` | the one card it names |
+| asking "how does X happen?" | `processes/CONTEXT.md` | the one movement card |
+| about to change something | `effects/CONTEXT.md` | the cards it lists |
+| checking coverage | `objects/_index.md` | `status:` column |
+
+## Names that collide
+
+Read this table before editing. Full detail and citations: `CONTEXT.md`.
+
+| You will hear | It actually is |
+|---|---|
+| "SIF dollars" | `portfolio_transactions.amount_cents` — integer cents, no `Money` type |
+| "balance" | derived, never stored. `portfolios` has **no cash column** |
+| "grade" | two things: `Grade` = level 5–8; `GradeEntry#math_grade` = letter `"A+"`..`"F"` |
+| "admin" | a boolean column, **not** an STI type. Only `Student`/`Teacher` are types |
+| "log in" | by `username`, **not** email |
+| "the student's classroom" | two rival paths: `users.classroom_id` **and** `classroom_enrollments` |
+| "Stocks for Good" | same app. Code says `StocksInTheFuture` |
+
+## The one rule
+
+A card may be wrong; the source cannot. If a card and the code disagree, the code wins —
+fix the card the same day and set `status: stale` if you cannot.
+
+---
+`AGENTS.md` and `routing.md` are generated copies of this file. Never hand-edit them —
+edit `CLAUDE.md` and run `_meta/sync-twins.sh`.