bytelyst-devops-tools/docs/repo-map.md

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/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
• 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/

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