docs: align repo navigation and operations notes

docs/operations.md

@@ -0,0 +1,179 @@
+# Operations Guide
+
+Common operational paths for the team.
+
+Use this file as the routing guide. For the exact support boundary, cross-check `docs/supported-scripts.md`.
+
+## 1. Remove A Collaborator Interactively
+
+Use:
+
+```bash
+./remove_user_interactive.sh
+```
+
+Use this when:
+
+- you need repository pattern matching
+- you want per-repository confirmation
+- you want the safest default path for access removal
+
+Requirements:
+
+- `curl`
+- `jq`
+- GitHub token with the necessary repo and org permissions
+
+## 2. Remove A Collaborator In A More Guided Flow
+
+Use:
+
+```bash
+./remove_user_guided.sh
+```
+
+Use this when:
+
+- you want a more opinionated step-by-step flow
+- you are onboarding someone to the repo tools
+
+## 3. Remove A Collaborator In A Scripted Way
+
+Use:
+
+```bash
+./remove_user_from_repos.sh
+```
+
+Use this when:
+
+- you already know the target root, user, and repo pattern
+- you want a repeatable command invocation
+
+Read first:
+
+- `README_remove_user_script.md`
+- `docs/supported-scripts.md`
+
+## 4. Run Common GitHub Admin Commands
+
+Use:
+
+```bash
+./bytelyst-cli.sh help
+```
+
+Typical commands:
+
+```bash
+./bytelyst-cli.sh list-public-repos --user <username>
+./bytelyst-cli.sh list-private-repos --org <orgname>
+./bytelyst-cli.sh check-collaborators --input github_acc_input.json
+```
+
+Use this when:
+
+- you need the main shared CLI entry point
+- the task fits the commands already exposed there
+
+## 5. Scan Multi-Repo Git Status
+
+Use:
+
+```bash
+./git-work-safety-tools/git_repos_status.sh
+./git-work-safety-tools/multi_repo_status.sh
+```
+
+Use this when:
+
+- you need visibility across many local repositories
+- you want safer batch git operations
+
+## 6. Safely Push Across Multiple Repositories
+
+Use:
+
+```bash
+./git-work-safety-tools/multi_repo_safe_push.sh
+```
+
+Use this when:
+
+- you are coordinating many repos
+- you want a safer batch push helper instead of ad hoc shell loops
+
+## 7. Scan GitHub Access Across Accounts
+
+Use:
+
+```bash
+cp accounts.example.json accounts.json
+./github_access_scripts/list_user_repos.sh <github_user>
+./github_access_scripts/check_repo_access.sh <github_user> <owner/repo>
+```
+
+Use this when:
+
+- you need access verification
+- you need a focused check outside the main CLI
+
+## 8. Generate Repo Scan Artifacts Locally
+
+Use:
+
+```bash
+./github_repo_scanners/create_user_repo_lists.sh
+./github_repo_scanners/run_contributor_json_creation.sh accounts.json
+```
+
+Generated outputs go to:
+
+- `github_repo_scanners/user_repos/`
+- `github_repo_scanners/contributor_repos/`
+
+Do not commit those outputs unless they are intentionally curated fixtures.
+
+## 9. Harden An Ubuntu VM
+
+Use:
+
+```bash
+sudo bash scripts/ubuntu-vm-security-update.sh --help
+sudo bash scripts/ubuntu-vm-security-update.sh --dry-run
+```
+
+Use this when:
+
+- you are preparing or refreshing an Ubuntu VM
+- you want unattended upgrades, UFW, and fail2ban configured
+
+Recommended order:
+
+1. Read `scripts/README.md`
+2. Run `--help`
+3. Run `--dry-run`
+4. Run the real command with explicit reboot behavior
+
+After a reboot triggered by the script, verify the resulting host state with:
+
+```bash
+test -f /var/run/reboot-required && echo "reboot still required" || echo "reboot clear"
+sudo systemctl status unattended-upgrades fail2ban
+sudo ufw status verbose
+sudo tail -n 50 /var/log/vm-security-update.log
+apt list --upgradable
+```
+
+If packages are still pending or the services are unhealthy, rerun:
+
+```bash
+sudo bash scripts/ubuntu-vm-security-update.sh
+```
+
+## Team Guidance
+
+- Prefer the supported entry points in `docs/tooling-status.md`.
+- Prefer `docs/operations.md` and `docs/supported-scripts.md` over scanning the repo root manually.
+- Prefer templates such as `accounts.example.json` and `.env.example` over ad hoc local files.
+- Do not commit local credentials, generated transcripts, or repo-scan outputs.

docs/remove_user_interactive.md

@@ -1,204 +1,126 @@
-# Interactive User Removal Tool
+# Interactive User Removal
 
-## Overview
+Reference for [`remove_user_interactive.sh`](/opt/bytelyst/bytelyst-devops-tools/remove_user_interactive.sh).
 
-`remove_user_interactive.sh` is a comprehensive command-line tool designed to remove users from GitHub repositories with advanced pattern matching and interactive confirmation features. The tool supports both individual user repositories and organization-wide operations.
+## Purpose
 
-## Features
+Use this script to remove a GitHub user from repositories that match a name pattern. It supports both:
 
-### 🎯 Core Functionality
+- interactive prompting
-- **Interactive User Input**: Guides users through token, user, and pattern collection
+- command-line arguments for repeatable runs
-- **Multi-Level Repository Discovery**: Handles both root account and organization repositories
-- **Wildcard Pattern Matching**: Supports complex repository patterns
-- **Batch Operations**: Process multiple repositories efficiently
-- **Rich Visual Feedback**: Color-coded logging with progress indicators
 
-### 🔐 Security Features
+This is the safer collaborator-removal path when you want per-repository confirmation by default.
-- **Token Validation**: Verifies GitHub API access before operations
-- **Interactive Confirmations**: Prevents accidental bulk operations
-- **Permission Checks**: Validates repository access permissions
-- **Error Handling**: Comprehensive error reporting and recovery
 
-### 🎨 User Experience
+## Requirements
-- **Progress Tracking**: Real-time progress indicators
+
-- **Flexible Confirmation System**: Multiple response options
+- `bash`
-- **Summary Reports**: Detailed operation statistics
+- `curl`
-- **Color-Coded Output**: Enhanced readability with emojis
+- `jq`
+- a GitHub token with enough access to inspect repositories and remove collaborators
+
+The script accepts a token via `-t/--token`, or it will prompt for one interactively.
 
 ## Usage
 
-### Basic Execution
+Interactive:
+
 ```bash
 ./remove_user_interactive.sh
 ```
 
-### Interactive Flow
+Non-interactive:
-1. **Dependency Check**: Validates required tools (`curl`, `jq`)
+
-2. **Authentication**: Collects and validates GitHub token
+```bash
-3. **Root User Input**: Specifies the root account/organization
+./remove_user_interactive.sh \
-4. **Target User**: Defines the user to remove
+  --user <github-username> \
-5. **Pattern Matching**: Sets repository selection criteria
+  --root <owner-or-org> \
-6. **Repository Discovery**: Finds all matching repositories
+  --pattern '<repo-pattern>' \
-7. **Confirmation**: Reviews and confirms the operation
+  --token "$GITHUB_TOKEN" \
-8. **Batch Processing**: Removes user from selected repositories
+  --non-interactive
-9. **Summary Report**: Displays operation results
+```
+
+Help:
+
+```bash
+./remove_user_interactive.sh --help
+```
+
+## Supported Flags
+
+- `-u`, `--user`
+  Username to remove.
+- `-r`, `--root`
+  Root GitHub user or organization used for repository discovery.
+- `-p`, `--pattern`
+  Repository name filter. `*` is supported as a wildcard.
+- `-t`, `--token`
+  GitHub personal access token.
+- `--non-interactive`
+  Auto-confirms all removals after discovery.
+- `-h`, `--help`
+  Show usage.
+
+## How Discovery Works
+
+The script:
+
+1. validates dependencies
+2. validates the GitHub token
+3. collects the root owner, target user, and repository pattern
+4. fetches repositories for the root user
+5. fetches organizations visible from that user and their repositories
+6. filters repositories by the provided pattern
+7. checks each repository for the target user as a collaborator
+8. asks for confirmation before each removal unless `--non-interactive` is used
+
+Repository names are handled as `owner/repo`. Invalid names discovered from the API are skipped.
 
 ## Pattern Matching
 
-The tool supports sophisticated wildcard patterns for repository selection:
+Examples:
 
-### Pattern Examples
+- `*`
-- `*-go-api*` - Matches any repository containing "-go-api"
+  Match all discovered repositories.
-- `frontend-*` - Matches repositories starting with "frontend-"
+- `frontend-*`
-- `*-service` - Matches repositories ending with "-service"
+  Match repositories whose names begin with `frontend-`.
-- `web-*-app` - Matches repositories with "web-" prefix and "-app" suffix
+- `*api*`
-- `exact-repo-name` - Matches specific repository name
+  Match repositories whose names contain `api`.
+- `exact-repo-name`
+  Match that exact repository name.
 
-### Pattern Behavior
+The script converts `*` to a regex-style wildcard internally. Matching is done against the repository name, not the full `owner/repo` path.
-- Patterns are case-sensitive
-- Wildcards (`*`) match any sequence of characters
-- Patterns apply to repository names, not full paths
-- Multiple patterns can be combined using shell globbing
 
-## Interactive Confirmation System
+## Confirmation Modes
 
-During the removal process, users have multiple response options:
+During interactive execution, each repository prompt supports:
 
-### Confirmation Options
+- `y`
-- **`[y]es`** - Remove user from current repository
+  Remove from the current repository.
-- **`[n]o`** - Skip current repository
+- `n`
-- **`[a]ll yes`** - Remove user from all remaining repositories
+  Skip the current repository.
-- **`[s]kip all`** - Skip all remaining repositories
+- `a`
-- **`[q]uit`** - Cancel entire operation
+  Remove from all remaining repositories.
+- `s`
+  Skip all remaining repositories.
+- `q`
+  Exit immediately.
 
-### Confirmation Modes
+## Exit And Result Notes
-- **`ask`** - Default mode, prompts for each repository
-- **`yes_all`** - Automatically confirm all operations
-- **`no_all`** - Automatically skip all operations
 
-## Repository Discovery
+- `204` from the GitHub API means the collaborator removal succeeded.
+- `404` usually means the user is not a collaborator on that repository, or the repository could not be resolved with the current access.
+- `403` during collaborator checks usually means the token lacks sufficient access for that repository.
 
-The tool performs comprehensive repository discovery:
+At the end, the script prints counts for:
 
-### Discovery Process
+- processed repositories
-1. **Root User Repositories**: Fetches all repositories owned by the root user
+- successful removals
-2. **Organization Discovery**: Identifies organizations the root user belongs to
+- failed removals
-3. **Organization Repositories**: Fetches repositories from each organization
+- skipped removals
-4. **Pattern Filtering**: Applies wildcard patterns to repository names
-5. **Deduplication**: Removes duplicate repositories from the final list
 
-### API Endpoints Used
+## Operational Guidance
-- `GET /users/{user}/repos` - User repositories
-- `GET /users/{user}/orgs` - User organizations
-- `GET /orgs/{org}/repos` - Organization repositories
-- `DELETE /repos/{owner}/{repo}/collaborators/{username}` - Remove collaborator
 
-## Error Handling
+- Prefer running without `--non-interactive` first unless you have already validated the repository pattern.
-
+- Use a narrow pattern before using `*` against a large owner or organization.
-The tool includes comprehensive error handling:
+- Keep the token out of shell history when possible. Prompted entry is safer than embedding it directly in commands.
-
+- Cross-check `docs/operations.md` and `docs/supported-scripts.md` if you are choosing between this script, `remove_user_guided.sh`, and `remove_user_from_repos.sh`.
-### HTTP Status Codes
-- **`204`** - Successful removal
-- **`404`** - User not found or not a collaborator
-- **`403`** - Insufficient permissions
-- **`401`** - Invalid authentication
-
-### Error Recovery
-- **Network Failures**: Retry mechanisms for API calls
-- **Rate Limiting**: Respects GitHub API rate limits
-- **Permission Errors**: Clear error messages and suggestions
-- **Invalid Input**: Input validation and correction prompts
-
-## Logging and Output
-
-### Log Levels
-- **Info** (ℹ️): General information messages
-- **Success** (✅): Successful operations
-- **Warning** (⚠️): Non-critical issues
-- **Error** (❌): Critical failures
-- **Progress** (🔄): Operation progress updates
-
-### Output Format
-```
-[EMOJI] [TIMESTAMP] [LEVEL] Message
-```
-
-### Summary Report
-```
-Operation Summary
-=================
-Total repositories processed: 15
-Successful removals: 12
-Failed removals: 1
-Skipped removals: 2
-Success rate: 80%
-```
-
-## Prerequisites
-
-### Required Tools
-- `curl` - HTTP client for API requests
-- `jq` - JSON processor for API responses
-
-### GitHub Token Permissions
-- `repo` - Repository access (read/write)
-- `admin:org` - Organization administration
-
-### Environment Requirements
-- Bash 4.0 or higher
-- Internet connectivity for GitHub API access
-- Valid GitHub Personal Access Token
-
-## Security Considerations
-
-### Token Security
-- Tokens are not stored or logged
-- Input is hidden during token entry
-- Tokens are validated before use
-
-### Operation Safety
-- Interactive confirmations prevent accidental operations
-- Detailed logging for audit trails
-- Rollback information provided for manual recovery
-
-### Access Control
-- Respects GitHub repository permissions
-- Validates user access before operations
-- Handles permission errors gracefully
-
-## Troubleshooting
-
-### Common Issues
-1. **Token Validation Fails**: Ensure token has correct permissions
-2. **Repository Not Found**: Check repository name and access permissions
-3. **User Not Found**: Verify username spelling and existence
-4. **Rate Limiting**: Wait for rate limit reset or use token with higher limits
-
-### Debug Mode
-Enable verbose output by setting:
-```bash
-export DEBUG=1
-./remove_user_interactive.sh
-```
-
-## Integration
-
-The tool integrates seamlessly with other ByteLyst DevOps tools:
-- Can be called from `bytelyst-cli.sh`
-- Supports JSON configuration files
-- Compatible with existing workflow scripts
-- Follows established logging and error handling patterns
-
-## Performance
-
-### Optimization Features
-- Paginated API requests for large datasets
-- Parallel processing where possible
-- Efficient pattern matching algorithms
-- Minimal memory footprint
-
-### Scale Considerations
-- Handles hundreds of repositories efficiently
-- Respects GitHub API rate limits
-- Provides progress feedback for long operations
-- Supports interruption and resumption

docs/repo-map.md

@@ -8,6 +8,8 @@ High-level map of the repository for contributors and AI agents.
 
 - `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`
@@ -23,6 +25,7 @@ High-level map of the repository for contributors and AI agents.
 
 ### Supporting Data And Inputs
 
+- `accounts.example.json`
 - `github_repos.json`
 - `github_acc_input.json`
 - `repos.json`
@@ -44,8 +47,18 @@ 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`
 
+### `.github/workflows/`
+
+Repository automation and validation.
+
+Key files:
+
+- `pre-commit.yml`
+- `shell-validation.yml`
 ### `git-work-safety-tools/`
 
 Scripts for scanning many git repositories and performing safer bulk workflows.
@@ -75,6 +88,7 @@ Key files:
 
 - `check_repo_access.sh`
 - `list_user_repos.sh`
+- `README.md`
 
 ### `github_repo_scanners/`
 
@@ -140,10 +154,23 @@ These still exist but are no longer the best starting point:
 
 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