Blocked until local/cloud runtime parity (#15798) and the config-default consolidation (#16039) complete. Filed now to capture the criteria; starting earlier would re-describe a surface we are about to delete.
The problem
The deployment guide tree does not deliver easy onboarding, and rewriting it today cannot fix that.
learn/agentos/DeploymentCookbook.md — 463 lines, 10 sections, ~35 environment variables presented as a flat table with "supply these values per service/profile as needed" and no signal about which the reader can ignore. Sections 2, 5 and 6 are almost entirely env-var explanation. It also carries a residual-owner ticket map (#11730–#11736) that no one onboarding will ever need, and a maintainer-only appendix.learn/agentos/cloud-deployment/Day0Tutorial.md — 780 lines, 8 milestones. Milestone 0 asks the operator to write their own MCP client (cat > /tmp/day0-call-tool.mjs, ~25 lines of SDK transport code) before anything has been seen to work; every later step is "write a JSON file to /tmp, invoke your hand-rolled client." And it never starts the production stack — it brings up docker-compose.test.yml with a deterministic provider mock, so an operator can complete the whole tutorial without ever running the thing they will deploy.
Both documents are competent. The failure is not writing quality — they accurately describe a system that requires too much configuration and performs too few of its own steps. Length is the symptom.
The criterion that matters
"Easier" means fewer steps the operator performs, not fewer lines. A rewrite that reaches 300 lines while the user still hand-runs every check has improved nothing. Each of those 8 milestones exists because the system cannot do it and report on itself.
Acceptance Criteria
Non-goals
Not a tone or formatting pass. Not consolidating the guide tree for its own sake. If the underlying surface has not shrunk when this starts, the ticket is not ready — say so and re-block rather than rewriting around it.
Related
#15798 parity epic · #16039 config-default consolidation (hard dependency) · #14230 local-first developer onboarding (contributor path — adjacent, not this) · #14793 the "download and run" moment.
Filed by @neo-opus-grace (Grace, Claude Opus 5) on operator direction — capture now, start after parity.
Blocked until local/cloud runtime parity (#15798) and the config-default consolidation (#16039) complete. Filed now to capture the criteria; starting earlier would re-describe a surface we are about to delete.
The problem
The deployment guide tree does not deliver easy onboarding, and rewriting it today cannot fix that.
learn/agentos/DeploymentCookbook.md— 463 lines, 10 sections, ~35 environment variables presented as a flat table with "supply these values per service/profile as needed" and no signal about which the reader can ignore. Sections 2, 5 and 6 are almost entirely env-var explanation. It also carries a residual-owner ticket map (#11730–#11736) that no one onboarding will ever need, and a maintainer-only appendix.learn/agentos/cloud-deployment/Day0Tutorial.md— 780 lines, 8 milestones. Milestone 0 asks the operator to write their own MCP client (cat > /tmp/day0-call-tool.mjs, ~25 lines of SDK transport code) before anything has been seen to work; every later step is "write a JSON file to /tmp, invoke your hand-rolled client." And it never starts the production stack — it brings updocker-compose.test.ymlwith a deterministic provider mock, so an operator can complete the whole tutorial without ever running the thing they will deploy.Both documents are competent. The failure is not writing quality — they accurately describe a system that requires too much configuration and performs too few of its own steps. Length is the symptom.
The criterion that matters
"Easier" means fewer steps the operator performs, not fewer lines. A rewrite that reaches 300 lines while the user still hand-runs every check has improved nothing. Each of those 8 milestones exists because the system cannot do it and report on itself.
Acceptance Criteria
cat-ed into/tmp.Non-goals
Not a tone or formatting pass. Not consolidating the guide tree for its own sake. If the underlying surface has not shrunk when this starts, the ticket is not ready — say so and re-block rather than rewriting around it.
Related
#15798 parity epic · #16039 config-default consolidation (hard dependency) · #14230 local-first developer onboarding (contributor path — adjacent, not this) · #14793 the "download and run" moment.
Filed by @neo-opus-grace (Grace, Claude Opus 5) on operator direction — capture now, start after parity.