docs(decision): DD-071 — schema-aware LSP completion for REQ-246 authoring friction (#546)

[avrabe]

Design decision for REQ-246 (#546)

A user finds raw-YAML artifact editing cumbersome — "we should have all in common but we miss the UI for helping humans to work with."

DD-071 decides: deliver the authoring help on the surface that already is "all in common" — the rivet LSP — by making its completion schema-aware, rather than standing up a new editing surface (a rivet serve write form or a VSIX webview form).

Why the LSP (grounded in source)

• Artifact writes already funnel through one core — rivet-core/src/mutate.rs (allowlist serializer render_artifact_yaml) — shared by the CLI and the MCP tools. The gap is not a missing writer; it's that nothing helps a human fill in a correct artifact while editing.
• The LSP already registers completion_provider (main.rs:17205) and the VSIX already runs it as a LanguageClient (extension.ts:176) — but lsp_completions (main.rs:18205) only offers artifact-IDs after target:/[[ and already-seen types after type:; it ignores the schema.
• The schema already exposes everything a form/completion needs: per-type fields with required flags, link-types with allowed target types (from_type_can_link), and enum values (schema.rs:1320/1334/258/272).

Consequence (the REQ-246 implementation this unblocks)

Enrich lsp_completions to offer, from the schema: field names (with required markers), enum field values, link types + valid target types, and a per-artifact-type skeleton snippet — validated against the same rules validate_add/validate_modify enforce, so suggestions match what the writer accepts. YAML stays canonical; no new write surface; every LSP editor benefits (not just VS Code).

Alternatives rejected

• Dashboard edit form — would stand up the first-ever server write path in serve (today strictly read-only for artifacts) plus CSRF/origin surface.
• VSIX webview form — a new UI bound to one editor; still needs the same schema-driven field model; viable as a later increment reusing this schema model.

Advances REQ-246 draft → approved. rivet validate PASS.

Refs: REQ-246, FEAT-001

🤖 Generated with Claude Code

[github-actions]

📐 Rivet artifact delta

Change	Count
Added	1
Removed	0
Modified	1
Downstream impacted (depth ≤ 5)	0

Graph

graph LR
  REQ_246["REQ-246"]:::modified
  DD_071["DD-071"]:::added
  classDef added fill:#d4edda,stroke:#28a745,color:#155724
  classDef removed fill:#f8d7da,stroke:#dc3545,color:#721c24
  classDef modified fill:#fff3cd,stroke:#ffc107,color:#856404
  classDef overflow fill:#e2e3e5,stroke:#6c757d,color:#495057,stroke-dasharray: 3 3

Loading

Added

• DD-071

Modified

ID	Changes
REQ-246

📎 Full HTML dashboard attached as workflow artifact rivet-delta-pr-659 — download from the workflow run.

_{Posted by rivet-delta workflow. The graph shows only changed artifacts; open the HTML dashboard (above) for full context.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!