> ## Documentation Index
> Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# velt-suggestions-best-practices

> Velt Suggestions implementation patterns and best practices for React, Next.js, and web applications. Use when adding suggestion mode (propose-then-review workflow), AI agent suggestion comments, accept/reject flows, suggestion targets on form inputs or custom components, suggestion status lifecycle (pending/accepted/rejected/stale), drift detection, or querying suggestions programmatically. Triggers on any task involving Velt suggestions, suggestion mode, data-velt-suggestion-target, SuggestionElement, useSuggestionUtils, enableSuggestionMode, commitSuggestion, suggestionAccepted, suggestionRejected, or building a propose-and-review editing workflow — even if the user doesn't explicitly say 'suggestions'.

This page is generated from the actual `SKILL.md` file on disk.

## Metadata

| Field               | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Source group        | User Skills                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Source root         | `/Users/meganharrison/.agents/skills`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Relative skill path | `velt-suggestions-best-practices/SKILL.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Actual file         | `/Users/meganharrison/.agents/skills/velt-suggestions-best-practices/SKILL.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Description         | Velt Suggestions implementation patterns and best practices for React, Next.js, and web applications. Use when adding suggestion mode (propose-then-review workflow), AI agent suggestion comments, accept/reject flows, suggestion targets on form inputs or custom components, suggestion status lifecycle (pending/accepted/rejected/stale), drift detection, or querying suggestions programmatically. Triggers on any task involving Velt suggestions, suggestion mode, data-velt-suggestion-target, SuggestionElement, useSuggestionUtils, enableSuggestionMode, commitSuggestion, suggestionAccepted, suggestionRejected, or building a propose-and-review editing workflow — even if the user doesn't explicitly say 'suggestions'. |
| Docs overview       | [User Skills](/skills/user-skills)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Why this exists

Use this page when you want to review the real instructions behind a skill
without leaving the docs site. The content below is copied from the actual
`SKILL.md` file, not rewritten by hand.

## Raw SKILL.md

```md theme={null}
---
name: velt-suggestions-best-practices
description: Velt Suggestions implementation patterns and best practices for React, Next.js, and web applications. Use when adding suggestion mode (propose-then-review workflow), AI agent suggestion comments, accept/reject flows, suggestion targets on form inputs or custom components, suggestion status lifecycle (pending/accepted/rejected/stale), drift detection, or querying suggestions programmatically. Triggers on any task involving Velt suggestions, suggestion mode, data-velt-suggestion-target, SuggestionElement, useSuggestionUtils, enableSuggestionMode, commitSuggestion, suggestionAccepted, suggestionRejected, or building a propose-and-review editing workflow — even if the user doesn't explicitly say 'suggestions'.
license: MIT
metadata:
  author: velt
  version: "1.0.0"
---

# 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-target` attributes 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

```