memuron 0.1.1__py3-none-any.whl

memuron/graphfs/query.py

@@ -0,0 +1,1782 @@
+"""Command parser and pipeline executor for the Memuron graph filesystem."""
+
+from __future__ import annotations
+
+from difflib import get_close_matches
+import re
+import shlex
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+from artha_engine import ArthaEngine
+
+from memuron.graphfs.manual import COMMANDS, help_items, manual_topics
+from memuron.graphfs.read_model import (
+    containing_collection,
+    expand_neighbors,
+    get_nodes,
+    grep_entries,
+    list_entries,
+    list_root,
+    node_edges,
+    space_edges,
+)
+from memuron.memory.recipes import search_memories, semantic_traverse_graph
+from memuron.security.tenant import org_scope_token
+
+MAX_PIPELINE_STAGES = 12
+MAX_RESULT_ITEMS = 1000
+SUPPORTED_COMMANDS = {
+    "cat",
+    "cd",
+    "children",
+    "explain",
+    "find",
+    "graph",
+    "grep",
+    "help",
+    "head",
+    "hubs",
+    "limit",
+    "links",
+    "ls",
+    "neighbors",
+    "neighborhood",
+    "parents",
+    "path",
+    "pwd",
+    "related",
+    "rg",
+    "select",
+    "semantic",
+    "sort",
+    "stat",
+    "traverse",
+    "tree",
+    "wc",
+    "where",
+    "why",
+}
+
+
+class FsQueryError(ValueError):
+    """Raised for invalid filesystem queries."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "invalid_query",
+        hint: str | None = None,
+        examples: list[str] | None = None,
+        help_query: str = "help errors",
+        stage: int | None = None,
+        command: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.hint = hint or "Run the suggested help query, then submit a corrected query."
+        self.examples = examples or []
+        self.help_query = help_query
+        self.stage = stage
+        self.command = command
+
+    def add_context(self, *, stage: int, command: str) -> "FsQueryError":
+        if self.stage is None:
+            self.stage = stage
+        if self.command is None:
+            self.command = command
+        if self.help_query == "help errors" and command in COMMANDS:
+            self.help_query = f"help {command}"
+        return self
+
+    def detail(self, *, query: str | None = None, cwd: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+            "hint": self.hint,
+            "examples": self.examples,
+            "help_query": self.help_query,
+        }
+        if self.stage is not None:
+            payload["stage"] = self.stage
+        if self.command is not None:
+            payload["command"] = self.command
+        if query is not None:
+            payload["query"] = query
+        if cwd is not None:
+            payload["cwd"] = cwd
+        return payload
+
+
+@dataclass(frozen=True)
+class Command:
+    name: str
+    tokens: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Cwd:
+    space_token: str | None = None
+    collection_id: str | None = None
+
+    @property
+    def path(self) -> str:
+        if not self.space_token:
+            return "/spaces"
+        path = f"/spaces/{self.space_token}"
+        if self.collection_id:
+            path += f"/collections/{self.collection_id}"
+        return path
+
+
+def parse_query(query: str) -> list[Command]:
+    if not query.strip():
+        raise FsQueryError(
+            "Query must not be empty.",
+            code="empty_query",
+            hint="Start with `help` for the manual or `ls` to inspect the current cwd.",
+            examples=["help", "ls"],
+            help_query="help overview",
+        )
+    try:
+        lexer = shlex.shlex(query, posix=True, punctuation_chars="|")
+        lexer.whitespace_split = True
+        lexer.commenters = ""
+        tokens = list(lexer)
+    except ValueError as exc:
+        raise FsQueryError(
+            f"Could not parse the query: {exc}",
+            code="parse_error",
+            hint="Close all quotes and quote multi-word search text.",
+            examples=['grep "authentication policy"', 'find --name "project notes"'],
+            help_query="help pipelines",
+        ) from exc
+
+    stages: list[list[str]] = [[]]
+    for token in tokens:
+        if token == "|":
+            if not stages[-1]:
+                raise FsQueryError(
+                    "Pipeline contains an empty command before `|`.",
+                    code="empty_pipeline_stage",
+                    hint="Put exactly one command between each pipe.",
+                    examples=["ls | limit 10", 'grep "policy" | neighbors --depth 1'],
+                    help_query="help pipelines",
+                )
+            stages.append([])
+        else:
+            stages[-1].append(token)
+    if not stages[-1]:
+        raise FsQueryError(
+            "Pipeline cannot end with `|`.",
+            code="empty_pipeline_stage",
+            hint="Remove the final pipe or add the next command.",
+            examples=["ls | limit 10"],
+            help_query="help pipelines",
+        )
+    if len(stages) > MAX_PIPELINE_STAGES:
+        raise FsQueryError(
+            f"Pipeline supports at most {MAX_PIPELINE_STAGES} commands.",
+            code="pipeline_too_long",
+            hint="Split the work into multiple requests and reuse returned node ids.",
+            help_query="help pipelines",
+        )
+
+    commands: list[Command] = []
+    for stage in stages:
+        name = stage[0].lower()
+        if name not in SUPPORTED_COMMANDS:
+            close = get_close_matches(name, sorted(SUPPORTED_COMMANDS), n=1, cutoff=0.55)
+            suggestion = close[0] if close else None
+            raise FsQueryError(
+                f"Unknown command: {name}.",
+                code="unknown_command",
+                hint=(
+                    f"Did you mean `{suggestion}`? Run `help {suggestion}` for its syntax."
+                    if suggestion
+                    else "Run `help commands` to see every supported command."
+                ),
+                examples=[suggestion] if suggestion else ["help commands"],
+                help_query=f"help {suggestion}" if suggestion else "help commands",
+            )
+        commands.append(Command(name=name, tokens=tuple(stage[1:])))
+    return commands
+
+
+def parse_cwd(raw: str | None) -> Cwd:
+    value = (raw or "/spaces").strip()
+    if not value.startswith("/"):
+        value = f"/{value}"
+    parts = [part for part in value.split("/") if part]
+    if not parts or parts == ["spaces"]:
+        return Cwd()
+    if parts[0] != "spaces":
+        raise FsQueryError(
+            "cwd must begin with `/spaces`.",
+            code="invalid_cwd",
+            hint="Use `/spaces` to discover spaces, then copy a returned path.",
+            examples=["/spaces", "/spaces/space.personal"],
+            help_query="help paths",
+        )
+    if len(parts) == 2:
+        return Cwd(space_token=parts[1])
+    if len(parts) == 4 and parts[2] == "collections":
+        return Cwd(space_token=parts[1], collection_id=parts[3])
+    raise FsQueryError(
+        "cwd has an unsupported shape.",
+        code="invalid_cwd",
+        hint="Use one of the documented cwd forms exactly.",
+        examples=[
+            "/spaces",
+            "/spaces/space.personal",
+            "/spaces/space.personal/collections/COLLECTION_ID",
+        ],
+        help_query="help paths",
+    )
+
+
+def _options(tokens: Iterable[str]) -> tuple[dict[str, str | bool], list[str]]:
+    options: dict[str, str | bool] = {}
+    positional: list[str] = []
+    values = list(tokens)
+    index = 0
+    while index < len(values):
+        token = values[index]
+        if token.startswith("--"):
+            key, separator, inline = token[2:].partition("=")
+            if not key:
+                raise FsQueryError("invalid empty flag")
+            if separator:
+                options[key.replace("-", "_")] = inline
+            elif index + 1 < len(values) and not values[index + 1].startswith("--"):
+                options[key.replace("-", "_")] = values[index + 1]
+                index += 1
+            else:
+                options[key.replace("-", "_")] = True
+        else:
+            positional.append(token)
+        index += 1
+    return options, positional
+
+
+def _checked_options(
+    command: Command,
+    *,
+    allowed: set[str],
+) -> tuple[dict[str, str | bool], list[str]]:
+    options, positional = _options(command.tokens)
+    unknown = sorted(set(options) - allowed)
+    if unknown:
+        flag = unknown[0].replace("_", "-")
+        documented = [
+            known.replace("_", "-")
+            for known in sorted(allowed)
+        ]
+        close = get_close_matches(flag, documented, n=1, cutoff=0.55)
+        suggestion = f"--{close[0]}" if close else None
+        raise FsQueryError(
+            f"`{command.name}` does not support flag `--{flag}`.",
+            code="unknown_flag",
+            hint=(
+                f"Use `{suggestion}` instead."
+                if suggestion
+                else f"Supported flags: {', '.join(f'--{item}' for item in documented) or '(none)'}."
+            ),
+            examples=COMMANDS[command.name].get("examples", [])[:2],
+            help_query=f"help {command.name}",
+        )
+    return options, positional
+
+
+def _integer(
+    value: Any,
+    *,
+    label: str,
+    minimum: int,
+    maximum: int,
+    command: str,
+) -> int:
+    try:
+        parsed = int(_text(value))
+    except (TypeError, ValueError) as exc:
+        raise FsQueryError(
+            f"{label} must be an integer, received `{value}`.",
+            code="invalid_number",
+            hint=f"Use a whole number from {minimum} to {maximum}.",
+            examples=COMMANDS[command].get("examples", [])[:2],
+            help_query=f"help {command}",
+        ) from exc
+    if parsed < minimum or parsed > maximum:
+        raise FsQueryError(
+            f"{label} must be between {minimum} and {maximum}, received {parsed}.",
+            code="number_out_of_range",
+            hint=f"Choose a value from {minimum} to {maximum}.",
+            examples=COMMANDS[command].get("examples", [])[:2],
+            help_query=f"help {command}",
+        )
+    return parsed
+
+
+def _text(value: Any) -> str:
+    return str(value or "")
+
+
+def _search_options(command: Command) -> tuple[dict[str, Any], list[str]]:
+    aliases = {
+        "-i": "ignore_case",
+        "--ignore-case": "ignore_case",
+        "-s": "case_sensitive",
+        "--case-sensitive": "case_sensitive",
+        "-S": "smart_case",
+        "--smart-case": "smart_case",
+        "-F": "literal",
+        "--fixed-strings": "literal",
+        "--literal": "literal",
+        "-v": "invert",
+        "--invert-match": "invert",
+    }
+    options: dict[str, Any] = {}
+    positional: list[str] = []
+    tokens = list(command.tokens)
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in aliases:
+            options[aliases[token]] = True
+        elif token in {"-m", "--max-count", "--limit"}:
+            if index + 1 >= len(tokens):
+                raise FsQueryError(
+                    f"`{token}` requires an integer.",
+                    code="missing_argument",
+                    hint="Put a maximum result count after the flag.",
+                    examples=COMMANDS[command.name]["examples"][:2],
+                    help_query=f"help {command.name}",
+                )
+            index += 1
+            options["limit"] = tokens[index]
+        elif token.startswith("-"):
+            raise FsQueryError(
+                f"`{command.name}` does not support flag `{token}`.",
+                code="unknown_flag",
+                hint="Run the focused help to see supported ripgrep-style flags.",
+                examples=COMMANDS[command.name]["examples"][:2],
+                help_query=f"help {command.name}",
+            )
+        else:
+            positional.append(token)
+        index += 1
+    return options, positional
+
+
+def _display(memory: dict[str, Any], placement: dict[str, Any] | None = None) -> str:
+    if placement and placement.get("name"):
+        return _text(placement["name"])
+    payload = memory.get("payload") if isinstance(memory.get("payload"), dict) else {}
+    if memory.get("node_type") == "collection" and payload.get("name"):
+        return _text(payload["name"])
+    for key in ("file_name", "filename"):
+        if payload.get(key):
+            return _text(payload[key])
+    content = " ".join(_text(memory.get("content")).split())
+    return content[:77] + ("..." if len(content) > 77 else "")
+
+
+class FsQueryExecutor:
+    def __init__(
+        self,
+        engine: ArthaEngine,
+        *,
+        cwd: Cwd,
+        spaces: list[dict[str, Any]],
+        org_id: str | None,
+    ) -> None:
+        self.engine = engine
+        self.cwd = cwd
+        self.spaces = spaces
+        self.org_id = org_id
+
+    def execute(self, commands: list[Command]) -> dict[str, Any]:
+        items: list[dict[str, Any]] | None = None
+        trace: list[dict[str, Any]] = []
+        navigation: dict[str, Any] | None = None
+        manual: dict[str, Any] | None = None
+        for index, command in enumerate(commands):
+            try:
+                if command.name in {"cd", "pwd", "help", "explain"} and len(commands) != 1:
+                    raise FsQueryError(
+                        f"`{command.name}` must be used as a standalone command.",
+                        code="standalone_command",
+                        hint=f"Run `{command.name}` in its own request without a pipe.",
+                        examples=COMMANDS[command.name].get("examples", [])[:2],
+                        help_query=f"help {command.name}",
+                    )
+
+                before = len(items) if items is not None else None
+                if command.name == "ls":
+                    items = self._ls(command)
+                elif command.name == "find":
+                    items = self._find(command, items)
+                elif command.name == "grep":
+                    items = self._grep(command, items)
+                elif command.name == "rg":
+                    items = self._rg(command, items)
+                elif command.name == "links":
+                    items = self._links(command, items, neighbors=False)
+                elif command.name in {"neighbors", "neighborhood"}:
+                    items = self._links(command, items, neighbors=True)
+                elif command.name == "graph":
+                    items = self._graph(command)
+                elif command.name == "parents":
+                    items = self._directional_relatives(command, items, parents=True)
+                elif command.name == "children":
+                    items = self._directional_relatives(command, items, parents=False)
+                elif command.name == "path":
+                    items = self._path(command, items)
+                elif command.name == "hubs":
+                    items = self._hubs(command, items)
+                elif command.name == "semantic":
+                    items = self._semantic(command, items)
+                elif command.name == "related":
+                    items = self._related(command, items)
+                elif command.name == "traverse":
+                    items = self._traverse(command, items)
+                elif command.name == "why":
+                    items = self._why(command, items)
+                elif command.name == "tree":
+                    items = self._tree(command)
+                elif command.name == "where":
+                    items = self._where(command, items)
+                elif command.name == "sort":
+                    items = self._sort(command, items)
+                elif command.name in {"limit", "head"}:
+                    items = self._limit(command, items)
+                elif command.name == "select":
+                    items = self._select(command, items)
+                elif command.name == "wc":
+                    items = self._wc(command, items)
+                elif command.name == "cat":
+                    items = self._cat(command, items)
+                elif command.name == "stat":
+                    items = self._stat(command, items)
+                elif command.name == "cd":
+                    navigation = self._cd(command)
+                    items = []
+                elif command.name == "pwd":
+                    if command.tokens:
+                        raise FsQueryError(
+                            "`pwd` does not accept arguments.",
+                            code="unexpected_argument",
+                            hint="Run `pwd` by itself.",
+                            examples=["pwd"],
+                            help_query="help pwd",
+                        )
+                    items = [{"kind": "cwd", "display": self.cwd.path, "path": self.cwd.path}]
+                elif command.name == "help":
+                    items = self._help(command)
+                    if items:
+                        manual_value = items[0].get("manual")
+                        manual = manual_value if isinstance(manual_value, dict) else None
+                elif command.name == "explain":
+                    items = self._explain(command)
+            except FsQueryError as exc:
+                raise exc.add_context(stage=index + 1, command=command.name) from exc
+            trace.append(
+                {
+                    "stage": index + 1,
+                    "command": command.name,
+                    "input_count": before,
+                    "output_count": len(items or []),
+                }
+            )
+
+        kind = "navigation" if navigation else "help" if manual else "result"
+        return {
+            "kind": kind,
+            "cwd": self.cwd.path,
+            "navigation": navigation,
+            "protocol": "memuron.graph-filesystem.v1",
+            "manual": manual,
+            "items": (items or [])[:MAX_RESULT_ITEMS],
+            "count": len(items or []),
+            "trace": trace,
+        }
+
+    def _org_token(self) -> str:
+        return org_scope_token(self.org_id) if self.org_id else ""
+
+    def _with_paths(self, items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        for item in items:
+            memory_id = _text(item.get("id"))
+            if item.get("type") == "collection" or item.get("node_type") == "collection":
+                item["path"] = f"/spaces/{self.cwd.space_token}/collections/{memory_id}"
+            elif self.cwd.collection_id:
+                item["path"] = f"{self.cwd.path}/nodes/{memory_id}"
+            else:
+                item["path"] = f"/spaces/{self.cwd.space_token}/nodes/{memory_id}"
+        return items
+
+    def _default_items(self) -> list[dict[str, Any]]:
+        return self._ls(Command("ls"))
+
+    def _ls(self, command: Command) -> list[dict[str, Any]]:
+        options, positional = _checked_options(
+            command,
+            allowed={"collections_only", "floating_only"},
+        )
+        if positional:
+            raise FsQueryError(
+                "`ls` accepts flags only; it does not accept a path argument.",
+                code="unexpected_argument",
+                hint="Put the desired path in the request's `cwd`, then run `ls`.",
+                examples=["ls", "ls --collections-only"],
+                help_query="help ls",
+            )
+        if not self.cwd.space_token:
+            return [
+                {
+                    "kind": "space",
+                    "id": _text(space["id"]),
+                    "type": "space",
+                    "node_type": "space",
+                    "display": _text(space["name"]),
+                    "token": _text(space["token"]),
+                    "description": _text(space.get("description")),
+                    "enabled": bool(space.get("is_enabled")),
+                    "path": f"/spaces/{space['token']}",
+                }
+                for space in self.spaces
+            ]
+        if self.cwd.collection_id:
+            items = list_entries(
+                self.engine.store,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token,
+                collection_id=self.cwd.collection_id,
+                node_type="collection" if options.get("collections_only") else None,
+                limit=MAX_RESULT_ITEMS,
+            )
+            if options.get("floating_only"):
+                items = []
+        else:
+            items = list_root(
+                self.engine.store,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token,
+                collections_only=bool(options.get("collections_only")),
+                floating_only=bool(options.get("floating_only")),
+                limit=MAX_RESULT_ITEMS,
+            )
+        return self._with_paths(items)
+
+    def _find(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(
+            command,
+            allowed={"type", "encoding", "id", "name", "floating"},
+        )
+        if positional:
+            raise FsQueryError(
+                "`find` filters must use named flags.",
+                code="unexpected_argument",
+                hint="Use `--name TEXT`, `--type TYPE`, `--encoding VALUE`, or `--id ID`.",
+                examples=COMMANDS["find"]["examples"][:2],
+                help_query="help find",
+            )
+        if items is None:
+            candidates = list_entries(
+                self.engine.store,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token or "",
+                collection_id=self.cwd.collection_id,
+                node_type=_text(options.get("type")) or None,
+                encoding=_text(options.get("encoding")) or None,
+                node_id=_text(options.get("id")) or None,
+                name=_text(options.get("name")) or None,
+                floating=bool(options.get("floating")),
+                limit=MAX_RESULT_ITEMS,
+            )
+            return self._with_paths(candidates)
+        candidates = items
+        for key in ("type", "encoding", "id"):
+            if key not in options:
+                continue
+            field = "type" if key == "type" else key
+            expected = _text(options[key]).lower()
+            candidates = [
+                item for item in candidates if _text(item.get(field)).lower() == expected
+            ]
+        if "name" in options:
+            needle = _text(options["name"]).lower().replace("*", "")
+            candidates = [
+                item for item in candidates if needle in _text(item.get("display")).lower()
+            ]
+        if options.get("floating"):
+            floating_ids = {
+                item["id"]
+                for item in list_entries(
+                    self.engine.store,
+                    org_token=self._org_token(),
+                    space_token=self.cwd.space_token or "",
+                    floating=True,
+                    limit=MAX_RESULT_ITEMS,
+                )
+            }
+            candidates = [item for item in candidates if item.get("id") in floating_ids]
+        return candidates
+
+    def _grep(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"limit", "literal"})
+        literal_value = options.get("literal")
+        if isinstance(literal_value, str):
+            positional.insert(0, literal_value)
+        query = " ".join(positional).strip()
+        if not query:
+            raise FsQueryError(
+                "`grep` requires search text.",
+                code="missing_argument",
+                hint="Put the search text after grep and quote multi-word text.",
+                examples=['grep "authentication"', 'grep "data plane" --limit 20'],
+                help_query="help grep",
+            )
+        return self._content_search(
+            command,
+            items,
+            query=query,
+            literal=bool(literal_value),
+            case_sensitive=False,
+            invert=False,
+            limit=options.get("limit"),
+        )
+
+    def _rg(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _search_options(command)
+        query = " ".join(positional).strip()
+        if not query:
+            raise FsQueryError(
+                "`rg` requires a search pattern.",
+                code="missing_argument",
+                hint="Put a regex after rg, or use -F for fixed text.",
+                examples=COMMANDS["rg"]["examples"][:2],
+                help_query="help rg",
+            )
+        if options.get("ignore_case") and options.get("case_sensitive"):
+            raise FsQueryError(
+                "`rg` cannot combine -i and -s.",
+                code="conflicting_flags",
+                hint="Choose explicit insensitive (-i), explicit sensitive (-s), or smart case (-S/default).",
+                examples=COMMANDS["rg"]["examples"][:3],
+                help_query="help rg",
+            )
+        case_sensitive = bool(options.get("case_sensitive"))
+        if not options.get("ignore_case") and not options.get("case_sensitive"):
+            case_sensitive = any(character.isupper() for character in query)
+        return self._content_search(
+            command,
+            items,
+            query=query,
+            literal=bool(options.get("literal")),
+            case_sensitive=case_sensitive,
+            invert=bool(options.get("invert")),
+            limit=options.get("limit"),
+        )
+
+    def _content_search(
+        self,
+        command: Command,
+        items: list[dict[str, Any]] | None,
+        *,
+        query: str,
+        literal: bool,
+        case_sensitive: bool,
+        invert: bool,
+        limit: Any,
+    ) -> list[dict[str, Any]]:
+        if not literal:
+            try:
+                re.compile(query, 0 if case_sensitive else re.IGNORECASE)
+            except re.error as exc:
+                raise FsQueryError(
+                    f"Invalid regular expression: {exc}.",
+                    code="invalid_regex",
+                    hint=f"Correct the regex, or use {'-F' if command.name == 'rg' else '--literal'} for fixed text.",
+                    examples=COMMANDS[command.name]["examples"][:3],
+                    help_query=f"help {command.name}",
+                ) from exc
+        k = _integer(
+            limit or 100,
+            label=f"{command.name} --limit",
+            minimum=1,
+            maximum=100,
+            command=command.name,
+        )
+        allowed = None
+        if items is not None:
+            allowed = {item.get("id") for item in items if item.get("kind") == "node"}
+        elif self.cwd.collection_id:
+            allowed = {item["id"] for item in self._default_items()}
+        hits = grep_entries(
+            self.engine.store,
+            query,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            allowed_ids={str(item) for item in allowed} if allowed is not None else None,
+            limit=k,
+            literal=literal,
+            case_sensitive=case_sensitive,
+            invert=invert,
+        )
+        return self._with_paths(hits)
+
+    def _links(
+        self,
+        command: Command,
+        items: list[dict[str, Any]] | None,
+        *,
+        neighbors: bool,
+    ) -> list[dict[str, Any]]:
+        options, positional = _checked_options(
+            command,
+            allowed={
+                "depth",
+                "direction",
+                "outbound",
+                "inbound",
+                "placements",
+                "include_self",
+            },
+        )
+        if positional:
+            raise FsQueryError(
+                f"`{command.name}` accepts flags only.",
+                code="unexpected_argument",
+                hint=f"Pipe seed nodes into `{command.name}` or let it use the current `ls` entries.",
+                examples=COMMANDS[command.name]["examples"][:2],
+                help_query=f"help {command.name}",
+            )
+        seeds = items if items is not None else self._default_items()
+        seed_ids = {item.get("id") for item in seeds if item.get("kind") == "node"}
+        direction = _text(options.get("direction") or "both")
+        if options.get("outbound"):
+            direction = "outbound"
+        elif options.get("inbound"):
+            direction = "inbound"
+        if direction not in {"both", "inbound", "outbound"}:
+            raise FsQueryError(
+                f"Invalid direction: `{direction}`.",
+                code="invalid_choice",
+                hint="Use `both`, `inbound`, or `outbound`.",
+                examples=[f"{command.name} --direction both", f"{command.name} --outbound"],
+                help_query=f"help {command.name}",
+            )
+        include_placements = bool(options.get("placements")) or neighbors
+        depth = _integer(
+            options.get("depth") or (2 if neighbors else 1),
+            label=f"{command.name} --depth",
+            minimum=1,
+            maximum=5,
+            command=command.name,
+        )
+        output = expand_neighbors(
+            self.engine.store,
+            {str(item) for item in seed_ids if item},
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            depth=depth,
+            direction=direction,
+            include_placements=include_placements,
+            include_self=bool(options.get("include_self")),
+        )
+        return self._with_paths(output)
+
+    def _graph(self, command: Command) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"limit"})
+        if positional:
+            raise FsQueryError(
+                "`graph` accepts flags only.",
+                code="unexpected_argument",
+                hint="Use --limit to bound exported nodes.",
+                examples=COMMANDS["graph"]["examples"][:2],
+                help_query="help graph",
+            )
+        limit = _integer(
+            options.get("limit") or 100,
+            label="graph --limit",
+            minimum=1,
+            maximum=1000,
+            command="graph",
+        )
+        nodes = list_entries(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            limit=limit,
+        )
+        node_ids = {str(node["id"]) for node in nodes}
+        edges = [
+            {
+                "id": str(edge["edge_id"]),
+                "source": str(edge["source_id"]),
+                "target": str(edge["target_id"]),
+                "type": str(edge["edge_type"]),
+                "description": str(edge.get("description") or ""),
+            }
+            for edge in space_edges(
+                self.engine.store,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token or "",
+            )
+            if str(edge["source_id"]) in node_ids and str(edge["target_id"]) in node_ids
+        ]
+        return [{
+            "kind": "graph",
+            "display": f"{len(nodes)} nodes, {len(edges)} edges",
+            "nodes": self._with_paths(nodes),
+            "edges": edges,
+            "node_count": len(nodes),
+            "edge_count": len(edges),
+            "bounded": len(nodes) == limit,
+        }]
+
+    def _directional_relatives(
+        self,
+        command: Command,
+        items: list[dict[str, Any]] | None,
+        *,
+        parents: bool,
+    ) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"all"})
+        if positional:
+            raise FsQueryError(
+                f"`{command.name}` accepts flags only.",
+                code="unexpected_argument",
+                hint=f"Pipe nodes into `{command.name}`.",
+                examples=COMMANDS[command.name]["examples"][:2],
+                help_query=f"help {command.name}",
+            )
+        seeds = items if items is not None else self._default_items()
+        seed_ids = {str(item["id"]) for item in seeds if item.get("kind") == "node"}
+        edges = space_edges(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            include_placements=True,
+        )
+        relative_ids: list[str] = []
+        for edge in edges:
+            if not options.get("all") and edge["edge_type"] != "placement":
+                continue
+            source_id = str(edge["source_id"])
+            target_id = str(edge["target_id"])
+            if parents and target_id in seed_ids:
+                relative_ids.append(source_id)
+            elif not parents and source_id in seed_ids:
+                relative_ids.append(target_id)
+        nodes = get_nodes(
+            self.engine.store,
+            list(dict.fromkeys(relative_ids)),
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token,
+        )
+        return self._with_paths(nodes)
+
+    def _hubs(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"limit"})
+        if positional:
+            raise FsQueryError(
+                "`hubs` accepts flags only.",
+                code="unexpected_argument",
+                hint="Use --limit to control the number of hubs.",
+                examples=COMMANDS["hubs"]["examples"][:2],
+                help_query="help hubs",
+            )
+        limit = _integer(
+            options.get("limit") or 10,
+            label="hubs --limit",
+            minimum=1,
+            maximum=100,
+            command="hubs",
+        )
+        candidates = items
+        if candidates is None:
+            candidates = list_entries(
+                self.engine.store,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token or "",
+                limit=MAX_RESULT_ITEMS,
+            )
+        return sorted(
+            [item for item in candidates if item.get("kind") == "node"],
+            key=lambda item: (-int(item.get("degree") or 0), str(item.get("id"))),
+        )[:limit]
+
+    def _path(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        tokens = list(command.tokens)
+        if items is not None:
+            seeds = [item for item in items if item.get("kind") == "node"]
+            if len(seeds) != 1 or len(tokens) != 1:
+                raise FsQueryError(
+                    "Piped `path` requires exactly one input node and one destination id.",
+                    code="invalid_syntax",
+                    hint="Limit the incoming stream to one node, then provide the destination id.",
+                    examples=COMMANDS["path"]["examples"][:2],
+                    help_query="help path",
+                )
+            from_id, to_id = str(seeds[0]["id"]), tokens[0]
+        elif len(tokens) == 2:
+            from_id, to_id = tokens
+        else:
+            raise FsQueryError(
+                "`path` requires FROM_ID TO_ID, or one piped node plus TO_ID.",
+                code="invalid_syntax",
+                hint="Provide two ids, or pipe one node into path.",
+                examples=COMMANDS["path"]["examples"][:2],
+                help_query="help path",
+            )
+        all_nodes = list_entries(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            limit=MAX_RESULT_ITEMS,
+        )
+        known = {str(item["id"]) for item in all_nodes}
+        if from_id not in known or to_id not in known:
+            raise FsQueryError(
+                "One or both path endpoints are not visible in this space.",
+                code="node_not_found",
+                hint="Use find, rg, or semantic to obtain endpoint ids in the current space.",
+                examples=COMMANDS["path"]["examples"][:2],
+                help_query="help path",
+            )
+        edges = space_edges(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+        )
+        adjacency: dict[str, list[tuple[str, dict[str, Any]]]] = {}
+        for edge in edges:
+            source_id, target_id = str(edge["source_id"]), str(edge["target_id"])
+            if source_id == target_id:
+                continue
+            adjacency.setdefault(source_id, []).append((target_id, edge))
+            adjacency.setdefault(target_id, []).append((source_id, edge))
+        queue: list[tuple[str, list[str], list[dict[str, Any]]]] = [(from_id, [from_id], [])]
+        visited = {from_id}
+        found_nodes: list[str] | None = None
+        found_edges: list[dict[str, Any]] = []
+        while queue:
+            current, node_path, edge_path = queue.pop(0)
+            if current == to_id:
+                found_nodes, found_edges = node_path, edge_path
+                break
+            for neighbor_id, edge in adjacency.get(current, []):
+                if neighbor_id in visited:
+                    continue
+                visited.add(neighbor_id)
+                queue.append((neighbor_id, [*node_path, neighbor_id], [*edge_path, edge]))
+        if found_nodes is None:
+            return [{
+                "kind": "path",
+                "status": "no_path",
+                "from_id": from_id,
+                "to_id": to_id,
+                "display": "No graph path found.",
+            }]
+        nodes_by_id = {
+            str(item["id"]): item
+            for item in get_nodes(
+                self.engine.store,
+                found_nodes,
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token,
+            )
+        }
+        output = []
+        for index, node_id in enumerate(found_nodes):
+            item = dict(nodes_by_id[node_id])
+            item["path_index"] = index
+            item["path_length"] = len(found_nodes) - 1
+            if index:
+                edge = found_edges[index - 1]
+                item["via"] = {
+                    "id": edge["edge_id"],
+                    "type": edge["edge_type"],
+                    "description": edge.get("description") or "",
+                }
+            output.append(item)
+        return self._with_paths(output)
+
+    def _semantic(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"limit", "links"})
+        query = " ".join(positional).strip()
+        if not query:
+            raise FsQueryError(
+                "`semantic` requires a natural-language query.",
+                code="missing_argument",
+                hint="Describe the memory you want to retrieve.",
+                examples=COMMANDS["semantic"]["examples"][:2],
+                help_query="help semantic",
+            )
+        limit = _integer(
+            options.get("limit") or 10,
+            label="semantic --limit",
+            minimum=1,
+            maximum=100,
+            command="semantic",
+        )
+        results, _scope = search_memories(
+            self.engine,
+            query,
+            k=limit,
+            scope=[self._org_token(), self.cwd.space_token or ""],
+            include_links=bool(options.get("links")),
+        )
+        allowed_ids = None
+        if items is not None:
+            allowed_ids = {str(item["id"]) for item in items if item.get("kind") == "node"}
+        scores = {
+            str(result["id"]): float(result.get("semantic_score") or 0)
+            for result in results
+            if result.get("type") == "memory_node"
+            and (allowed_ids is None or str(result["id"]) in allowed_ids)
+        }
+        matches = {
+            str(result["id"]): result
+            for result in results
+            if result.get("type") == "memory_node"
+            and (allowed_ids is None or str(result["id"]) in allowed_ids)
+        }
+        nodes = get_nodes(
+            self.engine.store,
+            list(scores),
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token,
+        )
+        for node in nodes:
+            node["score"] = scores.get(str(node["id"]), 0)
+            node["match"] = "semantic"
+            node["semantic_query"] = query
+            match = matches.get(str(node["id"]), {})
+            if match.get("matched_via"):
+                node["matched_via"] = match.get("matched_via")
+                node["matched_via_link_id"] = match.get("matched_via_link_id")
+                node["matched_link_description"] = match.get("matched_link_description")
+        return self._with_paths(sorted(nodes, key=lambda item: -float(item["score"])))
+
+    def _related(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"limit"})
+        if positional:
+            raise FsQueryError(
+                "`related` accepts flags only.",
+                code="unexpected_argument",
+                hint="Pipe one or more seed nodes into related.",
+                examples=COMMANDS["related"]["examples"][:2],
+                help_query="help related",
+            )
+        seeds = [item for item in (items or []) if item.get("kind") == "node"]
+        if not seeds:
+            raise FsQueryError(
+                "`related` requires pipeline input.",
+                code="missing_input",
+                hint="Find or search for seed memories first.",
+                examples=COMMANDS["related"]["examples"][:2],
+                help_query="help related",
+            )
+        limit = _integer(
+            options.get("limit") or 10,
+            label="related --limit",
+            minimum=1,
+            maximum=100,
+            command="related",
+        )
+        seed_ids = {str(item["id"]) for item in seeds}
+        semantic_queries = {
+            str(item["semantic_query"])
+            for item in seeds
+            if item.get("semantic_query")
+        }
+        if len(semantic_queries) == 1:
+            query = semantic_queries.pop()
+        else:
+            query = "\n".join(
+                str(item.get("preview") or item.get("display") or "")[:500]
+                for item in seeds[:5]
+            )
+        results = self._semantic(Command("semantic", (query, "--limit", str(min(100, limit + len(seeds))))), None)
+        return [item for item in results if str(item.get("id")) not in seed_ids][:limit]
+
+    def _traverse(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"depth", "threshold"})
+        query = " ".join(positional).strip()
+        seeds = [item for item in (items or []) if item.get("kind") == "node"]
+        if len(seeds) != 1 or not query:
+            raise FsQueryError(
+                "`traverse` requires exactly one piped seed node and a semantic query.",
+                code="invalid_syntax",
+                hint="Find one seed, limit to one, then describe which edges to follow.",
+                examples=COMMANDS["traverse"]["examples"][:2],
+                help_query="help traverse",
+            )
+        depth = _integer(
+            options.get("depth") or 2,
+            label="traverse --depth",
+            minimum=1,
+            maximum=5,
+            command="traverse",
+        )
+        try:
+            threshold = float(options.get("threshold") or 0.7)
+        except (TypeError, ValueError) as exc:
+            raise FsQueryError(
+                "traverse --threshold must be a number from 0 to 1.",
+                code="invalid_number",
+                hint="Use a decimal such as 0.7.",
+                examples=COMMANDS["traverse"]["examples"][:2],
+                help_query="help traverse",
+            ) from exc
+        if not 0 <= threshold <= 1:
+            raise FsQueryError(
+                "traverse --threshold must be between 0 and 1.",
+                code="number_out_of_range",
+                hint="Use a decimal from 0 to 1.",
+                examples=COMMANDS["traverse"]["examples"][:2],
+                help_query="help traverse",
+            )
+        payload = semantic_traverse_graph(
+            self.engine,
+            start_memory_id=str(seeds[0]["id"]),
+            query=query,
+            max_hops=depth,
+            edge_similarity_threshold=threshold,
+            scope=[self._org_token(), self.cwd.space_token or ""],
+        )
+        scores: dict[str, float] = {}
+        for edge in payload["traversed_edges"]:
+            destination = str(edge["to_memory_id"])
+            scores[destination] = max(scores.get(destination, 0), float(edge["similarity"]))
+        ids = [str(memory["id"]) for memory in payload["memories"]]
+        nodes = get_nodes(
+            self.engine.store,
+            ids,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token,
+        )
+        hops = {str(memory["id"]): int(memory["hop_distance"]) for memory in payload["memories"]}
+        for node in nodes:
+            node["hop_distance"] = hops.get(str(node["id"]), 0)
+            node["score"] = scores.get(str(node["id"]), 1.0 if node["id"] == seeds[0]["id"] else 0)
+            node["match"] = "semantic_traversal"
+        return self._with_paths(sorted(nodes, key=lambda item: (item["hop_distance"], -item["score"])))
+
+    def _why(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        tokens = list(command.tokens)
+        seeds = [item for item in (items or []) if item.get("kind") == "node"]
+        if len(seeds) != 1 or len(tokens) != 1:
+            raise FsQueryError(
+                "`why` requires one piped node and one related node id.",
+                code="invalid_syntax",
+                hint="Limit the source stream to one node, then provide the other node id.",
+                examples=COMMANDS["why"]["examples"][:2],
+                help_query="help why",
+            )
+        source_id, target_id = str(seeds[0]["id"]), tokens[0]
+        edges = space_edges(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+        )
+        reasons = []
+        for edge in edges:
+            endpoints = {str(edge["source_id"]), str(edge["target_id"])}
+            if endpoints != {source_id, target_id}:
+                continue
+            reasons.append({
+                "kind": "relationship_reason",
+                "id": str(edge["edge_id"]),
+                "type": str(edge["edge_type"]),
+                "source_id": str(edge["source_id"]),
+                "target_id": str(edge["target_id"]),
+                "description": str(edge.get("description") or ""),
+                "display": str(edge.get("description") or edge["edge_type"]),
+            })
+        if reasons:
+            return reasons
+        return [{
+            "kind": "relationship_reason",
+            "type": "none",
+            "source_id": source_id,
+            "target_id": target_id,
+            "description": "No direct projected edge connects these nodes. Use path to inspect indirect connections.",
+            "display": "No direct relationship.",
+        }]
+
+    def _tree(self, command: Command) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"depth"})
+        if positional:
+            raise FsQueryError(
+                "`tree` accepts flags only.",
+                code="unexpected_argument",
+                hint="Set the root with cwd and optionally use --depth.",
+                examples=COMMANDS["tree"]["examples"][:2],
+                help_query="help tree",
+            )
+        max_depth = _integer(
+            options.get("depth") or 3,
+            label="tree --depth",
+            minimum=1,
+            maximum=10,
+            command="tree",
+        )
+        nodes = list_entries(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+            limit=MAX_RESULT_ITEMS,
+        )
+        by_id = {str(node["id"]): node for node in nodes}
+        edges = space_edges(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+        )
+        children: dict[str, list[str]] = {}
+        placed: set[str] = set()
+        for edge in edges:
+            if edge["edge_type"] != "placement":
+                continue
+            parent_id, child_id = str(edge["source_id"]), str(edge["target_id"])
+            children.setdefault(parent_id, []).append(child_id)
+            placed.add(child_id)
+        roots = [self.cwd.collection_id] if self.cwd.collection_id else [
+            node_id for node_id in by_id if node_id not in placed
+        ]
+        output: list[dict[str, Any]] = []
+
+        def visit(node_id: str, depth: int, ancestors: set[str]) -> None:
+            if node_id not in by_id or node_id in ancestors or depth > max_depth:
+                return
+            item = dict(by_id[node_id])
+            item["tree_depth"] = depth
+            item["tree_prefix"] = "  " * depth
+            output.append(item)
+            for child_id in children.get(node_id, []):
+                visit(child_id, depth + 1, {*ancestors, node_id})
+
+        for root_id in roots:
+            if root_id:
+                visit(str(root_id), 0, set())
+        return self._with_paths(output)
+
+    def _where(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        if items is None:
+            items = self._default_items()
+        tokens = list(command.tokens)
+        if len(tokens) != 3:
+            raise FsQueryError(
+                "`where` requires exactly FIELD OPERATOR VALUE.",
+                code="invalid_syntax",
+                hint="Use a supported field and comparison operator.",
+                examples=COMMANDS["where"]["examples"][:2],
+                help_query="help where",
+            )
+        field, operator, raw_expected = tokens
+        if field not in {"degree", "display", "encoding", "node_type", "type"}:
+            raise FsQueryError(
+                f"`where` does not support field `{field}`.",
+                code="invalid_field",
+                hint="Use degree, display, encoding, or type. node_type is deprecated.",
+                examples=COMMANDS["where"]["examples"][:2],
+                help_query="help where",
+            )
+        if field == "type":
+            field = "type"
+        if operator not in {"=", "==", "!=", ">", ">=", "<", "<=", "~"}:
+            raise FsQueryError(
+                f"Unsupported where operator: `{operator}`.",
+                code="invalid_operator",
+                hint="Use =, ==, !=, >, >=, <, <=, or ~.",
+                examples=COMMANDS["where"]["examples"][:2],
+                help_query="help where",
+            )
+        if field != "degree" and operator not in {"=", "==", "!=", "~"}:
+            raise FsQueryError(
+                f"Operator `{operator}` cannot compare text field `{field}`.",
+                code="invalid_operator",
+                hint="Use =, ==, !=, or ~ for text fields. Use numeric operators with degree.",
+                examples=COMMANDS["where"]["examples"][:2],
+                help_query="help where",
+            )
+        if field == "degree":
+            try:
+                int(raw_expected)
+            except ValueError as exc:
+                raise FsQueryError(
+                    f"`degree` must be compared with an integer, received `{raw_expected}`.",
+                    code="invalid_number",
+                    hint="Use a whole number, for example `where degree > 5`.",
+                    examples=["ls | where degree > 5"],
+                    help_query="help where",
+                ) from exc
+
+        def matches(item: dict[str, Any]) -> bool:
+            actual = item.get(field)
+            if field == "degree":
+                left, right = int(actual or 0), int(raw_expected)
+                return {
+                    "=": left == right,
+                    "==": left == right,
+                    "!=": left != right,
+                    ">": left > right,
+                    ">=": left >= right,
+                    "<": left < right,
+                    "<=": left <= right,
+                }.get(operator, False)
+            left = _text(actual).lower()
+            right = raw_expected.lower()
+            return {
+                "=": left == right,
+                "==": left == right,
+                "!=": left != right,
+                "~": right in left,
+            }.get(operator, False)
+
+        return [item for item in items if matches(item)]
+
+    def _sort(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        if items is None:
+            items = self._default_items()
+        tokens = list(command.tokens)
+        if not tokens or len(tokens) > 2:
+            raise FsQueryError(
+                "`sort` requires FIELD and an optional asc or desc direction.",
+                code="invalid_syntax",
+                hint="Choose one supported field and optionally add `asc` or `desc`.",
+                examples=COMMANDS["sort"]["examples"][:2],
+                help_query="help sort",
+            )
+        field = "type" if tokens[0] in {"type", "node_type"} else tokens[0]
+        if field not in {"degree", "display", "encoding", "id", "type", "score"}:
+            raise FsQueryError(
+                f"`sort` does not support field `{field}`.",
+                code="invalid_field",
+                hint="Use degree, display, encoding, id, type, or score. node_type is deprecated.",
+                examples=COMMANDS["sort"]["examples"][:2],
+                help_query="help sort",
+            )
+        if len(tokens) == 2 and tokens[1].lower() not in {"asc", "desc"}:
+            raise FsQueryError(
+                f"Invalid sort direction: `{tokens[1]}`.",
+                code="invalid_choice",
+                hint="Use `asc` or `desc`.",
+                examples=COMMANDS["sort"]["examples"][:2],
+                help_query="help sort",
+            )
+        reverse = len(tokens) == 2 and tokens[1].lower() == "desc"
+        return sorted(
+            items,
+            key=lambda item: (
+                item.get(field) is None,
+                item.get(field) if field in {"degree", "score"} else _text(item.get(field)).lower(),
+            ),
+            reverse=reverse,
+        )
+
+    def _limit(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        if items is None:
+            items = self._default_items()
+        if len(command.tokens) != 1:
+            raise FsQueryError(
+                f"`{command.name}` requires exactly one integer.",
+                code="invalid_syntax",
+                hint=f"Put one whole number after {command.name}.",
+                examples=COMMANDS[command.name]["examples"][:2],
+                help_query=f"help {command.name}",
+            )
+        amount = _integer(
+            command.tokens[0],
+            label=command.name,
+            minimum=0,
+            maximum=MAX_RESULT_ITEMS,
+            command=command.name,
+        )
+        return items[:amount]
+
+    def _select(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        if items is None:
+            items = self._default_items()
+        fields = [
+            field.strip()
+            for token in command.tokens
+            for field in token.split(",")
+            if field.strip()
+        ]
+        if not fields:
+            raise FsQueryError(
+                "`select` requires one or more field names.",
+                code="missing_argument",
+                hint="Use comma-separated fields to reduce response size.",
+                examples=COMMANDS["select"]["examples"][:2],
+                help_query="help select",
+            )
+        available = sorted({key for item in items for key in item})
+        unknown = [field for field in fields if field not in available]
+        if unknown:
+            raise FsQueryError(
+                f"Unknown select field: {unknown[0]}.",
+                code="invalid_field",
+                hint=f"Fields available on this stream: {', '.join(available)}.",
+                examples=COMMANDS["select"]["examples"][:2],
+                help_query="help select",
+            )
+        return [{field: item.get(field) for field in fields} for item in items]
+
+    def _wc(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        options, positional = _checked_options(command, allowed={"tokens"})
+        if positional:
+            raise FsQueryError(
+                "`wc` accepts flags only.",
+                code="unexpected_argument",
+                hint="Pipe a node stream into wc.",
+                examples=COMMANDS["wc"]["examples"][:2],
+                help_query="help wc",
+            )
+        stream = items if items is not None else self._default_items()
+        contents = [str(item.get("content") or "") for item in stream]
+        characters = sum(len(content) for content in contents)
+        words = sum(len(content.split()) for content in contents)
+        result = {
+            "kind": "aggregate",
+            "display": f"{len(stream)} items",
+            "items": len(stream),
+            "nodes": sum(1 for item in stream if item.get("kind") == "node"),
+            "characters": characters,
+            "words": words,
+            "bytes": sum(len(content.encode("utf-8")) for content in contents),
+        }
+        if options.get("tokens"):
+            result["estimated_tokens"] = (characters + 3) // 4
+        return [result]
+
+    def _explain(self, command: Command) -> list[dict[str, Any]]:
+        query = " ".join(command.tokens).strip()
+        if not query:
+            raise FsQueryError(
+                "`explain` requires a quoted query pipeline.",
+                code="missing_argument",
+                hint="Wrap the pipeline in quotes so its pipes belong to explain.",
+                examples=COMMANDS["explain"]["examples"][:2],
+                help_query="help explain",
+            )
+        commands = parse_query(query)
+        semantic_commands = {"semantic", "related", "traverse"}
+        graph_commands = {
+            "graph",
+            "neighbors",
+            "neighborhood",
+            "links",
+            "parents",
+            "children",
+            "path",
+            "hubs",
+            "why",
+            "tree",
+        }
+        stages = []
+        for index, parsed in enumerate(commands, start=1):
+            if parsed.name in semantic_commands:
+                execution = "embedding and semantic projection"
+                cost = "high"
+            elif parsed.name in graph_commands:
+                execution = "indexed filesystem graph projection"
+                cost = "medium"
+            elif parsed.name in {"grep", "rg"}:
+                execution = "bounded filesystem content scan"
+                cost = "medium"
+            else:
+                execution = "in-memory stream transform or indexed lookup"
+                cost = "low"
+            stages.append({
+                "stage": index,
+                "command": parsed.name,
+                "tokens": list(parsed.tokens),
+                "execution": execution,
+                "estimated_cost": cost,
+            })
+        return [{
+            "kind": "query_plan",
+            "display": query,
+            "query": query,
+            "stages": stages,
+            "stage_count": len(stages),
+            "executes": False,
+        }]
+
+    def _cat(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        targets = self._targets(command, items, "cat")
+        return [{**item, "view": "content"} for item in targets]
+
+    def _stat(self, command: Command, items: list[dict[str, Any]] | None) -> list[dict[str, Any]]:
+        targets = self._targets(command, items, "stat")
+        edges = node_edges(
+            self.engine.store,
+            {item["id"] for item in targets},
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token or "",
+        )
+        output = []
+        for item in targets:
+            memory_id = item["id"]
+            output.append(
+                {
+                    **item,
+                    "view": "stat",
+                    "placements": [
+                        edge
+                        for edge in edges
+                        if edge.get("edge_type") == "placement"
+                        and memory_id in {edge["source_id"], edge["target_id"]}
+                    ],
+                    "semantic_links": [
+                        edge
+                        for edge in edges
+                        if edge.get("edge_type") == "semantic_link"
+                        and memory_id in {edge["source_id"], edge["target_id"]}
+                    ],
+                    "self_loop_count": sum(
+                        1
+                        for edge in edges
+                        if edge.get("edge_type") == "semantic_link"
+                        and edge["source_id"] == edge["target_id"] == memory_id
+                    ),
+                }
+            )
+        return output
+
+    def _targets(
+        self,
+        command: Command,
+        items: list[dict[str, Any]] | None,
+        name: str,
+    ) -> list[dict[str, Any]]:
+        if command.tokens:
+            if len(command.tokens) != 1:
+                raise FsQueryError(
+                    f"`{name}` accepts exactly one node id.",
+                    code="invalid_syntax",
+                    hint=f"Pass one id, or pipe nodes into `{name}` without an argument.",
+                    examples=COMMANDS[name]["examples"][:2],
+                    help_query=f"help {name}",
+                )
+            targets = get_nodes(
+                self.engine.store,
+                [command.tokens[0]],
+                org_token=self._org_token(),
+                space_token=self.cwd.space_token,
+            )
+            if not targets:
+                raise FsQueryError(
+                    f"Node not found: {command.tokens[0]}.",
+                    code="node_not_found",
+                    hint="Use `ls`, `find`, or `grep` to obtain a valid node id in this space.",
+                    examples=["ls | limit 20", "find --id NODE_ID"],
+                    help_query=f"help {name}",
+                )
+            return self._with_paths(targets)
+        if items is None:
+            raise FsQueryError(
+                f"`{name}` requires a node id or pipeline input.",
+                code="missing_argument",
+                hint=f"Pass a node id or pipe a node-producing command into `{name}`.",
+                examples=COMMANDS[name]["examples"][:2],
+                help_query=f"help {name}",
+            )
+        return [item for item in items if item.get("kind") == "node"]
+
+    def _cd(self, command: Command) -> dict[str, Any]:
+        if len(command.tokens) != 1:
+            raise FsQueryError(
+                "`cd` requires exactly one destination.",
+                code="invalid_syntax",
+                hint="Use a space token, collection id, @node-id, absolute cwd, or `..`.",
+                examples=COMMANDS["cd"]["examples"][:3],
+                help_query="help cd",
+            )
+        target = command.tokens[0]
+        if target in {"/", "/spaces"}:
+            cwd = Cwd()
+        elif target == "..":
+            cwd = Cwd(space_token=self.cwd.space_token) if self.cwd.collection_id else Cwd()
+        elif target.startswith("/spaces"):
+            cwd = parse_cwd(target)
+        elif target.startswith("space."):
+            cwd = Cwd(space_token=target)
+        elif target.startswith("@"):
+            cwd = self._resolve_node(target[1:])
+        else:
+            cwd = self._resolve_collection(target)
+        self._validate_cwd(cwd)
+        return {"cwd": cwd.path, "url": cwd.path}
+
+    def _resolve_collection(self, target: str) -> Cwd:
+        if not self.cwd.space_token:
+            matching_space = next(
+                (
+                    space for space in self.spaces
+                    if target in {_text(space["id"]), _text(space["token"]), _text(space["name"])}
+                ),
+                None,
+            )
+            if matching_space:
+                return Cwd(space_token=_text(matching_space["token"]))
+            available = [_text(space.get("token")) for space in self.spaces]
+            raise FsQueryError(
+                f"Space not found: {target}.",
+                code="space_not_found",
+                hint=f"Use a registered space token. Available: {', '.join(available) or '(none)'}.",
+                examples=["cd /spaces", "cd space.personal"],
+                help_query="help paths",
+            )
+        collections = list_entries(
+            self.engine.store,
+            org_token=self._org_token(),
+            space_token=self.cwd.space_token,
+            node_type="collection",
+            limit=MAX_RESULT_ITEMS,
+        )
+        matches = [
+            memory
+            for memory in collections
+            if target == memory["id"]
+            or target.lower() == _text(memory.get("display")).lower()
+        ]
+        if len(matches) != 1:
+            raise FsQueryError(
+                f"Collection {'not found' if not matches else 'is ambiguous'}: {target}.",
+                code="collection_not_found" if not matches else "ambiguous_collection",
+                hint=(
+                    "Run `ls --collections-only` and retry with an exact collection id."
+                    if not matches
+                    else "Retry with the exact collection id instead of its display name."
+                ),
+                examples=["ls --collections-only", "cd COLLECTION_ID"],
+                help_query="help cd",
+            )
+        return Cwd(space_token=self.cwd.space_token, collection_id=_text(matches[0]["id"]))
+
+    def _resolve_node(self, memory_id: str) -> Cwd:
+        memories = get_nodes(self.engine.store, [memory_id], org_token=self._org_token())
+        if not memories:
+            raise FsQueryError(
+                f"Node not found: {memory_id}.",
+                code="node_not_found",
+                hint="Use `find --id`, `ls`, or `grep` to obtain a valid node id.",
+                examples=["ls | limit 20", "find --id NODE_ID"],
+                help_query="help cd",
+            )
+        memory = memories[0]
+        space_tokens = [
+            token for token in memory.get("scope") or [] if _text(token).startswith("space.")
+        ]
+        preferred_space = self.cwd.space_token if self.cwd.space_token in space_tokens else None
+        space_token = preferred_space or (space_tokens[0] if space_tokens else None)
+        if not space_token:
+            raise FsQueryError(
+                f"Node has no space scope: {memory_id}.",
+                code="node_without_space",
+                hint="This node cannot be navigated through the space filesystem.",
+                examples=[f"stat {memory_id}"],
+                help_query="help paths",
+            )
+        parent_id = containing_collection(
+            self.engine.store,
+            memory_id,
+            org_token=self._org_token(),
+            space_token=space_token,
+        )
+        return Cwd(space_token=space_token, collection_id=parent_id)
+
+    def _validate_cwd(self, cwd: Cwd) -> None:
+        if cwd.space_token and not any(
+            _text(space.get("token")) == cwd.space_token for space in self.spaces
+        ):
+            available = [_text(space.get("token")) for space in self.spaces]
+            raise FsQueryError(
+                f"Space not found: {cwd.space_token}.",
+                code="space_not_found",
+                hint=f"Start at `/spaces`. Available tokens: {', '.join(available) or '(none)'}.",
+                examples=["cwd=/spaces, query=ls"],
+                help_query="help paths",
+            )
+        if cwd.collection_id:
+            collections = get_nodes(
+                self.engine.store,
+                [cwd.collection_id],
+                org_token=self._org_token(),
+                space_token=cwd.space_token,
+            )
+            if not collections:
+                raise FsQueryError(
+                    f"Collection not found: {cwd.collection_id}.",
+                    code="collection_not_found",
+                    hint="Run `ls --collections-only` at the space root and copy an exact id.",
+                    examples=["ls --collections-only"],
+                    help_query="help paths",
+                )
+            collection = collections[0]
+            if collection.get("node_type") != "collection":
+                raise FsQueryError(
+                    f"cwd target `{cwd.collection_id}` is not a collection.",
+                    code="not_a_collection",
+                    hint="Use `cd @NODE_ID` to resolve a node's containing collection.",
+                    examples=[f"cd @{cwd.collection_id}"],
+                    help_query="help cd",
+                )
+
+    def _help(self, command: Command) -> list[dict[str, Any]]:
+        if len(command.tokens) > 1:
+            raise FsQueryError(
+                "`help` accepts at most one topic.",
+                code="invalid_syntax",
+                hint="Use `help`, `help commands`, or `help COMMAND`.",
+                examples=["help", "help commands", "help grep"],
+                help_query="help overview",
+            )
+        topic = command.tokens[0].lower() if command.tokens else "overview"
+        try:
+            return help_items(topic)
+        except KeyError as exc:
+            close = get_close_matches(topic, manual_topics(), n=1, cutoff=0.55)
+            suggestion = close[0] if close else "commands"
+            raise FsQueryError(
+                f"Unknown help topic: {topic}.",
+                code="unknown_help_topic",
+                hint=f"Try `help {suggestion}`.",
+                examples=["help overview", "help commands", f"help {suggestion}"],
+                help_query="help commands",
+            ) from exc
+
+
+def run_fs_query(
+    engine: ArthaEngine,
+    *,
+    query: str,
+    cwd: str | None,
+    spaces: list[dict[str, Any]],
+    org_id: str | None,
+) -> dict[str, Any]:
+    parsed_cwd = parse_cwd(cwd)
+    commands = parse_query(query)
+    executor = FsQueryExecutor(
+        engine,
+        cwd=parsed_cwd,
+        spaces=spaces,
+        org_id=org_id,
+    )
+    executor._validate_cwd(parsed_cwd)
+    result = executor.execute(commands)
+    result["query"] = query
+    result["ast"] = [
+        {"command": command.name, "tokens": list(command.tokens)}
+        for command in commands
+    ]
+    return result