Structured collections: ordered folders, decision records and the graph edges between them, assembled into a readable whole.
Build the transitive closure of a bundle subtree: all (ancestor, descendant, depth) pairs reachable via 'contains' edges from rootKey. Includes depth-0 self rows. Useful for reachability queries and DAG validation.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rootKey | string | Required | The node_key of the bundle root |
Create a new OKF bundle (root node + backing metadata memory). The root is a D1 node with a mem_id pointing at a metadata memory tagged 'bundle-meta'. Returns the rootKey and metaMemId. Fails if slug already in use as a bundle node for this user.
| Parameter | Type | Required | Description |
|---|---|---|---|
| slug | string | Required | Unique slug for this bundle root (e.g. 'my-book'). Lowercase letters, digits and hyphens only, max 64. Frozen at creation. |
| title | string | Required | Human-readable bundle title |
| description | string | default "" | High-level description or thesis |
| okf_type | string | default "bundle" | OKF type for the root node (default 'bundle') |
| project | string | — | Project slug to scope the backing metadata memory. Omit for global. |
Record a structural decision and attach it, in one call, as a reference leaf to the bundle node it governs — so the 'why this is here / why this title / why this order' renders WITH the thing and the next session can't miss it. Mints a memory tagged 'decision' (okfType 'decision') with a structured body {question, chosen, rejected[], reason, decided_by, date} and wires it under the node as a 'reference' child. Use this for placement/title/ordering calls made in chat that would otherwise be lost and re-litigated.
| Parameter | Type | Required | Description |
|---|---|---|---|
| nodeKey | string | Required | node_key of the node this decision governs (the chapter/section/leaf it explains) |
| question | string | Required | The decision being recorded, e.g. 'Prologue vs epilogue for the cultivation series?' |
| chosen | string | Required | What was decided, e.g. 'Prologue — opens the book' |
| reason | string | Required | Why this was chosen |
| rejected | string[] | default [] | Alternatives considered and rejected |
| decided_by | string | — | Who decided (e.g. 'Boy'). Omit if not attributed. |
| date | string | — | ISO date the decision was made. Defaults to now. |
| slug | string | default "decision" | Slug for the decision leaf among the node's references. Default 'decision'. |
| project | string | — | Project slug to scope the decision memory. Omit for global. |
Add an edge between two bundle nodes (parent→child). relation='contains' (default) sets the child's canonical home; a node can have exactly one canonical parent. relation='reference' adds a non-home link (DAG). Surfaces a clear error if a 'contains' edge would violate the one-canonical-home rule.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | The node_key of the parent node |
| childKey | string | Required | The node_key of the child node |
| position | number | — | Explicit REAL position. If omitted, appended after existing siblings. |
| relation | stringcontains · reference | default "contains" | 'contains' = canonical home (one per node). 'reference' = additional link with no path. |
Move a child to a new position among its siblings using midpoint arithmetic — no sibling renumber ever. Provide beforeKey (sibling that will come BEFORE) and/or afterKey (sibling that will come AFTER). Pass null for beforeKey to move to front; null for afterKey to move to end; both null to append at end.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | The node_key of the parent |
| childKey | string | Required | The node_key of the child to reposition |
| beforeKey | string | default null | Sibling node_key that will come BEFORE the moved child, or null for 'move to front' |
| afterKey | string | default null | Sibling node_key that will come AFTER the moved child, or null for 'move to end' |
Remove an edge between two bundle nodes. Does NOT delete the nodes — only the structural link. After removal the child becomes a root if it had no other 'contains' parent.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | The node_key of the parent |
| childKey | string | Required | The node_key of the child to unlink |
Export a bundle as an OKF v0.1 bundle object. Returns concepts (memory-backed nodes in DFS order) and a generated index.md table-of-contents. For the full render including ASCII tree or markdown, use muninn_render_bundle.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rootKey | string | Required | The node_key of the bundle root to export |
Retrieve a bundle by its root node key. Returns the root node and its direct children edges. Pass resolve:true to also fetch child node details and (if memory-backed) a preview of the backing memory.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rootKey | string | Required | The node_key of the bundle root |
| resolve | boolean | default false | If true, hydrate child node details (slug, okf_type, mem_id preview) |
List bundle roots owned by the current user. A root is any node with no 'contains' parent. Optionally filter by project (matches the backing metadata memory's project scope).
| Parameter | Type | Required | Description |
|---|---|---|---|
| project | string | — | Filter roots whose backing metadata memory is scoped to this project. Omit to list all roots. |
Create a bundle node that points at an EXISTING memory and attach it under a parent — in one call. Use this to wrap content that already lives in a memory (e.g. a verbatim body, a chapter record) as a structural leaf so it shows up IN the bundle, not just tag-findable. bundle_create makes a NEW meta memory (for a folder/bundle root); this is for attaching real content you've already written. Set okfType to the leaf type ('text' for full body, 'record' for a chapter record, 'package'/'quotes'). relation defaults to 'contains' (the node's canonical home). Fails if the slug is taken or the parent/memory is missing.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | node_key of the parent to attach under |
| slug | string | Required | Unique slug for the new node (e.g. 'text'). Lowercased, frozen at creation. |
| memId | string | Required | ID of the EXISTING memory this node points at (its mem_id). |
| okfType | string | default "text" | OKF leaf type: 'text' (full body), 'record' (chapter record), 'package', 'quotes'. Default 'text'. |
| position | number | — | Explicit REAL position among siblings. Omit to append. |
| relation | stringcontains · reference | default "contains" | 'contains' = canonical home (one per node). 'reference' = additional DAG link. |
Hard-delete a bundle node and ALL edges touching it (as parent and child, contains + reference). For clearing orphan stubs and structure cleanup. Refuses a node that still has contains-children unless cascade=true (then deletes the whole subtree depth-first). NEVER deletes a content/record memory. Only when deleteBackingMeta=true AND the backing memory is tagged 'bundle-meta' AND no other node references it is the meta memory deleted; otherwise the memory is kept. dryRun=true (default) reports without writing.
| Parameter | Type | Required | Description |
|---|---|---|---|
| nodeKey | string | Required | node_key of the node to delete |
| cascade | boolean | default false | If true, delete the whole contains-subtree. Required to delete a node that has children. |
| deleteBackingMeta | boolean | default false | If true, also delete the backing memory IF it is a 'bundle-meta' memory with no other referencing node. Never deletes content memories. |
| dryRun | boolean | default true | If true (default), report what would be deleted without committing. |
Repoint an existing bundle node at a DIFFERENT backing memory WITHOUT delete+recreate. node_key, every edge, position, and all children (text/package/quotes leaves) are preserved — only the node's mem_id changes (and its denormalized okf_type/status, re-derived from the new memory). Use this when a record node should point at a replacement memory; the old path (edge_remove + node_delete + node_create) destroyed the node's children. newMemId may be a full or short-form (8-char) prefix.
| Parameter | Type | Required | Description |
|---|---|---|---|
| nodeKey | string | Required | node_key of the node to repoint |
| newMemId | string | Required | ID (full or 8-char prefix) of the memory the node should now point at |
Rename a bundle node's slug in place. The slug is normally frozen, but this is the sanctioned on-demand rename: node_key, every contains/reference edge, position, memId and okf_type are preserved exactly. Render (md/tree) stays byte-identical because headings come from the backing memory, not the slug — only OKF/MOKF filenames derived from the slug change. Fails if the new slug is already used by another node. dryRun=true (default) reports the change without writing.
| Parameter | Type | Required | Description |
|---|---|---|---|
| nodeKey | string | Required | node_key of the node to reslug (any node, not just a root) |
| newSlug | string | Required | The new slug. Lowercased. Lowercase letters, digits and hyphens only, max 64; 'memories', 'index' and 'manifest' are reserved. Must be unique among your bundle nodes. |
| dryRun | boolean | default true | If true (default), report what would change without committing. |
Bulk-attach MANY existing memories as children under ONE parent in a single call (vs one bundle_node_create per child). All-or-nothing: the batch is validated first (parent exists; each slug is free among siblings AND unique within the batch), then applied; any collision aborts the whole batch and names the offender, and a mid-apply failure rolls back every child created in this call. memIds may be full or short-form (8-char) prefixes. Use this to wire a chapter's leaves, or a whole series of sections, at once.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | node_key of the parent to attach all children under |
| children | object[] | Required | The children to attach, in order |
Detach multiple child nodes from a parent in one call. Removes only the structural edge — does NOT delete the child nodes or their backing memories. Inverse of muninn_bundle_nodes_create. Returns the count of edges removed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| parentKey | string | Required | node_key of the parent to detach from |
| childKeys | string[] | Required | node_keys of children to detach |
Update a bundle root's title and/or description. Updates the backing metadata memory and re-embeds it. The slug (the node's frozen path segment) is never changed here.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rootKey | string | Required | The node_key of the bundle root to update |
| title | string | — | New title |
| description | string | — | New description |
Render a bundle rooted at rootKey. format='md' produces document-markdown (the OKF render). format='tree' produces an ASCII slug tree. format='okf' returns the OKF v0.1 bundle as JSON. (tree only) show_keys appends node_key + memId to each line so you can act surgically (reslug/repoint/delete) from one call.
| Parameter | Type | Required | Description |
|---|---|---|---|
| rootKey | string | Required | The node_key of the bundle root |
| format | stringmd · tree · okf | default "md" | Output format: 'md' (markdown), 'tree' (ASCII), 'okf' (OKF v0.1 JSON) |
| include_descriptions | boolean | default true | (md only) Emit bundle and folder descriptions |
| child_separator | string | default "\n\n---\n\n" | (md only) Separator between children |
| section_heading_level | integer | default 2 | (md only) Heading level for section/folder nodes |
| child_heading_level | integer | default 3 | (md only) Heading level for memory-backed nodes |
| show_ids | boolean | default false | (md only) Append the memory ID to each heading |
| show_keys | boolean | default false | (tree only) Append [node_key=… memId=…] to each line so one tree call is enough to reslug/repoint/delete without a separate bundle_get. |