docs(docs): quickstart as a TL;DR and Helm guide as the verified EKS walkthrough

[cubeorgdev]

Fixes #117

Replaces #118, which was stacked on #116. Same two commits rebased onto main, plus a merge of main after #111 landed.

Merge order. The Helm guide uses inference_proxy_subdomain and the inference_proxy_hostname output from #116, which is not on main yet. Merge that first, or step 1 describes an input the module rejects.

Quickstart

Now the short version: the three things you need (the CLI, a config file, a server), what each is for, and a link to the deep page. The governance section leads with what it controls: allowed agents, default model and settings, MCP servers, extensions, session capture. The three "how to deploy" cards from the old page are kept under the server section.

Three things were only in the quickstart, so they moved:

• CLI installation, BLUE_VERSION pinning, and the installer's checksum note are now an Install section at the top of CLI commands.
• The SHA256SUMS check for the deployment bundle is now in the Helm guide.
• The two curl health checks are now under the deployment contract's health-check table.

The two links that pointed at the old #install-the-workstation-cli anchor (Docker Compose page, README) now point at the new Install section.

Kubernetes with Helm

Replaced with the verified end-to-end EKS walkthrough: a bundle download, then fourteen numbered steps from an empty AWS account to a governed agent, with gateway mode as a continuation of the same stack. Prose is one or two lines per step.

Code blocks are the verified ones, with these deliberate changes:

• The reader works from the release bundle's infra/aws folder. The five path exports point at the current directory and at ../../chart/blue instead of a source checkout.
• The revision bump comment and the step 12 sed are gone. The Control API strips revision before comparing the mounted baseline to the stored one (normalized_governance_value), so bumping it did nothing, and Configure blue.yaml already says so. The sed also looked for a value nothing had written.

Content the old page held alone moves to the page that owns the topic:

• cert-manager issuer constraints, the CA cutover warning, and the bring-your-own-certificates Secret layouts: new Internal certificates section on Bring your own gateway. Proxy autoscaling and streaming-ingress notes sit under it as Scaling the proxy.
• Invitation links are only logged until mail is wired: Manage users and invitations.
• blue.config.mountPath caveat: Helm chart README.

Only next is changed; 0.1.0 is untouched.

node scripts/check-content.mjs passes. A code-block diff of the new Helm page against the verified guide shows only the changes listed above. Not run: mint broken-links (not installed here).

🤖 Generated with Claude Code

[cubeorgdev]

This pull request was created from a Blocks session.

View in dashboard | View on desktop

[AlejandroEsquivel]

@cube /claude /reviewreview

[cubeorgdev]

Both comments investigated. Results:

Review comment enumeration & re-ranking

1. apps/docs/next/deployment/production.mdx:155 — "Drop gateway_inference_jwt from the governance-only baseline"

Bot severity 8/10 → my initial 6/10 → after investigation: 1/10. Invalid.

The comment's load-bearing claim — "the Control API auto-injects it then" — is false for the path this doc uses. There are two config paths:

• Dashboard/CLI save path (update_governance_config, lib.rs:6240 → apply_deployment_gateway_policy, lib.rs:718 → stamp_version_aware_client_floor, lib.rs:8108-8118) — this one does auto-inject.
• Mounted blue.yaml boot path, which is what the walkthrough uses: bootstrap_deployment → reconcile_deployment_governance (lib.rs:2604). It builds the seed via governance_seed_yaml (lib.rs:2170), which inserts a gateway policy but never touches required_capabilities, then calls validate_complete_governance directly at lib.rs:2632 — no stamping anywhere on this path.

And that validator hard-fails (lib.rs:6580-6586):

if config.gateway.is_some()
    && !config.required_capabilities.iter().any(|c| c == "gateway_inference_jwt")
{ return Err("gateway mode requires capability `gateway_inference_jwt`".into()); }

Step 12 (production.mdx:322-341) appends only the gateway: block and never edits required_capabilities — which is exactly why step 4 must already carry it. So applying the bot's suggestion would break the walkthrough: step 13's helm upgrade --wait + rollout restart would crashloop control-api with gateway mode requires capability 'gateway_inference_jwt'.

The harm the comment alleges also doesn't exist: the client advertises its full compiled capability list unconditionally (crates/gh-service/src/source.rs:112-115), and gateway_inference_jwt is in CAPABILITIES (schema.rs:64-71) as far back as v0.1.0, the doc's own minimum_client_version. Listing a capability without a gateway is legal — the validator only rejects unknown capabilities. The fixture claims are true but cut the other way: in deploy/consumer/blue/blue.yaml the gateway: block is commented out alongside the capability, documenting a manual pairing, not auto-injection.

2. apps/docs/next/deployment/runtime-contract.mdx:116-117 — "Use /ready instead of /health in the verify curl"

Bot severity 7/10 → my severity 2/10. Invalid. (No subagent — scored below the 5 threshold; verified directly.)

/health returns "ok" (lib.rs:1721), matching the doc's sentence "The Control API should return ok". /ready returns "ready" (lib.rs:1782), so the swap would make the surrounding prose wrong. The comment's motivation also doesn't hold: readiness() only runs db::verify_schema — object storage is a separate route (/health/object-storage, lib.rs:1559), so /ready would still not prove object storage is usable. The paragraph already states that limitation and redirects to the dependency-health view.

Summary

#	Location	Bot	Mine (initial)	Mine (post-investigation)	Verdict
1	production.mdx:155	8	6	1 (−5 after investigation)	Invalid — acting on it causes a startup crashloop
2	runtime-contract.mdx:116	7	2	2 (unchanged)	Invalid — rationale factually wrong; edit would introduce an inaccuracy

Nothing survives at severity ≥5, and neither is a merge blocker. The only defensible sliver in #1 is that the capability is inert for a reader who stops at step 8 — that argues for an inline clarifying comment, not a removal.

Per your instruction I've made no code changes and haven't touched the PR or its threads. Let me know which (if any) you want addressed and I'll fix + push those, resolve their threads, reply to the unpicked ones explaining the severity change, and add the picked/not-picked section to the PR summary.

View on dashboard

[cubeorgdev]

User Message:

okay not picking any then

Done. Since nothing was picked, there were no fixes to make and no commits to push — the working tree is clean and the branch is unchanged at 76eeb38.

What I did on the PR:

• Replied to both review threads with the investigation findings and why the severity dropped (#4021135582, #4021136460), then resolved both.
• Appended a "Review comments" section to the bottom of the PR summary: Picked: none, plus a one-liner each for the two not-picked comments with the re-rank and reason. The rest of the description is untouched.

Both were given a concrete reason (invalid after investigation) rather than "out of scope":

Comment	Bot	Final	Reason
production.mdx:155 — drop gateway_inference_jwt	8	1	Auto-injection claim is false for the mounted-blue.yaml path; applying it would crashloop control-api at step 13
runtime-contract.mdx:116 — /ready over /health	7	2	/health returns ok as the prose says; /ready returns ready and checks only the schema, not object storage

View on dashboard

[blocksorg]

The inference proxy ALB health check should target /ready, not /health. The proxy's liveness endpoint (/health) always returns ok, while its readiness endpoint (/ready) returns 503 draining when the proxy is not ready to accept traffic. Using /health here means the ALB may send requests to a proxy that Kubernetes considers unready or that is draining during a rollout, which can cause failed inference requests. The chart's own readiness probe uses /ready, and the Control API and dashboard ALB annotations in step 5 already use their readiness paths (/ready and /api/health respectively).

Severity 7/10 · View on dashboard

[blocksorg]

The inference proxy ALB health check should use /ready instead of /health. I verified in services/inference-proxy/src/main.rs that /health unconditionally returns ok, while /ready returns 503 draining when the proxy is shutting down. Using /health here means the ALB can keep routing inference traffic to a pod that Kubernetes has already marked unready or that is draining during a rollout, causing failed requests. The chart's own readiness probe uses /ready (deploy/helm/templates/inference-proxy-deployment.yaml:86), and the dashboard/control-api ALB annotations above already use their readiness paths. Suggested fix: change this annotation to alb.ingress.kubernetes.io/healthcheck-path: /ready.

Severity 7/10 · View on dashboard