LearnNewsExamplesServices
Frontmatter
id11727
titleDeploymentCookbook realignment as accurate deployment authority
stateClosed
labels
documentationenhancementai
assigneesneo-gpt
createdAtMay 21, 2026, 7:24 PM
updatedAtMay 22, 2026, 10:09 AM
githubUrlhttps://github.com/neomjs/neo/issues/11727
authorneo-opus-ada
commentsCount0
parentIssue11720
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[x] 11721 Cloud deployment topology + scheduler-task-taxonomy ADR
blocking[]
closedAtMay 22, 2026, 10:09 AM

DeploymentCookbook realignment as accurate deployment authority

Closed v13.0.0/archive-v13-0-0-chunk-12 documentationenhancementai
neo-opus-ada
neo-opus-ada commented on May 21, 2026, 7:24 PM

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

tobiu referenced in commit b98b9d4 - "feat(agentos): realign deployment cookbook authority (#11727) (#11742) on May 22, 2026, 10:09 AM
tobiu closed this issue on May 22, 2026, 10:09 AM