diff --git a/crates/evaluator/README.md b/crates/evaluator/README.md
new file mode 100644
index 0000000..fa4b931
--- /dev/null
+++ b/crates/evaluator/README.md
@@ -0,0 +1,29 @@
+## wrkflw-evaluator
+
+Small, focused helper for statically evaluating GitHub Actions workflow files.
+
+- **Purpose**: Fast structural checks (e.g., `name`, `on`, `jobs`) before deeper validation/execution
+- **Used by**: `wrkflw` CLI and TUI during validation flows
+
+### Example
+
+```rust
+use std::path::Path;
+
+let result = wrkflw_evaluator::evaluate_workflow_file(
+    Path::new(".github/workflows/ci.yml"),
+    /* verbose */ true,
+).expect("evaluation failed");
+
+if result.is_valid {
+    println!("Workflow looks structurally sound");
+} else {
+    for issue in result.issues {
+        println!("- {}", issue);
+    }
+}
+```
+
+### Notes
+- This crate focuses on structural checks; deeper rules live in `wrkflw-validators`.
+- Most consumers should prefer the top-level `wrkflw` CLI for end-to-end UX.
diff --git a/crates/executor/README.md b/crates/executor/README.md
new file mode 100644
index 0000000..aa665a2
--- /dev/null
+++ b/crates/executor/README.md
@@ -0,0 +1,29 @@
+## wrkflw-executor
+
+The execution engine that runs GitHub Actions workflows locally (Docker, Podman, or emulation).
+
+- **Features**:
+  - Job graph execution with `needs` ordering and parallelism
+  - Docker/Podman container steps and emulation mode
+  - Basic environment/context wiring compatible with Actions
+- **Used by**: `wrkflw` CLI and TUI
+
+### API sketch
+
+```rust
+use wrkflw_executor::{execute_workflow, ExecutionConfig, RuntimeType};
+
+let cfg = ExecutionConfig {
+    runtime: RuntimeType::Docker,
+    verbose: true,
+    preserve_containers_on_failure: false,
+};
+
+// Path to a workflow YAML
+let workflow_path = std::path::Path::new(".github/workflows/ci.yml");
+
+let result = execute_workflow(workflow_path, cfg).await?;
+println!("workflow status: {:?}", result.summary_status);
+```
+
+Prefer using the `wrkflw` binary for a complete UX across validation, execution, and logs.
diff --git a/crates/github/README.md b/crates/github/README.md
new file mode 100644
index 0000000..a5bf613
--- /dev/null
+++ b/crates/github/README.md
@@ -0,0 +1,23 @@
+## wrkflw-github
+
+GitHub integration helpers used by `wrkflw` to list/trigger workflows.
+
+- **List workflows** in `.github/workflows`
+- **Trigger workflow_dispatch** events over the GitHub API
+
+### Example
+
+```rust
+use wrkflw_github::{get_repo_info, trigger_workflow};
+
+# tokio_test::block_on(async {
+let info = get_repo_info()?;
+println!("{}/{} (default branch: {})", info.owner, info.repo, info.default_branch);
+
+// Requires GITHUB_TOKEN in env
+trigger_workflow("ci", Some("main"), None).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Notes: set `GITHUB_TOKEN` with the `workflow` scope; only public repos are supported out-of-the-box.
diff --git a/crates/gitlab/README.md b/crates/gitlab/README.md
new file mode 100644
index 0000000..e7d5ad2
--- /dev/null
+++ b/crates/gitlab/README.md
@@ -0,0 +1,23 @@
+## wrkflw-gitlab
+
+GitLab integration helpers used by `wrkflw` to trigger pipelines.
+
+- Reads repo info from local git remote
+- Triggers pipelines via GitLab API
+
+### Example
+
+```rust
+use wrkflw_gitlab::{get_repo_info, trigger_pipeline};
+
+# tokio_test::block_on(async {
+let info = get_repo_info()?;
+println!("{}/{} (default branch: {})", info.namespace, info.project, info.default_branch);
+
+// Requires GITLAB_TOKEN in env (api scope)
+trigger_pipeline(Some("main"), None).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Notes: looks for `.gitlab-ci.yml` in the repo root when listing pipelines.
diff --git a/crates/logging/README.md b/crates/logging/README.md
new file mode 100644
index 0000000..6ce6194
--- /dev/null
+++ b/crates/logging/README.md
@@ -0,0 +1,22 @@
+## wrkflw-logging
+
+Lightweight in-memory logging with simple levels for TUI/CLI output.
+
+- Thread-safe, timestamped messages
+- Level filtering (Debug/Info/Warning/Error)
+- Pluggable into UI for live log views
+
+### Example
+
+```rust
+use wrkflw_logging::{info, warning, error, LogLevel, set_log_level, get_logs};
+
+set_log_level(LogLevel::Info);
+info("starting");
+warning("be careful");
+error("boom");
+
+for line in get_logs() {
+    println!("{}", line);
+}
+```
diff --git a/crates/matrix/README.md b/crates/matrix/README.md
new file mode 100644
index 0000000..14db718
--- /dev/null
+++ b/crates/matrix/README.md
@@ -0,0 +1,20 @@
+## wrkflw-matrix
+
+Matrix expansion utilities used to compute all job combinations and format labels.
+
+- Supports `include`, `exclude`, `max-parallel`, and `fail-fast`
+- Provides display helpers for UI/CLI
+
+### Example
+
+```rust
+use wrkflw_matrix::{MatrixConfig, expand_matrix};
+use serde_yaml::Value;
+use std::collections::HashMap;
+
+let mut cfg = MatrixConfig::default();
+cfg.parameters.insert("os".into(), Value::from(vec!["ubuntu", "alpine"])) ;
+
+let combos = expand_matrix(&cfg).expect("expand");
+assert!(!combos.is_empty());
+```
diff --git a/crates/models/README.md b/crates/models/README.md
new file mode 100644
index 0000000..fb13be2
--- /dev/null
+++ b/crates/models/README.md
@@ -0,0 +1,16 @@
+## wrkflw-models
+
+Common data structures shared across crates.
+
+- `ValidationResult` for structural/semantic checks
+- GitLab pipeline models (serde types)
+
+### Example
+
+```rust
+use wrkflw_models::ValidationResult;
+
+let mut res = ValidationResult::new();
+res.add_issue("missing jobs".into());
+assert!(!res.is_valid);
+```
diff --git a/crates/parser/README.md b/crates/parser/README.md
new file mode 100644
index 0000000..c960eac
--- /dev/null
+++ b/crates/parser/README.md
@@ -0,0 +1,13 @@
+## wrkflw-parser
+
+Parsers and schema helpers for GitHub/GitLab workflow files.
+
+- GitHub Actions workflow parsing and JSON Schema validation
+- GitLab CI parsing helpers
+
+### Example
+
+```rust
+// High-level crates (`wrkflw` and `wrkflw-executor`) wrap parser usage.
+// Use those unless you are extending parsing behavior directly.
+```
diff --git a/crates/runtime/README.md b/crates/runtime/README.md
new file mode 100644
index 0000000..fa2f7e4
--- /dev/null
+++ b/crates/runtime/README.md
@@ -0,0 +1,13 @@
+## wrkflw-runtime
+
+Runtime abstractions for executing steps in containers or emulation.
+
+- Container management primitives used by the executor
+- Emulation mode helpers (run on host without containers)
+
+### Example
+
+```rust
+// This crate is primarily consumed by `wrkflw-executor`.
+// Prefer using the executor API instead of calling runtime directly.
+```
diff --git a/crates/ui/README.md b/crates/ui/README.md
new file mode 100644
index 0000000..3ef3c59
--- /dev/null
+++ b/crates/ui/README.md
@@ -0,0 +1,23 @@
+## wrkflw-ui
+
+Terminal user interface for browsing workflows, running them, and viewing logs.
+
+- Tabs: Workflows, Execution, Logs, Help
+- Hotkeys: `1-4`, `Tab`, `Enter`, `r`, `R`, `t`, `v`, `e`, `q`, etc.
+- Integrates with `wrkflw-executor` and `wrkflw-logging`
+
+### Example
+
+```rust
+use std::path::PathBuf;
+use wrkflw_executor::RuntimeType;
+use wrkflw_ui::run_wrkflw_tui;
+
+# tokio_test::block_on(async {
+let path = PathBuf::from(".github/workflows");
+run_wrkflw_tui(Some(&path), RuntimeType::Docker, true, false).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+Most users should run the `wrkflw` binary and select TUI mode: `wrkflw tui`.
diff --git a/crates/utils/README.md b/crates/utils/README.md
new file mode 100644
index 0000000..12dea7b
--- /dev/null
+++ b/crates/utils/README.md
@@ -0,0 +1,21 @@
+## wrkflw-utils
+
+Shared helpers used across crates.
+
+- Workflow file detection (`.github/workflows/*.yml`, `.gitlab-ci.yml`)
+- File-descriptor redirection utilities for silencing noisy subprocess output
+
+### Example
+
+```rust
+use std::path::Path;
+use wrkflw_utils::{is_workflow_file, fd::with_stderr_to_null};
+
+assert!(is_workflow_file(Path::new(".github/workflows/ci.yml")));
+
+let value = with_stderr_to_null(|| {
+    eprintln!("this is hidden");
+    42
+}).unwrap();
+assert_eq!(value, 42);
+```
diff --git a/crates/validators/README.md b/crates/validators/README.md
new file mode 100644
index 0000000..8095614
--- /dev/null
+++ b/crates/validators/README.md
@@ -0,0 +1,29 @@
+## wrkflw-validators
+
+Validation utilities for workflows and steps.
+
+- Validates GitHub Actions sections: jobs, steps, actions references, triggers
+- GitLab pipeline validation helpers
+- Matrix-specific validation
+
+### Example
+
+```rust
+use serde_yaml::Value;
+use wrkflw_models::ValidationResult;
+use wrkflw_validators::{validate_jobs, validate_triggers};
+
+let yaml: Value = serde_yaml::from_str(r#"name: demo
+on: [workflow_dispatch]
+jobs: { build: { runs-on: ubuntu-latest, steps: [] } }
+"#).unwrap();
+
+let mut res = ValidationResult::new();
+if let Some(on) = yaml.get("on") {
+    validate_triggers(on, &mut res);
+}
+if let Some(jobs) = yaml.get("jobs") {
+    validate_jobs(jobs, &mut res);
+}
+assert!(res.is_valid);
+```
diff --git a/crates/wrkflw/README.md b/crates/wrkflw/README.md
new file mode 100644
index 0000000..6fe2a24
--- /dev/null
+++ b/crates/wrkflw/README.md
@@ -0,0 +1,108 @@
+## WRKFLW (CLI and Library)
+
+This crate provides the `wrkflw` command-line interface and a thin library surface that ties together all WRKFLW subcrates. It lets you validate and execute GitHub Actions workflows and GitLab CI pipelines locally, with a built-in TUI for an interactive experience.
+
+- **Validate**: Lints structure and common mistakes in workflow/pipeline files
+- **Run**: Executes jobs locally using Docker, Podman, or emulation (no containers)
+- **TUI**: Interactive terminal UI for browsing workflows, running, and viewing logs
+- **Trigger**: Manually trigger remote runs on GitHub/GitLab
+
+### Installation
+
+```bash
+cargo install wrkflw
+```
+
+### Quick start
+
+```bash
+# Launch the TUI (auto-loads .github/workflows)
+wrkflw
+
+# Validate all workflows in the default directory
+wrkflw validate
+
+# Validate a specific file or directory
+wrkflw validate .github/workflows/ci.yml
+wrkflw validate path/to/workflows
+
+# Run a workflow (Docker by default)
+wrkflw run .github/workflows/ci.yml
+
+# Use Podman or emulation instead of Docker
+wrkflw run --runtime podman .github/workflows/ci.yml
+wrkflw run --runtime emulation .github/workflows/ci.yml
+
+# Open the TUI explicitly
+wrkflw tui
+wrkflw tui --runtime podman
+```
+
+### Commands
+
+- **validate**: Validate a workflow/pipeline file or directory
+  - GitHub (default): `.github/workflows/*.yml`
+  - GitLab: `.gitlab-ci.yml` or files ending with `gitlab-ci.yml`
+  - Exit code behavior (by default): `1` when validation failures are detected
+  - Flags: `--gitlab`, `--exit-code`, `--no-exit-code`, `--verbose`
+
+- **run**: Execute a workflow or pipeline locally
+  - Runtimes: `docker` (default), `podman`, `emulation`
+  - Flags: `--runtime`, `--preserve-containers-on-failure`, `--gitlab`, `--verbose`
+
+- **tui**: Interactive terminal interface
+  - Browse workflows, execute, and inspect logs and job details
+
+- **trigger**: Trigger a GitHub workflow (requires `GITHUB_TOKEN`)
+- **trigger-gitlab**: Trigger a GitLab pipeline (requires `GITLAB_TOKEN`)
+- **list**: Show detected workflows and pipelines in the repo
+
+### Environment variables
+
+- **GITHUB_TOKEN**: Required for `trigger` when calling GitHub
+- **GITLAB_TOKEN**: Required for `trigger-gitlab` (api scope)
+
+### Exit codes
+
+- `validate`: `0` if all pass; `1` if any fail (unless `--no-exit-code`)
+- `run`: `0` on success, `1` if execution fails
+
+### Library usage
+
+This crate re-exports subcrates for convenience if you want to embed functionality:
+
+```rust
+use std::path::Path;
+use wrkflw::executor::{execute_workflow, ExecutionConfig, RuntimeType};
+
+# tokio_test::block_on(async {
+let cfg = ExecutionConfig {
+    runtime_type: RuntimeType::Docker,
+    verbose: true,
+    preserve_containers_on_failure: false,
+};
+let result = execute_workflow(Path::new(".github/workflows/ci.yml"), cfg).await?;
+println!("status: {:?}", result.summary_status);
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+You can also run the TUI programmatically:
+
+```rust
+use std::path::PathBuf;
+use wrkflw::executor::RuntimeType;
+use wrkflw::ui::run_wrkflw_tui;
+
+# tokio_test::block_on(async {
+let path = PathBuf::from(".github/workflows");
+run_wrkflw_tui(Some(&path), RuntimeType::Docker, true, false).await?;
+# Ok::<_, Box<dyn std::error::Error>>(())
+# })?;
+```
+
+### Notes
+
+- See the repository root README for feature details, limitations, and a full walkthrough.
+- Service containers and advanced Actions features are best supported in Docker/Podman modes.
+- Emulation mode skips containerized steps and runs commands on the host.
\ No newline at end of file