convert pdf to md, add OVERVIEW and docs

worker-toolkit-stocks-in-the-future/repo/docs/map/_meta/build-index.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Rebuild objects/_index.md from card frontmatter.
+#
+# The index is generated, never hand-edited: a hand-curated index drifts, a derived one
+# cannot. Run after adding, moving, or re-verifying any object card.
+
+set -euo pipefail
+
+map_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+objects_dir="${map_dir}/objects"
+out="${objects_dir}/_index.md"
+
+field() { awk -v k="^$2:" '$0 ~ k { sub(/^[^:]*: */, ""); print; exit }' "$1"; }
+
+{
+  echo "# Object index"
+  echo
+  echo "One line per noun. Open the card, not the folder."
+  echo
+  echo "_Generated by \`_meta/build-index.sh\` from card frontmatter. Do not hand-edit._"
+  echo
+  echo "| Noun | Cluster | Universe | Status | Owning file |"
+  echo "|---|---|---|---|---|"
+
+  find "$objects_dir" -name '*.md' ! -name '_index.md' ! -name 'CONTEXT.md' \
+    | sort | while read -r f; do
+      rel="${f#"${objects_dir}"/}"
+      name=$(awk '/^# /{ sub(/^# /, ""); print; exit }' "$f")
+      printf '| [%s](%s) | %s | %s | %s | `%s` |\n' \
+        "$name" "$rel" "$(field "$f" cluster)" "$(field "$f" universe)" \
+        "$(field "$f" status)" "$(field "$f" entity)"
+    done
+} > "$out"
+
+echo "wrote $out ($(grep -c '^| \[' "$out") cards)"

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

@@ -0,0 +1,54 @@
+# Schema — the rules of this map
+
+The closed set of node types, the labels they carry, and the naming they follow. When
+practice and this file disagree, reconcile the same day — schema drift is how maps rot.
+
+## Node types
+
+| `type:` | Lives at | Carries |
+|---|---|---|
+| object | `objects/<cluster>/<slug>.md` | one noun: why / shape / connected to / hits |
+| process | `processes/<slug>.md` | one movement: input → movement → output |
+
+That is the whole set. `effects/CONTEXT.md` is an index, not a node type — it holds no
+facts of its own, only pointers into the two types above.
+
+## Frontmatter
+
+Object cards:
+
+```yaml
+type: object
+cluster: identity | org | gradebook | money | trading | content
+universe: live | leftover | ghost
+status: stub | verified | stale
+entity: app/models/order.rb        # the file that owns the fact
+```
+
+Process cards add `consumes:` and `produces:` as relative links to object cards. Those
+links draw the graph on their own — do not maintain a separate edge list.
+
+## Label rules
+
+- `universe: live` is the default. `leftover` and `ghost` must say why in the card body.
+- `status: verified` requires **a date, a commit, and citations** in the card. A card
+  with no `path:line` may not be `verified`.
+- `status: stale` is allowed and preferred over a confident wrong claim.
+- `entity:` is one path. If a noun is owned by several files, the card's Shape section
+  lists them; `entity:` names the primary one.
+
+## Naming
+
+- Slugs: kebab-case, singular, matching the product word where it differs from the class
+  name (`grade-level.md` owns `Grade`).
+- Clusters are the six above. Adding a seventh requires three nouns that genuinely do not
+  fit — not one that is merely new.
+- `_meta/` and `_templates/` hold rules and blanks. Underscore = about the map, not of it.
+- `AGENTS.md` and `routing.md` are generated from `CLAUDE.md` by `_meta/sync-twins.sh`.
+  Never hand-edited.
+
+## Citation rule
+
+Code is the source of truth. Cite `path:line`. If a comment and the code disagree, the
+code wins and the card says so. Never paste behaviour into a card that the source
+already states — point at it.

worker-toolkit-stocks-in-the-future/repo/docs/map/_meta/sync-twins.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Regenerate the entry-file twins from CLAUDE.md.
+#
+# CLAUDE.md is the only hand-edited entry file. AGENTS.md and routing.md are
+# byte-identical copies so that tools which ignore CLAUDE.md still find the catalog.
+# Run this after every edit to CLAUDE.md; CI-safe and idempotent.
+
+set -euo pipefail
+
+map_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+src="${map_dir}/CLAUDE.md"
+
+[[ -f "$src" ]] || { echo "missing $src" >&2; exit 1; }
+
+for twin in AGENTS.md routing.md; do
+  cp "$src" "${map_dir}/${twin}"
+  echo "wrote ${map_dir}/${twin}"
+done

worker-toolkit-stocks-in-the-future/repo/docs/map/_meta/verify-citations.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Check every path:line citation in the map against the real tree.
+#
+# A card marked `verified` with a citation that no longer resolves is worse than no card,
+# so this runs cheap and often. It checks two forms:
+#   `app/models/order.rb:137`   full path from the repo root
+#   `:137-148`                  shorthand, resolved against the card's `entity:`
+# It cannot tell you a citation points at the *wrong* line — only that the line exists.
+
+set -uo pipefail
+
+map_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+repo_root="$(cd "${map_dir}/../.." && pwd)"
+refs=$(mktemp)
+trap 'rm -f "$refs"' EXIT
+
+while IFS= read -r card; do
+  rel="${card#"${repo_root}"/}"
+  entity=$(awk '/^entity:/ { sub(/^entity: */, ""); print; exit }' "$card")
+
+  grep -oE '[A-Za-z0-9_][A-Za-z0-9_./-]*\.(rb|yml|erb|md|js|sh|json):[0-9]+(-[0-9]+)?' "$card" \
+    | sort -u | while read -r ref; do
+        printf '%s\t%s\t%s\n' "$rel" "${ref%:*}" "${ref##*:}"
+      done >> "$refs"
+
+  if [[ -n "$entity" ]]; then
+    grep -oE '`:[0-9]+(-[0-9]+)?`' "$card" | tr -d '`' | sort -u | while read -r ref; do
+      printf '%s\t%s\t%s\n' "$rel" "$entity" "${ref#:}"
+    done >> "$refs"
+  fi
+done < <(find "$map_dir" -name '*.md')
+
+total=0; bad=0
+while IFS=$'\t' read -r card path spec; do
+  total=$((total + 1))
+  full="${repo_root}/${path}"
+  if [[ ! -f "$full" ]]; then
+    echo "MISSING FILE  ${card} -> ${path}"
+    bad=$((bad + 1)); continue
+  fi
+  last="${spec##*-}"
+  lines=$(wc -l < "$full")
+  if (( last > lines )); then
+    echo "LINE OUT OF RANGE  ${card} -> ${path}:${spec} (file has ${lines} lines)"
+    bad=$((bad + 1))
+  fi
+done < "$refs"
+
+echo "checked ${total} citations, ${bad} broken"
+[[ $bad -eq 0 ]]