Execute a read-only SQL query against the scry project database. Use this to discover project state, search docs, check coverage, inspect anchors.

Supports SELECT and WITH (CTE) queries only. All mutator keywords (INSERT, UPDATE, DELETE, DROP, etc.) are blocked.

Key tables: scry__doc — knowledge graph entries (@scry.entry markers) columns: id, kind, status, weight, summary, rationale, applies, current_path, ephemeral, missing_since, content_hash, extras (JSON1; NULL when absent), created_at, updated_at extras: single-depth scalar map per scry-spec FR4.B (v1.1.0+). Query with JSON1, e.g. SELECT id, json_extract(extras, '$.cost_usd') AS cost FROM scry__doc WHERE kind = 'deliverable' ORDER BY cost DESC scry__doc_tag — tags as a join table: doc_id, tag scry__doc_seeded_question — seeded questions: doc_id, ordinal, question scry__anchor — named code location bookmarks: id, doc_id, description, content_hash, created_at, updated_at scry__anchor_seeded_question — anchor seeded questions: anchor_id, ordinal, question scry__bind — binding markers (@scry.bind): id, source_doc_id, source_local_id, target_id, target_fragment, comment, content_hash, created_at, updated_at scry__rel — typed edges between docs: from_id, to_id, predicate (depends_on|implements|supersedes|satisfies), fragment scry__file — universal file body index: path, doc_id, body, content_hash, last_modified scry__bind_fts — full-text search over bindings (source_local_id, target_id, comment) scry__warning — lint-style warnings: id, kind, marker_kind, marker_id, file_path, message, detected_at (kinds: misplaced_doc, depends_on_cycle) scry__doc_fts — full-text search over docs (id, summary, rationale, applies, current_path) scry__doc_tag_fts — full-text search over tags (tag, doc_id UNINDEXED) scry__doc_seeded_question_fts — full-text search over seeded questions (question, doc_id UNINDEXED) scry__anchor_fts — full-text search over anchors (id, description) scry__file_fts — full-text search over file bodies (path, body); prefer scry_grep tool

Returns JSON: {"results": [...], "row_count": N}

REQUIRED before writing any @scry.* marker. Generates a collision-free ID and returns the marker schema with per-field instructions. Follow the returned instructions exactly when filling fields.

Also performs collision detection and returns warnings alongside the ID:

tier1_collisions — markers with the SAME prefix already in the DB. If any tier-1 hit is the same logical concept, ABANDON the new ID and reference the existing marker instead — stranded IDs pollute scry.

tier2_neighbors — markers in the same kind+first-segment family (informational; may reveal related prior work to link against).

Args: kind: "entry", "anchor", or "bind" prefix: Human-readable prefix. entry: MUST contain a dot (e.g. "design.auth-flow", "task.fix-bug") anchor/bind: MUST NOT contain dots (e.g. "auth-check", "validate-jwt")

Returns JSON with: id, schema (marker_open/close + per-field instructions), and optionally tier1_collisions + tier2_neighbors when they exist.

Field quality matters (FR4.A authoring guidance): summary — prose sentences + 'Also:' keyword cluster at the end. "JWT auth middleware, validates bearer tokens. Also: JWT, bearer-token, auth-guard, refresh-flow" tags — carry both classifier and bare-keyword forms. ["topic:auth", "auth", "scope:runtime", "runtime"] rationale — Why this artifact exists: the problem it solves or the role it fills. Not why you would search for it, not a findability claim, not its importance. Lesson: "prevents re-introducing the auth bypass fixed in PR 412". Design: "centralizes token checks so endpoints do not each re-implement them". Track wake: "owns the reflect-mcp build-to-PyPI path". Bad: "invisible to scry without this", "this is important". applies — verb-shaped triggers (actions, not topics). "modifying auth, adding protected endpoints" not "when working on auth" seeded_questions — include both full questions AND fragment queries. ["What is the JWT refresh flow?", "JWT refresh token implementation"]

PREFERRED over raw scry_mint. Generates a collision-free scry marker ID (same as scry_mint) and augments the response with existing-marker warnings:

Tier 1 — exact-prefix collision: markers with the same prefix already in scry__doc. If any tier-1 hit is the same logical concept, ABANDON the new ID and reference the existing marker instead — stranded IDs pollute scry.

Tier 2 — family-slug neighbors: related markers in the same slug family (informational; may reveal related prior work to link against).

Args: kind: 'entry', 'anchor', or 'bind' prefix: Human-readable prefix. entry MUST contain a dot (e.g. 'design.auth-flow', 'task.fix-bug'). anchor/bind must NOT contain dots (e.g. 'auth-check', 'validate-jwt').

Returns: id, marker schema (same as scry_mint), plus tier-1/tier-2 collision info.

Rebuild the DB from disk markers. Use after git pull, bulk file moves, or if query results seem stale. The file watcher handles live indexing — only call this for full re-scans.

Walks all project files, parses @scry.* markers, upserts to DB. Idempotent. Uses content-hash dedup.

Args: force: If true, hard-deletes records whose files no longer exist. If false (default), sets missing_since and warns. path: Optional scope, relative to project root. None (default) — full corpus walk. Current behavior, unchanged. — re-index exactly that one file. — re-index every file under that directory, recursively. If path does not exist on disk, returns a clear error. Scoped reconciliation: flagged_missing, misplaced_doc warnings, and force-deletes are all scoped to the path — docs outside the scope are never flagged as missing.

Returns JSON with counts per marker type, any warnings, and a scope field echoing the path argument (null for a full walk).

Lower the index back to disk-only state. The DB forgets; the disk remembers.

Truncates all scry index tables (scry__doc, scry__anchor, scry__bind, scry__rel, scry__file, scry__warning, and join tables) in a single atomic transaction. Schema is preserved; FTS tables update via existing triggers. Disk markers are never modified.

Requires protocol-level user confirmation via MCP elicitation before executing — the operation will not proceed if the confirmation is declined, cancelled, or unavailable.

Args: then_surface: If True, immediately runs scry_surface after the sink to rebuild the index from disk markers in a single call. Equivalent to "reset + reindex."

Returns JSON with pre-deletion counts and operation result.

Create a clean PR branch with all @scry.* markers stripped.

By default, files inside agent/** and any AGENT.md are excluded from scrubbing — their markers are left intact. Only tracked files outside the agent workspace are cleaned. This matches the common workflow: agent/ is gitignored (or excluded via .git/info/exclude), so only the tracked source files need clean markers for PR submission.

Set include_agent=true to restore the prior behavior: scrub everything and remove the agent/ directory entirely.

Creates {branch}--clean from current HEAD. Does not stage or commit — leaves unstaged changes for the user.

Fails if on main/master or if working tree is dirty.

Run validation or transformation scripts with DB access.

Actions: list — discover available scripts (bundled + project-local) run — execute a named script

Args: action: "list" or "run" script: script name (required for action="run") params: arbitrary params passed to the script (optional)

Scripts have read-write DB access. They return structured JSON.

Full-text search over all indexed file bodies (scry__file_fts).

Complements scry_sql: use this when you want broad full-text search across file content, not just curated marker fields.

Returns one hit per file (highest BM25-ranked match).

Args: query: FTS5 query string — plain words, phrases ("foo bar"), boolean (foo AND bar, foo OR bar, NOT foo). Accepts standard FTS5 syntax. kind: Optional: filter to files whose associated doc has this kind (e.g. 'design', 'lesson', 'pattern'). Files without a doc marker are excluded when this filter is set. status: Optional: filter by doc status (e.g. 'active', 'draft'). Files without a doc marker are excluded when set. path_glob: Optional: GLOB pattern on file path, e.g. 'agent/design/' or '.py'. Applied before FTS. limit: Max number of results to return (default 20).

Returns JSON: { "hits": [ { "path": "agent/design/...", "doc_id": "design.foo~abcd1234" | null, "snippet": "...text with matches highlighted...", "score": 12.4, "match_count": 3 } ], "total_matches": 47, "query": "...", "filters_applied": { "kind": null, "status": null, "path_glob": null } }

Tips:

• Combine with scry_sql: get doc IDs from scry_grep, then JOIN to scry__doc_tag or scry__doc for richer metadata.

• Use path_glob to scope to a subtree: 'agent/design/*'

• scry__file is populated during scry_surface; call that first if results are empty on a fresh DB.

Probe the scry project database and report health.

Designed for substrate code (e.g. reflection's wake.py auto-restore loop) that needs to distinguish actual corruption from transient WAL write-lock contention. The same scry-mcp connection primitives are used as for every other tool — long busy_timeout, WAL journal mode, retry semantics — so a healthy-but-busy DB will not be reported as corrupt.

Returns JSON with these fields:

status "ok" | "corrupt" | "locked" integrity result of PRAGMA integrity_check (string), or null when the probe could not run (e.g. status=locked) doc_count integer row count of scry__doc, or null when the table does not exist yet (fresh / unmigrated DB) doc_count_error populated when doc_count is null and the count query failed for a known-benign reason (table missing); null otherwise db_path absolute path to the project.db file probed error string explanation when status != "ok"; null otherwise

Status semantics for substrate decisions:

status="ok" DB is healthy. Do not quarantine. status="locked" DB is healthy but contended. Do NOT quarantine; retry the probe on the next wake. Substrate code that conflates this with corruption causes the Group-C cascade described in the May 2026 diagnostic. status="corrupt" DB failed PRAGMA integrity_check or could not be opened as a SQLite database at all. Safe to initiate auto-restore.

A status="ok" with doc_count=null and doc_count_error="no such table: scry__doc" is a fresh-and-unmigrated DB. Substrate should run migrations (or call scry_surface) rather than quarantine.