Inline AI schema explanations in the editor

[josephschorr]

Summary

Adds an agent-driven Explain control to the schema editor that overlays AI-generated explanations inline in Monaco — without ever modifying the schema text. A tristate toggle (Off / Compact / Full) controls density; a Regenerate button re-runs the agent on demand.

• Off — clean schema.
• Compact — a short ghost tag at the end of each symbol's line; click a tag to expand its full explanation block.
• Full — a dimmed, indented explanation block above each definition / relation / permission / caveat.
• Hover any symbol for its full explanation, with a regenerate link.

Explanations are generated by a new explain_schema assistant client tool (the model supplies the content; nothing is written into the schema). They anchor to symbols by name via the SpiceDB parser, so they re-position as you edit and mark themselves stale (dimmed + ↻) when a symbol's body changes — regeneration is on-demand (never per-keystroke) to control token spend.

Gated entirely on AppConfig().aiEnabled.

How it works

• explain_schema client tool validates each symbol against the current parse, hashes its source for staleness, and writes a persisted Zustand store (useSchemaAnnotationStore).
• A pure resolution layer (resolve.ts) maps symbol → Monaco range and computes staleness via @authzed/spicedb-parser-js (reads caveat ranges from the raw AST to work around a v1.2.0 wrapper bug).
• renderAnnotations.ts paints after-decoration tags (Compact) and view-zone blocks (Full / click-expanded), width-constrained and indented to line up with the code.
• Wired into EditorDisplay (schema editor only) with a once-registered dsl hover provider; the hover's command: trust is scoped to the regenerate command only, so LLM-authored text can't smuggle other executable command links into a trusted tooltip.
• Backend: a short guidance paragraph added to PLAYGROUND_INSTRUCTIONS; no structural backend change — the tool executes client-side via the existing tool-handoff path.

Notable fixes made along the way

• Inline annotations weren't painting until a tab-switch/reload — the schema editor uses automaticLayout: false, so decorations/view-zones added after generation weren't flushed; a forced editor.layout() on the next frame fixes it.
• Guard against wiping prior annotations when a model call resolves zero symbols.
• Reconcile the "generating" spinner with the assistant turn lifecycle (don't clear it before the turn starts; surface turn errors).

Testing

• Unit: symbol resolution + staleness, the store, the explain_schema tool (incl. unknown-symbol handling), the generation trigger, light-markdown rendering, and the reconcileGeneratingStatus / shouldGenerate helpers.
• Browser (Playwright): the Monaco renderer — Compact tags, Full blocks-only, Compact click-to-expand, and clearing on Off.
• tsc --noEmit clean; oxlint clean aside from 2 pre-existing react/only-export-components warnings on co-located, test-imported helpers.

⚠️ The live LLM round-trip (toggle → OpenRouter → explain_schema → inline render) was verified manually with VITE_AI_ENABLED=true + an OpenRouter key. It is not covered by automated tests (there's no backend LLM mock), so give it a manual smoke test before merge.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
playground	Ready	Preview	Sep 19, 2026 4:20pm UTC