# 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. `CLAUDE.md` for Claude-specific guidance

## High-Signal Areas

### Primary

- `bytelyst-cli.sh`
- `remove_user_interactive.sh`
- `remove_user_guided.sh`
- `remove_user_from_repos.sh`
- `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.

## 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.