docs: V2 architecture docs, ADR-0007, local dev guide, code generation workflow

[markturansky]

Summary

• ADR-0007 — documents the decision to adopt rh-trex-ai + PostgreSQL + generated SDKs + Control Plane (deciders: Mark Turansky, Kevin Howell; anchored to the technical evaluation gist from 2026-02-16)
• V2 architecture diagrams — updated docs/internal/architecture/README.md and components/architecture.md with Mermaid diagrams covering the full TRex → API → SDK → CLI → Control Plane pipeline
• Local dev guide — docs/internal/developer/local-development/v2-stack.md: startup sequence, port map, smoke tests, troubleshooting for the full V2 stack
• Code generation workflow — docs/internal/developer/code-generation.md: TRex Kind generator through SDK regen pipeline
• Component READMEs — rewrote components/ambient-api-server/README.md; created components/ambient-control-plane/README.md
• Deployment docs — updated docs/internal/deployment/README.md with V2 component table, actual ports from manifests, secrets config, and health/log commands

Test plan

• Mermaid diagrams render correctly in GitHub
• All internal links resolve
• ADR-0007 appears in docs/internal/adr/README.md index
• Port numbers match manifests (ambient-api-server-service.yml: 8000/4433/4434)

🤖 Generated with Claude Code

[github-actions]

Claude Code Review

Summary

PR 810 is a documentation-only change (plus one blank-line deletion in client.go) that adds ADR-0007, V2 architecture diagrams, a local dev guide for the V2 stack, a code generation workflow doc, updated component READMEs, and a rewritten deployment guide. Writing quality and structural organisation are strong; several pre-existing broken links are corrected. One new broken link was introduced, and ADR-0006 remains absent from the index despite existing in the repo.

---

Blocker Issues: None.

Critical Issues: None.

---

Major Issues

1. Broken link: runner README points to non-existent directory

• File: docs/internal/architecture/README.md (V1 Components table, Runner row)
• Problem: The added link resolves to components/runners/claude-code-runner/README.md, which does not exist. The runner lives at components/runners/ambient-runner/.
• Fix: Change claude-code-runner to ambient-runner in the relative link.

---

Minor Issues

1. ADR index skips ADR-0006

• File: docs/internal/adr/README.md
• Problem: docs/internal/adr/0006-ambient-runner-sdk-architecture.md already exists in the repo but is absent from the index table. This PR adds 0007, making the gap visible (0005 to 0007). 0006 should be added at the same time.

2. Go version inconsistency

• File: docs/internal/developer/local-development/v2-stack.md, prerequisites table
• Problem: States Go 1.24+, but CLAUDE.md documents the project baseline as Go 1.21+. Reconcile one way or the other.

3. Stray emoji in headings

• File: docs/internal/architecture/README.md
• Problem: The PR removes emoji from most headings but ## Core Concepts (below the diff) still has one. Inconsistent style in the same file.

---

Positive Highlights

• ADR-0007 is well-crafted: clear problem statement, three distinct options with explicit trade-offs, outcome anchored to a named external evaluation, and an honest negative/risk section.
• Link repair: four previously broken relative paths in the deployment README (../OPENSHIFT_DEPLOY.md, ../OPENSHIFT_OAUTH.md, ../s3-storage-configuration.md, ../minio-quickstart.md) are silently corrected - these files are in docs/internal/deployment/, not the parent directory.
• Mermaid diagrams are consistent: the TRex pipeline is expressed identically across components/architecture.md, docs/internal/architecture/README.md, and docs/internal/developer/code-generation.md.
• Control Plane README documents write-back echo detection, reconnect backoff, and graceful shutdown explicitly - the detail needed to prevent future debugging surprises.
• V2 stack local dev guide is actionable: startup sequence, port map, and smoke tests give a new contributor a concrete path without reading source code.

---

Recommendations (priority order)

1. (Required before merge) Fix docs/internal/architecture/README.md runner link: claude-code-runner to ambient-runner.
2. Add ADR-0006 to the index table in docs/internal/adr/README.md.
3. Resolve Go version discrepancy between v2-stack.md (1.24+) and CLAUDE.md (1.21+).
4. Remove emoji from the Core Concepts heading in docs/internal/architecture/README.md.

[ambient-code]

Review Queue Status

Check	Status	Detail
CI	FAIL	End-to-End Tests
Conflicts	FAIL	Merge conflicts detected

Action needed: Fix failing CI checks, Resolve merge conflicts

Auto-generated by Review Queue workflow. Updated when PR changes.

[jeremyeder]

Closing — the V2 components (api-server, SDK, CLI) need docs but this PR is 7 weeks stale. Will generate fresh documentation from the current codebase state.