# AGENTS.md

Guidance for AI coding agents working in this repository.

## Purpose

This repo is a mixed operational workspace, not a single product codebase. Your first job is orientation:

- identify whether the task targets root Bash tooling, a subproject, or generated data
- avoid treating tracked JSON or output files as canonical source without checking context
- prefer doc and safety improvements unless the requested task clearly requires behavioral changes

## Canonical Docs

Read these first:

1. `README.md`
2. `docs/getting-started.md`
3. `docs/repo-map.md`
4. `docs/tooling-status.md`
5. `scripts/README.md` when the task involves standalone operational scripts
6. `CLAUDE.md` for Claude-specific guidance

## High-Signal Areas

### Primary

- `bytelyst-cli.sh`
- `deployment-status.sh` - Comprehensive deployment status report for investment trading
- `deploy-invttrdg.sh` - Production deployment script for investment trading
- `remove_user_interactive.sh`
- `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/`

### Secondary Or Self-Contained

- `Slack Message/`
- `youtube/`
- `supabase monitor/`

Do not assume these subprojects share the same dependencies or conventions as the root scripts.

## Sensitive And Generated Files

Handle these carefully:

- `accounts.json`
- account or user snapshot JSON files in the repo root
- `github_repo_scanners/contributor_repos/*.json`
- `.env` files
- generated outputs under `supabase monitor/output/`

These may contain secrets, usernames, or operational snapshots. Avoid printing contents unless necessary for the task.

## Editing Rules

- Prefer small, targeted changes.
- Preserve operational scripts' current interface unless the task asks for a breaking change.
- When reorganizing docs, keep old filenames if external references may depend on them.
- Do not move or delete generated/tracked data files unless explicitly asked.
- If you add a new directory or script, update `docs/repo-map.md`.

## Recommended Workflow

1. Determine whether the task is about:
   - GitHub admin Bash scripts
   - multi-repo git safety tooling
   - a Python side project
   - repo documentation or cleanup
2. Read only the files relevant to that surface.
3. Check whether there is an existing README in that subdirectory.
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
git status --short --branch
rg --files
sed -n '1,220p' README.md
sed -n '1,220p' docs/repo-map.md
```

## Pitfalls

- The repo contains legacy one-off scripts and tracked local artifacts.
- Directory names do not always reflect actual function. `supabase monitor/` is a YouTube-processing workflow project.
- The root README should stay broad; detailed usage belongs in `docs/` or a subdirectory README.
