diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b60b2df07aa..5acdb843770 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,197 @@
 # Contributing to ci-tools
 
+Thank you for your interest in contributing to CI-Tools! This guide will help you understand how to contribute effectively.
+
+## How to Contribute
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/ci-tools.git
+cd ci-tools
+
+# Add upstream remote
+git remote add upstream https://github.com/openshift/ci-tools.git
+```
+
+### 2. Create a Branch
+
+```bash
+# Create a feature branch from main
+git checkout -b feature/my-feature
+
+# Or a bugfix branch
+git checkout -b fix/bug-description
+```
+
+### 3. Make Your Changes
+
+- Write clear, readable code
+- Follow Go conventions and style
+- Add tests for new functionality
+- Update documentation as needed
+
+### 4. Test Your Changes
+
+```bash
+# Run unit tests
+make test
+
+# Run linters
+make lint
+
+# Run integration tests (if applicable)
+make integration
+
+# Verify code generation
+make verify-gen
+```
+
+### 5. Commit Your Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit with descriptive message
+git commit -m "Add feature: description of changes"
+```
+
+**Commit Message Guidelines:**
+- Use imperative mood ("Add feature" not "Added feature")
+- Keep first line under 72 characters
+- Add detailed description if needed
+- Reference issues: "Fix #123: description"
+
+### 6. Push and Create Pull Request
+
+```bash
+# Push to your fork
+git push origin feature/my-feature
+```
+
+Then create a Pull Request on GitHub with:
+- Clear title and description
+- Reference to related issues
+- Screenshots/logs if applicable
+- Checklist of what was tested
+
+## Branching Model
+
+### Branch Naming
+
+- `feature/description` - New features
+- `fix/description` - Bug fixes
+- `docs/description` - Documentation updates
+- `refactor/description` - Code refactoring
+- `test/description` - Test improvements
+
+### Branch Strategy
+
+- **main** - Production-ready code
+- **Feature branches** - Created from main, merged back via PR
+- **Release branches** - For release-specific fixes (if needed)
+
+## Coding Standards
+
+### Go Style
+
+Follow [Effective Go](https://golang.org/doc/effective_go) and [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).
+
+**Formatting:**
+```bash
+# Use gofmt
+make gofmt
+
+# Or goimports (handles imports)
+go run ./vendor/github.com/openshift-eng/openshift-goimports/ -m github.com/openshift/ci-tools
+```
+
+**Key Guidelines:**
+- Use `gofmt` for formatting
+- Run `goimports` to organize imports
+- Follow naming conventions (exported = Capital, unexported = lowercase)
+- Keep functions focused and small
+- Add comments for exported functions/types
+
+### Code Organization
+
+- **Packages**: Group related functionality
+- **Files**: Keep files focused (one main type per file when possible)
+- **Tests**: `*_test.go` files alongside source
+- **Test Data**: Use `testdata/` directories
+
+### Error Handling
+
+```go
+// Good: Wrap errors with context
+if err != nil {
+    return fmt.Errorf("failed to load config: %w", err)
+}
+
+// Good: Use errors.Is and errors.As for error checking
+if errors.Is(err, os.ErrNotExist) {
+    // handle
+}
+```
+
+### Logging
+
+```go
+// Use logrus for structured logging
+import "github.com/sirupsen/logrus"
+
+logrus.WithFields(logrus.Fields{
+    "config": configPath,
+    "error": err,
+}).Error("Failed to load config")
+```
+
+### Testing
+
+**Unit Tests:**
+```go
+func TestFunction(t *testing.T) {
+    // Arrange
+    input := "test"
+    
+    // Act
+    result := Function(input)
+    
+    // Assert
+    if result != expected {
+        t.Errorf("Expected %v, got %v", expected, result)
+    }
+}
+```
+
+**Table-Driven Tests:**
+```go
+func TestFunction(t *testing.T) {
+    tests := []struct {
+        name     string
+        input    string
+        expected string
+    }{
+        {
+            name:     "normal case",
+            input:    "test",
+            expected: "result",
+        },
+    }
+    
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := Function(tt.input)
+            if result != tt.expected {
+                t.Errorf("got %v, want %v", result, tt.expected)
+            }
+        })
+    }
+}
+```
+
 ## The Code Review Process
 ### Submit a PR
 
@@ -89,7 +281,145 @@ For the critical or complex changes, it is acceptable to review the code partial
 ### Good Things
 _If you see something nice in the CL, tell the developer, especially when they addressed one of your comments in a great way. Code reviews often just focus on mistakes, but they should offer encouragement and appreciation for good practices, as well. It’s sometimes even more valuable, in terms of mentoring, to tell a developer what they did right than to tell them what they did wrong._ [1]
 
+## FAQ
+
+### General Questions
+
+**What is CI-Tools?**
+CI-Tools is a collection of command-line utilities and services that power the OpenShift Continuous Integration system. It provides tools for managing CI configurations, orchestrating builds, running tests, and managing the CI infrastructure.
+
+**Who maintains CI-Tools?**
+The OpenShift Test Platform (TP) team maintains CI-Tools. See the [OWNERS](OWNERS) file for the list of maintainers.
+
+**How do I get started?**
+1. Read the [docs/README.md](docs/README.md) for overview
+2. Set up your environment ([docs/SETUP.md](docs/SETUP.md))
+3. Explore the codebase ([docs/ARCHITECTURE.md](docs/ARCHITECTURE.md))
+
+### Development Questions
+
+**How do I build the project?**
+```bash
+# Build all tools
+make build
+
+# Install to $GOPATH/bin
+make install
+
+# Build specific tool
+go build ./cmd/ci-operator
+```
+
+**How do I run tests?**
+```bash
+# Run all unit tests
+make test
+
+# Run specific package tests
+go test ./pkg/api/...
+
+# Run integration tests
+make integration
+```
+
+**What's the difference between unit tests, integration tests, and e2e tests?**
+- **Unit Tests**: Test individual functions/units in isolation
+- **Integration Tests**: Test components working together
+- **E2E Tests**: Test complete workflows end-to-end (require cluster access)
+
+### CI Operator Questions
+
+**What is CI Operator?**
+CI Operator is the core orchestration engine that reads YAML configurations and executes multi-stage image builds and tests on OpenShift clusters.
+
+**How do I test a CI Operator config locally?**
+```bash
+ci-operator \
+  --config=path/to/config.yaml \
+  --git-ref=org/repo@branch \
+  --target=test-name \
+  --namespace=my-namespace
+```
+
+**What's the difference between `--target` and running all steps?**
+`--target` runs only the specified target and its dependencies. Without `--target`, all steps are run.
+
+### Troubleshooting
+
+**My build is failing, how do I debug it?**
+1. Check the config: `ci-operator-checkconfig --config=config.yaml`
+2. Run locally: `ci-operator --config=config.yaml --git-ref=...`
+3. Check logs: `oc logs -n namespace pod-name`
+4. Check artifacts: `oc rsync -n namespace pod:/artifacts ./local`
+
+**I'm getting "permission denied" errors**
+1. Check kubeconfig: `kubectl config current-context`
+2. Verify cluster access: `kubectl get nodes`
+3. Check RBAC permissions
+4. Try logging in: `oc login <cluster-url>`
+
+**Config changes aren't taking effect**
+1. Verify config is in correct location
+2. Check if Prow jobs were regenerated
+3. Verify PR was merged
+4. Check if Prow picked up changes (may take a few minutes)
+
+## Onboarding for New Contributors
+
+### What to Learn Before Contributing
+
+**Essential Knowledge:**
+1. **Go Programming Language** - Go basics, concurrency, testing, modules
+2. **Kubernetes/OpenShift** - Kubernetes API, Pods, Services, Controllers
+3. **YAML** - YAML syntax and working with YAML in Go
+4. **Git and GitHub** - Git workflow, GitHub Pull Request process
+
+**Recommended Knowledge:**
+1. **CI/CD Concepts** - Continuous Integration principles, build pipelines
+2. **Prow** - Prow architecture, job types, plugins
+3. **Container Technology** - Docker basics, container images, ImageStreams
+4. **Distributed Systems** - Event-driven architecture, controller pattern
+
+### Important Concepts
+
+**CI Operator Configuration**: Declarative YAML configurations that define base images, images to build, tests to run, and image promotion rules. See `pkg/api/config.go` and `pkg/config/load.go`.
+
+**Dependency Graph**: CI Operator builds a dependency graph to determine execution order. Steps have inputs (Requires) and outputs (Creates). See `pkg/api/graph.go`.
+
+**Step Execution Framework**: Steps are composable building blocks that implement a common interface. See `pkg/steps/step.go`.
+
+**Controller Pattern**: Many tools use the Kubernetes controller pattern - watch resources, reconcile desired state, handle errors gracefully. See `pkg/controller/util/reconciler.go`.
+
+### Beginner Roadmap
+
+**Phase 1: Understanding the Basics (Week 1-2)**
+- Read [docs/README.md](docs/README.md) and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Set up development environment ([docs/SETUP.md](docs/SETUP.md))
+- Build and run a simple tool locally
+- Read through `cmd/ci-operator/main.go`
+
+**Phase 2: Understanding CI Operator (Week 3-4)**
+- Study `pkg/api/config.go` to understand configuration structure
+- Study `pkg/api/graph.go` to understand dependency graphs
+- Study `pkg/steps/` to understand step execution
+- Create a simple test config and run it locally
+
+**Phase 3: Making Your First Contribution (Week 5+)**
+- Find a good first issue (labeled "good first issue" or "help wanted")
+- Understand the problem and proposed solution
+- Implement the fix or feature
+- Write tests
+- Create a Pull Request
+
+### Getting Help
+
+- **GitHub Issues**: Search existing issues or create new ones
+- **Pull Requests**: Ask questions in PR comments
+- **Slack**: #forum-testplatform (for OpenShift team members)
+- **Documentation**: Read the docs in `docs/` directory
+
 ## References
-1. [Google Engineering Practices Documentation](https://google.github.io/eng-practices/): [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) and [The CL author’s guide to getting through code review](https://google.github.io/eng-practices/review/developer/)
+
+1. [Google Engineering Practices Documentation](https://google.github.io/eng-practices/): [How to do a code review](https://google.github.io/eng-practices/review/reviewer/) and [The CL author's guide to getting through code review](https://google.github.io/eng-practices/review/developer/)
 1. [The Code Review Process in Kubernetes community](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process)
 1. [Submitting patches: the essential guide to getting your code into the kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html)
diff --git a/cmd/autotestgridgenerator/README.md b/cmd/autotestgridgenerator/README.md
new file mode 100644
index 00000000000..1163639fb73
--- /dev/null
+++ b/cmd/autotestgridgenerator/README.md
@@ -0,0 +1,40 @@
+# autotestgridgenerator
+
+Automatically generates and updates OpenShift testgrid definitions by running the testgrid-config-generator and creating pull requests.
+
+## Overview
+
+This tool automates the process of updating testgrid configurations in the kubernetes/test-infra repository. It runs the testgrid-config-generator command and creates/updates pull requests with the generated changes.
+
+## Usage
+
+```bash
+autotestgridgenerator \
+  --testgrid-config=/path/to/testgrid/config \
+  --release-config=/path/to/release/config \
+  --prow-jobs-dir=/path/to/prow/jobs \
+  --allow-list=/path/to/allow-list \
+  --github-token-path=/path/to/token
+```
+
+## Options
+
+- `--testgrid-config`: Directory where testgrid output will be stored
+- `--release-config`: Directory of release config files
+- `--prow-jobs-dir`: Directory where prow-job configs are stored
+- `--allow-list`: File containing release-type information to override defaults
+- `--github-login`: GitHub username to use (default: openshift-bot)
+- `--assign`: GitHub username or team to assign PR to (default: openshift/test-platform)
+- `--working-dir`: Working directory for git operations
+
+## How It Works
+
+1. Executes `/usr/bin/testgrid-config-generator` with provided configuration
+2. Generates testgrid configuration files
+3. Creates or updates a pull request in kubernetes/test-infra with the changes
+4. PR title format: "Update OpenShift testgrid definitions by auto-testgrid-generator job at <timestamp>"
+
+## Related Tools
+
+- [testgrid-config-generator](../testgrid-config-generator) - Generates testgrid configurations
+
diff --git a/cmd/backport-verifier/README.md b/cmd/backport-verifier/README.md
new file mode 100644
index 00000000000..5e0ae6440c3
--- /dev/null
+++ b/cmd/backport-verifier/README.md
@@ -0,0 +1,47 @@
+# backport-verifier
+
+Prow plugin that validates backports by verifying commits come from merged PRs in upstream repositories.
+
+## Overview
+
+The backport-verifier is a Prow webhook plugin that automatically validates backport pull requests. It checks that commits in a backport PR reference valid, merged upstream pull requests.
+
+## Features
+
+- Validates commit messages follow the `UPSTREAM: <PR_NUMBER>: <message>` format
+- Verifies referenced upstream PRs exist and are merged
+- Adds labels to PRs based on validation status:
+  - `backports/validated-commits` - All commits validated
+  - `backports/unvalidated-commits` - Some commits could not be validated
+- Responds to `/validate-backports` command in PR comments
+
+## Configuration
+
+The tool requires a configuration file mapping downstream repositories to their upstream counterparts:
+
+```yaml
+repositories:
+  openshift/kubernetes: kubernetes/kubernetes
+  openshift/etcd: etcd-io/etcd
+```
+
+## Usage
+
+```bash
+backport-verifier \
+  --config-path=/path/to/config.yaml \
+  --hmac-secret-file=/path/to/hmac-secret \
+  --github-token-path=/path/to/token
+```
+
+## How It Works
+
+1. Listens for pull request events and issue comments
+2. Extracts commit messages matching `UPSTREAM: <PR_NUMBER>: <message>` pattern
+3. Verifies each referenced upstream PR exists and is merged
+4. Updates PR labels and comments based on validation results
+
+## Commands
+
+- `/validate-backports` - Manually trigger validation for a PR
+
diff --git a/cmd/bugzilla-backporter/README.md b/cmd/bugzilla-backporter/README.md
new file mode 100644
index 00000000000..78a91cdf69f
--- /dev/null
+++ b/cmd/bugzilla-backporter/README.md
@@ -0,0 +1,42 @@
+# bugzilla-backporter
+
+Web service for managing Bugzilla bug clones and backports.
+
+## Overview
+
+The bugzilla-backporter provides a web interface and API for creating and managing Bugzilla bug clones across different target releases. It's used to track and manage backports of bugs to different OpenShift versions.
+
+## Features
+
+- Create bug clones for different target releases
+- View existing clones for a bug
+- Get bug details in JSON format
+- Landing page with usage information
+
+## Usage
+
+```bash
+bugzilla-backporter \
+  --bugzilla-api-key-path=/path/to/api-key \
+  --plugin-config=/etc/plugins/plugins.yaml \
+  --address=:8080
+```
+
+## Endpoints
+
+- `GET /` - Landing page with help information
+- `GET /clones` - List clones for a bug
+- `POST /clones/create` - Create a new bug clone
+- `GET /bug` - Get bug details in JSON format
+- `GET /help` - Help information
+
+## Configuration
+
+Requires:
+- Bugzilla API key
+- Plugin configuration file (for target release versions)
+
+## Related Packages
+
+- [pkg/backporter](../../pkg/backporter) - Bugzilla backporting logic
+
diff --git a/cmd/check-cluster-profiles-config/README.md b/cmd/check-cluster-profiles-config/README.md
new file mode 100644
index 00000000000..e7f3654fd52
--- /dev/null
+++ b/cmd/check-cluster-profiles-config/README.md
@@ -0,0 +1,30 @@
+# check-cluster-profiles-config
+
+Validates cluster profile configurations against actual cluster resources.
+
+## Overview
+
+This tool validates that cluster profile configurations defined in CI operator configs match the actual cluster profiles available in the cluster. It ensures consistency between configuration and reality.
+
+## Usage
+
+```bash
+check-cluster-profiles-config \
+  --config-path=/path/to/cluster-profile-config.yaml
+```
+
+## Options
+
+- `--config-path`: Path to the cluster profile config file
+
+## How It Works
+
+1. Loads cluster profile configuration
+2. Connects to Kubernetes cluster
+3. Validates that configured profiles exist and match cluster resources
+4. Reports any mismatches or missing profiles
+
+## Related
+
+- [pkg/api](../../pkg/api) - Cluster profile definitions
+
diff --git a/cmd/ci-operator-config-mirror/README.md b/cmd/ci-operator-config-mirror/README.md
new file mode 100644
index 00000000000..40b98c7ced7
--- /dev/null
+++ b/cmd/ci-operator-config-mirror/README.md
@@ -0,0 +1,45 @@
+# ci-operator-config-mirror
+
+Mirrors ci-operator configuration files from one organization to another in the openshift/release repository.
+
+## Overview
+
+This tool copies ci-operator configuration files from one GitHub organization to another within the openshift/release repository. It's useful for maintaining separate configurations for different organizational structures.
+
+## Usage
+
+```bash
+ci-operator-config-mirror \
+  --config-dir=ci-operator/config \
+  --to-org=target-org \
+  --only-org=source-org \
+  --confirm
+```
+
+## Options
+
+- `--config-dir`: Directory containing ci-operator configs
+- `--to-org`: Target organization to mirror configs to
+- `--only-org`: Only mirror configs from this organization (optional)
+- `--clean`: Delete existing target org directory before mirroring (default: true)
+- `--confirm`: Actually perform the mirroring (required)
+
+## How It Works
+
+1. Scans source organization's config files
+2. Copies them to the target organization directory
+3. Updates promotion namespaces if needed (ocp vs ocp-private)
+4. Optionally cleans existing target directory first
+
+## Example
+
+Mirror all configs from `openshift` org to `myorg`:
+
+```bash
+ci-operator-config-mirror \
+  --config-dir=ci-operator/config \
+  --to-org=myorg \
+  --only-org=openshift \
+  --confirm
+```
+
diff --git a/cmd/ci-operator-configresolver/README.md b/cmd/ci-operator-configresolver/README.md
new file mode 100644
index 00000000000..1dd1d64f8a7
--- /dev/null
+++ b/cmd/ci-operator-configresolver/README.md
@@ -0,0 +1,46 @@
+# ci-operator-configresolver
+
+HTTP server that resolves and serves ci-operator configurations with resolved references.
+
+## Overview
+
+The configresolver provides a web service that loads ci-operator configurations, resolves all references (base images, includes, etc.), and serves them via HTTP. It also provides a web UI for browsing configurations.
+
+## Features
+
+- Resolves ci-operator config references in real-time
+- Serves resolved configs via REST API
+- Web UI for browsing configurations
+- Watches for config changes and reloads automatically
+- Integrates with step registry
+
+## Usage
+
+```bash
+ci-operator-configresolver \
+  --config-path=/path/to/configs \
+  --registry-path=/path/to/registry \
+  --address=:8080 \
+  --ui-address=:8081
+```
+
+## Options
+
+- `--config-path`: Path to ci-operator config directory
+- `--registry-path`: Path to step registry
+- `--address`: Address for API server (default: :8080)
+- `--ui-address`: Address for web UI (default: :8081)
+- `--release-repo-git-sync-path`: Path for git-synced release repo
+- `--log-level`: Logging level
+
+## API Endpoints
+
+- `GET /config` - Get resolved config for org/repo/branch
+- `GET /resolve` - Resolve config with parameters
+- Web UI available at the UI address
+
+## Related
+
+- [pkg/configresolver](../../pkg/api/configresolver) - Config resolution logic
+- [pkg/registry](../../pkg/registry) - Step registry
+
diff --git a/cmd/ci-operator-prowgen/README.md b/cmd/ci-operator-prowgen/README.md
index 50b22cf4ad2..d525b87f8cd 100644
--- a/cmd/ci-operator-prowgen/README.md
+++ b/cmd/ci-operator-prowgen/README.md
@@ -1,10 +1,31 @@
-prowgen
-=======
+# ci-operator-prowgen
+
+Generates Prow job configurations from ci-operator configuration files.
+
+## Overview
 
 Prowgen is a tool that generates [job configurations](https://docs.prow.k8s.io/docs/jobs/) based on
 [ci-operator configuration](https://docs.ci.openshift.org/docs/architecture/ci-operator/) and its own
 configuration file named `.config.prowgen`.
 
+## Usage
+
+```bash
+ci-operator-prowgen \
+  --from-dir=ci-operator/config \
+  --to-dir=ci-operator/jobs
+```
+
+## Options
+
+- `--from-dir`: Directory containing ci-operator configs
+- `--to-dir`: Directory to write generated Prow job configs
+- `--from-release-repo`: Use release repo as source
+- `--to-release-repo`: Write to release repo
+- `--known-infra-file`: Known infrastructure job files
+
+## Configuration
+
 The contents of `.config.prowgen` will be appended to every job configuration during Prowgen execution:
 
 **Example:**
diff --git a/cmd/ci-operator/README.md b/cmd/ci-operator/README.md
new file mode 100644
index 00000000000..2da8c27f90d
--- /dev/null
+++ b/cmd/ci-operator/README.md
@@ -0,0 +1,138 @@
+# ci-operator
+
+The core orchestration engine for OpenShift CI. Reads declarative YAML configurations and executes multi-stage image builds and tests on OpenShift clusters.
+
+## Overview
+
+`ci-operator` is the main tool that orchestrates CI jobs for OpenShift projects. It:
+
+- Reads YAML configuration files that define builds, tests, and image promotion
+- Builds a dependency graph to determine execution order
+- Executes steps in parallel where possible
+- Manages Kubernetes resources (Builds, Pods, ImageStreams)
+- Collects artifacts and promotes images after successful builds
+
+## Usage
+
+### Basic Usage
+
+```bash
+ci-operator \
+  --config=path/to/config.yaml \
+  --git-ref=org/repo@branch \
+  --target=test-name
+```
+
+### With JOB_SPEC (typical in Prow)
+
+```bash
+export JOB_SPEC='{
+  "type":"presubmit",
+  "job":"pull-ci-openshift-kubernetes-main-unit",
+  "refs":{
+    "org":"openshift",
+    "repo":"kubernetes",
+    "base_ref":"main",
+    "base_sha":"abc123def456",
+    "pulls":[{"number":12345,"author":"user","sha":"def789"}]
+  }
+}'
+ci-operator --config=config.yaml
+```
+
+### Common Options
+
+- `--config`: CI operator config file (required)
+- `--git-ref`: Git reference in format `org/repo@branch`
+- `--target`: Specific target to run (image name or test name)
+- `--namespace`: Kubernetes namespace (auto-generated if not provided)
+- `--promote`: Promote images after successful build
+- `--artifact-dir`: Directory for artifact collection
+- `--print-graph`: Print dependency graph and exit
+- `--dry-run`: Show what would be done without executing
+
+## How It Works
+
+1. **Configuration Loading**: Loads and validates YAML configuration
+2. **Graph Building**: Builds dependency graph from config to determine execution order
+3. **Input Resolution**: Resolves base images and other inputs
+4. **Namespace Creation**: Creates a namespace for the build
+5. **Step Execution**: Executes steps in dependency order (builds images, runs tests)
+6. **Artifact Collection**: Collects artifacts from completed steps
+7. **Image Promotion**: Promotes images to release streams (if `--promote` is used)
+8. **Cleanup**: Cleans up namespace (if configured)
+
+## Configuration
+
+CI Operator configs are YAML files with this structure:
+
+```yaml
+base_images:
+  base:
+    namespace: openshift
+    name: base
+    tag: "4.15"
+
+build_root:
+  image_stream_tag:
+    namespace: openshift
+    name: release
+    tag: golang-1.21
+
+images:
+- dockerfile_path: Dockerfile
+  to: my-image
+
+tests:
+- as: unit
+  commands: make test
+  container:
+    from: my-image
+```
+
+See [pkg/api/config.go](../../pkg/api/config.go) for the full configuration structure.
+
+## Key Components
+
+- **Configuration Loading**: `pkg/config/load.go`
+- **Graph Building**: `pkg/api/graph.go`
+- **Step Execution**: `pkg/steps/`
+- **Image Promotion**: `pkg/promotion/`
+
+## Examples
+
+### Running a Test
+
+```bash
+ci-operator \
+  --config=config.yaml \
+  --git-ref=myorg/myrepo@main \
+  --target=unit
+```
+
+### Building and Promoting Images
+
+```bash
+ci-operator \
+  --config=config.yaml \
+  --git-ref=openshift/origin@main \
+  --target=images \
+  --promote
+```
+
+### Debugging
+
+```bash
+# Print dependency graph
+ci-operator --config=config.yaml --print-graph
+
+# Run with verbose logging
+ci-operator --config=config.yaml --log-level=debug
+```
+
+## Related Documentation
+
+- [Architecture Guide](../../docs/ARCHITECTURE.md) - System architecture and design
+- [CI Operator Reference](https://steps.svc.ci.openshift.org/) - Step registry documentation
+- [OpenShift CI Documentation](https://docs.ci.openshift.org/) - Official CI documentation
+
diff --git a/cmd/ci-secret-bootstrap/README.md b/cmd/ci-secret-bootstrap/README.md
index 40fff157526..af267b08be6 100644
--- a/cmd/ci-secret-bootstrap/README.md
+++ b/cmd/ci-secret-bootstrap/README.md
@@ -1,7 +1,11 @@
-# CI-Secret-Bootstrap
+# ci-secret-bootstrap
+
+Bootstraps CI secrets from BitWarden and syncs them across Kubernetes/OpenShift clusters.
+
+## Overview
 
 This tool extends the [populate-secrets-from-bitwarden.sh](https://github.com/openshift/release/blob/c8c89d08c56c653b91eb8c7580657f7ce522253f/ci-operator/populate-secrets-from-bitwarden.sh)
-to support mirroring secrets cross Kubernetes/OpenShift-clusters.
+to support mirroring secrets across Kubernetes/OpenShift clusters. It reads secrets from BitWarden and creates Kubernetes secrets in specified clusters and namespaces.
 
 ## Args and config.yaml
 
diff --git a/cmd/cluster-display/README.md b/cmd/cluster-display/README.md
new file mode 100644
index 00000000000..2d4d64ea8c2
--- /dev/null
+++ b/cmd/cluster-display/README.md
@@ -0,0 +1,42 @@
+# cluster-display
+
+Web service for displaying information about OpenShift CI clusters.
+
+## Overview
+
+Cluster-display provides a web interface to view information about clusters used in OpenShift CI, including cluster pools, cluster deployments, and their status.
+
+## Features
+
+- View cluster pool information
+- Display cluster deployment status
+- Filter and search clusters
+- Real-time cluster status updates
+
+## Usage
+
+```bash
+cluster-display \
+  --kubeconfig=/path/to/kubeconfig \
+  --port=8090
+```
+
+## Options
+
+- `--kubeconfig`: Path to kubeconfig file
+- `--port`: Port to run the server on (default: 8090)
+- `--log-level`: Logging level (default: info)
+- `--gracePeriod`: Grace period for server shutdown
+
+## Web Interface
+
+The tool provides a web interface accessible at the configured port showing:
+- Cluster pools and their status
+- Cluster deployments
+- Cluster availability
+- Resource information
+
+## Related
+
+- [pkg/api](../../pkg/api) - Cluster profile and API definitions
+
diff --git a/cmd/cluster-operator-status/README.md b/cmd/cluster-operator-status/README.md
new file mode 100644
index 00000000000..7c8f7d6607e
--- /dev/null
+++ b/cmd/cluster-operator-status/README.md
@@ -0,0 +1,82 @@
+# cluster-operator-status
+
+`cluster-operator-status` is a tool that analyzes the health status of OpenShift cluster operators. It can either read cluster operator status from stdin (parsing `oc get co` output) or query a cluster directly.
+
+## Usage
+
+### Reading from stdin
+
+Parse cluster operator status from `oc get co` output:
+
+```bash
+oc --context build01 get co | cluster-operator-status --from-stdin
+```
+
+### Querying a cluster directly
+
+Query cluster operators from a specific context:
+
+```bash
+cluster-operator-status --context build01
+```
+
+Or use the default/in-cluster context:
+
+```bash
+cluster-operator-status
+```
+
+## Output
+
+The tool provides a summary of cluster operator health:
+
+- **Total Operators**: Count of all cluster operators
+- **Healthy**: Operators that are available, not degraded, and not progressing
+- **Degraded**: Operators with `Degraded=True`
+- **Unavailable**: Operators with `Available=False`
+- **Progressing**: Operators that are currently updating (normal during upgrades)
+
+For each problematic operator, it displays:
+- Operator name
+- Version
+- Time since the status changed
+- Error/degradation message
+
+## Examples
+
+### Analyze from command output
+
+```bash
+$ oc --context build01 get co | cluster-operator-status --from-stdin
+
+=== Cluster Operator Health Summary ===
+
+Total Operators: 35
+  ✓ Healthy: 28
+  ⚠ Degraded: 5
+  ✗ Unavailable: 2
+  ⟳ Progressing: 7
+
+=== Degraded Operators ===
+
+authentication (Version: 4.19.19, Since: 36d)
+  Message: APIServerDeploymentDegraded: 1 of 3 requested instances are unavailable...
+
+=== Unavailable Operators ===
+
+kube-storage-version-migrator (Version: 4.19.19, Since: 14h)
+  Message: KubeStorageVersionMigratorAvailable: Waiting for Deployment
+```
+
+### Query cluster directly
+
+```bash
+$ cluster-operator-status --context build01
+
+=== Cluster Operator Health Summary ===
+...
+```
+
+
+
+
diff --git a/cmd/clusterimageset-updater/README.md b/cmd/clusterimageset-updater/README.md
new file mode 100644
index 00000000000..c524ceace1b
--- /dev/null
+++ b/cmd/clusterimageset-updater/README.md
@@ -0,0 +1,32 @@
+# clusterimageset-updater
+
+Updates ClusterImageSet resources based on cluster pool specifications.
+
+## Overview
+
+This tool generates ClusterImageSet YAML files from cluster pool specifications. It reads cluster pool YAML files and creates corresponding ClusterImageSet resources for use in cluster provisioning.
+
+## Usage
+
+```bash
+clusterimageset-updater \
+  --pools=/path/to/cluster-pools \
+  --imagesets=/path/to/output
+```
+
+## Options
+
+- `--pools`: Path to directory containing cluster pool specs (*_clusterpool.yaml files)
+- `--imagesets`: Path to directory for output ClusterImageSet files (*_clusterimageset.yaml files)
+
+## How It Works
+
+1. Scans input directory for cluster pool YAML files
+2. Extracts version information from pool labels
+3. Generates ClusterImageSet resources with appropriate version streams
+4. Writes output files to the specified directory
+
+## Related
+
+- [pkg/release](../../pkg/release) - Release and version management
+
diff --git a/cmd/determinize-ci-operator/README.md b/cmd/determinize-ci-operator/README.md
new file mode 100644
index 00000000000..5b0504826a5
--- /dev/null
+++ b/cmd/determinize-ci-operator/README.md
@@ -0,0 +1,39 @@
+# determinize-ci-operator
+
+Normalizes and formats ci-operator configuration files for consistency.
+
+## Overview
+
+Determinize-ci-operator ensures that ci-operator configuration files are consistently formatted and ordered. It normalizes YAML structure, sorts fields, and ensures deterministic output.
+
+## Usage
+
+```bash
+determinize-ci-operator \
+  --config-dir=ci-operator/config \
+  --confirm
+```
+
+## Options
+
+- `--config-dir`: Directory containing ci-operator configs
+- `--confirm`: Actually write changes (required for modifications)
+- `--prow-jobs-dir`: Directory containing prow job configs (optional)
+
+## How It Works
+
+1. Loads all ci-operator configuration files
+2. Normalizes YAML structure and ordering
+3. Sorts fields consistently
+4. Writes normalized configs back (if --confirm is used)
+
+## Use Cases
+
+- Ensure consistent formatting across all configs
+- Prepare configs for commit
+- Validate config structure
+
+## Related
+
+- [pkg/config](../../pkg/config) - Configuration loading and management
+
diff --git a/cmd/determinize-peribolos/README.md b/cmd/determinize-peribolos/README.md
new file mode 100644
index 00000000000..d55240b9b36
--- /dev/null
+++ b/cmd/determinize-peribolos/README.md
@@ -0,0 +1,32 @@
+# determinize-peribolos
+
+Normalizes and formats Peribolos configuration files for consistency.
+
+## Overview
+
+Determinize-peribolos ensures that Peribolos (GitHub organization management) configuration files are consistently formatted and ordered.
+
+## Usage
+
+```bash
+determinize-peribolos \
+  --config-path=/path/to/peribolos.yaml \
+  --confirm
+```
+
+## Options
+
+- `--config-path`: Path to Peribolos configuration file
+- `--confirm`: Actually write changes (required for modifications)
+
+## How It Works
+
+1. Loads Peribolos configuration
+2. Normalizes YAML structure and ordering
+3. Sorts fields consistently
+4. Writes normalized config back (if --confirm is used)
+
+## Related
+
+- Peribolos - GitHub organization management tool
+
diff --git a/cmd/determinize-prow-config/README.md b/cmd/determinize-prow-config/README.md
new file mode 100644
index 00000000000..32889ec611a
--- /dev/null
+++ b/cmd/determinize-prow-config/README.md
@@ -0,0 +1,32 @@
+# determinize-prow-config
+
+Normalizes and formats Prow configuration files for consistency.
+
+## Overview
+
+Determinize-prow-config ensures that Prow configuration files are consistently formatted and ordered. It normalizes YAML structure and ensures deterministic output.
+
+## Usage
+
+```bash
+determinize-prow-config \
+  --prow-config=/path/to/config.yaml \
+  --confirm
+```
+
+## Options
+
+- `--prow-config`: Path to Prow configuration file
+- `--confirm`: Actually write changes (required for modifications)
+
+## How It Works
+
+1. Loads Prow configuration file
+2. Normalizes YAML structure and ordering
+3. Sorts fields consistently
+4. Writes normalized config back (if --confirm is used)
+
+## Related
+
+- Prow - Kubernetes CI/CD system
+
diff --git a/cmd/docgen/README.md b/cmd/docgen/README.md
new file mode 100644
index 00000000000..8bf45034ab6
--- /dev/null
+++ b/cmd/docgen/README.md
@@ -0,0 +1,18 @@
+# docgen
+
+Generates documentation from code and configuration files.
+
+## Overview
+
+Docgen is a documentation generation tool that extracts information from code and configuration files to generate documentation.
+
+## Usage
+
+```bash
+docgen [options]
+```
+
+## Related
+
+- Used for generating documentation from various sources
+
diff --git a/cmd/dptp-pools-cm/README.md b/cmd/dptp-pools-cm/README.md
new file mode 100644
index 00000000000..19524bf28e7
--- /dev/null
+++ b/cmd/dptp-pools-cm/README.md
@@ -0,0 +1,19 @@
+# dptp-pools-cm
+
+Manages cluster pool ConfigMaps for DPTP (Dev Productivity and Test Platform).
+
+## Overview
+
+This tool manages ConfigMaps that define cluster pools used by the test platform for provisioning test clusters.
+
+## Usage
+
+```bash
+dptp-pools-cm [options]
+```
+
+## Related
+
+- Cluster pool management
+- ConfigMap operations
+
diff --git a/cmd/entrypoint-wrapper/README.md b/cmd/entrypoint-wrapper/README.md
new file mode 100644
index 00000000000..a6c981d768b
--- /dev/null
+++ b/cmd/entrypoint-wrapper/README.md
@@ -0,0 +1,18 @@
+# entrypoint-wrapper
+
+Wrapper utility for Prow entrypoint execution.
+
+## Overview
+
+Entrypoint-wrapper provides additional functionality around Prow's entrypoint binary, such as logging, metrics collection, or custom execution logic.
+
+## Usage
+
+```bash
+entrypoint-wrapper [entrypoint-args...]
+```
+
+## Related
+
+- Prow entrypoint - Job execution entrypoint
+
diff --git a/cmd/generate-registry-metadata/README.md b/cmd/generate-registry-metadata/README.md
new file mode 100644
index 00000000000..8e7e54b640a
--- /dev/null
+++ b/cmd/generate-registry-metadata/README.md
@@ -0,0 +1,19 @@
+# generate-registry-metadata
+
+Generates metadata files for container image registries.
+
+## Overview
+
+This tool generates metadata files that describe container images in registries, including image tags, digests, and other metadata.
+
+## Usage
+
+```bash
+generate-registry-metadata [options]
+```
+
+## Related
+
+- Container registry management
+- Image metadata
+
diff --git a/cmd/helpdesk-faq/README.md b/cmd/helpdesk-faq/README.md
new file mode 100644
index 00000000000..321b3cc8006
--- /dev/null
+++ b/cmd/helpdesk-faq/README.md
@@ -0,0 +1,18 @@
+# helpdesk-faq
+
+Manages FAQ content for helpdesk systems.
+
+## Overview
+
+Helpdesk-faq provides functionality for managing and serving FAQ content for helpdesk or support systems.
+
+## Usage
+
+```bash
+helpdesk-faq [options]
+```
+
+## Related
+
+- [pkg/helpdesk-faq](../../pkg/helpdesk-faq) - FAQ management logic
+
diff --git a/cmd/job-trigger-controller-manager/README.md b/cmd/job-trigger-controller-manager/README.md
new file mode 100644
index 00000000000..62e2b032b07
--- /dev/null
+++ b/cmd/job-trigger-controller-manager/README.md
@@ -0,0 +1,24 @@
+# job-trigger-controller-manager
+
+Kubernetes controller manager for triggering Prow jobs.
+
+## Overview
+
+This controller manager runs controllers that watch for events and trigger Prow jobs based on configured rules and conditions.
+
+## Usage
+
+```bash
+job-trigger-controller-manager \
+  --kubeconfig=/path/to/kubeconfig
+```
+
+## Options
+
+- `--kubeconfig`: Path to kubeconfig file
+- Additional controller-specific options
+
+## Related
+
+- [pkg/controller](../../pkg/controller) - Controller implementations
+
diff --git a/cmd/payload-testing-prow-plugin/README.md b/cmd/payload-testing-prow-plugin/README.md
new file mode 100644
index 00000000000..53cc4976e7b
--- /dev/null
+++ b/cmd/payload-testing-prow-plugin/README.md
@@ -0,0 +1,23 @@
+# payload-testing-prow-plugin
+
+Prow plugin for managing payload testing workflows.
+
+## Overview
+
+This Prow plugin provides functionality for managing and orchestrating payload testing workflows, including triggering tests, managing test runs, and reporting results.
+
+## Usage
+
+Configured as a Prow plugin in the Prow configuration.
+
+## Features
+
+- Payload test triggering
+- Test run management
+- Result reporting
+
+## Related
+
+- Prow plugins
+- Payload testing workflows
+
diff --git a/cmd/pipeline-controller/README.md b/cmd/pipeline-controller/README.md
new file mode 100644
index 00000000000..f50e5c5b756
--- /dev/null
+++ b/cmd/pipeline-controller/README.md
@@ -0,0 +1,25 @@
+# pipeline-controller
+
+Kubernetes controller for managing CI/CD pipelines.
+
+## Overview
+
+Pipeline-controller manages pipeline resources and orchestrates pipeline execution based on defined workflows and dependencies.
+
+## Usage
+
+```bash
+pipeline-controller \
+  --kubeconfig=/path/to/kubeconfig
+```
+
+## Options
+
+- `--kubeconfig`: Path to kubeconfig file
+- Additional controller-specific options
+
+## Related
+
+- Pipeline management
+- CI/CD orchestration
+
diff --git a/cmd/pj-rehearse/README.md b/cmd/pj-rehearse/README.md
new file mode 100644
index 00000000000..1d151a497e8
--- /dev/null
+++ b/cmd/pj-rehearse/README.md
@@ -0,0 +1,19 @@
+# pj-rehearse
+
+Rehearses Prow job configurations before merging changes.
+
+## Overview
+
+Pj-rehearse tests Prow job configurations by running them in a rehearsal environment to validate changes before they're merged to production.
+
+## Usage
+
+```bash
+pj-rehearse [options]
+```
+
+## Related
+
+- [pkg/rehearse](../../pkg/rehearse) - Rehearsal logic
+- Prow job validation
+
diff --git a/cmd/rebalancer/README.md b/cmd/rebalancer/README.md
new file mode 100644
index 00000000000..b18d2a611b7
--- /dev/null
+++ b/cmd/rebalancer/README.md
@@ -0,0 +1,19 @@
+# rebalancer
+
+Rebalances workloads across clusters or resources.
+
+## Overview
+
+Rebalancer redistributes workloads or resources to optimize utilization and balance load across available clusters or resources.
+
+## Usage
+
+```bash
+rebalancer [options]
+```
+
+## Related
+
+- Workload management
+- Resource optimization
+
diff --git a/cmd/result-aggregator/README.md b/cmd/result-aggregator/README.md
new file mode 100644
index 00000000000..4d5c7e4ad33
--- /dev/null
+++ b/cmd/result-aggregator/README.md
@@ -0,0 +1,19 @@
+# result-aggregator
+
+Aggregates test results from multiple sources.
+
+## Overview
+
+Result-aggregator collects and aggregates test results from various sources, providing a unified view of test outcomes.
+
+## Usage
+
+```bash
+result-aggregator [options]
+```
+
+## Related
+
+- Test result management
+- Result aggregation
+
diff --git a/cmd/retester/README.md b/cmd/retester/README.md
new file mode 100644
index 00000000000..817cf0fef9c
--- /dev/null
+++ b/cmd/retester/README.md
@@ -0,0 +1,26 @@
+# retester
+
+Automatically retests failed jobs.
+
+## Overview
+
+Retester monitors job failures and automatically triggers retests for failed jobs based on configured policies.
+
+## Usage
+
+```bash
+retester \
+  --prow-config=/path/to/config.yaml \
+  --github-token-path=/path/to/token
+```
+
+## Options
+
+- `--prow-config`: Path to Prow configuration
+- `--github-token-path`: Path to GitHub token
+- `--dry-run`: Show what would be done without making changes
+
+## Related
+
+- [pkg/retester](../../pkg/retester) - Retest logic and policies
+
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 00000000000..3ccaecab70d
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,802 @@
+# CI-Tools Architecture and Usage Guide
+
+This document provides a comprehensive guide to CI-Tools architecture, codebase structure, and practical usage examples.
+
+## Table of Contents
+
+- [System Architecture](#system-architecture)
+- [Component Architecture](#component-architecture)
+- [Repository Structure](#repository-structure)
+- [Core Components](#core-components)
+- [Usage Examples](#usage-examples)
+- [Design Patterns](#design-patterns)
+- [Deployment Architecture](#deployment-architecture)
+- [Security Architecture](#security-architecture)
+- [Extension Points](#extension-points)
+
+## System Architecture
+
+The CI-Tools repository provides a distributed system of tools and services that work together to manage the OpenShift CI infrastructure. The architecture follows a microservices-like pattern where each tool has a specific responsibility.
+
+### High-Level Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "CI Infrastructure"
+        Prow[Prow CI System]
+        K8s[Kubernetes/OpenShift Clusters]
+        Registry[Image Registry]
+        GCS[Google Cloud Storage]
+        Vault[Vault/GSM Secrets]
+    end
+    
+    subgraph "CI-Tools Components"
+        CIOperator[ci-operator<br/>Build Orchestrator]
+        ConfigMgmt[Configuration Management Tools]
+        ImageMgmt[Image Management Tools]
+        SecretMgmt[Secret Management Tools]
+        ClusterMgmt[Cluster Management Tools]
+        Controllers[Kubernetes Controllers]
+    end
+    
+    subgraph "Configuration Sources"
+        ReleaseRepo[openshift/release<br/>Repository]
+        RepoConfigs[Repository CI Configs]
+    end
+    
+    subgraph "Developer Tools"
+        RepoInit[repo-init UI/API]
+        WebUIs[Web UIs<br/>pod-scaler, vault-manager]
+    end
+    
+    Prow --> CIOperator
+    CIOperator --> K8s
+    CIOperator --> Registry
+    CIOperator --> GCS
+    
+    ConfigMgmt --> ReleaseRepo
+    ConfigMgmt --> RepoConfigs
+    ConfigMgmt --> Prow
+    
+    ImageMgmt --> Registry
+    ImageMgmt --> K8s
+    
+    SecretMgmt --> Vault
+    SecretMgmt --> K8s
+    
+    ClusterMgmt --> K8s
+    Controllers --> K8s
+    
+    RepoInit --> ReleaseRepo
+    WebUIs --> Controllers
+    
+    style CIOperator fill:#e1f5ff
+    style ConfigMgmt fill:#fff4e1
+    style ImageMgmt fill:#e8f5e9
+    style SecretMgmt fill:#fce4ec
+    style ClusterMgmt fill:#f3e5f5
+```
+
+## Component Architecture
+
+### CI Operator Architecture
+
+The CI Operator is the core orchestration engine. It follows a graph-based execution model.
+
+```mermaid
+graph LR
+    A[Load Config] --> B[Parse YAML]
+    B --> C[Build Dependency Graph]
+    C --> D[Resolve Inputs]
+    D --> E[Create Namespace]
+    E --> F[Execute Steps]
+    F --> G[Collect Artifacts]
+    G --> H[Promote Images]
+    H --> I[Cleanup]
+    
+    F --> F1[Build Images]
+    F --> F2[Run Tests]
+    F --> F3[Execute Templates]
+    
+    style A fill:#e1f5ff
+    style F fill:#fff4e1
+    style H fill:#e8f5e9
+```
+
+### Configuration Management Flow
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant Repo as openshift/release
+    participant Auto as autoconfigbrancher
+    participant Tools as Config Tools
+    participant Prow as Prow
+    
+    Dev->>Repo: Creates/Updates CI Config
+    Auto->>Repo: Periodically Runs
+    Auto->>Tools: Executes config-brancher
+    Tools->>Repo: Propagates to Release Branches
+    Auto->>Tools: Executes ci-operator-prowgen
+    Tools->>Repo: Generates Prow Jobs
+    Auto->>Repo: Creates PR with Changes
+    Repo->>Prow: Merges PR
+    Prow->>Prow: Updates Job Configs
+```
+
+### Image Build and Promotion Flow
+
+```mermaid
+graph TD
+    A[Source Code Change] --> B[Prow Triggers Job]
+    B --> C[ci-operator Starts]
+    C --> D[Create Build Namespace]
+    D --> E[Build Base Images]
+    E --> F[Build Component Images]
+    F --> G[Run Tests]
+    G --> H{Tests Pass?}
+    H -->|Yes| I[Promote Images]
+    H -->|No| J[Report Failure]
+    I --> K[Tag to Release Stream]
+    K --> L[Update ImageStreams]
+    
+    style I fill:#e8f5e9
+    style J fill:#ffebee
+```
+
+### Data Flow Diagram
+
+```mermaid
+flowchart TD
+    subgraph "Input Sources"
+        GH[GitHub Events]
+        Config[CI Configs]
+        Secrets[Secret Stores]
+    end
+    
+    subgraph "Processing"
+        Prow[Prow]
+        CIOp[ci-operator]
+        Controllers[Controllers]
+    end
+    
+    subgraph "Storage"
+        Registry[Image Registry]
+        GCS[GCS Artifacts]
+        BigQuery[BigQuery Metrics]
+        Prometheus[Prometheus Metrics]
+    end
+    
+    subgraph "Output"
+        Results[Test Results]
+        Images[Promoted Images]
+        Reports[Reports/Dashboards]
+    end
+    
+    GH --> Prow
+    Config --> Prow
+    Secrets --> Controllers
+    
+    Prow --> CIOp
+    Controllers --> Registry
+    
+    CIOp --> Registry
+    CIOp --> GCS
+    CIOp --> BigQuery
+    
+    Controllers --> Prometheus
+    
+    Registry --> Images
+    GCS --> Results
+    BigQuery --> Reports
+    Prometheus --> Reports
+```
+
+## Repository Structure
+
+The CI-Tools repository follows a standard Go project layout with clear separation of concerns:
+
+```
+ci-tools/
+├── cmd/                    # Command-line tools and applications
+├── pkg/                    # Shared libraries and packages
+├── test/                   # Test files and test data
+├── hack/                   # Build scripts and utilities
+├── images/                 # Container image definitions
+├── vendor/                 # Vendored dependencies
+├── docs/                   # Documentation
+├── Makefile               # Build automation
+├── go.mod                  # Go module definition
+└── README.md              # Main README
+```
+
+### `/cmd` - Command-Line Tools
+
+This directory contains all executable tools. Each subdirectory represents a standalone command-line application. See individual `cmd/<tool-name>/README.md` files for detailed documentation.
+
+**Core CI Tools:**
+- `ci-operator/` - Main CI orchestration engine
+- `ci-operator-prowgen/` - Generates Prow jobs from ci-operator configs
+- `ci-operator-checkconfig/` - Validates ci-operator configurations
+- `ci-operator-configresolver/` - Resolves ci-operator config references
+
+**Configuration Management:**
+- `config-brancher/` - Propagates configs to release branches
+- `autoconfigbrancher/` - Orchestrates multiple config tools
+- `determinize-ci-operator/` - Normalizes CI configs
+- `ci-operator-yaml-creator/` - Creates CI configs from templates
+
+**Image Management:**
+- `registry-replacer/` - Replaces registry references
+- `ci-images-mirror/` - Mirrors images between registries
+- `promoted-image-governor/` - Manages image promotion
+- `clusterimageset-updater/` - Updates cluster image sets
+
+**Secret Management:**
+- `ci-secret-generator/` - Generates secrets from templates
+- `ci-secret-bootstrap/` - Bootstraps secrets for repos
+- `gsm-secret-sync/` - Syncs secrets from Google Secret Manager
+- `vault-secret-collection-manager/` - Web UI for Vault secrets
+
+**Cluster Management:**
+- `cluster-init/` - Initializes test clusters
+- `dptp-controller-manager/` - Main Kubernetes controller manager
+- `cluster-display/` - Displays cluster information
+
+**Job Management:**
+- `prow-job-dispatcher/` - Dispatches jobs to clusters
+- `job-run-aggregator/` - Aggregates job run data
+- `result-aggregator/` - Aggregates test results
+- `retester/` - Retests failed jobs
+
+**Developer Tools:**
+- `repo-init/` - Web UI/API for repo initialization
+- `prcreator/` - Creates pull requests
+- `backport-verifier/` - Verifies backports
+- `blocking-issue-creator/` - Creates blocking issues
+
+### `/pkg` - Shared Packages
+
+This directory contains reusable Go packages used across multiple tools. See individual `pkg/<package-name>/README.md` files for detailed documentation.
+
+**Core API:**
+- `pkg/api/` - Core data structures and types
+  - `config.go` - CI operator configuration types
+  - `types.go` - Common type definitions
+  - `graph.go` - Dependency graph implementation
+  - `promotion.go` - Image promotion logic
+
+**Configuration:**
+- `pkg/config/` - Configuration loading and management
+- `pkg/defaults/` - Default value handling
+- `pkg/validation/` - Configuration validation
+
+**CI Operator Components:**
+- `pkg/steps/` - Step execution framework
+- `pkg/registry/` - Step registry management
+- `pkg/prowgen/` - Prow job generation
+- `pkg/rehearse/` - Job rehearsal logic
+
+**Kubernetes Integration:**
+- `pkg/kubernetes/` - Kubernetes client utilities
+- `pkg/controller/` - Controller implementations
+- `pkg/dispatcher/` - Job dispatching logic
+
+**Utilities:**
+- `pkg/util/` - General utilities
+- `pkg/junit/` - JUnit XML handling
+- `pkg/github/` - GitHub API integration
+- `pkg/jira/` - Jira integration
+- `pkg/slack/` - Slack integration
+
+## Core Components
+
+### CI Operator
+
+#### How CI Operator Works
+
+1. **Configuration Loading** (`pkg/config/load.go`):
+   - Loads YAML configuration
+   - Resolves references and includes
+   - Validates configuration
+
+2. **Graph Building** (`pkg/api/graph.go`):
+   - Builds dependency graph from config
+   - Determines execution order
+   - Identifies parallel execution opportunities
+
+3. **Step Execution** (`pkg/steps/`):
+   - Executes steps in dependency order
+   - Manages Kubernetes resources
+   - Collects artifacts
+   - Handles errors and retries
+
+4. **Image Promotion** (`pkg/promotion/`):
+   - Tags images to release streams
+   - Updates ImageStreams
+   - Handles promotion policies
+
+#### Key API
+
+```go
+// Configuration Structure (pkg/api/config.go)
+type ReleaseBuildConfiguration struct {
+    InputConfiguration
+    BuildRoot
+    Images
+    Tests
+    Promotion
+    ReleaseTagConfiguration
+}
+
+// Step Interface (pkg/steps/step.go)
+type Step interface {
+    Inputs() []api.InputDefinition
+    Validate() error
+    Run(ctx context.Context) error
+    Requires() []api.StepLink
+    Creates() []api.StepLink
+    Provides() (api.ParameterMap, error)
+}
+```
+
+### Configuration Management
+
+#### How Configuration Management Works
+
+1. **Config Brancher** (`cmd/config-brancher/`):
+   - Reads ci-operator configs from openshift/release
+   - Identifies repos promoting to current release
+   - Copies configs to future release branches
+   - Disables promotion conflicts
+
+2. **Prowgen** (`cmd/ci-operator-prowgen/`):
+   - Reads ci-operator configs
+   - Generates Prow job YAML files
+   - Organizes jobs by org/repo/branch
+   - Handles periodic, presubmit, postsubmit jobs
+
+3. **Autoconfigbrancher** (`cmd/autoconfigbrancher/`):
+   - Orchestrates multiple config tools
+   - Runs tools in sequence
+   - Creates PRs with changes
+   - Auto-merges approved PRs
+
+### Controllers
+
+#### How Controllers Work
+
+1. **Controller Manager** (`cmd/dptp-controller-manager/`):
+   - Initializes multiple controllers
+   - Manages controller lifecycle
+   - Handles graceful shutdown
+
+2. **Individual Controllers** (`pkg/controller/`):
+   - Watch Kubernetes resources
+   - Reconcile desired state
+   - Handle errors and retries
+   - Update resource status
+
+#### Reconciler Interface
+```go
+type Reconciler interface {
+    Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
+}
+```
+
+## Usage Examples
+
+### CI Operator Usage
+
+#### Basic Usage
+
+```bash
+# Basic execution
+ci-operator \
+  --config=path/to/config.yaml \
+  --git-ref=openshift/kubernetes@main \
+  --target=unit
+
+# With JOB_SPEC (typical in Prow)
+export JOB_SPEC='{
+  "type":"presubmit",
+  "job":"pull-ci-openshift-kubernetes-main-unit",
+  "refs":{
+    "org":"openshift",
+    "repo":"kubernetes",
+    "base_ref":"main",
+    "base_sha":"abc123def456",
+    "pulls":[{"number":12345,"author":"user","sha":"def789"}]
+  }
+}'
+ci-operator --config=config.yaml
+```
+
+#### Common Options
+
+```bash
+ci-operator \
+  --config=config.yaml \           # CI operator config file
+  --git-ref=org/repo@branch \       # Git reference
+  --target=test-name \               # Specific target to run
+  --namespace=my-namespace \        # Kubernetes namespace
+  --promote \                       # Promote images after build
+  --artifact-dir=/tmp/artifacts \   # Artifact collection directory
+  --print-graph                     # Print dependency graph
+```
+
+### Configuration Management
+
+#### Generating Prow Jobs
+
+```bash
+# Generate jobs for all configs
+ci-operator-prowgen \
+  --from-dir=ci-operator/config \
+  --to-dir=ci-operator/jobs
+
+# Generate for specific org/repo
+ci-operator-prowgen \
+  --from-dir=ci-operator/config/openshift/kubernetes \
+  --to-dir=ci-operator/jobs/openshift/kubernetes
+```
+
+#### Branching Configurations
+
+```bash
+# Branch configs for next release
+config-brancher \
+  --current-release=4.15 \
+  --future-release=4.16 \
+  --config-dir=ci-operator/config \
+  --confirm
+```
+
+### Image Management
+
+#### Managing Image Promotion
+
+```bash
+# Check promotion policies
+promoted-image-governor \
+  --ci-operator-config-path=ci-operator/config \
+  --release-controller-mirror-config-dir=core-services/release-controller/_releases \
+  --dry-run
+
+# Explain why an image is/isn't promoted
+promoted-image-governor \
+  --explain=ocp/4.15:my-image \
+  --ci-operator-config-path=ci-operator/config
+```
+
+### Cluster Management
+
+#### Running Controllers
+
+```bash
+# Run controller manager
+dptp-controller-manager \
+  --kubeconfig=~/.kube/config \
+  --controllers=promotionreconciler,testimagesdistributor
+
+# Run specific controller only
+dptp-controller-manager \
+  --kubeconfig=~/.kube/config \
+  --controllers=promotionreconciler \
+  --controller-options=promotionreconciler:dry-run=true
+```
+
+### Workflow Examples
+
+#### Example 1: Adding CI to a New Repository
+
+```bash
+# 1. Use repo-init to generate initial config (via web UI or API)
+# 2. Review generated config
+cat ci-operator/config/myorg/myrepo/main.yaml
+
+# 3. Generate Prow jobs
+ci-operator-prowgen \
+  --from-dir=ci-operator/config/myorg/myrepo \
+  --to-dir=ci-operator/jobs/myorg/myrepo
+
+# 4. Create PR to openshift/release
+git add ci-operator/config/myorg/myrepo ci-operator/jobs/myorg/myrepo
+git commit -m "Add CI for myorg/myrepo"
+git push origin my-branch
+```
+
+#### Example 2: Debugging a Failing CI Job
+
+```bash
+# 1. Get job config
+ci-operator-checkconfig \
+  --config=ci-operator/config/myorg/myrepo/main.yaml
+
+# 2. Run locally with same config
+ci-operator \
+  --config=ci-operator/config/myorg/myrepo/main.yaml \
+  --git-ref=myorg/myrepo@main \
+  --target=failing-test \
+  --namespace=my-debug-namespace
+
+# 3. Check logs
+oc logs -n my-debug-namespace -l job-name=...
+
+# 4. Collect artifacts
+oc rsync -n my-debug-namespace pod-name:/artifacts ./local-artifacts
+```
+
+## Design Patterns
+
+### 1. Declarative Configuration
+All tools use YAML-based declarative configurations stored in the `openshift/release` repository. This ensures:
+- Version control of all configurations
+- Easy rollback capabilities
+- Consistency across environments
+
+### 2. Graph-Based Execution
+CI Operator uses a dependency graph to:
+- Determine execution order
+- Enable parallel execution where possible
+- Handle caching and reuse of artifacts
+
+### 3. Controller Pattern
+Many tools follow the Kubernetes controller pattern:
+- Watch for changes in resources
+- Reconcile desired state
+- Handle errors and retries gracefully
+
+### 4. Microservices Architecture
+Each tool is independent and can be:
+- Deployed separately
+- Scaled independently
+- Updated without affecting others
+
+### 5. Event-Driven
+The system responds to events:
+- GitHub webhooks trigger Prow jobs
+- Config changes trigger reconciliation
+- Image builds trigger promotions
+
+## Deployment Architecture
+
+### Production Deployment
+
+```mermaid
+graph TB
+    subgraph "app.ci Cluster"
+        subgraph "CI-Tools Namespace"
+            Controllers[Controller Pods]
+            WebServices[Web Service Pods]
+            CronJobs[CronJob Pods]
+        end
+        
+        subgraph "CI Namespace"
+            ProwComponents[Prow Components]
+        end
+    end
+    
+    subgraph "Build Clusters"
+        Build01[build01]
+        Build02[build02]
+        BuildN[buildN...]
+    end
+    
+    subgraph "External Services"
+        GitHub[GitHub]
+        Quay[Quay.io]
+        GCS[Google Cloud]
+        Vault[Vault]
+    end
+    
+    Controllers --> Build01
+    Controllers --> Build02
+    Controllers --> BuildN
+    
+    ProwComponents --> Controllers
+    ProwComponents --> GitHub
+    
+    Controllers --> Quay
+    Controllers --> GCS
+    Controllers --> Vault
+    
+    style Controllers fill:#e1f5ff
+    style Build01 fill:#fff4e1
+```
+
+### Controller Architecture
+
+The dptp-controller-manager runs multiple controllers:
+
+```mermaid
+graph LR
+    subgraph "dptp-controller-manager"
+        PR[Promotion Reconciler]
+        TID[Test Images Distributor]
+        SASR[SA Secret Refresher]
+        TISIC[Test ImageStream Import Cleaner]
+        EC[Ephemeral Cluster Controller]
+    end
+    
+    subgraph "Kubernetes API"
+        IS[ImageStreams]
+        Secrets[Secrets]
+        Namespaces[Namespaces]
+        CustomResources[Custom Resources]
+    end
+    
+    PR --> IS
+    TID --> IS
+    SASR --> Secrets
+    TISIC --> IS
+    EC --> Namespaces
+    EC --> CustomResources
+    
+    style PR fill:#e1f5ff
+    style EC fill:#fff4e1
+```
+
+### Component Interaction Diagram
+
+```mermaid
+graph TB
+    subgraph "Configuration Layer"
+        ConfigBrancher[config-brancher]
+        ProwGen[ci-operator-prowgen]
+        Determinize[determinize-ci-operator]
+    end
+    
+    subgraph "Execution Layer"
+        CIOperator[ci-operator]
+        Dispatcher[prow-job-dispatcher]
+    end
+    
+    subgraph "Management Layer"
+        Controllers[Kubernetes Controllers]
+        ClusterInit[cluster-init]
+    end
+    
+    subgraph "Supporting Services"
+        SecretGen[ci-secret-generator]
+        ImageMirror[ci-images-mirror]
+        RepoInit[repo-init]
+    end
+    
+    ConfigBrancher --> ProwGen
+    ProwGen --> Dispatcher
+    Dispatcher --> CIOperator
+    CIOperator --> Controllers
+    Controllers --> ClusterInit
+    
+    SecretGen --> Controllers
+    ImageMirror --> Controllers
+    RepoInit --> ConfigBrancher
+    
+    style CIOperator fill:#e1f5ff
+    style Controllers fill:#fff4e1
+```
+
+## Security Architecture
+
+```mermaid
+graph TB
+    subgraph "Authentication"
+        GitHub[GitHub OAuth]
+        LDAP[LDAP]
+        ServiceAccounts[K8s Service Accounts]
+    end
+    
+    subgraph "Authorization"
+        OWNERS[OWNERS Files]
+        RBAC[Kubernetes RBAC]
+        VaultPolicies[Vault Policies]
+    end
+    
+    subgraph "Secrets Management"
+        Vault[Vault]
+        GSM[Google Secret Manager]
+        K8sSecrets[Kubernetes Secrets]
+    end
+    
+    GitHub --> OWNERS
+    LDAP --> RBAC
+    ServiceAccounts --> RBAC
+    
+    OWNERS --> Vault
+    RBAC --> K8sSecrets
+    VaultPolicies --> Vault
+    
+    Vault --> GSM
+    GSM --> K8sSecrets
+    
+    style Vault fill:#e1f5ff
+    style RBAC fill:#fff4e1
+```
+
+## Scalability Considerations
+
+1. **Horizontal Scaling**: Controllers and services can be scaled horizontally
+2. **Sharding**: Prow configs are sharded across multiple files
+3. **Caching**: Image builds leverage layer caching
+4. **Parallel Execution**: CI Operator executes independent steps in parallel
+5. **Resource Management**: Pod scaler optimizes resource allocation
+
+## Monitoring and Observability
+
+```mermaid
+graph LR
+    subgraph "Metrics Collection"
+        Prometheus[Prometheus]
+        BigQuery[BigQuery]
+    end
+    
+    subgraph "Logging"
+        Stackdriver[Stackdriver Logs]
+        LocalLogs[Local Log Files]
+    end
+    
+    subgraph "Tracing"
+        OpenTelemetry[OpenTelemetry]
+    end
+    
+    subgraph "Dashboards"
+        Grafana[Grafana]
+        CustomDashboards[Custom UIs]
+    end
+    
+    Prometheus --> Grafana
+    BigQuery --> CustomDashboards
+    Stackdriver --> Grafana
+    OpenTelemetry --> Grafana
+    
+    style Prometheus fill:#e1f5ff
+    style Grafana fill:#fff4e1
+```
+
+## Extension Points
+
+1. **Custom Steps**: Add to `pkg/steps/`
+2. **Custom Controllers**: Add to `pkg/controller/`
+3. **Custom Tools**: Add to `cmd/`
+4. **Custom Validators**: Add to `pkg/validation/`
+
+## Best Practices
+
+1. **Always use `--dry-run` first** when making changes
+2. **Test locally** before pushing changes
+3. **Use `--confirm`** explicitly for destructive operations
+4. **Check configs** with `ci-operator-checkconfig` before committing
+5. **Normalize configs** with `determinize-ci-operator` before PRs
+6. **Review generated Prow jobs** before merging
+7. **Use version control** for all configuration changes
+
+## Troubleshooting
+
+### Job Fails Immediately
+- Check config syntax: `ci-operator-checkconfig --config=config.yaml`
+- Verify git ref is accessible
+- Check namespace permissions
+
+### Images Not Building
+- Verify base images exist
+- Check Dockerfile paths
+- Review build logs: `oc logs -n namespace build-name`
+
+### Tests Timeout
+- Increase timeout in config
+- Check resource requests
+- Review test logs for hangs
+
+### Promotion Fails
+- Verify promotion configuration
+- Check image stream permissions
+- Review promotion policies
+
+## Getting Help
+
+- Check tool help: `tool-name --help`
+- Review logs with `--log-level=debug`
+- Search GitHub issues
+- Ask in #forum-testplatform on Slack
+- Check component README files in `cmd/` and `pkg/` directories
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000000..300eef49a59
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,96 @@
+# CI-Tools Documentation
+
+Welcome to the CI-Tools documentation! This directory contains comprehensive documentation for understanding, using, and contributing to CI-Tools.
+
+## Documentation Index
+
+### Getting Started
+
+- **[Overview](OVERVIEW.md)** - High-level overview of what CI-Tools is, what problems it solves, and who it's for
+- **[Setup Guide](SETUP.md)** - Step-by-step instructions for setting up your development environment
+- **[Usage Guide](USAGE.md)** - Practical examples and instructions for using CI-Tools
+
+### Understanding the Codebase
+
+- **[Architecture](ARCHITECTURE.md)** - System architecture, component diagrams, and design patterns
+- **[Codebase Walkthrough](CODEBASE_WALKTHROUGH.md)** - Detailed explanation of the repository structure and key components
+
+### Contributing
+
+- **[Contributing Guide](CONTRIBUTING_GUIDE.md)** - How to contribute, coding standards, and PR guidelines
+- **[Onboarding Guide](ONBOARDING.md)** - Learning path for new contributors, important concepts, and beginner roadmap
+
+### Reference
+
+- **[FAQ](FAQ.md)** - Frequently asked questions and answers
+- **[Summaries](SUMMARIES.md)** - Summaries at different technical levels (non-technical, intermediate, advanced)
+
+## Quick Start
+
+**New to CI-Tools?**
+1. Start with the [Overview](OVERVIEW.md) to understand what CI-Tools is
+2. Follow the [Setup Guide](SETUP.md) to get your environment ready
+3. Try the [Usage Guide](USAGE.md) to learn how to use the tools
+
+**Want to contribute?**
+1. Read the [Contributing Guide](CONTRIBUTING_GUIDE.md)
+2. Follow the [Onboarding Guide](ONBOARDING.md) to understand the codebase
+3. Find a good first issue and start contributing!
+
+**Looking for specific information?**
+- Check the [FAQ](FAQ.md) for common questions
+- Browse the [Architecture](ARCHITECTURE.md) docs for system design
+- Review the [Codebase Walkthrough](CODEBASE_WALKTHROUGH.md) for code structure
+
+## Documentation Structure
+
+```text
+docs/
+├── README.md                 # This file
+├── OVERVIEW.md              # High-level overview
+├── ARCHITECTURE.md          # System architecture and diagrams
+├── CODEBASE_WALKTHROUGH.md  # Code structure and components
+├── SETUP.md                 # Development environment setup
+├── USAGE.md                 # Usage examples and guides
+├── CONTRIBUTING_GUIDE.md    # Contribution guidelines
+├── ONBOARDING.md            # New contributor guide
+├── FAQ.md                   # Frequently asked questions
+└── SUMMARIES.md             # Technical summaries
+```
+
+## External Resources
+
+- [OpenShift CI Documentation](https://docs.ci.openshift.org/) - Official OpenShift CI documentation
+- [Prow Documentation](https://github.com/kubernetes/test-infra/tree/master/prow) - Prow CI system documentation
+- [CI Operator Reference](https://steps.svc.ci.openshift.org/) - CI Operator step registry
+
+## Getting Help
+
+- **Documentation**: Browse the docs in this directory
+- **GitHub Issues**: Search existing issues or create new ones
+- **Slack**: #forum-testplatform (for OpenShift team members)
+- **Pull Requests**: Ask questions in PR comments
+
+## Contributing to Documentation
+
+Documentation improvements are always welcome! To contribute:
+
+1. Make your changes to the relevant documentation file
+2. Test that links work and formatting is correct
+3. Create a Pull Request with your changes
+4. Reference any related issues
+
+See the [Contributing Guide](CONTRIBUTING_GUIDE.md) for more details.
+
+## Documentation Standards
+
+- Use Markdown format
+- Include code examples where helpful
+- Add diagrams using Mermaid syntax
+- Keep language clear and beginner-friendly
+- Update related docs when making changes
+
+## License
+
+This documentation is part of the CI-Tools project and is licensed under the Apache-2.0 license.
+
diff --git a/docs/SETUP.md b/docs/SETUP.md
new file mode 100644
index 00000000000..f3e1b826827
--- /dev/null
+++ b/docs/SETUP.md
@@ -0,0 +1,444 @@
+# Setup Guide (Beginner Friendly)
+
+This guide will help you set up a development environment for working with CI-Tools.
+
+## Prerequisites
+
+### Required Software
+
+1. **Go** (version 1.24.0 or later)
+   ```bash
+   # Check your Go version
+   go version
+   
+   # If not installed, download from https://golang.org/dl/
+   ```
+
+2. **Git**
+   ```bash
+   git --version
+   # Install via your package manager if needed
+   ```
+
+3. **Make**
+   ```bash
+   make --version
+   # Usually pre-installed on Linux/macOS
+   ```
+
+4. **Docker** (optional, for building container images)
+   ```bash
+   docker --version
+   ```
+
+### Optional but Recommended
+
+- **kubectl** - For interacting with Kubernetes clusters
+- **oc** (OpenShift CLI) - For interacting with OpenShift clusters
+- **jq** - For JSON processing in scripts
+- **yq** - For YAML processing
+
+## Installation Steps
+
+### 1. Clone the Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/openshift/ci-tools.git
+cd ci-tools
+
+# If you plan to contribute, fork first and clone your fork
+```
+
+### 2. Set Up Go Environment
+
+```bash
+# Set Go environment variables (if not already set)
+export GOPATH=$HOME/go
+export PATH=$PATH:$GOPATH/bin
+
+# Verify Go is working
+go env
+```
+
+### 3. Install Dependencies
+
+```bash
+# Download and vendor dependencies
+make update-vendor
+
+# Or use go mod directly
+go mod download
+go mod vendor
+```
+
+### 4. Build the Tools
+
+```bash
+# Build all tools
+make build
+
+# Or install to $GOPATH/bin
+make install
+
+# Build specific tool
+go build ./cmd/ci-operator
+```
+
+### 5. Verify Installation
+
+```bash
+# Check that tools are installed
+which ci-operator
+ci-operator --help
+
+# List all available tools
+ls $GOPATH/bin/ | grep -E "(ci-|config-|prow-)"
+```
+
+## Environment Requirements
+
+### Development Environment
+
+- **Operating System**: Linux or macOS (Windows with WSL2)
+- **Memory**: Minimum 8GB RAM (16GB recommended)
+- **Disk Space**: At least 10GB free space
+- **Network**: Internet connection for downloading dependencies
+
+### For Testing with OpenShift
+
+- Access to an OpenShift cluster (or use CodeReady Containers for local development)
+- Valid kubeconfig file
+- Appropriate cluster permissions
+
+### For Integration Testing
+
+- Access to `app.ci` OpenShift cluster (for OpenShift team members)
+- GitHub token with appropriate permissions
+- Access to Vault (for secret management tools)
+
+## How to Run the Project
+
+### Running Individual Tools
+
+Most tools are command-line applications. Here are examples:
+
+#### CI Operator
+
+```bash
+# Basic usage
+ci-operator \
+  --config=path/to/config.yaml \
+  --git-ref=org/repo@ref \
+  --target=test-name
+
+# With JOB_SPEC environment variable
+export JOB_SPEC='{"type":"presubmit","job":"test-job",...}'
+ci-operator --config=config.yaml
+```
+
+#### Configuration Tools
+
+```bash
+# Generate Prow jobs from ci-operator configs
+ci-operator-prowgen --from-dir=configs --to-dir=jobs
+
+# Branch configurations
+config-brancher --current-release=4.15 --future-release=4.16
+
+# Determinize (normalize) configs
+determinize-ci-operator --config-dir=configs --confirm
+```
+
+#### Controller Manager
+
+```bash
+# Run the controller manager locally
+dptp-controller-manager \
+  --kubeconfig=~/.kube/config \
+  --controllers=promotionreconciler,testimagesdistributor
+```
+
+### Running Tests
+
+```bash
+# Run all unit tests
+make test
+
+# Run specific package tests
+go test ./pkg/api/...
+
+# Run with verbose output
+go test -v ./pkg/api/...
+
+# Run integration tests
+make integration
+
+# Run specific integration suite
+make integration SUITE=multi-stage
+
+# Run end-to-end tests (requires cluster access)
+make e2e
+```
+
+### Running Locally with Docker
+
+Some tools can be run in containers:
+
+```bash
+# Build container image
+docker build -t ci-tools:latest .
+
+# Run tool in container
+docker run --rm ci-tools:latest ci-operator --help
+```
+
+## How to Test It
+
+### Unit Testing
+
+```bash
+# Run all unit tests
+make test
+
+# Run tests for specific package
+go test ./pkg/config/...
+
+# Run tests with coverage
+go test -cover ./pkg/...
+
+# Generate coverage report
+go test -coverprofile=coverage.out ./pkg/...
+go tool cover -html=coverage.out
+```
+
+### Integration Testing
+
+```bash
+# Run integration tests
+make integration
+
+# Update golden files (if test outputs changed)
+make update-integration
+
+# Run specific suite
+make integration SUITE=config-brancher
+```
+
+### Manual Testing
+
+1. **Test CI Operator Locally:**
+   ```bash
+   # Create a test config
+   cat > test-config.yaml <<EOF
+   base_images:
+     base:
+       namespace: openshift
+       name: base
+       tag: "4.15"
+   tests:
+   - as: unit
+     commands: echo "test"
+   EOF
+   
+   # Run with dry-run (if supported)
+   ci-operator --config=test-config.yaml --dry-run
+   ```
+
+2. **Test Configuration Tools:**
+   ```bash
+   # Test config-brancher with sample configs
+   config-brancher \
+     --current-release=4.15 \
+     --future-release=4.16 \
+     --config-dir=test/integration/config-brancher/input
+   ```
+
+## Common Errors and Solutions
+
+### Error: "go: cannot find module"
+
+**Solution:**
+```bash
+# Ensure you're in the repository root
+cd /path/to/ci-tools
+
+# Download dependencies
+go mod download
+
+# Or update vendor
+make update-vendor
+```
+
+### Error: "command not found: ci-operator"
+
+**Solution:**
+```bash
+# Install tools
+make install
+
+# Or add $GOPATH/bin to PATH
+export PATH=$PATH:$GOPATH/bin
+
+# Or build and use directly
+go build ./cmd/ci-operator
+./ci-operator --help
+```
+
+### Error: "permission denied" when accessing cluster
+
+**Solution:**
+```bash
+# Check kubeconfig
+kubectl config current-context
+
+# Verify cluster access
+kubectl get nodes
+
+# Check if you need to login
+oc login <cluster-url>
+```
+
+### Error: "cannot load package" or import errors
+
+**Solution:**
+```bash
+# Clean module cache
+go clean -modcache
+
+# Re-download dependencies
+go mod download
+
+# Verify go.mod is correct
+go mod verify
+```
+
+### Error: "no such file or directory" for test data
+
+**Solution:**
+```bash
+# Ensure you're running from repository root
+pwd  # Should show /path/to/ci-tools
+
+# Check test data exists
+ls test/integration/
+```
+
+### Error: Build failures due to missing dependencies
+
+**Solution:**
+```bash
+# Update vendor directory
+make update-vendor
+
+# Or use go mod
+go mod tidy
+go mod vendor
+```
+
+### Error: TypeScript compilation errors (for frontend tools)
+
+**Solution:**
+```bash
+# Install Node.js dependencies
+cd cmd/pod-scaler/frontend
+npm install
+
+# Or use make target
+make npm-pod-scaler NPM_ARGS="ci"
+
+# Build frontend
+make cmd/pod-scaler/frontend/dist
+```
+
+### Error: "context deadline exceeded" when testing
+
+**Solution:**
+- Increase timeout: `go test -timeout=10m ./...`
+- Check cluster connectivity
+- Verify resource availability
+
+## Development Workflow
+
+### 1. Make Changes
+
+```bash
+# Create a feature branch
+git checkout -b feature/my-feature
+
+# Make your changes
+# ...
+
+# Format code
+make format
+
+# Run tests
+make test
+```
+
+### 2. Verify Changes
+
+```bash
+# Run linters
+make lint
+
+# Verify code generation
+make verify-gen
+
+# Run integration tests
+make integration
+```
+
+### 3. Commit Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit with descriptive message
+git commit -m "Add feature X"
+
+# Push to your fork
+git push origin feature/my-feature
+```
+
+## IDE Setup
+
+### VS Code
+
+Recommended extensions:
+- Go extension
+- YAML extension
+- Kubernetes extension
+
+Settings:
+```json
+{
+  "go.useLanguageServer": true,
+  "go.formatTool": "goimports",
+  "editor.formatOnSave": true
+}
+```
+
+### GoLand / IntelliJ
+
+- Install Go plugin
+- Configure Go SDK
+- Enable goimports on save
+
+## Next Steps
+
+After setting up your environment:
+
+1. Read the [Usage Guide](USAGE.md) to learn how to use the tools
+2. Explore the [Codebase Walkthrough](CODEBASE_WALKTHROUGH.md) to understand the structure
+3. Check the [Contributing Guide](CONTRIBUTING_GUIDE.md) if you want to contribute
+4. Review the [Onboarding Guide](ONBOARDING.md) for deep dive
+
+## Getting Help
+
+- Check existing documentation
+- Search existing issues on GitHub
+- Ask in #forum-testplatform on Slack (for OpenShift team members)
+- Create a new issue with detailed error information
+
diff --git a/pkg/api/README.md b/pkg/api/README.md
new file mode 100644
index 00000000000..362c807dc52
--- /dev/null
+++ b/pkg/api/README.md
@@ -0,0 +1,107 @@
+# pkg/api
+
+Core API package containing data structures and types used throughout CI-Tools.
+
+## Overview
+
+This package defines the fundamental data structures for CI-Tools, including:
+
+- CI Operator configuration structures
+- Dependency graph implementation
+- Image promotion logic
+- Common type definitions
+- Step links and parameters
+
+## Key Types
+
+### Configuration
+
+**`ReleaseBuildConfiguration`** (`config.go`):
+The main configuration structure that defines:
+- Base images to use
+- Images to build
+- Tests to run
+- Image promotion rules
+- Release configuration
+
+### Dependency Graph
+
+**`Node`** (`graph.go`):
+Represents a step in the execution graph with:
+- Step implementation
+- Required inputs (`Requires`)
+- Created outputs (`Creates`)
+
+**`Graph`** (`graph.go`):
+Manages the dependency graph:
+- `BuildPartialGraph()` - Builds graph for specific targets
+- `TopologicalSort()` - Sorts nodes by dependencies
+- `ResolveMultiArch()` - Resolves multi-arch requirements
+
+### Step Interface
+
+**`Step`** (defined in `pkg/steps/step.go`):
+Common interface for all execution steps:
+```go
+type Step interface {
+    Inputs() []api.InputDefinition
+    Validate() error
+    Run(ctx context.Context) error
+    Requires() []api.StepLink
+    Creates() []api.StepLink
+    Provides() (api.ParameterMap, error)
+}
+```
+
+### Promotion
+
+**`PromotionTarget`** (`promotion.go`):
+Defines where images should be promoted:
+- Target namespace
+- Target name
+- Additional images
+- Excluded images
+
+## Usage
+
+### Loading Configuration
+
+```go
+import "github.com/openshift/ci-tools/pkg/api"
+
+config, err := api.LoadConfig("path/to/config.yaml")
+```
+
+### Building Dependency Graph
+
+```go
+import "github.com/openshift/ci-tools/pkg/api"
+
+nodes, err := api.BuildPartialGraph(steps, targets)
+stepList, errs := nodes.TopologicalSort()
+```
+
+### Working with Step Links
+
+```go
+import "github.com/openshift/ci-tools/pkg/api"
+
+// Create a step link for an image
+link := api.StepLinkForImage("my-image")
+
+// Create a step link for a release
+link := api.StepLinkForRelease(api.LatestReleaseName)
+```
+
+## Related Packages
+
+- **`pkg/config`**: Configuration loading and validation
+- **`pkg/steps`**: Step implementations
+- **`pkg/promotion`**: Image promotion logic
+- **`pkg/defaults`**: Default value handling
+
+## Documentation
+
+- [Architecture Guide](../../docs/ARCHITECTURE.md) - System architecture
+- [CI Operator Reference](https://steps.svc.ci.openshift.org/) - Step registry
+
diff --git a/pkg/controller/README.md b/pkg/controller/README.md
new file mode 100644
index 00000000000..93cdbe4236c
--- /dev/null
+++ b/pkg/controller/README.md
@@ -0,0 +1,92 @@
+# pkg/controller
+
+Kubernetes controller implementations for CI-Tools.
+
+## Overview
+
+This package contains Kubernetes controllers that manage CI resources. Controllers follow the standard Kubernetes controller pattern:
+
+- Watch for changes in resources
+- Reconcile desired state
+- Handle errors and retries gracefully
+- Update resource status
+
+## Controllers
+
+### Promotion Reconciler
+
+**`pkg/controller/promotionreconciler/`**:
+Manages image promotion based on policies:
+- Watches ImageStreams for successful builds
+- Promotes images to release streams
+- Handles promotion policies and exclusions
+
+### Test Images Distributor
+
+**`pkg/controller/test-images-distributor/`**:
+Distributes test images to clusters:
+- Watches for new test images
+- Mirrors images to target clusters
+- Manages image distribution policies
+
+### Service Account Secret Refresher
+
+**`pkg/controller/serviceaccount_secret_refresher/`**:
+Refreshes service account secrets:
+- Monitors service account secrets
+- Rotates secrets periodically
+- Updates references in pods
+
+### Ephemeral Cluster Controller
+
+**`pkg/controller/ephemeralcluster/`**:
+Manages ephemeral test clusters:
+- Provisions clusters on demand
+- Monitors cluster lifecycle
+- Cleans up expired clusters
+
+### Test ImageStream Import Cleaner
+
+**`pkg/controller/testimagestreamimportcleaner/`**:
+Cleans up test ImageStream imports:
+- Removes stale imports
+- Manages import lifecycle
+
+## Controller Manager
+
+All controllers run in `dptp-controller-manager` (`cmd/dptp-controller-manager/`):
+
+```bash
+dptp-controller-manager \
+  --kubeconfig=~/.kube/config \
+  --controllers=promotionreconciler,testimagesdistributor
+```
+
+## Controller Pattern
+
+Controllers implement the reconciler interface:
+
+```go
+type Reconciler interface {
+    Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
+}
+```
+
+## Utilities
+
+**`pkg/controller/util/`**:
+Common utilities for controllers:
+- Reconciler helpers
+- Error handling
+- Retry logic
+
+## Related Packages
+
+- **`pkg/api`**: Core API types
+- **`pkg/kubernetes`**: Kubernetes client utilities
+
+## Documentation
+
+- [Architecture Guide](../../docs/ARCHITECTURE.md) - System architecture
+- [Controller Manager README](../../cmd/dptp-controller-manager/README.md) - Controller manager documentation
+
diff --git a/pkg/steps/README.md b/pkg/steps/README.md
new file mode 100644
index 00000000000..e35f804a420
--- /dev/null
+++ b/pkg/steps/README.md
@@ -0,0 +1,97 @@
+# pkg/steps
+
+Step execution framework for CI-Tools. Provides the building blocks for CI job execution.
+
+## Overview
+
+The steps package implements the execution framework for CI-Tools. Steps are composable building blocks that:
+
+- Declare their inputs and outputs
+- Execute specific actions (build images, run tests, etc.)
+- Can provide parameters to dependent steps
+- Are executed in dependency order based on a graph
+
+## Step Interface
+
+All steps implement the `Step` interface:
+
+```go
+type Step interface {
+    Inputs() []api.InputDefinition
+    Validate() error
+    Run(ctx context.Context) error
+    Requires() []api.StepLink
+    Creates() []api.StepLink
+    Provides() (api.ParameterMap, error)
+}
+```
+
+## Step Types
+
+### Build Steps
+
+- **`src`**: Source code checkout
+- **`bin`**: Binary build
+- **`rpms`**: RPM build
+- **`images`**: Container image builds
+
+### Test Steps
+
+- **`test`**: Generic test execution
+- **`e2e`**: End-to-end tests
+- **`integration`**: Integration tests
+
+### Utility Steps
+
+- **`template`**: Template execution
+- **`promote`**: Image promotion
+- **`release`**: Release tagging
+
+## Step Registry
+
+The step registry (`pkg/steps/registry/`) contains reusable step definitions that can be referenced in CI configurations.
+
+## Execution
+
+Steps are executed via the `Run()` function which:
+
+1. Builds a dependency graph from steps
+2. Topologically sorts steps by dependencies
+3. Executes steps in order (parallel where possible)
+4. Collects artifacts from completed steps
+5. Handles errors and retries
+
+## Usage
+
+### Creating a Custom Step
+
+```go
+type MyStep struct {
+    // step fields
+}
+
+func (s *MyStep) Requires() []api.StepLink {
+    return []api.StepLink{api.StepLinkForImage("base-image")}
+}
+
+func (s *MyStep) Creates() []api.StepLink {
+    return []api.StepLink{api.StepLinkForImage("my-image")}
+}
+
+func (s *MyStep) Run(ctx context.Context) error {
+    // step implementation
+    return nil
+}
+```
+
+## Related Packages
+
+- **`pkg/api`**: Core API types and graph structures
+- **`pkg/config`**: Configuration loading
+- **`pkg/promotion`**: Image promotion logic
+
+## Documentation
+
+- [Architecture Guide](../../docs/ARCHITECTURE.md) - System architecture
+- [CI Operator Reference](https://steps.svc.ci.openshift.org/) - Step registry documentation
+