# Repository Map

High-level map of the repository for contributors and AI agents.

## Top Level

### Core Bash Tooling

- `bytelyst-cli.sh`
  - Main CLI entry point for common GitHub operations.
- `setup.sh`
  - Bootstrap script for installing `pre-commit` and local git hooks.
- `remove_user_interactive.sh`
  - Interactive collaborator removal across matching repositories.
- `remove_user_guided.sh`
  - Guided UX wrapper for the removal workflow.
- `remove_user_from_repos.sh`
  - Non-guided removal script.
- `delete_team_interactive.sh`
  - Interactive team deletion.
- `make_repos_private.sh`
  - Repository visibility changes.
- `list_*.sh`
  - Read-oriented listing and reporting utilities.

### Supporting Data And Inputs

- `accounts.example.json`
- `github_repos.json`
- `github_acc_input.json`
- `repos.json`
- `repos.txt`
- `users_white_list.json`
- `users_black_list.json`
- account snapshot JSON files in the root

These are operational inputs or snapshots, not general-purpose source files.

## Directories

### `docs/`

Canonical onboarding and repo navigation docs.

Current key files:

- `docs/getting-started.md`
- `docs/repo-map.md`
- `docs/tooling-status.md`
- `docs/supported-scripts.md`
- `docs/operations.md`
- `docs/remove_user_interactive.md`
- `docs/hermes-setup-upgrade-roadmap.md`
- `docs/hermes-operations.md`
- `docs/deployment-optimization-roadmap.md` - deployment orchestration roadmap (build-off-VM, zero-downtime, VM resource caps); complements `docker-build-optimization-roadmap.md`
- `docs/llm-utility-workflows.md`
- `docs/gitea-registry-and-package-resolution.md`
- `docs/vm-security-blind-spots-roadmap.md`
- `docs/vm-exposure-inventory.md`

### `.github/workflows/`

Repository automation and validation.

Key files:

- `pre-commit.yml`
- `shell-validation.yml`

### `agent-queue/`

Folder-based "kanban" runner for headless coding-agent CLIs (`devin` · `claude` · `codex`).
Drop prompt `.md` files into `queue/inbox/` and they execute in auto-approve mode, moving
`inbox → doing → done/failed` with live status. Zero deps, bash 3.2-compatible.

Key files:

- `agent-queue.sh` — main script (`init` · `add` · `run` · `status` · `watch` · `stop` · `logs`)
- `README.md` — usage, engine flag mapping, safety notes
- `queue/` — runtime kanban state (gitignored)

### `git-work-safety-tools/`

Scripts for scanning many git repositories and performing safer bulk workflows.

Key files:

- `git_repos_status.sh`
- `git_repos_rebase_commit_push.sh`
- `multi_repo_safe_push.sh`
- `multi_repo_status.sh`
- `multi_repo_interactive_fix.sh`

### `scripts/`

Self-contained operational scripts that do not fit the older root-level naming pattern.

Key files:

- `ubuntu-vm-security-update.sh`
- `deploy-gigafactory.sh` - one-shot local deploy of the Agent Gigafactory (common_plat platform-service) + ecosystem product registration; `--stop` / `--register-only` modes
- `open-notebook-pilot/` - backup, restore-readiness, and sanitized ingestion smoke scripts for the private Open Notebook pilot
- `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.

Key files:

- `_source_all.alias`
- `install.sh`
- `README.md`

### `github_access_scripts/`

Focused GitHub access checks.

Key files:

- `check_repo_access.sh`
- `list_user_repos.sh`
- `README.md`

### `github_repo_scanners/`

Repo scanning scripts plus generated JSON outputs.

Key files:

- `create_user_repo_lists.sh`
- `create_contributor_repo_lists.sh`
- `run_contributor_json_creation.sh`
- `user_repos/`
- `contributor_repos/*.json`

### `Slack Message/`

Python Slack CLI utility.

Key files:

- `slack_poster.py`
- `README.md`
- `requirements.txt`

### `youtube/`

YouTube transcript and summarization utilities.

Key files:

- `transcribe_yt_video.py`
- `enhanced_yt_transcript.py`
- `summarize_with_perplexity.py`
- `README_youtube_transcripts.md`
- `captions/`
- `prompts/`

### `supabase monitor/`

Separate Python workflow project for YouTube processing. The folder name is misleading; inspect local docs before changing code.

Key files:

- `README.md`
- `EXECUTION_GUIDE.md`
- `workflow.py`
- `api.py`
- `agents/`
- `utils/`
- `output/`

### `deployments/`

Protected deployment artifacts and runbooks for private ByteLyst ops pilots.

Key files:

- `deployments/open-notebook-pilot/` — localhost-only Open Notebook pilot compose/runbook; secrets and runtime data stay under `/etc/bytelyst` and `/opt/bytelyst`, outside git.

### `dashboard/`

ByteLyst DevOps dashboard — internal product for deployment orchestration and service monitoring.

This is a full ByteLyst product (backend + web) integrated with the common platform:

- Backend: Fastify 5 (port 4004) with platform-service auth, Cosmos DB, deployment orchestration
- Web: Next.js 16 (port 3000) with react-auth, service status cards, deploy buttons
- Integration: Links to/from admin-web, uses @bytelyst/* packages

Key files:

- `dashboard/backend/src/` — Fastify server, services/deployments/health modules
- `dashboard/web/src/` — Next.js app, API client, auth provider
- `dashboard/shared/product.json` — Product identity (devops-internal)
- `dashboard/README.md` — Setup and usage documentation
- `dashboard/ENDPOINTS.md` — Canonical dashboard URL and endpoint inventory

See `dashboard/README.md` for architecture and setup instructions.

### `_AZURE/`

Account-specific notes and operational docs.

Treat contents as environment-specific documentation rather than core project source.

## Legacy Docs

These still exist but are no longer the best starting point:

- `README_interactive_script.md`
- `README_remove_user_script.md`

Prefer `docs/` for new canonical documentation.

## Legacy Root Utilities

These still exist in the repo root but are not the preferred discovery path:

- `interactive_user_removal.sh`
- `cleanup.sh`
- `sync_repos.sh`
- `test.sh`
- `test_interactive.sh`

Treat them as compatibility or one-off helpers unless a canonical doc points to them directly.

## Cleanup Guidance

When cleaning this repo:

- do not delete tracked outputs or snapshots unless explicitly asked
- prefer adding orientation docs over moving operational files
- prefer documenting supported entry points over renaming legacy root scripts
- avoid renaming legacy scripts unless you also provide compatibility shims or update all references
