docs(agents): document "cut tracker items" workflow

Add a "Cutting Tracker Items" section to AGENTS.md and register
scripts/tracker-seed/ in docs/repo-map.md so future "cut items to track"
requests route to the seed tooling instead of ad-hoc API calls.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

AGENTS.md

@@ -32,6 +32,7 @@ Read these first:
 - `remove_user_guided.sh`
 - `remove_user_from_repos.sh`
 - `scripts/`
+- `scripts/tracker-seed/` - file work items into the ByteLyst tracker (see "Cutting Tracker Items")
 - `git-work-safety-tools/`
 - `github_access_scripts/`
 
@@ -75,6 +76,37 @@ These may contain secrets, usernames, or operational snapshots. Avoid printing c
 4. Make the smallest coherent change set.
 5. If docs or discoverability changed, update the canonical docs listed above.
 
+## Cutting Tracker Items (work tracking)
+
+When the user asks to **"cut items to track"** (file feature/bug/task tickets for
+some work — e.g. the findings in `ENGINEERING_REVIEW_SCORECARD.md`), use the
+seed tooling in `scripts/tracker-seed/`. Do **not** hand-roll API calls.
+
+How the tracker works:
+- Items live in the ByteLyst tracker, served by **platform-service**
+  (`POST /api/items`, in `learning_ai_common_plat/services/platform-service`),
+  and viewed in **tracker-web** (`learning_ai_common_plat/dashboards/tracker-web`, `:3003`).
+- Item schema: `{ productId, type: bug|feature|task, priority: critical|high|medium|low,
+  title, description, labels[], source, visibility, ... }`. Items are scoped per `productId`.
+- Auth is an HS256 JWT signed with the shared `JWT_SECRET` (verified offline by
+  platform-service); the seed script mints one itself.
+
+Standard procedure:
+1. **Add payloads** to `scripts/tracker-seed/engineering-review-items.json`
+   (or a new payload file): one entry per item, scoped to the right `productId`.
+   Use the `repoToProductId` map in that file for repo → product slugs
+   (e.g. `learning_ai_notes` → `notelett`, common-plat/infra → `platform`).
+2. **Preview** with no side effects: `node scripts/tracker-seed/seed-tracker-items.mjs --dry-run`.
+3. **Create for real only when the platform stack is up** (it writes real records):
+   `JWT_SECRET=<secret> PLATFORM_API_URL=http://localhost:4003 node scripts/tracker-seed/seed-tracker-items.mjs`.
+   The script dedupes by title per product, so re-running is safe (`--force` to bypass).
+4. If the stack is **not running** (no Docker / nothing on `:4003`), do **not**
+   stand up Cosmos just to seed — commit the payloads + run instructions and tell
+   the user to run the script when the stack is next up. Confirm before any live
+   write (creating items is a side-effecting datastore operation).
+
+See `scripts/tracker-seed/README.md` for full details.
+
 ## Good First Checks
 
 ```bash

docs/repo-map.md

@@ -98,6 +98,18 @@ Key files:
 - `ubuntu-vm-security-update.sh`
 - `README.md`
 
+#### `scripts/tracker-seed/`
+
+Seeds work items into the ByteLyst tracker (platform-service `POST /api/items`,
+viewed in tracker-web). Use when asked to "cut items to track" — see the
+"Cutting Tracker Items" section in `AGENTS.md`.
+
+Key files:
+
+- `seed-tracker-items.mjs` - dependency-free seeder (mints HS256 token, dedupes by title, `--dry-run`)
+- `engineering-review-items.json` - item payloads + repo→productId map
+- `README.md`
+
 ### `aliases/`
 
 Reusable Bash/Zsh alias bundle for common git, tmux, shell, directory, and listing shortcuts.