@rubytech/create-realagent 1.0.628 → 1.0.631

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -29,7 +29,10 @@ set -euo pipefail
 # --------------------------------------------------------------------------
 
 # shellcheck source=_stream-log.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_stream-log.sh"
+# Resolve symlinks before dirname — ~/setup-tunnel.sh is installed as a symlink
+# (see packages/create-maxy/src/index.ts:installTunnelScripts), so the raw
+# BASH_SOURCE[0] points at $HOME, not the scripts directory where _stream-log.sh lives.
+source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
 require_stream_log_path setup-tunnel
 
 # --------------------------------------------------------------------------
@@ -303,7 +306,23 @@ echo "wrote ${CFG_DIR}/tunnel.state"
 # --------------------------------------------------------------------------
 # Restart the brand's user-space service so resume-tunnel.sh (its
 # ExecStartPre) picks up the new tunnel.state + config.yml and spawns the
-# connector. The script is autonomous — it completes the deployment.
+# connector.
+#
+# CRITICAL: this script runs inside ${BRAND}.service's cgroup whenever the
+# admin agent invokes it via the Bash tool. `systemctl --user restart
+# ${BRAND}.service` from inside that cgroup SIGTERMs the whole cgroup —
+# the node server, the claude subprocess, the Bash child, and this script
+# itself (Task 558). Dispatching the restart to a transient systemd-run
+# unit is the ONLY primitive that creates a new cgroup outside the service
+# — setsid/nohup/disown/& all inherit cgroup membership, and
+# `systemd-run --scope` runs in the caller's scope.
+#
+# The transient timer fires $RESTART_DELAY seconds after dispatch; the
+# script exits 0 cleanly in microseconds, then the timer restarts the
+# service from its own cgroup — semantically identical to an operator
+# SSH-invoked `systemctl restart`. Post-restart verification (connector
+# up + hostname probe) is out of scope here — the client reconnects and
+# the next admin turn can verify via MCP tools.
 # --------------------------------------------------------------------------
 
 if ! systemctl --user list-unit-files "${BRAND}.service" --no-pager --no-legend | grep -q "${BRAND}.service"; then
@@ -312,48 +331,57 @@ if ! systemctl --user list-unit-files "${BRAND}.service" --no-pager --no-legend
   exit 1
 fi
 
-echo "Restarting ${BRAND}.service to spawn the connector with the new tunnel state..."
-systemctl --user restart "${BRAND}.service"
-
-# Give resume-tunnel.sh a moment to spawn the connector before probing.
-sleep 3
+if ! command -v systemd-run >/dev/null 2>&1; then
+  phase_line setup-tunnel step=service-restart-dispatched result=error \
+    reason=systemd-run-missing
+  echo "ERROR: systemd-run is not in PATH." >&2
+  echo "       The script dispatches the ${BRAND}.service restart to a transient" >&2
+  echo "       systemd user unit so it does not kill its own cgroup (Task 558)." >&2
+  echo "       Install systemd userspace (standard on supported Maxy Pi images)." >&2
+  exit 1
+fi
 
-# --------------------------------------------------------------------------
-# Post-restart verification — connector running and subdomains live?
-# Poll each hostname up to VERIFY_TIMEOUT seconds so DNS propagation has
-# time to catch up (subdomains routed by cloudflared typically resolve
-# within 10-30s; apex-flattened or freshly-created records may need longer).
-# --------------------------------------------------------------------------
+RESTART_DELAY=3
+TRANSIENT_UNIT="maxy-tunnel-restart-$$-$(date +%s)"
+phase_line setup-tunnel step=service-restart-dispatched \
+  unit="${TRANSIENT_UNIT}" delay="${RESTART_DELAY}s" \
+  cmd="systemctl --user restart ${BRAND}.service"
+
+# Dispatch via systemd-run --user --on-active — creates a transient unit
+# with its own cgroup that fires the restart after RESTART_DELAY seconds.
+# --collect auto-GCs the unit after it terminates. The script exits before
+# the timer fires; no race because the exit is microseconds and the timer
+# is seconds. Capture stderr so the operator sees the actual systemd-run
+# failure reason (e.g. "Failed to connect to bus" when linger is disabled).
+SYSTEMD_RUN_ERR="$(mktemp -t maxy-systemd-run-err.XXXXXX)"
+if systemd-run --user --unit="${TRANSIENT_UNIT}.service" \
+    --description="Detached restart of ${BRAND}.service (Task 558)" \
+    --on-active="${RESTART_DELAY}s" \
+    --collect \
+    /bin/systemctl --user restart "${BRAND}.service" 2>"${SYSTEMD_RUN_ERR}"; then
+  RESTART_RC=0
+else
+  RESTART_RC=$?
+fi
 
-if ! ps -ef | grep -q "[c]loudflared.*--config ${CFG_DIR}/config.yml"; then
-  echo "" >&2
-  echo "ERROR: ${BRAND}.service restarted but no cloudflared connector is running" >&2
-  echo "       with --config ${CFG_DIR}/config.yml." >&2
-  echo "       Check ${HOME}/.${BRAND}/logs/cloudflared.log for the failure reason." >&2
+if [ "${RESTART_RC}" -ne 0 ]; then
+  STDERR_TEXT="$(cat "${SYSTEMD_RUN_ERR}" 2>/dev/null | tr '\n' ' ' | head -c 500 || echo 'unavailable')"
+  rm -f "${SYSTEMD_RUN_ERR}"
+  phase_line setup-tunnel step=service-restart-dispatched result=error \
+    reason=systemd-run-failed exit="${RESTART_RC}" unit="${TRANSIENT_UNIT}" \
+    stderr="${STDERR_TEXT}"
+  echo "ERROR: systemd-run failed to dispatch the transient restart (exit=${RESTART_RC})." >&2
+  echo "       systemd-run stderr: ${STDERR_TEXT}" >&2
+  echo "       If stderr mentions 'Failed to connect to bus', the user-scope systemd" >&2
+  echo "       instance isn't running. Fix: 'loginctl enable-linger \$(whoami)' and retry." >&2
+  echo "       The service was NOT restarted. Re-run the script or restart manually:" >&2
+  echo "         systemctl --user restart ${BRAND}.service" >&2
   exit 1
 fi
+rm -f "${SYSTEMD_RUN_ERR}"
 
-VERIFY_TIMEOUT=60
-POLL_INTERVAL=5
-echo "Connector running against ${CFG_DIR}/config.yml — verifying each subdomain hostname (up to ${VERIFY_TIMEOUT}s per host for DNS propagation):"
-for H in "${HOSTNAMES[@]}"; do
-  if is_apex "$H"; then continue; fi
-  ELAPSED=0
-  STATUS="000"
-  while [ "${ELAPSED}" -lt "${VERIFY_TIMEOUT}" ]; do
-    STATUS=$(curl -o /dev/null -s -w '%{http_code}' --max-time 5 -I "https://${H}" || echo "000")
-    if [ "${STATUS}" != "530" ] && [ "${STATUS}" != "000" ]; then
-      break
-    fi
-    sleep "${POLL_INTERVAL}"
-    ELAPSED=$((ELAPSED + POLL_INTERVAL))
-  done
-  if [ "${STATUS}" = "530" ] || [ "${STATUS}" = "000" ]; then
-    echo "  ${H}: HTTP ${STATUS} after ${VERIFY_TIMEOUT}s — DNS propagation slow or connector-to-edge issue"
-  else
-    echo "  ${H}: HTTP ${STATUS} — live (after ${ELAPSED}s)"
-  fi
-done
+phase_line setup-tunnel step=service-restart-armed exit=0 unit="${TRANSIENT_UNIT}"
+echo "${BRAND}.service restart armed via ${TRANSIENT_UNIT} (fires in ${RESTART_DELAY}s)."
 
 # --------------------------------------------------------------------------
 # Apex ACTION REQUIRED summary
@@ -377,6 +405,8 @@ if [ "${#APEX_HOSTNAMES[@]}" -gt 0 ]; then
   echo "============================================================"
 fi
 
+phase_line setup-tunnel step=done tunnel="${TUNNEL_NAME}" id="${TUNNEL_ID}"
 echo ""
 echo "Done. tunnel=${TUNNEL_NAME} id=${TUNNEL_ID}"
-echo "Verify subdomain hostnames with: curl -I https://${HOSTNAMES[0]}"
+echo "Service will restart in ~${RESTART_DELAY}s to load the new config."
+echo "Verify hostnames with: curl -I https://${HOSTNAMES[0]}"

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -20,7 +20,7 @@ Any Cloudflare action outside these four surfaces is a discipline violation —
 
 ## 1. Autonomous path — `setup-tunnel.sh`
 
-Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, service restart, and post-restart verification — all in one invocation. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
+Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, and dispatches the `${BRAND}.service` restart to a transient `systemd-run` unit (Task 558) — all in one invocation. The restart fires a few seconds after the script exits so the script does not kill its own cgroup when invoked via the Bash tool; the chat UI receives a `server_shutdown` SSE frame and reconnects automatically. Post-restart hostname verification is out of scope for the script (connector is not up when the script exits) — verify via the next admin turn or manually with `curl -I https://<hostname>`. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
 
 ### Inputs to collect before invoking
 

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -80,6 +80,14 @@ Ask naturally:
 - "What did I last discuss about the Acme proposal?"
 - "Who have I met from the fintech conference?"
 
+## Listing and counting (Task 557)
+
+Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
+
+You can also open the Neo4j Browser at any time from the burger menu → **Graph**. Sign in with your Neo4j username (`neo4j`) and password (stored in `config/.neo4j-password` on the device). Run `MATCH (n) RETURN n LIMIT 25` for a visual overview of your graph, or write your own Cypher for ad-hoc exploration.
+
+The browser reaches only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop.
+
 ## Privacy
 
 All memory is stored on your local Raspberry Pi. The Neo4j database never leaves your network. Maxy does not sync memory to any cloud service or third party.

package/payload/platform/plugins/memory/mcp/scripts/graph/accept.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Task 557 acceptance harness for the graph MCP integration.
+#
+# Spawns the graph shim, drives it as a JSON-RPC client over stdio, runs
+# one query per acceptance class, prints PASS/FAIL per check, and exits
+# non-zero if any check fails. Assumes the brand's Neo4j is running and
+# the fixture in fixture.cypher has been seeded.
+#
+# Usage:
+#   PLATFORM_ROOT=~/.maxy/platform bash accept.sh           # infers NEO4J_URI from env
+#   PLATFORM_ROOT=~/.maxy/platform NEO4J_URI=bolt://localhost:7687 bash accept.sh
+#
+# Dependencies: node, python3 (for JSON-RPC framing), uvx (via the shim).
+#
+# Exit codes:
+#   0  all PASS
+#   1  one or more FAIL
+#   2  setup error (shim missing, uvx missing, etc.)
+
+set -euo pipefail
+
+PLATFORM_ROOT="${PLATFORM_ROOT:-$(cd "$(dirname "$0")/../../../../.." && pwd)}"
+SHIM="${PLATFORM_ROOT}/lib/graph-mcp/dist/index.js"
+
+if [[ ! -f "$SHIM" ]]; then
+  echo "FAIL: shim not built at $SHIM — run 'npm run build:lib' in $PLATFORM_ROOT" >&2
+  exit 2
+fi
+
+if ! command -v uvx >/dev/null 2>&1; then
+  echo "FAIL: uvx not on PATH — run: curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y" >&2
+  exit 2
+fi
+
+PASS=0
+FAIL=0
+TOTAL=0
+
+run_check() {
+  local label="$1"
+  local query="$2"
+  local tool="${3:-maxy-graph_read_neo4j_cypher}"
+  TOTAL=$(( TOTAL + 1 ))
+
+  # Drive the shim via a short Node inline client. Exits 0 with the response
+  # body on stdout when the tool call succeeds; exits 1 on any RPC error.
+  if out=$(
+    node -e "
+      const { spawn } = require('node:child_process');
+      const shim = process.env.SHIM;
+      const tool = process.env.TOOL;
+      const query = process.env.QUERY;
+      const proc = spawn('node', [shim], { stdio: ['pipe', 'pipe', 'inherit'] });
+      let buf = '';
+      proc.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
+      const send = (obj) => proc.stdin.write(JSON.stringify(obj) + '\n');
+      send({ jsonrpc: '2.0', id: 1, method: 'initialize',
+             params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'accept.sh', version: '1.0' } } });
+      setTimeout(() => {
+        send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+        const params = tool === 'maxy-graph_get_neo4j_schema' ? {} : { query };
+        send({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: tool, arguments: params } });
+      }, 1500);
+      setTimeout(() => {
+        proc.kill('SIGTERM');
+        // Look for id:2 response in the buffer
+        const lines = buf.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try { const m = JSON.parse(line); if (m.id === 2) {
+            if (m.error) { console.error('RPC_ERROR: ' + JSON.stringify(m.error)); process.exit(1); }
+            const text = m.result && m.result.content && m.result.content[0] && m.result.content[0].text || '';
+            process.stdout.write(text);
+            process.exit(0);
+          } } catch (_) {}
+        }
+        console.error('NO_RESPONSE');
+        process.exit(1);
+      }, 10000);
+    " 2>/dev/null
+  ); then
+    if [[ -n "$out" ]]; then
+      echo "PASS: ${label} (response ${#out}b)"
+      PASS=$(( PASS + 1 ))
+    else
+      echo "FAIL: ${label} (empty response)"
+      FAIL=$(( FAIL + 1 ))
+    fi
+  else
+    echo "FAIL: ${label} (RPC error or timeout)"
+    FAIL=$(( FAIL + 1 ))
+  fi
+}
+
+# Exported env used by the inline Node client above.
+export SHIM
+export PLATFORM_ROOT
+
+export TOOL="maxy-graph_get_neo4j_schema"
+export QUERY=""
+run_check "get_neo4j_schema returns labels" ""
+
+export TOOL="maxy-graph_read_neo4j_cypher"
+
+export QUERY="MATCH (n) RETURN labels(n)[0] AS type, count(*) AS n ORDER BY n DESC LIMIT 20"
+run_check "enumerate by label" "$QUERY"
+
+export QUERY="MATCH (n:Task) RETURN count(n) AS total"
+run_check "count Tasks" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'}) RETURN elementId(p) AS id, p.givenName, p.email LIMIT 1"
+run_check "find person by email" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'})-[r]-(m) RETURN type(r) AS rel, labels(m)[0] AS neighbourType LIMIT 10"
+run_check "neighbours of fixture person" "$QUERY"
+
+export QUERY="MATCH (n) WHERE n.createdAt IS NOT NULL RETURN labels(n)[0] AS type, toString(n.createdAt) AS createdAt ORDER BY n.createdAt DESC LIMIT 5"
+run_check "recent nodes projection" "$QUERY"
+
+export QUERY="CALL db.labels() YIELD label RETURN label ORDER BY label"
+run_check "db.labels() schema introspection" "$QUERY"
+
+echo ""
+if [[ $FAIL -eq 0 ]]; then
+  echo "ALL PASS — ${PASS}/${TOTAL}"
+  exit 0
+else
+  echo "FAIL — ${PASS}/${TOTAL} passed, ${FAIL} failed"
+  exit 1
+fi

package/payload/platform/plugins/memory/mcp/scripts/graph/fixture.cypher

@@ -0,0 +1,59 @@
+// Task 557 — acceptance fixture for the graph MCP integration.
+// Seeds one node per primary label so accept.sh can verify enumerate,
+// count, find, neighbours, recent, and schema queries end-to-end.
+// Safe to re-run: MERGE on a synthetic accountId prefix + deterministic ids.
+
+MERGE (p:Person {email: 'graph-accept@test.maxy.local'})
+  ON CREATE SET p.givenName = 'Graph',
+                p.familyName = 'Accept',
+                p.telephone = '+440000557001',
+                p.status = 'active',
+                p.accountId = 'accept-557',
+                p.createdAt = datetime()
+MERGE (b:LocalBusiness {accountId: 'accept-557'})
+  ON CREATE SET b.name = 'Accept Corp',
+                b.businessType = 'test-fixture',
+                b.createdAt = datetime()
+MERGE (s:Service {serviceId: 'accept-557-service-1'})
+  ON CREATE SET s.name = 'Test Service',
+                s.accountId = 'accept-557',
+                s.createdAt = datetime()
+MERGE (t:Task {taskId: 'accept-557-task-1'})
+  ON CREATE SET t.title = 'Acceptance task',
+                t.status = 'open',
+                t.priority = 'P2',
+                t.accountId = 'accept-557',
+                t.createdAt = datetime()
+MERGE (e:Event {eventId: 'accept-557-event-1'})
+  ON CREATE SET e.name = 'Acceptance event',
+                e.status = 'scheduled',
+                e.startDate = datetime(),
+                e.accountId = 'accept-557',
+                e.createdAt = datetime()
+MERGE (c:Conversation {conversationId: 'accept-557-conv-1'})
+  ON CREATE SET c.name = 'Acceptance conversation',
+                c.agentType = 'admin',
+                c.accountId = 'accept-557',
+                c.createdAt = datetime()
+MERGE (m:Message {messageId: 'accept-557-msg-1'})
+  ON CREATE SET m.role = 'user',
+                m.content = 'Acceptance test message',
+                m.accountId = 'accept-557',
+                m.createdAt = datetime()
+MERGE (kd:KnowledgeDocument {attachmentId: 'accept-557-doc-1'})
+  ON CREATE SET kd.name = 'Acceptance document',
+                kd.accountId = 'accept-557',
+                kd.createdAt = datetime()
+MERGE (sec:Section {sectionId: 'accept-557-sec-1'})
+  ON CREATE SET sec.title = 'Section one',
+                sec.accountId = 'accept-557',
+                sec.createdAt = datetime()
+MERGE (ch:Chunk {chunkId: 'accept-557-chk-1'})
+  ON CREATE SET ch.text = 'Chunk text for acceptance.',
+                ch.accountId = 'accept-557',
+                ch.createdAt = datetime()
+MERGE (p)-[:WORKS_FOR]->(b)
+MERGE (b)-[:OFFERS]->(s)
+MERGE (kd)-[:HAS_SECTION]->(sec)
+MERGE (sec)-[:HAS_CHUNK]->(ch)
+MERGE (c)-[:HAS_MESSAGE]->(m);

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -0,0 +1,195 @@
+<!-- Injected into admin system prompt by claude-agent.ts when agentType === "admin". -->
+<!-- Consumed by the upstream mcp-neo4j-cypher server via `maxy-graph_read_neo4j_cypher`. -->
+<!-- Source of truth for node labels and properties: platform/neo4j/schema.cypher + plugins/memory/references/schema-*.md. -->
+
+# Graph interrogation (read-only Cypher cookbook)
+
+When a user asks a relational question about their own graph — *"list all my
+people", "how many tasks do I have", "find the person with email X", "what's
+linked to this business", "show me the 20 most recently created nodes" — use
+`maxy-graph_read_neo4j_cypher` or `maxy-graph_get_neo4j_schema`, not
+`memory-search`. Vector search is for "things like this"; Cypher is for "the
+exact set where".
+
+The connected Neo4j instance contains only this brand's data (per-brand
+instance architecture — see `.docs/neo4j.md`). You never need an account
+filter in the query.
+
+## Non-negotiable: never return raw nodes
+
+`RETURN n` dumps every property, including the 768-dim `embedding` float
+array. This blows the context budget on the first row. **Always enumerate the
+properties you want.**
+
+  Wrong: `MATCH (n:Person) RETURN n LIMIT 20`
+  Right: `MATCH (n:Person) RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone LIMIT 20`
+
+Apply this convention to every query. Only project the fields you need to
+answer the question. When in doubt, exclude `embedding`, `embeddingText`, and
+any property whose name ends in `_vector`.
+
+## Cookbook
+
+Parameterise results with `ORDER BY` and `LIMIT` every time — even an
+"inventory" query should bound itself. Default limit: 50.
+
+### Enumerate
+
+All nodes, grouped by label, with a human-readable name:
+
+```cypher
+MATCH (n)
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       elementId(n) AS id
+ORDER BY type, name
+LIMIT 200
+```
+
+One label only:
+
+```cypher
+MATCH (n:Person)
+RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone
+ORDER BY n.familyName, n.givenName
+LIMIT 100
+```
+
+### Count
+
+Total across the graph:
+
+```cypher
+MATCH (n)
+RETURN count(n) AS total
+```
+
+By label:
+
+```cypher
+MATCH (n)
+RETURN labels(n)[0] AS type, count(*) AS n
+ORDER BY n DESC
+```
+
+### Find
+
+By exact email:
+
+```cypher
+MATCH (p:Person {email: $email})
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.telephone, p.status
+```
+
+Partial name, case-insensitive:
+
+```cypher
+MATCH (p:Person)
+WHERE toLower(p.givenName) CONTAINS toLower($q)
+   OR toLower(p.familyName) CONTAINS toLower($q)
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.email
+LIMIT 20
+```
+
+### Neighbours
+
+What is linked to a node (1 hop out, undirected):
+
+```cypher
+MATCH (n)-[r]-(m)
+WHERE elementId(n) = $id
+RETURN type(r) AS rel,
+       labels(m)[0] AS neighbourType,
+       coalesce(m.name, m.title, m.email, '(unnamed)') AS neighbour,
+       elementId(m) AS neighbourId
+LIMIT 50
+```
+
+### Recent
+
+Most recently created nodes (any label):
+
+```cypher
+MATCH (n)
+WHERE n.createdAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       toString(n.createdAt) AS createdAt,
+       elementId(n) AS id
+ORDER BY n.createdAt DESC
+LIMIT 20
+```
+
+Most recently updated:
+
+```cypher
+MATCH (n)
+WHERE n.updatedAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.email, '(unnamed)') AS name,
+       toString(n.updatedAt) AS updatedAt,
+       elementId(n) AS id
+ORDER BY n.updatedAt DESC
+LIMIT 20
+```
+
+### Schema
+
+All labels present in the graph:
+
+```cypher
+CALL db.labels() YIELD label RETURN label ORDER BY label
+```
+
+All relationship types:
+
+```cypher
+CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType ORDER BY relationshipType
+```
+
+Or use `maxy-graph_get_neo4j_schema` for a richer one-shot structural summary.
+
+### Fulltext
+
+Use the `knowledge_fulltext` index for keyword-style search across
+KnowledgeDocument / Section / Chunk content:
+
+```cypher
+CALL db.index.fulltext.queryNodes('knowledge_fulltext', $query)
+YIELD node, score
+WHERE score > 0.5
+RETURN labels(node)[0] AS type,
+       coalesce(node.name, node.title, node.heading, '(unnamed)') AS name,
+       score,
+       elementId(node) AS id
+LIMIT 20
+```
+
+### Filter by status or category
+
+Events that are cancelled:
+
+```cypher
+MATCH (e:Event {status: 'cancelled'})
+RETURN elementId(e) AS id, e.name, toString(e.startDate) AS start
+ORDER BY e.startDate DESC
+LIMIT 50
+```
+
+Tasks by status:
+
+```cypher
+MATCH (t:Task {status: $status})
+RETURN elementId(t) AS id, t.title, toString(t.createdAt) AS created, t.priority
+ORDER BY t.createdAt DESC
+LIMIT 50
+```
+
+## When to switch back to memory-search
+
+- "Things similar to X" → `memory-search` (vector + BM25 hybrid)
+- "Candidates to rank by criterion Y" → `memory-rank`
+- "Conversations where we discussed Z" → `conversation-search`
+
+Cypher is for relational certainty. Vector search is for similarity. They
+answer different questions; don't use one to fake the other.