EPIC: pipeline visualizer - render the generated pipeline as a diagram

[joshua-temple]

Summary

cascade compiles a manifest into GitHub Actions workflows, but the shape of the pipeline it
produces - the job DAG, the environment promotion chain, the cross-repo flows - is only
visible by reading generated YAML. This epic adds a first-class way to render the pipeline as
a diagram so a reader can see, at a glance, what cascade will do.

The first and only emit target is Mermaid. GitHub renders Mermaid natively in Markdown,
issues, and pull requests, so a Mermaid diagram is committable to a README and viewable in a
PR with no external tooling. That native rendering is the entire reason to start here.

The renderer is built behind a pluggable emit layer so a higher-fidelity render engine
can be added later (see the deferred follow-up) without reworking the model. The architecture
mirrors the separation proven in the sibling crucible project:
viewmodel -> render -> theme -> emit
(crucible/cmd/crucible/internal/viewmodel builds a render-agnostic model; its render
package emits source under a Theme). cascade adopts the same split: an abstract pipeline
view model, a theme layer, and an Emitter interface whose first implementation is Mermaid.

What we render (grounded in the real model)

The visualizer reads cascade's existing internal model - it introduces no new manifest fields:

• Job DAG - internal/generate/graph.go: DependencyGraph{Nodes, Edges, OptionalEdges, Order}, CallbackInfo{Name, JobID, DisplayName, Type, ...}, BuildDependencyGraph(cfg),
  and TopologicalSort(). This is the job-level graph (validate -> builds -> deploys with
  hard and optional edges).
• Environment promotion chain - internal/config (TrunkConfig.Environments,
  EnvState, EnvState.IsDiverged(), EnvStateSnapshot, PromotionMode default/cascade)
  and internal/promote (+ internal/hotfix): the dev -> ... -> prod chain plus the hotfix
  divergence and rejoin states.
• Cross-repo flow - internal/config ExternalRepoConfig, ExternalDeployConfig,
  NotifyConfig (satellite repo notifies its primary after a dev deploy), and
  ExternalDeployState: the primary repo coordinating its dependent satellite repos.
• Multi-component (monorepo) - the reserved Components map[string]ComponentConfig
  shape. This depends on the multi-component schema model existing and is therefore gated;
  see the monorepo rendering child issue and the monorepo epic epic: schema_version 2 - additive, opt-in monorepo support in a single manifest #279.

Three granularities

1. Environment state machine - dev -> ... -> prod with hotfix divergence/rejoin loops.
2. Pipeline stages - the lifecycle: trunk -> build -> deploy -> promote -> release.
3. Full job DAG - every job and edge from DependencyGraph.

Where it lives

A new top-level CLI command sits alongside the existing root subcommands registered in
cmd/cascade/main.go (generate-workflow, plan, verify, status, environments,
external, promote, hotfix, ...). The verb is cascade graph (see the CLI child issue for
the verb decision).

Integration hooks

• A committable diagram in a repo README (run the command, paste/commit the Mermaid).
• Optionally, a diagram of the pending change in the generated PR plan-preview lane
  (PRPreviewConfig / cascade-pr-preview.yaml, the read-only preview from feat: optional PR plan-preview workflow #40).
• A docs page under docs/src/content/docs/.

Theming

A separable theme layer (mirroring crucible's Theme / DefaultTheme split) templates the
Mermaid init directive and classDef styling. Ship a cascade theme and a monotone bland
theme, and accept a user-supplied theme file.

Child issues and dependency order

render core + view model + Mermaid emitter   <- foundation, no deps
CLI command: cascade graph                    <- depends on render core
three granularities                           <- depends on render core, CLI
theme templating + two built-in themes        <- depends on render core
cross-repo artifact rendering                 <- depends on render core, granularities
monorepo / multi-component rendering          <- depends on render core, granularities AND monorepo epic #279
integration hooks: README + PR preview + docs <- depends on CLI, granularities
DEFERRED: robust render engine behind emitter <- depends on render core; later, lower priority

• visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301 Render core: pipeline view model, pluggable emitter, Mermaid emitter
• visualizer: cascade graph command with --granularity and --format #302 CLI command: cascade graph with --granularity and --format (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301)
• visualizer: three rendering granularities (env / stages / jobs) #303 Three granularities: env state machine, pipeline stages, full job DAG (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301, visualizer: cascade graph command with --granularity and --format #302)
• visualizer: theme layer with cascade and bland built-in themes #304 Theme templating with cascade and bland built-in themes (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301)
• visualizer: render the cross-repo flow (primary + dependent satellites) #305 Cross-repo artifact rendering (primary + dependent satellites) (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301, visualizer: three rendering granularities (env / stages / jobs) #303)
• visualizer: render multi-component (monorepo) pipelines #306 Monorepo / multi-component rendering (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301, visualizer: three rendering granularities (env / stages / jobs) #303 and monorepo epic epic: schema_version 2 - additive, opt-in monorepo support in a single manifest #279)
• visualizer: integration hooks (README diagram, PR plan-preview diagram, docs) #307 Integration hooks: README, PR plan-preview, docs page (depends on visualizer: cascade graph command with --granularity and --format #302, visualizer: three rendering granularities (env / stages / jobs) #303)
• visualizer (deferred): high-fidelity render engine behind the emitter #308 DEFERRED: high-fidelity render engine behind the pluggable emitter (depends on visualizer: pipeline view model + pluggable emitter + Mermaid emitter #301)

Out of scope (for now)

• Any non-Mermaid emit format. The robust SVG/PNG engine is deferred to the final child issue
  and is purely additive thanks to the pluggable emitter.