Remove junk and fragment nodes from the knowledge graph. CALL THIS when: search results are returning noise — short fragments like "what", "only core", "memory" that clearly have no semantic value. Run after a heavy ingestion session to keep the graph clean. DO NOT call this obsessively. Run once every 50-100 ingestions, not after every ingest. Over-cleaning removes nodes that are building blocks for relationships. Removes nodes where: - content length < min_content_length (default 15 chars) - node has zero relationships AND zero semantic neighbors - content is a single stopword with no context Args: min_content_length: Minimum characters for a node to survive. Default 15.

State Verifier — 3-Tier QA Coverage for SQUAD Products. SUMA Testing Manifesto (sealed April 13, 2026): 200 OK is not a test. It is a rumor. Every write operation must be followed by a database assertion. Every endpoint is a button. Every button must have a test. MODES: READ (default): Returns coverage report from testframe_reports DB. Classifies gaps by tier and severity. Identifies "shallow" tests (status-code-only, no DB assertion). GENERATE (mode="generate"): Uses OPTION C: SUMA graph (WHY/WHAT) + your code_context (HOW) Generates test scaffolds in 3 tiers: - Component: endpoint isolation, UI element presence - Technical: DB state verification after API calls (State Verifier pattern) - Functional: end-to-end business workflow with all-layer assertions Requires code_context (paste the relevant file/endpoint code). The 3-Tier taxonomy: component → Single endpoint or UI element in isolation technical → Database state AFTER API call (State Verifier) functional → Complete business workflow, all layers verified The gap severity taxonomy: missing → No test exists (CRITICAL) not_implemented → Planned but not written (HIGH) shallow → Test exists but only checks HTTP status, no DB assertion (HIGH) flaky → Non-deterministic (HIGH) skipped → Marked skip/todo (MEDIUM) dead_end → Tests a UI element that no longer exists (LOW, cleanup) Args: product: Product to query (e.g. "squad-suma-mcp", "squad-qms", "squad-ghostgate"). If omitted in READ mode, returns all products. area: Filter by test area (e.g. "auth", "ingest", "assign"). Optional. mode: "read" (default) or "generate" (AI test generation via Option C). tier_filter: Filter by test tier — "component", "technical", or "functional". If omitted, all tiers returned. decision_graph: Hierarchical Tech Questionnaire (REQUIRED for generate mode). Structure: { "platform": { "type": "web|android|ios|api|robotics", "framework": "React|Flutter|FastAPI|etc", "auth_mode": "GhostGate|GoogleSSO|JWT|none" }, "database": { "engine": "postgresql|sqlite|none", "orm": "prisma|sqlalchemy|none", "target_table": "table_name" } } code_context: Optional raw code string to test (UI components, API routes). ingest_snapshot: If True, saves coverage state as a K-WIL graph node. Returns (READ mode): overall_coverage_pct, products[], gaps_by_tier, shallow_tests, recommendation Returns (GENERATE mode): component_tests[], technical_tests[], functional_tests[], manifesto_violations[]

Generate industry-standard documentation for any project using SUMA graph memory. This tool does NOT fabricate. It retrieves real war stories, architecture rulings, and deployment facts from the K-WIL graph, then uses Gemini to render them as professional documentation. The graph IS the source of truth — suma_doc makes it readable. Why this beats a generic doc generator: Generic: "Here is how to install." (stateless, stale, hallucinated) suma_doc: "We chose REST over MCP because [Architect Ruling Apr 5]. Here is how it works in production: [real deployment from graph]. Avoid X — we tried it and [root cause]." Args: prompt: What documentation to generate. Be specific. Examples: "Write a README for the SUMA MCP Server API" "Generate an ARCHITECTURE.md explaining the ring_search algorithm" "Write a CHANGELOG entry for today's /api/wakeup deployment" "Create an API reference for /api/ingest and /api/search" "Write an onboarding guide for a new backend engineer joining the QMS team" project: Optional filter to narrow graph search to a specific product. Examples: "suma-mcp", "squad-qms", "squad-ghostgate", "squad-companion" doc_type: Optional hint to shape output format. "readme" → GitHub README with badges + sections "architecture" → Design doc with decisions, trade-offs, diagrams description "api_reference" → Endpoint table + request/response examples "changelog" → Conventional Commits format, grouped by type "onboarding" → Step-by-step guide for a new engineer "runbook" → Ops runbook with commands, failure modes, escalation If omitted, Gemini infers the best format from the prompt. Returns: document: The generated documentation (markdown) nodes_used: Number of graph nodes retrieved as source material source_summary: Brief description of what the graph provided doc_type_detected: What format was generated

Query relationships (edges) in the graph. Use this to explore how entities are connected. Relationships have: - emotional_valence: -1.0 (negative) to +1.0 (positive) - evidence_node_id: The note that proves this relationship - context_snippet: The sentence that established it Args: entity_id: Filter edges connected to this entity relation_type: Filter by relationship type (e.g. "works_with", "created", "part_of") min_valence: Only return edges with emotional_valence >= this value limit: Max edges to return. Default 50. Returns: List of edges with their metadata.

List all entities (Spheres) in the graph, sorted by gravitational mass. FRACTAL ONTOLOGY: Every entity IS a sphere. Rajesh is a sphere, Work is a sphere, iPhone 15 is a sphere. The only difference is gravitational mass (degree = edge count) and flavor (entity_type). Entity flavors: person, place, object, concept, event, organization, category Args: entity_type: Filter by flavor (e.g. "person", "concept", "category") min_degree: Only return entities with at least this many connections limit: Max entities to return. Default 50. Returns: List of entities with their metadata.

Query a specific entity (person, concept, place, etc.) from the graph. Use this to answer "Who is X?" or "What is Y?" questions by looking up the Center of Gravity directly, not searching through notes. Args: name: Entity name to look up (e.g. "Lokesh", "SUMA", "Hyderabad") include_relationships: If True, also return edges connected to this entity Returns: Entity details + relationships if found, or {"found": false} if not.