space

Space

The canonical reference for working with a Huabu Space. This file covers the read side: the on-disk layout and the tools that turn it into structured data. Mutation is gated behind a separate tool (space_commands) and a separate reference file — see the Mutating a Space section below.

Schemas are the source of truth. This skill explains semantics and idioms. Field names, types, and required parameters live on the corresponding tool / command schema. When in doubt about a field, trust the schema.

---

A Space has two surfaces

A Space exposes two complementary surfaces, each owned by its own family of tools. Pick the family by what you want to know, not by which tool feels familiar.

Surface A — A folder of text files

Node text, frontmatter, skill files, memory, history. Read with read, find, ls, grep.

<Space>/
  nodes/
    <safeLabel>.md         # one file per node: YAML frontmatter + Markdown body
  memory/*.md              # long-form, agent-curated memory
  skills/<id>/SKILL.md     # per-Space skill overrides (optional)
  .artifacts/<id><ext>     # raw bytes (image / pdf / video / cover); `read` returns images inline, rejects pdf / video
  .history/                # saved threads, event log (rarely needed)

A node's filename is deterministically derived from its label and kept in 1:1 sync, so when you have the label you can build the path yourself:

nodes/<safeLabel>.md

safeLabel = the label with characters \ / : * ? " < > | (and ASCII control chars) replaced by _. Spaces, hyphens, parentheses, dots, and any other character are kept verbatim — do not substitute them. Only leading/trailing dots and spaces are stripped, and the result is truncated to 120 chars. Empty / missing labels fall back to the stable nodeId.

Examples:

label	safeLabel	path
Dolphin Migration	Dolphin Migration	nodes/Dolphin Migration.md
Notes (draft)	Notes (draft)	nodes/Notes (draft).md
Foo: Bar / Baz	Foo_ Bar _ Baz	nodes/Foo_ Bar _ Baz.md
trailing.	trailing	nodes/trailing.md

• Have the label → read("nodes/<safeLabel>.md") directly. Don't find first when you already have the label — build the path.
• Have only the nodeId → find("nodes/*.md") or grep (results carry nodeId, label, nodeType); the stable id also lives in each file's id: frontmatter.
• A direct read returns ENOENT (rare — usually means the label was just edited mid-flight) → fall back to find / grep.

Surface B — Layout & connectivity data (space.json)

Where each node sits, how big it is, which frame it belongs to, what colour it's painted; every edge's endpoints and style. Stored as one space.json per Space, served through get_space_outline, inspect_nodes, inspect_edges. These tools also expose derived fields you can't read off disk — distance, direction, hops, clusterId, arrangement — computed on the fly from the same data, which is why you should query through them rather than read("space.json") and parse it yourself.

Boundary rule of thumb

Property	Tool
label, content, summary, keywords, src	read / grep
position, size, parentFrame, visual style	inspect_nodes
edge direction / lineStyle / stroke	inspect_edges
whole-Space overview, spatial clusters	get_space_outline

Tool decision matrix

Question	Tool
"Give me the lay of the land"	get_space_outline()
"What does this node say?"	read("nodes/<safeLabel>.md")
"Where is this node? How big? In which frame?"	inspect_nodes({ ids: ["<id>"] })
"What's near this node?"	inspect_nodes({ nearNode: { id } })
"What connects to this node?"	inspect_nodes({ connectedTo: { id } })
"What does that edge look like?"	inspect_edges({ ids: ["<edgeId>"] })
"Which nodes mention 'gradient descent'?"	grep
"List all PDFs"	find("**/*.pdf") or inspect_nodes({ byType: "pdf" })
"Load a deeper Space reference"	read("skills/space/references/<name>.md")

Gotchas

Behaviour the schema can't convey:

• ** Selection & Position Geometry (CRITICAL):** The selected-node / anchor context DOES NOT directly contain position, size, parent frame, or geometry coordinates. If you need to place a new node near, relative to, or offset from a selected or anchor node, you MUST first call inspect_nodes({ ids: ["<anchorId>"] }) (or get_space_outline) to query its geometry.
• Coordinates — idioms. Each node carries two coordinate fields (defined on the inspect_nodes / space_commands schemas): writable parent-local position and read-only world absolutePosition. Practical placement: to put a child next to a sibling in the same frame, add an offset to the sibling's position; to place a root node near some reference, use the reference's absolutePosition (root-local == world); to align a framed child to something outside its frame, submit target.absolutePosition − thisFrame.absolutePosition. Into a column/row/grid (structured) frame, position is only a sort hint — the frame owns the final slot. In grid mode position does not decide rows either: pass cells on SET_FRAME_LAYOUT to place children, giving paired children the same row.
• Nodes in context are metadata only. Pass a node's supplied file path straight to read for the body. Only when a node is mentioned outside your context (e.g. it appears in a Space snapshot but wasn't shown as a <node>) do you build the path yourself via the safeLabel rule above. For spatial / structural info (including position), call inspect_nodes({ ids: ["<id>"] }).
• Cross-Space reads are World-only. Tools default to the conversation's Space. In a World conversation, first read the World outline, take targetCanvasId from a canonical spacePreview, then pass it to get_space_outline, inspect_nodes, inspect_edges, read, grep, find, or ls. The target must be a live ordinary Space addressed by exactly one canonical preview. snapshot_nodes remains owner-scoped because it materializes cache artifacts; use read with targetCanvasId to view source images inline. This never grants cross-Space writes; space_commands remains World-scoped.
• read returns image artifacts inline as vision content: pass an image node's frontmatter src straight to read, OR — for an inline ![](<key>) image embedded in a note body — call read(".artifacts/<key>") to see it. PDF / video bytes still live under .artifacts/ but are not readable — their src URL is the only handle.
• Before placing new nodes, anchor on the selection / a referenced node / a focal cluster — never pick coordinates from the global bbox alone, or new nodes land outside the user's viewport. If setting size, inspect and match comparable nearby nodes; with no comparable peer, omit it and use the canonical default. See layout-recipes.md for long-Note and per-type sizing rules.

---

Mutating a Space

The filesystem tools (read, find, ls, grep) are read-only — there is no write / edit_file / rm. Every mutation flows through one tool: space_commands.

• If space_commands is not in your available tool list → you are in read-only mode. Do not attempt mutations and do not claim in your reply that you performed any.
• If space_commands is available → the tool's own schema and description carry the full command set, the id / dependency-ordering rule, and per-field behaviour. For composed multi-command recipes see command-cookbook.md; for diagram geometry see layout-recipes.md.
• Commands are not guaranteed to succeed. Each command in a call reports its own outcome in results[]; on failure it carries a reason (e.g. invalid-target when a CONNECT / SET_NODE_PARENT endpoint doesn't exist). Read it and adjust — don't assume a write landed.

---

Deeper dives

Load on demand when the situation calls for it:

• read("skills/space/references/command-cookbook.md") — composed batch patterns: brainstorm, merge / synthesize, group into a frame, restyle a cluster, tidy a row, …
• read("skills/space/references/layout-recipes.md") — coordinate system, hierarchical / left-to-right / grid layouts, frames (including when to pick the row-aligned grid frame mode over column), and the row-track flowchart / roadmap recipe.