amadan
spec: real carlos deploy story on carloku.com (deploy URL output + hello demo app)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 file changed,
+118
−0
docs/superpowers/specs/2026-08-09-carloku-deploy-story-design.md+118 −0
diff --git a/docs/superpowers/specs/2026-08-09-carloku-deploy-story-design.md b/docs/superpowers/specs/2026-08-09-carloku-deploy-story-design.md| new file mode 100644 |
| index 000000000..4943683d1 |
| --- /dev/null |
| +++ b/docs/superpowers/specs/2026-08-09-carloku-deploy-story-design.md |
| @@ -0,0 +1,118 @@ |
| +# Real `carlos deploy` story on carloku.com — design (2026-08-09) |
| + |
| +Paul's ask: put the new `carlos deploy` on carloku.com, make the command |
| +output the URL it deployed to, and make the homepage example a REAL app — |
| +"hello world" running at `hello.<sqid>.oncarlos.com`. New hero copy supplied |
| +verbatim (approved over the don't-overclaim flag: Tito proves on-prem, Eleven |
| +and Amadan are the named hybrid customers, "billions" is an architecture |
| +claim the design backs). |
| + |
| +Four parts, in rollout order: CLI output change → hello app → provisioning → |
| +site update. |
| + |
| +## A. CLI: name the destination on every path (platform repo, deploy.go) |
| + |
| +Today the deploy verb only names the URL when the watch confirms it |
| +(`live https://<host>`); the held-for-bake and mid-failure paths exit without |
| +ever saying where the deploy was going. |
| + |
| +Change: immediately after `deployTargets` resolves (before ship, so every |
| +later path — held, watch, even a ship failure — has already named the |
| +destination), print: |
| + |
| +- one host: `deploying https://hello.baf.oncarlos.com` |
| +- N > 1 hosts: `deploying N instances on <channel>` (aggregate — a fleet- |
| + sized channel must not print 21 lines; the per-host `live` lines and the |
| + timeout diagnostics already name hosts individually as they resolve) |
| + |
| +The static-path note keeps its recheck-window explanation but stops |
| +repeating the host list (the deploying line just printed it). The |
| +no-instance path is unchanged: there is genuinely no URL to name, and its |
| +existing "promoted, nothing to watch" message stands. The final |
| +`live https://<host>` lines are unchanged. |
| + |
| +Tests (deploy_e2e_test.go): pin the new line on the binary path (single |
| +host), the aggregate form (multi-host), the static path (no host repetition |
| +in the watching note), and the held path (URL printed before the bake note). |
| + |
| +Review: Sonnet implements from the brief; Opus reviews (member-facing |
| +production CLI path, per the delegation policy). |
| + |
| +## B. The hello app (new public repo carlosframework/hello) |
| + |
| +The homepage example must be inspectable and real. A ~20-line Go program, |
| +matching the exec-backend contract (internal/activator/backend_exec.go |
| +launches `<bin> --socket <path> --db <path>`): |
| + |
| +- parse `--socket` and `--db` (db ignored), remove any stale socket file, |
| + `net.Listen("unix", socket)`, serve `hello world\n` (text/plain) on every |
| + request. |
| +- go.mod (module github.com/carlosframework/hello), README framing it as |
| + the app running on the carloku.com homepage with the two commands (build |
| + linux-arm64, `carlos deploy`), LICENSE matching the org convention. |
| + |
| +## C. Provisioning (production flagship, via carlos CLI only) |
| + |
| +Per the operate-via-API rule — no AWS, no box commands; any missing CLI |
| +verb is a filed product gap, not an SSM session: |
| + |
| +1. `carlos accounts create` — new dedicated demo account owned by |
| + paul@keymail.dev. Sqid mints sequentially (likely `baf`); the homepage |
| + embeds whatever actually mints. |
| +2. Domains pass auto-mints `*.<sqid>.oncarlos.com` DNS + wildcard cert; |
| + verify by TLS handshake before deploying. |
| +3. `carlos apps create -app hello -account <sqid>`. |
| +4. `carlos instances create -app hello -host hello.<sqid>.oncarlos.com |
| + -channel stable` (exec backing, hibernation on — hibernating when idle |
| + is the story, not a bug). |
| +5. Build hello GOOS=linux GOARCH=arm64; `carlos deploy -app hello |
| + -account <sqid> ./hello` with the CLI built from part A. Capture the |
| + session verbatim — it becomes the homepage terminal content. |
| +6. Verify: `curl https://hello.<sqid>.oncarlos.com` returns `hello world` |
| + and an `X-Carlos-Version` matching the shipped build. |
| + |
| +## D. carloku.com update (branch off flagship-redesign) |
| + |
| +The live site serves the flagship-redesign lineage (draft PR #1), so the |
| +change branches from and PRs against `flagship-redesign`, stacking under |
| +Paul's draft. |
| + |
| +- Hero headline: **The uncompromising app platform**. Subtitle, verbatim: |
| + "Carloku is an app hosting platform that accepts no tradeoffs. Deploy in |
| + seconds. Scale to billions. Simple commands, massive power. Cloud, |
| + hybrid, and on-prem: all first-class. Welcome to the new standard. Get |
| + ready to ship." |
| +- `<title>`, meta description, og:description updated to match the new |
| + positioning (🤖 marker retained on the description). |
| +- Terminal mock: replaced with the captured REAL `carlos deploy` session |
| + from part C (using console.carloku.com — real output; the site-wide |
| + dashboard→console rename stays PR #2's job), ending in |
| + `live https://hello.<sqid>.oncarlos.com`. A visible link near the |
| + terminal invites the visitor to open the app — it really is running — |
| + and the footer/terminal area links carlosframework/hello as source. |
| + aria-label updated to describe the one-command session. |
| +- Workflow section: leads with `carlos deploy` as the one-command form |
| + (ship + promote + watch until the URL serves the new build); ship / |
| + promote / rollback stay as the decomposed look-before-you-go story. |
| +- /get-started/: after the ship and promote steps, a short "or in one |
| + motion" addition showing `carlos deploy`. |
| + |
| +Ship the site via the member form (`carlos deploy -app carloku -kind |
| +static -host carloku.com <site-dir>`, per the recipe merged in carloku |
| +PR #3); pinfra scripts are the fallback if account membership refuses the |
| +member path. Verify with `curl -sI https://carloku.com` X-Carlos-Version |
| +and the new copy in the body. |
| + |
| +## Out of scope |
| + |
| +- dashboard→console rename across the site (draft PR #2). |
| +- Merging draft PR #1 (Paul merges). |
| +- Any pricing copy (site says nothing about pricing). |
| +- Fleet-scale watch output beyond the aggregate deploying line. |
| + |
| +## Verification summary |
| + |
| +Platform gates: go build/vet/test ./... -count=1 clean, gofmt clean on |
| +touched files, GOOS=darwin compile. End-to-end proof: the homepage terminal |
| +content is a paste of a real session, and hello.<sqid>.oncarlos.com serves |
| +"hello world" with the version header the session shipped. |