carton-mcp

WHAT: the development-flow for the split-content capability — separating a concept whose description (n.d) holds raw CONTENT (a data dump / pasted document) from a real DESCRIPTION, by splitting the raw content into its own `{concept_name}_Desc_Content` node. Covers `carton_split_content.py` (both `build_split_spec`, the pure spec function, and `split_content_concept`, the thin neo4j-writing wrapper — self-contained, ONE module, per the one-capability-one-module law), the `Desc_Content` universal type, the `has_desc_content` relationship, and the `split_content_concept` MCP tool. WHEN: when editing `carton_split_content.py`, `split_content_concept`, the `Desc_Content` type, or the `has_desc_content` relationship; or adding a new capability that also needs the content-vs-description split (any of).

WHAT: the dev-flow for the OPTIONAL domain/subdomain/personal_domain/produces params on add_concept_tool_func — the internal chokepoint function every CartON concept-creation caller (Dragonbones, sm_gate.py, split_content_concept, the migration scripts) passes through, whether or not they use the add_concept MCP tool. WHEN: when editing add_concept_tool_func's domain/subdomain/personal_domain/produces params, merge_optional_domain_fields, or PERSONAL_DOMAINS in add_concept_tool.py (any of).

WHAT: the development-flow for changing the CartON KV / CartonObj capability — the embedded-structured-KV-in-concept-descriptions feature (a <CartonObj name=..>{ JSON-with-bare-refs }</CartonObj> fence in n.d): the carton_kv parser/normalizer, edit_carton_obj (surgical single-leaf body edits + remove_fence), validate_carton_obj (schema + did-you-mean refs), the auto_link_description fence-opacity, fence-preservation (carry_forward_fences), ref-expansion, and the is_schema schema registry. It is the COMPLETE distributed edit-set (lib ↔ utils wrappers ↔ MCP tools ↔ the linker ↔ the daemon's live parse path ↔ the schema graph) + deploy + the only valid E2E test. WHEN: when editing carton_kv.py, the edit_carton_obj / validate_carton_obj / get_concept-expand MCP tools, the auto_link_description fence-opacity masking, the daemon fence/desc-mode parse path (parse_queue_file_to_concepts / batch_create_concepts_neo4j), or the is_schema schema-registry; or adding ANY new CartonObj capability (any of).

WHAT: the dev-flow for editing the WEBBING AGENT — carton's standing CONCEPT-ATOMIZATION daemon, CLONED from the proven Sophia (docmirror-cohere) architecture: CODE detects a batch of under-structured, autolinker-processed, main-agent-authored concepts (linked=true, source in CHAT_SOURCES, webbed IS NULL), serves them to a fresh SDNAC run each tick, the agent ADDS real is_a/part_of/instantiates/produces structure + child concepts, and CODE verifies + marks webbed=true. Covers webbing_agent.py, webbing_agent_worker.py, and the one-line SYSTEM_SOURCES coupling in observation_worker_daemon.py. WHEN: when editing webbing_agent.py, webbing_agent_worker.py, the eligibility predicate (_is_underdeveloped), the batch-goal builder (_build_batch_goal), the WEBBER_SYSTEM_PROMPT, the webbed/source recursion-guard, or CHAT_SOURCES/SYSTEM_SOURCES in observation_worker_daemon.py (any of).

WHAT: just-in-time building of TreeShell nodes from CartON graph relationships — when a jump targets a coordinate not found in any family JSON config, resolve the CartON concept into a cached Menu node whose options come from its HAS_PART relationships. WHEN: when a TreeShell jump target is not found in any loaded family JSON config, you need a node built on the fly from a CartON concept, or working on JIT node resolution for SANCREV game navigation.

WHAT: the CartON MCP — a persistent knowledge graph (Neo4j + ChromaDB) you add concepts to, query, edit, and project. WHEN: persisting knowledge, creating observations/concepts, querying concept networks, semantic search, or editing a concept's description/structured data.

WHAT: Precision editing of CartON concept descriptions WHEN: When you need to update a concept description with surgical edits

WHAT: capture architectural design insights from a conversation into CartON as Design_-prefixed concepts in an architecture collection, with full descriptions and cross-reference relationships to other design concepts. WHEN: when an architecture discussion produces design insights that need to be persisted beyond conversation context, or you want to save a design decision into the architecture review collection.

WHAT: how to diagnose and restart the CartON observation worker daemon when it dies — check the worker log for the crash reason and relaunch the daemon with the required Neo4j env vars. WHEN: when ps aux shows no observation_worker process, carton_management says the daemon is off, queued observations stop being processed, or _ensure_daemon_running fails.

WHAT: how CartON indexes concepts into ChromaDB directly from the daemon's memory, with no wiki filesystem intermediary — SmartChromaRAG.ingest_concepts takes concept dicts and makes them semantically searchable. WHEN: when working on how concepts get embedded and become queryable via chroma_query, after the daemon batch-writes concepts to Neo4j, or when semantic search results are missing or stale.

WHAT: the fix that makes only HAS_OPTION relationships become TreeShell children — replace the hardcoded GIINT child_types in _jit_node_from_carton with the HAS_OPTION relationship, so TreeShell options are explicitly programmed via CartON instead of inferred from structural relationships. WHEN: when JIT-loaded CartON nodes wrongly display structural relationships as navigable options, you want a JIT node to show only explicitly programmed HAS_OPTION children, or fixing _jit_node_from_carton.

WHAT: how to diagnose and fix CartON MCP broken pipe errors where reads work but writes fail — recovering the CartON write path after an MCP process failure. WHEN: when add_concept returns Errno 32 Broken pipe but get_concept still works, CartON writes fail while reads succeed, or the CartON MCP process needs restarting to restore writes.

WHAT: where the memory-tier ontology (Memory_Tier, Memory_Tier_0..3, UltraMap, Hypercluster) lives now — it MOVED to SOMA's OWL; do NOT design it in CartON. WHEN: you need to find/edit the memory-tier ontology types, or you're tempted to re-add a CartON memory-ontology bootstrap.

WHAT: the actual CartON Neo4j graph schema — the single :Wiki node label, its node properties (name, description, timestamp, etc.), and the relationship types CartON uses to connect concepts. WHEN: when you need to understand how CartON stores and relates concepts in Neo4j, write a Cypher query against the graph, or check which node properties and relationship types are available.

WHAT: how to program TreeShell navigation options via CartON HAS_OPTION relationships — each HAS_OPTION target becomes a navigable, just-in-time-resolvable child node, so the CartON graph is the surface where you program a TreeShell menu's children. WHEN: when you want to create menu structure in TreeShell by programming CartON relationships, control exactly which children a TreeShell node shows, or use HAS_OPTION to add navigable options to a node.

WHAT: why CartON relationships are NOT immediately queryable right after add_concept — the node is created instantly but its relationships go through the daemon unwind, so Neo4j traversal queries against the just-created concept come back empty; query from already-committed parent concepts instead. WHEN: any time you query Neo4j right after writing a concept, a relationship you just added is missing from a traversal, or you are debugging timing of when graph data becomes available after a write.

WHAT: the implementation pattern for making CartON the source of truth for TreeShell node definitions — embed the raw node dict as a JSON marker in the concept description during sync (node_sync.py), so TreeShell nodes persist to and load from the CartON graph. WHEN: when implementing or changing CartON as the source of truth for TreeShell nodes, embedding a node definition as JSON in a concept description, or wiring TreeShell node loading to read from CartON.

WHAT: which CartON relationship types map to TreeShell navigable children — how to structure a concept with HAS_PART / HAS_COMPONENT / HAS_FEATURE / HAS_DELIVERABLE / HAS_TASK relationships so it renders as a navigable TreeShell node with children via just-in-time loading. WHEN: when you want CartON concepts to appear as TreeShell menus with options, choosing which relationship types make a concept's children navigable, or structuring a concept so it renders as a full TreeShell node.

WHAT: the architecture where persistent agent memory files (MEMORY.md and other memory artifacts) are auto-generated VIEWS projected from the CartON knowledge graph, with CartON as the single source of truth — you never hand-edit the memory file, you change the graph and recompile. WHEN: when designing or improving how the agent's persistent memory works across sessions, deciding where memory should be stored, or wondering why MEMORY.md should not be edited directly.

WHAT: the existing TreeShell-to-CartON integration in heaven-tree-repl — how node_sync.py, learnings.py, and renderer.py form the bridge between TreeShell navigation and the CartON knowledge graph (fire-and-forget sync to CartON on render). WHEN: when building or extending the CartON-backed TreeShell, figuring out what already exists versus what still needs building, or working on node sync / rendering between TreeShell and CartON.

WHAT: the three CartON observation queue file formats and when to use each one (raw_concept flat format, observation format, batch format) for files written to the carton_queue directory that the observation worker daemon processes. WHEN: when writing or generating files into carton_queue/ from a hook or script, choosing a queue file format, or debugging why queued observations land in the failed/ folder.

WHAT: CartON's server-side payload stashing — on a failed/exception add_concept the partial payload is stashed so a retry merges new fields without re-typing everything. WHEN: an add_concept errors and you want to re-send only the missing fields, or you're reasoning about the stash/clear_stash params.

WHAT: the bidirectional population pattern between the CartON knowledge graph and TreeShell navigation nodes — how a NODE_DEF embedded in a CartON concept description and the family JSON configs resolve into a TreeShell node, in both directions. WHEN: when customizing TreeShell nodes, understanding how TreeShell configs resolve from JSON versus a CartON override, or building a mental model of how CartON concepts become navigable TreeShell nodes.