docs(quickstart): name the reachable probe URLs and the liveness/readiness split

[os-zhuang]

Fixes#88

content/docs/quickstart.mdx only. English source only — the six locale siblings are left for the translation pass, per AGENTS.md.

What changed

The "What's running" table row

| http://localhost:3000/health | Liveness probe |

becomes two rows naming the endpoints a local reader can actually reach, plus a short paragraph saying which endpoint carries which failure and handing the wiring decision to the deploy pages.

The row pointed at a 404 — measured, not inferred

The card ruled that /health is a live route and that the fix must not imply it 404s. The dispatcher registration it cites is real, but it is a dispatcher-internal cleanPath, not a wire path. route-ledger.ts says so in its own scope note ("prepend /api/v1 for the wire path"), the GET /health row is not marked absolute, and client-url-conformance.test.ts:117 compiles exactly that row with the /api/v1 prefix. dispatcher-plugin.ts mounts the two probe branches only as ${prefix}/health and ${prefix}/ready — its own comment says "only reachable over HTTP once mounted EXPLICITLY here (there is no catch-all)" — and serve.ts:2566 constructs the plugin with no prefix, so the default /api/v1 applies. The bare root /health alias exists in the cloud container entrypoint (objectos-runtime/src/node-server.ts:133), whose comment states that without the alias the probe 404s; that entrypoint is not what os start runs.

So I booted the real thing rather than resting on the reading. npm i @objectstack/cli@17.0.0 — the exact package this page tells the reader to install — then os start --port 3877 on a clean home:

/api/v1/health -> 200 {"success":true,"data":{"status":"ok","timestamp":"...","version":"1.0.0","uptime":7.34}}
/api/v1/ready -> 200 {"success":true,"data":{"status":"ready","state":"running"}}
/health -> 404 {"error":"Not found"}
/ready -> 404 {"error":"Not found"}

The page therefore now names the two URLs that answer. It does not say anything about the bare path, and no probe row was dropped — the row was corrected and a second one added. The ruling's premise needs revising, though, and that is a maintainer call, not mine: under os start the old URL was a 404, so the quickstart was naming a path this entrypoint does not serve. /health remains live in the product — as a cloud-container alias and as the dispatcher branch behind /api/v1/health — which is why the page stays silent about it rather than calling it dead.

Why a paragraph, and why only one

The card's point is that swapping paths would land the letter and miss it: a reader who wires only liveness gets a probe that stays green through a database outage. But quickstart's reader has just run os start with no orchestrator and no database to lose, so a full 503-on-dead-driver section here would be worse than useless — it would duplicate, out of context, what deploy/docker.mdx:121 and deploy/kubernetes.mdx:38 already say well.

The shape chosen: name both endpoints in the table, state in two sentences which failure each one carries, then send the reader onward for the wiring. The distinction survives; the deploy pages keep owning the deployment argument. Both new rows are things a local reader can open in a browser and see answer 200, which is what the rest of that table is for.

Wording was checked against both deploy pages so the three agree.

Verification

All of this on the final commit, 727d5bf:

• npx turbo run type-check --force --concurrency=2 — 1 successful, cache bypass, force executing dbc711ac3cdb3ea9.
• npx turbo run build --force --concurrency=2 — 1 successful, cache bypass, force executing, 556 static paths.
• check-translation-ownership.mjs --actor os-zhuang --files changed.txt — exit 0 (0 translation artifacts, 1 other file).
• check-translations.mjs — exit 0, translations gate passed.
• check-translation-output.mjs --self-test — exit 0, 20 cases, every rule demonstrated able to fail.
• check-translation-output.mjs --files changed.txt — exit 0, blocking on 0 changed translation(s), 116 pre-existing findings reported.
• Rendered HTML read from apps/docs/.next/server/app/en/docs/quickstart.html: both rows and the paragraph render, and the two new links resolve to prerendered deploy/docker.html and deploy/kubernetes.html.
• Live probe against a real os start, as above.

Translation note: the six quickstart.*.mdx siblings were already stale on origin/main before this change (their stamped source_sha matches neither the old nor the new English file). The output validator now reports six non-blocking findings on them — they still carry http://localhost:3000/health, which the English page no longer has. Non-blocking by design, but it means six locales keep showing the 404 URL until the next translation pass, which is worth prioritising.

Reported, not edited

• resources/changelog.mdx:285 — left alone. It records what a past release did.
• glossary.mdx, configure/runtime.mdx, observability.mdx, faq.mdx — sibling cards own those this round.
• Filed as quickstart.mdx sample os start output does not match what CLI 17.0.0 prints, and the plugin count is wrong #94: the page's two sample os start output blocks do not match what CLI 17.0.0 prints (duplicated Console: line, an Account: line the CLI does not print, no MCP: line, Plugins: 23 loaded against a measured 30), and the same duplication shows up in the "What's running" table and the plugin blockquote. Different defect class, so not folded in here. Retire "Console" as the name of the end-user surface; keep a name only for the admin surface (Setup) #79 is adjacent but explicitly excludes CLI output samples, and Align the docs with framework 17.0 — the pages still describe the 16.x contract #78 already landed without touching those blocks.

---

Generated by Claude Code