docs: simplify lifecycle sections for the converge model

The apply/converge + gateway refactors let the docs collapse a lot:

- design.md §Component Lifecycle: the build→install→deploy three-step
  ("enables and starts services") becomes two moves — develop, then
  `castle apply` (activation polymorphic over the manager). Filesystem
  layout de-duped and corrected (program source is /data/repos/<name>,
  not the long-removed ~/.castle/code).
- registry.md §Lifecycle: three near-identical per-kind flows (service/
  tool/job) collapse into one flow + a "what apply does per manager"
  table. Manager table's "start/stop" column → "how apply activates".
  Fixed stale paths-table rows (code/<name>) and a stale `service run`.
- developing-castle.md endpoint list: `POST /apply` is the one lifecycle
  endpoint; dropped retired `/deploy`; service actions are restart-only;
  added `/config/deployments/{name}/enabled`.

Net −37 lines; no retired-verb or stale-path references remain in docs.
This commit is contained in:
2026-07-02 12:20:33 -07:00
parent 7410680f57
commit 43a6ad76bb
3 changed files with 66 additions and 103 deletions

View File

@@ -47,15 +47,17 @@ for tools/libraries.
## castle-api endpoints (port 9020)
- Core: `GET /health`, `GET /stream` (SSE: health, service-action, mesh)
- Converge: `POST /apply` (`{name?, plan?}`) — the one lifecycle endpoint
- Deployments: `GET /deployments[/{name}]`, `GET /status`
- Catalog + editing: `GET /programs[/{name}]`, `POST /programs/{name}/{action}`,
`PUT|DELETE /programs/{name}`; likewise `/services`, `/jobs`
- Config: `GET|PUT /`, `POST /apply`, `POST /deploy`
- Gateway: `GET /gateway`, `GET /gateway/caddyfile` (reload is convergence: `POST /apply`)
- Catalog + editing: `GET /programs[/{name}]`, `POST /programs/{name}/{action}`
(dev verbs only), `PUT|DELETE /programs/{name}`; likewise `/services`, `/jobs`
- Config: `GET|PUT /`, `POST /config/apply`, `PUT /config/deployments/{name}/enabled`
- Gateway: `GET /gateway`, `GET /gateway/caddyfile`, `PUT /gateway/config` (making
routes live is convergence: `POST /apply`)
- Mesh: `GET /mesh/status`, `GET /nodes[/{hostname}]`
- Agents (dashboard terminal UX): `GET /agents`, `GET /agents/sessions`,
`GET /agents/history`, `DELETE /agents/sessions/{id}`, `WS /agents/{name}/session`
- Service actions: `POST /services/{name}/{action}`, `GET /services/{name}/unit`
- Service actions: `POST /services/{name}/restart`, `GET /services/{name}/unit`
## Infrastructure internals