memuron 0.1.1__py3-none-any.whl

memuron/graphfs/manual.py

@@ -0,0 +1,635 @@
+"""Self-describing manual for the Memuron graph filesystem query language."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+COMMAND_GROUPS: dict[str, list[str]] = {
+    "discover": ["help", "ls", "pwd", "cd", "tree"],
+    "search": ["find", "rg", "grep", "semantic", "related"],
+    "graph": [
+        "graph",
+        "neighbors",
+        "neighborhood",
+        "links",
+        "parents",
+        "children",
+        "hubs",
+        "path",
+        "traverse",
+        "why",
+    ],
+    "transform": ["where", "sort", "head", "limit", "select", "wc"],
+    "inspect": ["cat", "stat", "explain"],
+}
+
+COMMANDS: dict[str, dict[str, Any]] = {
+    "ls": {
+        "summary": "List spaces, root entries, or collection members at the current cwd.",
+        "syntax": "ls [--collections-only] [--floating-only]",
+        "input": "Starts a pipeline. Ignores no prior stream.",
+        "output": "Spaces at /spaces; otherwise node entries visible at cwd.",
+        "flags": {
+            "--collections-only": "Return collections only.",
+            "--floating-only": "Return unplaced root nodes only.",
+        },
+        "examples": ["ls", "ls --collections-only", "ls | sort degree desc | limit 20"],
+    },
+    "find": {
+        "summary": "Structurally select nodes using indexed fields.",
+        "syntax": "find [--type TYPE] [--encoding ENCODING] [--id ID] [--name TEXT] [--floating]",
+        "input": "Starts a pipeline or filters its incoming node stream.",
+        "output": "Matching nodes.",
+        "flags": {
+            "--type": "Canonical structural type: text, document, image, or collection.",
+            "--encoding": "Exact encoding such as memory or document_chunk.",
+            "--id": "Exact node id.",
+            "--name": "Case-insensitive display-name substring; * is accepted.",
+            "--floating": "Only nodes not placed in a collection.",
+        },
+        "examples": [
+            "find --type text",
+            "find --encoding document_chunk | limit 10",
+            'find --name "architecture"',
+        ],
+    },
+    "grep": {
+        "summary": "Search node content with a case-insensitive regex, or fixed text with --literal.",
+        "syntax": 'grep [--literal] "PATTERN" [--limit N]',
+        "input": "Starts a pipeline or searches only nodes from the incoming stream.",
+        "output": "Matching nodes ordered by the projection search.",
+        "flags": {
+            "--literal": "Treat PATTERN as fixed text instead of a regular expression.",
+            "--limit": "Maximum search hits, from 1 to 100. Default: 100.",
+        },
+        "notes": [
+            "Regex matching is case-insensitive by default.",
+            "`disco*` matches `disc` followed by zero or more `o` characters; use `disc.*` for any suffix.",
+        ],
+        "examples": [
+            'grep "authentication"',
+            'grep "new" | grep "disco*"',
+            'grep "disc.*" --limit 20',
+            'grep --literal "data[0]"',
+            'find --type text | grep "authorization"',
+        ],
+    },
+    "rg": {
+        "summary": "Ripgrep-style regex search with smart-case defaults and familiar flags.",
+        "syntax": 'rg [-i|-s|-S] [-F] [-v] [-m N] "PATTERN"',
+        "input": "Starts a pipeline or searches only nodes from the incoming stream.",
+        "output": "Matching nodes with score=1.0.",
+        "flags": {
+            "-i, --ignore-case": "Always case-insensitive.",
+            "-s, --case-sensitive": "Always case-sensitive.",
+            "-S, --smart-case": "Case-sensitive only when PATTERN contains uppercase; this is the default.",
+            "-F, --fixed-strings": "Treat PATTERN as literal text.",
+            "-v, --invert-match": "Return nodes that do not match.",
+            "-m, --max-count": "Maximum results from 1 to 100.",
+        },
+        "examples": [
+            'rg "discov.*"',
+            'rg -i "Discovery" -m 20',
+            'rg -F "data[0]"',
+            'find --type text | rg -v "deprecated"',
+        ],
+    },
+    "semantic": {
+        "summary": "Retrieve memories by semantic meaning in the current space.",
+        "syntax": 'semantic "NATURAL LANGUAGE QUERY" [--limit N] [--links]',
+        "input": "Starts a pipeline, or reranks only incoming nodes.",
+        "output": "Memory nodes with semantic score and match=semantic.",
+        "flags": {
+            "--limit": "Maximum memory results from 1 to 100. Default: 10.",
+            "--links": "Allow relationship descriptions to participate in retrieval.",
+        },
+        "cost": "Embedding-backed; usually slower than rg.",
+        "examples": [
+            'semantic "decisions about deployment reliability"',
+            'find --type text | semantic "authentication risks" --limit 5',
+        ],
+    },
+    "related": {
+        "summary": "Find memories semantically related to incoming seed nodes.",
+        "syntax": "related [--limit N]",
+        "input": "Requires one or more incoming memory nodes.",
+        "output": "Semantically related nodes, excluding the seeds.",
+        "cost": "Embedding-backed.",
+        "examples": [
+            'rg "Guardian" | head 1 | related --limit 10',
+            "find --id NODE_ID | related",
+        ],
+    },
+    "neighbors": {
+        "summary": "Expand incoming nodes through semantic and placement edges.",
+        "syntax": "neighbors [--depth N] [--direction both|inbound|outbound] [--include-self]",
+        "input": "Uses incoming nodes; without input it uses the current ls entries.",
+        "output": "Neighbor nodes. Depth is clamped to 1..5.",
+        "flags": {
+            "--depth": "Traversal depth from 1 to 5. Default: 2.",
+            "--direction": "both, inbound, or outbound.",
+            "--inbound": "Shortcut for --direction inbound.",
+            "--outbound": "Shortcut for --direction outbound.",
+            "--include-self": "Keep seed nodes in the result.",
+            "--placements": "Include collection placement edges; already enabled for neighbors.",
+        },
+        "examples": [
+            'grep "authentication" | neighbors --depth 1',
+            "find --id artha_123 | neighbors --direction outbound --include-self",
+        ],
+    },
+    "neighborhood": {
+        "summary": "Alias for neighbors, matching the graph API terminology.",
+        "syntax": "neighborhood [--depth N] [--direction both|inbound|outbound] [--include-self]",
+        "input": "Uses incoming nodes; without input it uses current ls entries.",
+        "output": "The bounded N-hop graph neighborhood.",
+        "flags": {
+            "--depth": "Traversal depth from 1 to 5. Default: 2.",
+            "--direction": "both, inbound, or outbound.",
+            "--include-self": "Keep seed nodes in the result.",
+        },
+        "examples": [
+            'semantic "authentication" | head 1 | neighborhood --depth 2',
+            "find --id NODE_ID | neighborhood --include-self",
+        ],
+    },
+    "links": {
+        "summary": "Follow graph links from incoming or current nodes.",
+        "syntax": "links [--depth N] [--direction both|inbound|outbound] [--placements] [--include-self]",
+        "input": "Uses incoming nodes; without input it uses the current ls entries.",
+        "output": "Linked nodes.",
+        "flags": {
+            "--depth": "Traversal depth from 1 to 5. Default: 1.",
+            "--direction": "both, inbound, or outbound.",
+            "--inbound": "Shortcut for --direction inbound.",
+            "--outbound": "Shortcut for --direction outbound.",
+            "--placements": "Also traverse collection placement edges.",
+            "--include-self": "Keep seed nodes in the result.",
+        },
+        "examples": ["find --id artha_123 | links", "links --placements --depth 2"],
+    },
+    "parents": {
+        "summary": "Return structural parents of incoming nodes.",
+        "syntax": "parents [--all]",
+        "input": "Uses incoming nodes; without input it uses current ls entries.",
+        "output": "Parent collection nodes. --all also considers semantic inbound edges.",
+        "examples": ["find --id NODE_ID | parents", 'rg "chunk text" | parents'],
+    },
+    "children": {
+        "summary": "Return structural children of incoming collection nodes.",
+        "syntax": "children [--all]",
+        "input": "Uses incoming nodes; without input it uses current ls entries.",
+        "output": "Placed child nodes. --all also considers semantic outbound edges.",
+        "examples": ["find --id COLLECTION_ID | children", "ls --collections-only | children"],
+    },
+    "hubs": {
+        "summary": "Return the highest-degree nodes in the current or incoming stream.",
+        "syntax": "hubs [--limit N]",
+        "input": "Starts from all nodes in the space or ranks incoming nodes.",
+        "output": "Nodes ordered by projected graph degree.",
+        "examples": ["hubs", "find --type text | hubs --limit 20"],
+    },
+    "path": {
+        "summary": "Find the shortest projected graph path between two nodes.",
+        "syntax": "path FROM_ID TO_ID | INPUT_ONE_NODE | path TO_ID",
+        "input": "Two ids, or exactly one incoming node plus a destination id.",
+        "output": "Ordered path nodes with path_index, path_length, and edge reason in via.",
+        "examples": ["path NODE_A NODE_B", "find --id NODE_A | path NODE_B"],
+    },
+    "traverse": {
+        "summary": "Follow graph edges whose descriptions semantically match a query.",
+        "syntax": 'traverse "EDGE QUERY" [--depth N] [--threshold 0..1]',
+        "input": "Requires exactly one incoming seed node.",
+        "output": "Visited nodes with hop_distance and edge similarity score.",
+        "cost": "Embedding-backed graph traversal.",
+        "examples": [
+            'find --id NODE_ID | traverse "deployment consequences"',
+            'semantic "Guardian" | head 1 | traverse "design decisions" --depth 2',
+        ],
+    },
+    "why": {
+        "summary": "Explain the direct projected relationship between two nodes.",
+        "syntax": "why OTHER_NODE_ID",
+        "input": "Requires exactly one incoming source node.",
+        "output": "Placement or semantic edge descriptions; suggests path when no direct edge exists.",
+        "examples": ["find --id NODE_A | why NODE_B", "path NODE_A NODE_B | head 1 | why NODE_B"],
+    },
+    "tree": {
+        "summary": "Show the bounded collection and placement hierarchy.",
+        "syntax": "tree [--depth N]",
+        "input": "Starts a pipeline using cwd as the root.",
+        "output": "Flattened tree nodes with tree_depth and tree_prefix.",
+        "examples": ["tree", "tree --depth 5 | select tree_depth,type,display,id"],
+    },
+    "graph": {
+        "summary": "Export a bounded node-and-edge graph payload from the current space.",
+        "syntax": "graph [--limit N]",
+        "input": "Starts a pipeline and uses the current space.",
+        "output": "One graph item containing nodes, internal edges, and counts.",
+        "notes": [
+            "Use select/tree/neighborhood for smaller agent-facing responses when full topology is unnecessary.",
+            "The related graph commands below cover every graph API operation.",
+        ],
+        "commands": [
+            "graph",
+            "neighborhood",
+            "neighbors",
+            "links",
+            "parents",
+            "children",
+            "hubs",
+            "path",
+            "why",
+            "traverse",
+            "tree",
+        ],
+        "examples": ["graph --limit 100", "graph --limit 25 | select node_count,edge_count"],
+    },
+    "where": {
+        "summary": "Filter an incoming stream using a field comparison.",
+        "syntax": "where FIELD OPERATOR VALUE",
+        "input": "Uses incoming nodes; without input it uses the current ls entries.",
+        "output": "Nodes satisfying the comparison.",
+        "fields": ["degree", "display", "encoding", "type"],
+        "operators": ["=", "==", "!=", ">", ">=", "<", "<=", "~"],
+        "notes": ["Use ~ for case-insensitive text containment.", "Numeric operators are intended for degree."],
+        "examples": ["ls | where degree > 5", 'find --type text | where display ~ "policy"'],
+    },
+    "sort": {
+        "summary": "Sort a node stream by a supported field.",
+        "syntax": "sort FIELD [asc|desc]",
+        "input": "Uses incoming nodes; without input it uses the current ls entries.",
+        "output": "The same nodes in sorted order.",
+        "fields": ["degree", "display", "encoding", "id", "type", "score"],
+        "examples": ["ls | sort degree desc", "find --type text | sort display asc"],
+    },
+    "limit": {
+        "summary": "Keep the first N items from a stream.",
+        "syntax": "limit N",
+        "input": "Uses incoming nodes; without input it uses the current ls entries.",
+        "output": "At most N items. N must be from 0 to 1000.",
+        "examples": ["ls | limit 20", 'grep "policy" | limit 5'],
+    },
+    "head": {
+        "summary": "Keep the first N items; familiar alias for limit.",
+        "syntax": "head N",
+        "input": "Uses incoming nodes; without input it uses current ls entries.",
+        "output": "At most N items.",
+        "examples": ["ls | head 20", 'semantic "policy" | head 5'],
+    },
+    "select": {
+        "summary": "Project only selected fields to reduce agent context usage.",
+        "syntax": "select FIELD[,FIELD...]",
+        "input": "Uses incoming items; without input it uses current ls entries.",
+        "output": "Items containing exactly the selected fields.",
+        "examples": [
+            "ls | select id,type,display",
+            'semantic "policy" | select id,preview,score',
+        ],
+    },
+    "wc": {
+        "summary": "Summarize stream size and content volume.",
+        "syntax": "wc [--tokens]",
+        "input": "Uses incoming items; without input it uses current ls entries.",
+        "output": "One aggregate with items, nodes, characters, words, and bytes.",
+        "flags": {"--tokens": "Also include a rough character-based token estimate."},
+        "examples": ['rg "policy" | wc --tokens', "find --encoding document_chunk | wc"],
+    },
+    "explain": {
+        "summary": "Inspect a pipeline execution plan without running it.",
+        "syntax": 'explain "PIPELINE"',
+        "input": "Standalone only. Quote the whole pipeline.",
+        "output": "Stages, execution backend, and relative estimated cost.",
+        "examples": [
+            'explain "rg policy | neighbors --depth 2 | head 10"',
+            'explain "semantic deployment | related --limit 5"',
+        ],
+    },
+    "cat": {
+        "summary": "Return complete node content.",
+        "syntax": "cat NODE_ID",
+        "input": "A node id, or incoming nodes when NODE_ID is omitted.",
+        "output": "Nodes with view=content.",
+        "examples": ["cat artha_123", 'grep "decision" | limit 1 | cat'],
+    },
+    "stat": {
+        "summary": "Return node metadata, placements, and semantic links.",
+        "syntax": "stat NODE_ID",
+        "input": "A node id, or incoming nodes when NODE_ID is omitted.",
+        "output": "Nodes with view=stat, placements, and semantic_links.",
+        "examples": ["stat artha_123", "find --id artha_123 | stat"],
+    },
+    "cd": {
+        "summary": "Resolve a new cwd. The client must use navigation.cwd on its next request.",
+        "syntax": "cd DESTINATION",
+        "input": "Standalone only.",
+        "output": "A navigation object; it does not mutate server-side session state.",
+        "destinations": [
+            "/spaces",
+            "space.personal",
+            "/spaces/space.personal/collections/COLLECTION_ID",
+            "COLLECTION_ID",
+            "@NODE_ID",
+            "..",
+        ],
+        "examples": ["cd space.personal", "cd artha_collection_id", "cd @artha_node_id", "cd .."],
+    },
+    "pwd": {
+        "summary": "Return the cwd supplied with this request.",
+        "syntax": "pwd",
+        "input": "Standalone only.",
+        "output": "One cwd item.",
+        "examples": ["pwd"],
+    },
+    "help": {
+        "summary": "Read this manual or one focused topic.",
+        "syntax": "help [overview|commands|search|graph|compact|pipelines|paths|errors|examples|COMMAND]",
+        "input": "Standalone only.",
+        "output": "Structured help items.",
+        "examples": ["help", "help grep", "help pipelines", "help errors"],
+    },
+}
+
+TOPICS: dict[str, dict[str, Any]] = {
+    "overview": {
+        "title": "How to use Memuron graph filesystem queries",
+        "instructions": [
+            "POST one query string and one cwd to /memuron/spaces/query.",
+            "Begin at cwd=/spaces with query=ls to discover spaces.",
+            "Use the returned space path as cwd, then run ls, find, or grep.",
+            "Chain commands with |. Each stage receives the previous stage's node stream.",
+            "Use ids returned by commands with cat, stat, cd, links, and find --id.",
+            "cd is declarative: copy navigation.cwd into the next request's cwd.",
+            "Use `type` for the structural node category. node_type is deprecated.",
+            "Use `encoding` for subtype or origin, for example memory or document_chunk.",
+            "When a query fails, follow detail.hint and detail.examples; use detail.help_query for more.",
+            "Use `help search` for retrieval, `help graph` for graph operations, and `help compact` to reduce output tokens.",
+        ],
+        "field_glossary": {
+            "type": "Canonical structural category: text, image, document, or collection.",
+            "node_type": "Deprecated alias for type; present only for compatibility.",
+            "encoding": "Subtype/origin such as memory, document_chunk, document_collection, pdf_source, image_vlm.",
+            "degree": "Total projected graph connectivity in the current space, including placement and semantic edges.",
+            "preview": "Short content preview. Use cat for full content.",
+            "content_length": "Full content length in characters.",
+            "truncated": "Whether preview/display omits some content.",
+        },
+        "first_requests": [
+            {"cwd": "/spaces", "query": "ls"},
+            {"cwd": "/spaces/space.personal", "query": "ls"},
+            {"cwd": "/spaces/space.personal", "query": 'grep "topic" | limit 10'},
+        ],
+    },
+    "search": {
+        "title": "Lexical and semantic retrieval",
+        "instructions": [
+            "Use rg for regex or fixed-text content search with ripgrep-style smart case.",
+            "Use semantic when wording may differ but meaning is similar.",
+            "Use related after obtaining seed nodes to retrieve conceptually similar memories.",
+            "Use grep when you specifically want always-case-insensitive regex behavior.",
+            "Filter structurally with find before searching when type or encoding is known.",
+        ],
+        "decision_guide": {
+            "exact_or_pattern": "rg",
+            "literal_special_characters": "rg -F",
+            "meaning_or_concept": "semantic",
+            "similar_to_known_memory": "related",
+        },
+        "examples": [
+            'rg "deploy.*fail" | select id,preview',
+            'semantic "why production deployments failed" --limit 10',
+            'semantic "Guardian architecture" | head 1 | related --limit 10',
+        ],
+    },
+    "graph": {
+        "title": "Graph operations",
+        "instructions": [
+            "Use neighbors for bounded N-hop expansion across semantic and placement edges.",
+            "Use links for semantic links only unless --placements is supplied.",
+            "Use parents and children for collection placement direction.",
+            "Use hubs to rank highly connected nodes.",
+            "Use path for shortest paths and why for direct edge explanations.",
+            "Use traverse when edge descriptions should be selected by semantic meaning.",
+            "Use tree for the collection hierarchy.",
+        ],
+        "commands": [
+            "neighbors",
+            "neighborhood",
+            "links",
+            "parents",
+            "children",
+            "hubs",
+            "path",
+            "why",
+            "traverse",
+            "tree",
+            "graph",
+        ],
+        "examples": [
+            'semantic "authentication" | head 1 | neighbors --depth 2',
+            "path NODE_A NODE_B",
+            "find --id NODE_A | why NODE_B",
+            'find --id NODE_A | traverse "decisions caused by this" --depth 2',
+        ],
+    },
+    "compact": {
+        "title": "Reducing response size and measuring context",
+        "instructions": [
+            "Use head or limit to bound item count.",
+            "Use select to return only fields the agent needs.",
+            "Use wc --tokens before cat when a stream may contain large content.",
+            "Prefer preview over content until full text is required.",
+            "Use explain to inspect relative pipeline cost without execution.",
+        ],
+        "examples": [
+            'semantic "deployment" | head 5 | select id,preview,score',
+            'find --encoding document_chunk | wc --tokens',
+            'explain "semantic deployment | neighbors --depth 2 | head 10"',
+        ],
+    },
+    "pipelines": {
+        "title": "Pipeline model",
+        "instructions": [
+            "A pipeline is left-to-right: source | filter | traversal | ordering | limit | view.",
+            "Typical sources are ls, find, rg, grep, semantic, tree, and hubs.",
+            "where, sort, head, limit, select, links, neighbors, parents, children, related, and wc transform streams.",
+            "cat and stat can consume a stream, so `grep \"x\" | limit 1 | cat` is valid.",
+            "cd, pwd, and help must be standalone.",
+            "Quote multi-word values so the parser keeps them together.",
+        ],
+        "examples": [
+            'find --type text | grep "access policy" | neighbors --depth 1 | limit 20',
+            "ls | where degree > 2 | sort degree desc | limit 10",
+            'grep "decision" | limit 1 | stat',
+        ],
+    },
+    "documents": {
+        "title": "Document representation",
+        "instructions": [
+            "Documents are represented as a collection-backed subgraph.",
+            "The root document container has type=collection and encoding=document_collection.",
+            "The original uploaded file is a child node with type=document or type=image and an encoding like pdf_source.",
+            "Chunks are child text nodes with encoding=document_chunk.",
+            "Document containers include payload.collection_kind=document and payload.document with source metadata.",
+        ],
+    },
+    "paths": {
+        "title": "cwd and navigation",
+        "valid_cwds": [
+            "/spaces",
+            "/spaces/SPACE_TOKEN",
+            "/spaces/SPACE_TOKEN/collections/COLLECTION_ID",
+        ],
+        "instructions": [
+            "cwd is explicit request state, not a server-side shell session.",
+            "At /spaces, ls returns available space tokens and paths.",
+            "At a space root, ls returns collections plus floating nodes.",
+            "At a collection cwd, ls returns placed members.",
+            "After cd, use response.navigation.cwd as the next request's cwd.",
+        ],
+    },
+    "errors": {
+        "title": "Error recovery contract",
+        "fields": {
+            "code": "Stable machine-readable category.",
+            "message": "What was wrong.",
+            "hint": "The most likely correction.",
+            "examples": "Known-good replacement queries.",
+            "help_query": "A query that returns the relevant manual section.",
+            "stage": "One-based failing pipeline stage when available.",
+            "command": "Failing command when available.",
+        },
+        "instructions": [
+            "Do not blindly retry the same invalid query.",
+            "Apply hint, preserve the current cwd, and retry a corrected query.",
+            "If uncertain, execute help_query and inspect the structured result.",
+        ],
+    },
+}
+
+WORKED_EXAMPLES = [
+    {
+        "goal": "Discover the system",
+        "steps": [
+            {"cwd": "/spaces", "query": "ls"},
+            {"cwd": "/spaces/SPACE_TOKEN_FROM_RESULT", "query": "ls"},
+        ],
+    },
+    {
+        "goal": "Find relevant memories and inspect context",
+        "steps": [
+            {"cwd": "/spaces/space.personal", "query": 'grep "authentication" | limit 10'},
+            {
+                "cwd": "/spaces/space.personal",
+                "query": 'grep "authentication" | neighbors --depth 1 | limit 20',
+            },
+        ],
+    },
+    {
+        "goal": "Inspect one exact node",
+        "steps": [
+            {"cwd": "/spaces/space.personal", "query": "find --id NODE_ID | stat"},
+            {"cwd": "/spaces/space.personal", "query": "cat NODE_ID"},
+        ],
+    },
+]
+
+
+def filesystem_manual(topic: str | None = None) -> dict[str, Any]:
+    normalized = (topic or "overview").strip().lower()
+    if normalized == "commands":
+        return {
+            "topic": "commands",
+            "title": "Command index",
+            "start_here": [
+                {"topic": "search", "purpose": "Choose lexical, regex, semantic, or related retrieval."},
+                {"topic": "graph", "purpose": "Navigate, export, traverse, and explain graph structure."},
+                {"topic": "compact", "purpose": "Bound output and reduce agent context usage."},
+            ],
+            "groups": deepcopy(COMMAND_GROUPS),
+            "commands": {
+                name: {"summary": spec["summary"], "syntax": spec["syntax"]}
+                for name, spec in COMMANDS.items()
+            },
+        }
+    if normalized == "examples":
+        return {"topic": "examples", "title": "Worked examples", "examples": deepcopy(WORKED_EXAMPLES)}
+    if normalized == "graph":
+        return {
+            "topic": "graph",
+            **deepcopy(TOPICS["graph"]),
+            "export_command": deepcopy(COMMANDS["graph"]),
+        }
+    if normalized in COMMANDS:
+        return {
+            "topic": normalized,
+            "title": f"{normalized} command",
+            "command": normalized,
+            **deepcopy(COMMANDS[normalized]),
+        }
+    if normalized in TOPICS:
+        return {"topic": normalized, **deepcopy(TOPICS[normalized])}
+    raise KeyError(normalized)
+
+
+def manual_topics() -> list[str]:
+    return [
+        "overview",
+        "commands",
+        "search",
+        "graph",
+        "compact",
+        "pipelines",
+        "paths",
+        "documents",
+        "errors",
+        "examples",
+        *COMMANDS,
+    ]
+
+
+def help_items(topic: str | None = None) -> list[dict[str, Any]]:
+    manual = filesystem_manual(topic)
+    if manual["topic"] == "commands":
+        index = {
+            "kind": "help",
+            "display": "Memuron command index",
+            "description": "Start with the search, graph, or compact guide; then inspect focused command help.",
+            "topic": "commands",
+            "manual": manual,
+        }
+        guides = [
+            {
+                "kind": "help",
+                "display": f"help {guide['topic']}",
+                "description": guide["purpose"],
+                "topic": guide["topic"],
+                "manual": filesystem_manual(guide["topic"]),
+            }
+            for guide in manual["start_here"]
+        ]
+        commands = [
+            {
+                "kind": "help",
+                "display": spec["syntax"],
+                "description": spec["summary"],
+                "topic": name,
+                "group": next(
+                    (group for group, names in COMMAND_GROUPS.items() if name in names),
+                    "other",
+                ),
+                "manual": spec,
+            }
+            for name, spec in manual["commands"].items()
+        ]
+        return [index, *guides, *commands]
+    return [
+        {
+            "kind": "help",
+            "display": str(manual["title"]),
+            "description": str(manual.get("summary") or "Structured Memuron query manual."),
+            "topic": manual["topic"],
+            "manual": manual,
+        }
+    ]