docs(migration): update NeoDash guide with corpus-tested findings

[alfredo1996]

Summary

Refresh `getting-started/migration-from-neodash.mdx` based on a real-world validation pass against the OpenStudyBuilder NeoDash corpus — 17 dashboards, 12-46 widgets each, heavy use of parameters/click actions/styling.

Sections added

• Real-world tested tip at the top with a link to the corpus
• Click actions — documents both NeoDash shapes (object `{type: 'set-parameter'}` and string `'set variable'` + customizationValue) plus the JSON example users will recognise from older NeoDash exports
• Conditional / rule-based styling — explicit operator-mapping table (= → ==, !=, <, >, <=, >=, contains) and the no-color-drop behaviour
• Auto-refresh — `refreshRate` (seconds) → `cacheTtlMinutes` mapping
• Known limitations — the one residual gap surfaced by testing (only first `actionsRules` rule converted, tracked in fix(neodash-converter): only first actionsRules rule is converted; surface dropped rules to user #882) plus the NeoDash-only built-in parameters note

Sections refined

• Chart type mapping table — adds the entries shipped in fix(neodash-converter): map text→markdown and circlePacking→circle-packing #878 (`text → markdown`, `circlePacking → circle-packing`), plus the already-supported aliases (`iframe`/`iFrame`, `choropleth`/`areamap`, `graph3d`/`3d-graph`, `gantt`) that weren't documented before
• Troubleshooting — replaces the generic items with corpus-real cases: schema-update files that aren't dashboards, the text-widget JSON-fallback bug (fixed in v1.0.1), click-action multi-rule limitation, silent auto-save bug (fixed in v1.0.1)

Companion work this session

• fix(neodash-converter): map text→markdown and circlePacking→circle-packing #878 — `text`/`circlePacking` mapping (merged)
• fix(neodash-converter): accept string-form 'set variable' actionsRules (#880) #881 — string-form action rules (merged)
• fix(neodash-converter): only first actionsRules rule is converted; surface dropped rules to user #882 — multi-rule actions limitation (issue filed)
• fix(cli): isAppReady gets 401 from /api/health — readiness check times out in real demo runs #879 — `isAppReady` 401 (issue filed)

Test plan

• Diff review — no broken anchor links, MDX syntax preserved
• CI: Astro check validates MDX build (pending)
• Visual: docs site renders the new sections correctly

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Expanded the NeoDash→NeoBoard migration guide with validated importer tips, extended widget/chart type mappings and aliases, detailed importer behavior for report/click-action and auto-refresh conversions, conditional styling/operator mapping notes, clarified known limitations (first click-action rule only, query built-in mismatches), and improved troubleshooting for format, widget alias/casing, Markdown/Text import, table click actions, layout, and saved-state issues.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8e1d5eb4-30b9-4dcc-9bdf-aa1c7edec885

📥 Commits

Reviewing files that changed from the base of the PR and between 34d218d and 50cbc9b.

📒 Files selected for processing (1)

• docs/src/content/docs/getting-started/migration-from-neodash.mdx

---

Walkthrough

Documentation update to the NeoDash→NeoBoard migration guide adding an importer validation callout, expanded widget type mappings and aliases, detailed conversion rules for click actions, conditional styling, and auto-refresh, plus expanded troubleshooting and known limitations.

Changes

NeoDash Migration Documentation

Layer / File(s)	Summary
Importer validation, widget mapping, and conversion behavior docs/src/content/docs/getting-started/migration-from-neodash.mdx	Adds "Real-world tested" callout validating importer against a NeoDash corpus; extends widget type mapping with iFrame casing variants, Text→Markdown, Select→Parameter Select, Circle Packing and Choropleth aliases, 3D Graph rendering, and Gantt; documents both object and string-form click action (Report Actions) conversion; maps NeoDash conditional styling operators to NeoBoard equivalents (including default color behavior for colorless rules); and covers auto-refresh to query caching conversion with rounding/floor behavior and known limitations for multi-rule click actions and NeoDash-only built-ins.
Troubleshooting and known limitations docs/src/content/docs/getting-started/migration-from-neodash.mdx	Updates "Invalid format" troubleshooting to cover non-dashboard NeoDash project files; explains JSON Viewer fallbacks due to unrecognized or casing-specific widget types; documents the fixed Text→Markdown import bug (v1.0.1) with re-import guidance; and adds notes about table click-action parameter import limits (only first rule), layout differences from grid systems, and saved-changes appearing lost after reload tied to an auto-save error toast fix in v1.0.1.

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• alfredo1996/neoboard#878: Introduces the same text→markdown and circlePacking→circle-packing type aliases in neodash-converter that the migration docs now document.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(migration): update NeoDash guide with corpus-tested findings' clearly summarizes the main change—a documentation update to the NeoDash migration guide based on validated real-world corpus findings.
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/neodash-migration-guide-corpus-findings

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/src/content/docs/getting-started/migration-from-neodash.mdx`:
- Line 170: The wording incorrectly states that refreshRate is "rounded up";
update the docs to say cacheTtlMinutes is derived by rounding to the nearest
minute using Math.round and then clamped to a minimum of 1 minute. Reference the
conversion from refreshRate to cacheTtlMinutes and mention Math.round and the
minimum-1 clamp so readers understand the exact behavior.
- Line 164: The doc line "Rules without a `color` value are dropped during
import — NeoBoard requires a color per rule." is incorrect because the current
converter defaults missing colors to "`#000000`" and retains those rules; update
that sentence to reflect actual behavior (e.g., "Rules without a `color` value
are retained — the converter defaults missing colors to `#000000`") or, if you
prefer to change runtime behavior instead, modify the import converter to drop
rules when `color` is missing; reference the documented sentence and the
converter behavior when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 01ee60bf-25a4-4092-9a8f-4df6ce04d9a6

📥 Commits

Reviewing files that changed from the base of the PR and between 8280eb7 and 34d218d.

📒 Files selected for processing (1)

• docs/src/content/docs/getting-started/migration-from-neodash.mdx