KB Ingestion Phase 3: Cloud Deployment Guide + Worked Examples

Context

Phase 3 sub-ticket of Epic #11624 (Cloud-Native KB Ingestion for External Workspaces). Graduated from Discussion #11623. Blocked-by Phase 2 #11626 — guide content depends on stable Phase 0/1 contracts AND Phase 2 service+facade shape (operator and ingestion-flow examples need real endpoint names + payload shapes to be substrate-correct).

This phase ships the operator-facing substrate for self-service cloud Agent OS deployments: a guide tree explaining how clients configure KB, write custom sources/parsers, wire git hooks, and reason about tenant boundaries.

The Problem

After Phase 0/1 + Phase 2 land, the system is technically functional for cloud deployments — but cloud operators have no documented onboarding path. Per Discussion #11623 §9 + operator framing:

"a graduation goal for the sandbox epic must include a new guide, which explains how clients can configure KB and their deployment pipelines."

Without the guide:

• Cloud deployment teams must reverse-engineer the contracts from source code
• Custom-source/custom-parser authoring becomes word-of-mouth knowledge
• Hook-wiring + tenant-boundary semantics get re-derived per deployment
• Security boundaries (operator-installed/Neo-shipped/signed-package for server-side parsers; client-side for everything else) lack a canonical reference

The Architectural Reality

This phase creates a new guide tree:

The Fix

1. Guide Tree Authoring

Each *.md document follows existing learn/agentos/ discipline:

• Anchor & Echo discipline (per AGENTS.md): JSDoc @summary cross-links to relevant source files
• Cross-links to #9999, #10010, #10011, #10030 for retrieval-side / identity / RLS / concept-ontology substrate
• Cross-links to Phase 0/1 (#11625) + Phase 2 (#TBD) schemas + service contracts
• Capability framing only (no commercial-customer references; per Neo's external-positioning discipline)

2. Worked Example

examples/cloud-deployment/minimal-external-workspace/:

• Minimal package.json (Neo as dependency)
• One source file in a hypothetical language (e.g., .proto for protobuf — common cross-language demo)
• One custom Source class registered via the Phase 0/1 registry API
• One custom Parser emitting parsed-chunk-v1 records
• README explaining how to run the example end-to-end

3. Hook Example

examples/cloud-deployment/pre-push-hook.sh:

• Bash pre-push hook
• Computes git diff against last-pushed SHA
• Calls ingestSourceFiles via the bulk-facade CLI (or MCP tool depending on batch size)
• Handles delete tombstones + revision-boundary payload
• Comments explain extension points for client customization

4. Validation

• All referenced files in guide examples actually exist
• All code examples are runnable (CI lint or manual smoke test)
• All cross-references resolve (no dead #NNNN or [link] references)
• Guide tree integrates into learn/tree.json discovery

Acceptance Criteria

• learn/agentos/cloud-deployment/Overview.md written and linked in learn/tree.json
• learn/agentos/cloud-deployment/Configuration.md written; documents all configs introduced in Phase 0/1 + Phase 2
• learn/agentos/cloud-deployment/CustomSources.md written; includes worked-example reference
• learn/agentos/cloud-deployment/CustomParsers.md written; covers server-side AND client-side parser authoring
• learn/agentos/cloud-deployment/HookWiring.md written; includes shell-hook example reference
• learn/agentos/cloud-deployment/Security.md written; codifies write-side stamping + spoof-rejection + parser sandboxing boundaries + KB-as-cache vs MC-as-store data-recovery framing (cross-link to Phase 4 Epic #11628 retention-policy framing)
• learn/agentos/cloud-deployment/MigrationPath.md written; documents zero-config upgrade path for existing Neo deployments
• examples/cloud-deployment/minimal-external-workspace/ exists and runs end-to-end
• examples/cloud-deployment/pre-push-hook.sh exists and demonstrates the contract
• All guide-referenced files exist (validation step)
• All code examples runnable (manual smoke test documented in PR)
• Guide tree appears in KB after manage_knowledge_base({action: 'sync'}) — learn/agentos/cloud-deployment/*.md chunked + retrievable

Out of Scope

• Generated API docs from inline JSDoc (handled by existing docs/ build pipeline)
• Per-client deployment runbooks (those belong to client-side documentation, not Neo substrate)
• Marketing or commercial-positioning material (capability framing only — neutral technical reference)
• WASM/tree-sitter server-side parser sandboxing patterns → future Discussion when feature exists

Avoided Traps

Related

• Parent Epic: #11624
• Blocked-by: Phase 2 #11626 (service + facade shape must stabilize) — itself blocked-by Phase 0/1 [#11625]
• Origin Discussion: #11623 (§9 Guide Deliverable specifies the tree)
• Cross-substrate guide siblings: learn/agentos/KnowledgeBase.md, learn/agentos/tooling/MultiTenantMigrationGuide.md, learn/agentos/CodeExecution.md, learn/agentos/SharedDeployment.md

Origin Session ID

7360e917-1733-4cdd-a6f3-5ac51c34b838

Handoff Retrieval Hints

• query_raw_memories({query: 'cloud deployment guide custom sources parsers hook wiring'})
• ask_knowledge_base({query: 'learn agentos guide tree structure new substrate', type: 'guide'})
• Discussion #11623 §9 is the authoritative scope-source
• Phase 2 (#TBD) MUST be merged before drafting HookWiring.md + worked example (depends on real endpoint names + payload shapes)
• Sections that CAN be drafted post-Phase-0/1, pre-Phase-2 (low-risk): Overview.md (architectural framing), Security.md (sandboxing + write-side stamping invariants), MigrationPath.md (zero-config upgrade story). Saves wall-clock time if Phase 3 starts in parallel once Phase 0/1 merges.