Skip to content

docs(docs): add wheels deploy guides and CLI reference (starlight-native mdx)#2190

Merged
bpamiri merged 1 commit into
developfrom
peter/wheels-deploy-guides
Apr 22, 2026
Merged

docs(docs): add wheels deploy guides and CLI reference (starlight-native mdx)#2190
bpamiri merged 1 commit into
developfrom
peter/wheels-deploy-guides

Conversation

@bpamiri

@bpamiri bpamiri commented Apr 21, 2026

Copy link
Copy Markdown
Collaborator

Summary

Fills the deployment docs slot deliberately left empty when the v4 guides rewrite shipped (#2169). The Kamal-based wheels deploy port (#2187) is now documented for end users in Starlight-native MDX under web/sites/guides/src/content/docs/v4-0-0-snapshot/.

Deployment guides (7 files under deployment/):

  • index.mdx rewrite — replaces the "no wheels deploy in 4.0 today" placeholder with a landing page covering the Kamal lineage, when to reach for the tool vs. alternatives, and the zero-downtime rollover story.
  • first-deploy.mdx — guided tutorial from wheels deploy initwheels deploy with Starlight <Steps>.
  • config-reference.mdx — full deploy.yml schema. Every allowed top-level key was sourced directly from cli/lucli/services/deploy/config/Validator.cfc on this branch.
  • accessories.mdx, secrets.mdx, hooks.mdx — topic-focused how-tos.
  • migrating-from-kamal.mdx — the ERB-vs-Mustache divergence is called out in a <Aside type="caution"> at the top.

CLI reference (69 files under command-line-tools/commands/deploy/):

  • One page per verb across 10 groups (top-level + app/proxy/accessory/build/registry/server/prune/lock/secrets). Each page carries frontmatter, synopsis, flags table, behavior paragraph, and 1-2 examples. Behavior is sourced directly from the *Cli.cfc files on develop — e.g. the Phase 2 marker-file app live/app maintenance implementation is documented honestly rather than as full proxy-native maintenance.

Sidebar (src/sidebars/v4-0-0-snapshot.json):

  • Deployment & Operations: 6 new items promoted to the top; existing production-config, docker-deployment, vm-deployment, security-hardening, observability-and-logging entries retained below unchanged.
  • CLI Reference: new "Deploy Commands" subsection with collapsible per-verb-group leaves.

Test plan

  • cd web && pnpm --filter @wheels-dev/site-guides build — green. 415 pages built; all 76 new pages render with correct sidebar position.
  • Sidebar JSON validates as JSON (python3 -c "import json; json.load(open(...))").
  • Spot-checked frontmatter shape, Starlight component imports, and voice against existing pages (start-here/tutorial/index.mdx, basics/models-and-the-orm.mdx).
  • Preview locally with pnpm --filter @wheels-dev/site-guides dev and click through the new sidebar sections.
  • Verify migrating-from-kamal.mdx ERB-vs-Mustache callout reads loud enough.

Notes

  • Ruby Kamal on-server parity and the deliberate Mustache-for-ERB schema divergence follow the spec at docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md.
  • Per cli/CLAUDE.md:67 the commit does not include a Co-Authored-By trailer.

…ive mdx)

Adds the deployment docs slot deliberately left empty when the v4 guides
rewrite shipped (#2169). The wheels deploy Kamal port (#2187) is now
documented for end users:

Deployment guides (web/sites/guides/src/content/docs/v4-0-0-snapshot/deployment/):
- index.mdx rewrite: replaces the "no wheels deploy in 4.0" placeholder
  with a proper landing describing the Kamal lineage, when to use it,
  and the zero-downtime rollover story
- first-deploy.mdx: guided tutorial from init → setup → deploy
- config-reference.mdx: full deploy.yml schema, with every allowed
  top-level key sourced from Validator.cfc
- accessories.mdx: sidecar lifecycle
- secrets.mdx: .kamal/secrets and the 5 adapters (op/bw/aws/lpass/doppler)
- hooks.mdx: KAMAL_* env contract + pre/post/post-failure
- migrating-from-kamal.mdx: coexistence contract, ERB→Mustache divergence

CLI reference (web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/):
- 69 per-verb pages — every verb in DeployMainCli, DeployAppCli,
  DeployProxyCli, DeployAccessoryCli, DeployBuildCli, DeployRegistryCli,
  DeployServerCli, DeployPruneCli, DeployLockCli, DeploySecretsCli
- Each page: frontmatter, synopsis, flags table, behavior, examples
- Behavior sourced directly from the *Cli.cfc files on develop

Sidebar wiring (web/sites/guides/src/sidebars/v4-0-0-snapshot.json):
- Deployment & Operations: 6 new items promoted to top, existing
  production-config/docker/vm/security/observability retained below
- CLI Reference: new "Deploy Commands" subsection with collapsible
  per-verb-group leaves

Build: pnpm --filter @wheels-dev/site-guides build succeeds, 415 pages.

Cross-reference: #2187 (the port).
@bpamiri
bpamiri merged commit 39a7cbb into develop Apr 22, 2026
10 of 11 checks passed
@bpamiri
bpamiri deleted the peter/wheels-deploy-guides branch April 22, 2026 00:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant