---
id: 11727
title: DeploymentCookbook realignment as accurate deployment authority
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-gpt
createdAt: '2026-05-21T17:24:47Z'
updatedAt: '2026-05-22T08:09:33Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11727'
author: neo-opus-ada
commentsCount: 0
parentIssue: 11720
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy:
  - '[x] 11721 Cloud deployment topology + scheduler-task-taxonomy ADR'
blocking: []
closedAt: '2026-05-22T08:09:33Z'
---
# DeploymentCookbook realignment as accurate deployment authority

## Context

Sub **F1** of Epic #11720 (Cloud Agent OS Deployment Readiness). **Blocked-by D0 #11721** (realign after the topology decision). MVP-class is a V-B-A item (deferrable-vs-critical — confirm via the sub→PR-chain map).

D0 is now delivered by ADR 0014 (`learn/agentos/decisions/0014-cloud-deployment-topology-and-scheduler-task-taxonomy.md`), merged through PR #11738. The sub→PR-chain map on #11720 (`IC_kwDODSospM8AAAABDOzogg`) classifies F1 as MVP-required for #11720 closeout; pickup V-B-A narrows realignment breadth, not existence.

## The Problem

`learn/agentos/DeploymentCookbook.md` is **stale as deployment authority**: it documents the older clients/proxy/KB/MC/data-layer + two-image-sidecar shape; its only orchestrator section is `Local Orchestrator Dev-Sync Roots` (local-maintainer material, not cloud); its known-gaps list still points at older #108xx work. It misrepresents the current and target Agent OS deployment.

## The Fix

Realign `DeploymentCookbook.md` as accurate deployment authority after D0/D1: the current baseline vs the decided target topology; the cloud-safe scheduler/task taxonomy; the model-provider profile; persistence / bind-mounts; health / proof references; a clearly-isolated **local-only orchestrator appendix** (not the cloud spine); stale known-gaps cleanup.

Also perform the deployment-guide-tree stale sweep called out in #11720 comment `IC_kwDODSospM8AAAABDOJ0qQ`: `learn/agentos/cloud-deployment/*`, `examples/cloud-deployment/*`, and deployment references touched by the cookbook realignment must not contradict the cookbook, ADR 0014, or the current #11720 owner map.

## Contract Ledger

| Target Surface | Source of Authority | Proposed Behavior | Fallback / Edge Case | Docs | Evidence |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `learn/agentos/DeploymentCookbook.md` as deployment authority | Epic #11720; ADR 0014; #11720 sub→PR-chain map comment `IC_kwDODSospM8AAAABDOzogg`; #11720 lost-item audit `IC_kwDODSospM8AAAABDOJ0qQ` | Cookbook describes current baseline vs D0 target topology, cloud-safe scheduler lane taxonomy, provider profile boundary, persistence/redeploy pointers, health/proof handoffs, and current known gaps. | If Sub B/C/D are still in flight, cookbook explicitly labels their outputs as pending owner-map handoffs instead of pretending the reference profile/proof already exists. | Yes — cookbook is the target doc. | Markdown/link validation, stale-reference sweep, and reviewer comparison against ADR 0014 + #11720 owner-map. |
| Local-only orchestrator material | ADR 0014 §2.1-§2.4; Sub A #11722 config surface | Local maintainer dev-sync/wake/MLX/kbSync material is isolated into a clearly labeled local-only appendix, separate from the cloud deployment spine. | Any retained local-only instruction must be explicitly marked not applicable to cloud tenant deployments. | Yes. | Grep/assertion that local-only sections are labeled and cloud spine does not prescribe local worktrees, git pulls, desktop wake delivery, or local KB sync cascade. |
| Deployment guide-tree consistency | #11720 lost-item audit; #11727 ACs; ADR 0014 | Surrounding cloud-deployment guides and examples touched by this work do not contradict the cookbook on topology, security/auth state, tenant ingestion, or local-only behavior. | If a broader stale guide is out of F1 scope, the cookbook names the owner/ticket rather than silently leaving a contradiction. | Yes, only where directly touched or needed to prevent contradiction. | Targeted `rg` stale-term sweep and link/path checks. |
| Stale known-gaps list | #11720 owner map; #11730 residual epic; issue #11719 boundary | Known gaps cite #11720/#11730/#11719-era tracked work, not obsolete #108xx-only placeholders. | Preserve #11719 as a separate narrow markdown-table rendering defect; do not fold it into F1. | Yes. | Known-gaps section review plus `rg` for obsolete issue references in the cookbook. |

## Acceptance Criteria

- [ ] `DeploymentCookbook.md` reflects the D0-decided topology + the Sub C production reference profile handoff state.
- [ ] Local-only orchestrator dev-sync material is isolated into a clearly-labelled appendix.
- [ ] The stale known-gaps list is refreshed (cites the #11720/#11730 substrate, not older #108xx work as authority).
- [ ] Deployment-guide-tree stale sweep performed for directly related cloud deployment guides/examples; no contradiction is left with the cookbook, ADR 0014, or the #11720 owner map.

## Out of Scope

- The day-0 tutorial (Sub F2 — a separate artifact + ticket).
- #11719 (the `DeploymentCookbook` §6 Markdown table-rendering bug — a separate narrow defect).
- Implementing the production reference compose/profile itself (Sub B #11723 and Sub C #11724).
- Runtime healthcheck / journey proof implementation (Sub D #11725).

## Related

Parent #11720 · blocked-by #11721 (D0, now delivered by PR #11738 / ADR 0014) · #11719 (separate `DeploymentCookbook` §6 defect) · Origin Discussion #11718 §5 Sub F1.

## Origin Session ID

`8e1dc8ca-b5a5-4479-b3cf-31918eb4a5b2`

## Timeline

- 2026-05-21T17:24:48Z @neo-opus-ada added the `documentation` label
- 2026-05-21T17:24:49Z @neo-opus-ada added the `enhancement` label
- 2026-05-21T17:24:49Z @neo-opus-ada added the `ai` label
- 2026-05-21T17:27:30Z @neo-opus-ada added parent issue #11720
- 2026-05-21T17:27:53Z @neo-opus-ada marked this issue as being blocked by #11721
- 2026-05-21T17:32:55Z @neo-gpt cross-referenced by #11720
- 2026-05-21T17:50:38Z @neo-gpt cross-referenced by #11729
- 2026-05-21T18:29:12Z @neo-opus-ada cross-referenced by #11730
- 2026-05-21T18:43:04Z @neo-opus-ada cross-referenced by #11736
- 2026-05-21T20:46:50Z @neo-opus-ada cross-referenced by PR #11738
- 2026-05-21T21:11:13Z @neo-opus-ada cross-referenced by PR #11737
- 2026-05-21T22:13:36Z @neo-gpt assigned to @neo-gpt
- 2026-05-21T22:27:35Z @neo-gpt referenced in commit `be55693` - "feat(agentos): realign deployment cookbook authority (#11727)"
- 2026-05-21T22:29:15Z @neo-gpt cross-referenced by PR #11742
- 2026-05-21T22:32:14Z @neo-opus-ada cross-referenced by #11724
- 2026-05-22T02:31:08Z @neo-gpt referenced in commit `95633fb` - "feat(agentos): realign deployment cookbook authority (#11727)"
- 2026-05-22T08:02:31Z @neo-gpt referenced in commit `1a36f9e` - "feat(agentos): realign deployment cookbook authority (#11727)"
- 2026-05-22T08:09:33Z @tobiu referenced in commit `b98b9d4` - "feat(agentos): realign deployment cookbook authority (#11727) (#11742)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-22T08:09:34Z @tobiu closed this issue

