docs: recommend dialogApi + use*Dialog hook as the default pattern

[pendragon25]

Summary

Flips the outdated "prefer inline useState dialogs" guidance in AGENTS.md and docs/ui/dialog.md to recommend the project's actual convention: a use*Dialog hook that wraps dialogApi.open(...).

CodeRabbit has been flagging dialogApi-based dialogs as convention violations on PRs (most recently #274). @CptnFizzbin confirmed on that thread that the guidance is out of date and asked for the docs to be updated.

Why the old guidance no longer applies

The old text claimed dialogApi "renders outside the provider tree" so dialogs lost access to CharacterSheetProvider. That's no longer true:

• DialogApiProvider is mounted inside CharacterSheetProvider in the character routes ($characterId.tsx) and inside the builder root.
• DialogErrorBoundary already catches OutOfContextError and gracefully shows an alert if a future tree ever did drop a provider.

A quick audit of the codebase: 38 dialogs use the use*Dialog + dialogApi pattern (e.g. useAddKarmaDialog, useActiveSkillDialog, useSpellFormDialog, useConfirmDialog, every dialog under src/components/items/dialogs/). Zero use the inline useState pattern the guideline currently recommends.

What changed

• AGENTS.md → Dialog patterns — first bullet flipped; the other two (compound Dialog, useConfirmDialog) stay verbatim.
• docs/ui/dialog.md:
  • "Inline useState dialog (no DialogApi)" section intro reframed from "prefer this pattern" to "use only when no DialogApi is available." The example code below stays — it's still valid when applicable.
  • Guidelines section first bullet flipped to recommend the useDialogApi + use*Dialog hook pattern; the other three bullets unchanged.

Test plan

• grep "Prefer inline" AGENTS.md docs/ returns no matches.
• grep "renders outside the provider tree" returns no matches.
• Both files render cleanly in markdown preview.
• CodeRabbit dry-run: the next review on a PR using dialogApi should no longer flag the pattern. (No way to verify short of opening another PR — flagging for the next review cycle.)

Docs-only change — no code, no tests, no CI surface affected.

[coderabbitai]

Warning

Review limit reached

@CptnFizzbin, we couldn't start this review because you've used your available PR reviews for now.

Your plan includes 1 review of capacity. Refill in 30 minutes and 54 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1fce9737-ac64-4845-a190-2f9f17325da4

📥 Commits

Reviewing files that changed from the base of the PR and between 6bc7fdf and 3c6b2e8.

📒 Files selected for processing (2)

• AGENTS.md
• docs/ui/dialog.md

Walkthrough

This PR updates documentation guidance across two files to establish useDialogApi + use*Dialog hook pattern as the preferred dialog approach. It clarifies that DialogApiProvider context is already available in the app's provider tree and that inline useState dialogs should be reserved for scenarios where the API context is inaccessible.

Changes

Dialog Pattern Guidance

Layer / File(s)	Summary
Dialog pattern documentation updates AGENTS.md, docs/ui/dialog.md	Dialog patterns guidance in AGENTS.md updated to prefer dialogApi + use*Dialog hook pattern over inline useState. docs/ui/dialog.md clarified with notes that DialogApiProvider is mounted within CharacterSheetProvider and that inline useState pattern is fallback-only, with Guidelines section revised to recommend the hook pattern.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly summarizes the main change: recommending dialogApi + use*Dialog hook as the default pattern, which matches the primary objective of flipping guidance in the documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/dialog-pattern-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pendragon25]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.