docs: add heph validate guide and update CI guide

website/docs/guides/ci.md

@@ -11,11 +11,8 @@ few flags make CI runs cleaner and turn heph's guarantees into gates.
 
 ## Plain log output
 
-The interactive TUI assumes a terminal. In CI, force log-only output:
-
-```bash title="terminal"
-heph run //... --no-tui
-```
+The interactive TUI assumes a terminal. In CI, force log-only output with
+`--no-tui`.
 
 ## Fail on stale codegen
 
@@ -31,16 +28,18 @@ If a generated file is missing or out of date, the run exits non-zero with a
 diff — so a contributor who forgot to regenerate gets a red build, not a silent
 drift.
 
-## Check the .gitignore is in sync
+## Validate the workspace
 
-`copy` codegen outputs belong in `.gitignore`, and heph maintains that block for
-you. Make CI fail if it's out of date:
+[`heph validate`](/docs/guides/validate) checks that every target resolves, that
+no two `codegen = copy` targets write to the same path, and that `.gitignore` is
+current — all in one read-only command:
 
 ```bash title="terminal"
-heph tool gen-gitignore
-git diff --exit-code .gitignore
+heph validate
 ```
 
+It reports every problem it finds, not just the first one.
+
 ## Reuse the cache
 
 The [cache](/docs/concepts/caching) is keyed by input hash, so persisting it
@@ -51,7 +50,7 @@ using your CI's caching mechanism, keyed on your lockfiles.
 ## A representative job
 
 ```bash title="terminal"
-heph run //... --no-tui --frozen        # build everything; fail on stale codegen
-heph run //... --no-tui                 # run tests / checks
-heph tool gen-gitignore && git diff --exit-code .gitignore
+heph run //... --frozen        # build everything; fail on stale codegen
+heph run //...                 # run tests / checks
+heph validate                  # check targets resolve and .gitignore is current
 ```

website/docs/guides/validate.md

@@ -0,0 +1,38 @@
+---
+title: "Validating your workspace"
+sidebar_position: 3
+description: Use heph validate to catch broken targets, overlapping codegen outputs, and a stale .gitignore before they reach CI.
+---
+
+# Validating your workspace
+
+`heph validate` checks your workspace without running any builds. It resolves every target's inputs, detects overlapping codegen outputs, and verifies that `.gitignore` is current. All three checks run in parallel and every failure is reported at once — not just the first one — so you can fix everything in a single pass.
+
+## What it checks
+
+| Check | What it catches |
+|-------|-----------------|
+| **Target link** | Every in-scope target is parsed and its runtime inputs are resolved. A missing dependency or an unresolvable target surfaces here. No execution happens. |
+| **Codegen overlap** | Two `codegen = copy` targets that write to the same output path. |
+| **`.gitignore` freshness** | The `.gitignore` block maintained by heph is out of date. If stale, the error message tells you to run `heph tool gen-gitignore`. Skipped when a package matcher is provided. |
+
+## Usage
+
+```bash title="terminal"
+heph validate              # whole workspace
+heph validate //pkg/...    # scope to a package matcher
+```
+
+When a package matcher is provided, the `.gitignore` freshness check is skipped (it applies to the whole workspace), and a warning is printed to say so. The target link and overlap checks still run.
+
+If any check fails, `heph validate` exits non-zero and lists every problem it found.
+
+## In CI
+
+`heph validate` is a natural CI gate: it is read-only, exits non-zero on any problem, and surfaces all failures in one run.
+
+```bash title="terminal"
+heph validate
+```
+
+See [Using heph in CI](/docs/guides/ci) for a representative CI job.

website/sidebars.ts

@@ -30,7 +30,7 @@ const sidebars: SidebarsConfig = {
       type: 'category',
       label: 'Guides',
       collapsible: false,
-      items: ['guides/first-build', 'guides/ci', 'guides/remote-cache', 'guides/inspecting-builds', 'guides/editor-setup', 'guides/claude-code-plugin'],
+      items: ['guides/first-build', 'guides/ci', 'guides/validate', 'guides/remote-cache', 'guides/inspecting-builds', 'guides/editor-setup', 'guides/claude-code-plugin'],
     },
     {
       type: 'category',