velt-js Velt Suggestions Best Practices
Comprehensive guide for implementing Velt's Suggestions API — a propose-then-review editing workflow where edits (from humans or AI agents) are captured as proposals that reviewers accept or reject. Contains 14 rules across 6 categories.
When to Apply
Reference these guidelines when:
- Adding suggestion mode to form inputs, tables, or custom components
- Implementing an AI-proposes / human-reviews workflow
- Wiring
data-velt-suggestion-targetattributes to DOM elements - Handling accept/reject events and applying accepted changes
- Querying suggestions by target or status for custom UI
- Understanding suggestion lifecycle states (pending → accepted/rejected/stale)
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Core | CRITICAL | core- |
| 2 | Targets | CRITICAL | targets- |
| 3 | Mode | HIGH | mode- |
| 4 | Capture | HIGH | capture- |
| 5 | Lifecycle | HIGH | lifecycle- |
| 6 | Data | MEDIUM | data- |
Prerequisites
Suggestions require Velt Comments to be set up — the accept/reject UI renders on the Velt comment dialog. Ensure VeltProvider is configured with authProvider and Comments are working before adding Suggestions.
Compiled Documents
AGENTS.md— Compressed index of all rules with file paths (start here)AGENTS.full.md— Full verbose guide with all rules expanded inline