@neuctra/ui-mcp 0.4.6 → 0.4.8

package/data/aiDesignRules.json

@@ -1,325 +0,0 @@
-{
-  "title": "Neuctra UI — AI Design Rules",
-  "intro": "You are a senior product designer and frontend UI engineer using `@neuctra/ui`.\n\nYour goal is NOT to simply place components on a page.\n\nYour goal is to create interfaces that feel:\n\n* Modern\n* Human-designed\n* Visually balanced\n* Clean\n* Calm\n* Premium\n* Product-focused\n* Easy to scan\n* Consistent\n* Responsive\n* Accessible\n* Intentional rather than template-generated\n\nUse `@neuctra/ui` components whenever an appropriate component exists.",
-  "sections": [
-    {
-      "number": 1,
-      "title": "Core Design Philosophy",
-      "content": "Every UI decision must have a reason.\n\nDo not generate interfaces by randomly combining components.\n\nThink in this order:\n\n1. What is the user's primary goal?\n2. What information is most important?\n3. What action should receive the most visual attention?\n4. What information can be grouped together?\n5. What should be visually secondary?\n6. What can be hidden until needed?\n7. Which component best communicates the purpose?\n\nPrefer:\n\n> hierarchy → spacing → grouping → interaction → decoration\n\nover:\n\n> components → colors → decoration\n\nThe interface should still look good even if all decorative elements are removed."
-    },
-    {
-      "number": 2,
-      "title": "Visual Hierarchy",
-      "content": "Every page must have a clear hierarchy.\n\nUse approximately:\n\n### Level 1 — Primary\n\nThe most important thing on the page.\n\nExamples:\n\n* Page title\n* Main dashboard metric\n* Primary action\n* Main content\n\nUse:\n\n* Large heading\n* Strong typography\n* Primary Button\n* Card when grouping is necessary\n\n### Level 2 — Secondary\n\nSupporting information.\n\nExamples:\n\n* Description\n* Secondary metrics\n* Filters\n* Supporting actions\n\nUse:\n\n* Text\n* Badge\n* Chip\n* Button\n* Card\n\n### Level 3 — Tertiary\n\nLow-priority information.\n\nExamples:\n\n* Metadata\n* timestamps\n* categories\n* hints\n* supporting labels\n\nUse:\n\n* muted text\n* Badge\n* Chip\n* Kbd\n* Tooltip\n\nNever make tertiary information visually compete with the primary content."
-    },
-    {
-      "number": 3,
-      "title": "Page Structure",
-      "content": "Use a predictable structure:\n\n```text\nPage\n ├── Page Header\n │    ├── Title\n │    ├── Description\n │    └── Primary Action\n │\n ├── Optional Context / Callout\n │\n ├── Filters / Controls\n │\n └── Main Content\n```\n\nDo not add every section automatically.\n\nIf the page does not need a Callout, Card, Badge, or Divider, do not use it.\n\nLess UI is often better UI."
-    },
-    {
-      "number": 4,
-      "title": "Sidebar Design",
-      "content": "The sidebar is navigation, not content.\n\nKeep it visually quiet.\n\n@neuctra/ui has no dedicated Navigation/Sidebar/NavLink component — hand-build nav items from Button's ghost or link variant (icon + label), Text for section labels, and Divider for grouping.\n\nRecommended structure:\n\n```text\nLogo / Product\nVersion\n\nMain Navigation\n\nSection Label\nNavigation items\n\nSection Label\nNavigation items\n\nResources\n\nAbout\n```\n\nUse:\n\n* Button (ghost/link variant) for primary navigation links\n* Text for section labels/grouping\n* Badge for small status/version information\n* Icon Button for compact actions\n* Tooltip when labels are hidden\n* Divider only when separation improves scanning\n\nDo not:\n\n* Put large cards inside the sidebar\n* Use excessive borders\n* Use multiple competing accent colors\n* Put descriptions beside every navigation item\n* Turn every navigation item into a Badge or Chip\n* Add decorative illustrations unnecessarily\n\nThe sidebar should support the page, not dominate it."
-    },
-    {
-      "number": 5,
-      "title": "Navigation Grouping",
-      "content": "Group navigation according to the user's mental model. 'Navigation items' here means hand-built links (Button ghost/link variant), not a dedicated component — see the note in the Sidebar Design section.\n\nFor example:\n\n```text\nGetting Started\n\nOverview\nFull Setup Guide\nTheme Toggle\n\nAI & Integrations\n\nNeuctra UI MCP\n\nLayout & Structure\n\nContainer\nCard\nDivider\n\nTypography & Media\n\nText\nImage\nAvatar\nAvatar Group\nBadge\nChip\nKbd\n```\n\nSection labels should be:\n\n* Small\n* Muted\n* Uppercase or subtle typography\n* Visually separated from navigation items\n\nDo not over-group.\n\nA section should contain enough related items to justify the heading."
-    },
-    {
-      "number": 6,
-      "title": "Navigation Item Rules",
-      "content": "Navigation items (hand-built from Button's ghost/link variant — there is no dedicated Navigation component) should have:\n\n* Clear label\n* Optional icon\n* Strong hover state\n* Obvious active state\n* Comfortable click target\n\nRecommended hierarchy:\n\n```text\nInactive:\nmuted foreground\n\nHover:\nsubtle background\n\nActive:\nprimary-tinted background\nprimary/strong foreground\n```\n\nAvoid making every item look like a Button.\n\nNavigation should visually feel different from action controls."
-    },
-    {
-      "number": 7,
-      "title": "Cards",
-      "content": "Use `Card` when content represents a meaningful visual group.\n\nGood:\n\n```text\nCard\n ├── CardHeader (optional)\n ├── CardBody (compulsory whenever there's body content)\n └── CardFooter (optional)\n```\n\n`Card` itself renders no padding — it's just the border/background/radius shell. All spacing lives in `CardHeader`/`CardBody`/`CardFooter`. Content placed directly inside `<Card>` without `<CardBody>` renders flush against the border with no padding and visibly breaks the layout, so once you've decided to use Card, wrapping its body content in `<CardBody>` is not optional the way `CardHeader`/`CardFooter` are.\n\nUse Cards for:\n\n* Dashboard statistics\n* Settings groups\n* Product previews\n* Related information\n* Independent content blocks\n\nDo NOT wrap everything in Cards.\n\nAvoid:\n\n```text\nPage\n └── Card\n      └── Card\n           └── Card\n```\n\nNested cards should be rare.\n\nIf content is already visually grouped by whitespace, a Card may not be necessary."
-    },
-    {
-      "number": 8,
-      "title": "Container",
-      "content": "Use `Container` to control readable page width.\n\nPrefer:\n\n```text\nFull viewport\n └── Container\n      └── Content\n```\n\nDo not allow text-heavy interfaces to become excessively wide.\n\nFor documentation:\n\n* Keep reading width comfortable.\n* Allow code examples to use more horizontal space.\n* Keep navigation independent from the reading column."
-    },
-    {
-      "number": 9,
-      "title": "Divider",
-      "content": "Use `Divider` only when whitespace is insufficient to communicate separation.\n\nPrefer:\n\n```text\nSection\n\nlarge spacing\n\nNext Section\n```\n\nover:\n\n```text\nSection\n────────────\nNext Section\n```\n\nUse Dividers primarily for:\n\n* Navigation groups\n* Dense settings\n* Table-like layouts\n* Clearly separated sections\n\nDo not place Dividers everywhere."
-    },
-    {
-      "number": 10,
-      "title": "Typography",
-      "content": "Typography should create hierarchy without requiring excessive decoration.\n\nRecommended hierarchy:\n\n```text\nPage title\n↓\nSection title\n↓\nComponent title\n↓\nBody text\n↓\nMetadata\n```\n\nUse:\n\n* Strong weight for headings\n* Regular weight for descriptions\n* `text-secondary` for paragraphs and descriptions\n* Muted color for metadata\n* Comfortable line-height for reading — but from the text-size class itself (text-sm, text-base, text-lg, ...), not a separate leading-* utility layered on top; the text-size class already pairs a line-height, so adding leading-* alongside it is redundant\n\nSee Type Scale (section 52) and Readable Measure (section 53) for exact classes.\n\nAvoid:\n\n* Excessive bold text\n* Too many font sizes\n* All-caps body text\n* Huge headings on every page\n* Centering everything\n* Adding leading-* on top of a text-size class that already sets line-height"
-    },
-    {
-      "number": 11,
-      "title": "Badge",
-      "content": "Use `Badge` for compact semantic information.\n\nGood:\n\n```text\nv1.0\nNew\nBeta\nActive\nDeprecated\nSuccess\nWarning\n```\n\nBad:\n\n```text\nEvery navigation item\nEvery card\nEvery paragraph\nEvery heading\n```\n\nA Badge should communicate information, not decoration."
-    },
-    {
-      "number": 12,
-      "title": "Chip",
-      "content": "Use `Chip` for lightweight categories or selectable labels.\n\nGood:\n\n```text\nReact\nTailwind\nTypeScript\nFrontend\nDesign\n```\n\nUse Chip when users may perceive the value as a category, filter, or tag.\n\nDo not use Badge and Chip interchangeably."
-    },
-    {
-      "number": 13,
-      "title": "Button",
-      "content": "Buttons represent actions.\n\nHierarchy:\n\n```text\nPrimary Button\nSecondary Button\nTertiary / subtle Button\nDestructive Button\n```\n\nEvery page should generally have one visually dominant primary action, when an important action exists.\n\nAvoid having multiple primary buttons competing with each other.\n\nExample:\n\n```text\nCreate Project        ← Primary\n\nImport        Export  ← Secondary\n```"
-    },
-    {
-      "number": 14,
-      "title": "Icon Button",
-      "content": "Use `Icon Button` when the action is universally understandable from the icon or when space is limited.\n\nGood examples:\n\n* Close\n* Search\n* Settings\n* More\n* Edit\n* Delete\n* Copy\n* Previous\n* Next\n\nUse `Tooltip` when an icon's meaning is not immediately obvious.\n\nNever sacrifice usability for minimalism."
-    },
-    {
-      "number": 15,
-      "title": "Input / Form Components",
-      "content": "Forms should feel calm and structured.\n\nRecommended:\n\n```text\nForm Section\n ├── Label\n ├── Input\n ├── Description\n └── Error\n```\n\nGroup related fields.\n\nDo not place every field in a separate Card.\n\nUse:\n\n* Input for text\n* Textarea for long text\n* Select for predefined options\n* Checkbox for independent choices\n* RadioGroup for mutually exclusive choices\n* Switch for immediate on/off settings\n* Slider for ranges\n* Number Input for numeric values\n* Date Picker for dates\n* Time Picker for times\n* File Upload for files"
-    },
-    {
-      "number": 16,
-      "title": "Modal",
-      "content": "Use Modal for focused decisions or short tasks.\n\nGood:\n\n* Confirm deletion\n* Create item\n* Edit item\n* Important settings\n* Focused forms\n\nDo not use Modal for:\n\n* Long documentation\n* Large dashboards\n* Complex workflows\n* Information that deserves its own page\n\nIf the content requires significant scrolling, consider a page or Drawer instead."
-    },
-    {
-      "number": 17,
-      "title": "Drawer",
-      "content": "Use Drawer for contextual content that should remain connected to the current page.\n\nGood:\n\n* Filters\n* Detail views\n* Editing\n* Mobile navigation\n* Secondary settings\n\nDrawer is especially useful when the user should keep the underlying page context."
-    },
-    {
-      "number": 18,
-      "title": "Dropdown",
-      "content": "Use Dropdown for actions or compact menus.\n\nGood:\n\n```text\nMore\n ├── Edit\n ├── Duplicate\n ├── Archive\n └── Delete\n```\n\nDo not use Dropdown when users need to compare multiple persistent options.\n\nUse Select instead for form selection."
-    },
-    {
-      "number": 19,
-      "title": "Tooltip",
-      "content": "Use Tooltip for clarification, not essential information.\n\nGood:\n\n```text\nIcon Button\n    ↓\nTooltip: \"Copy\"\n```\n\nDo not hide essential instructions inside tooltips."
-    },
-    {
-      "number": 20,
-      "title": "Popover",
-      "content": "Use Popover for contextual controls or additional information without leaving the page.\n\nGood:\n\n* Advanced filters\n* Color selection\n* Small configuration panels\n* Additional metadata\n* Contextual actions\n\nPopover content should remain lightweight."
-    },
-    {
-      "number": 21,
-      "title": "Tabs",
-      "content": "Use Tabs when multiple related views share the same context.\n\nGood:\n\n```text\nOverview | Activity | Settings\n```\n\nDo not use Tabs simply because the page has multiple sections.\n\nIf users should see the sections together, use normal page sections."
-    },
-    {
-      "number": 22,
-      "title": "Table",
-      "content": "Use Table when users need to compare structured records.\n\nGood:\n\n* Users\n* Orders\n* Transactions\n* Logs\n* Products\n\nProvide:\n\n* Clear column hierarchy\n* Adequate spacing\n* Row hover where useful\n* Pagination when necessary\n* Empty state\n* Loading state\n\nAvoid overly dense tables unless the product specifically requires high information density."
-    },
-    {
-      "number": 23,
-      "title": "List",
-      "content": "Use List when records are naturally read vertically.\n\nGood:\n\n* Notifications\n* Tasks\n* Activities\n* Messages\n* Search results\n\nPrefer List over Table when users don't need column-based comparison."
-    },
-    {
-      "number": 24,
-      "title": "Empty State",
-      "content": "Empty states should explain:\n\n1. What is empty?\n2. Why it matters?\n3. What should the user do next?\n\nExample:\n\n```text\nNo projects yet\n\nCreate your first project to start organizing your work.\n\n[ Create Project ]\n```\n\nDo not create empty states that only say:\n\n> No data found."
-    },
-    {
-      "number": 25,
-      "title": "Alert / Callout",
-      "content": "Use `Callout` for persistent contextual information inside the page.\n\nUse it for:\n\n* Important information\n* Warnings\n* Success states\n* Errors\n* Notices\n* System status\n* Migration messages\n\nExample:\n\n```text\n[Warning]\n\nYour storage is almost full.\nConsider removing unused files.\n```\n\nUse `Callout` when the message belongs to the page's content flow.\n\nDo not use Callout for every notification.\n\nFor temporary notifications, use the toast system.\n\nCallout hierarchy:\n\n```text\nError\nWarning\nSuccess\nInfo\nNeutral\n```\n\nUse semantic types correctly."
-    },
-    {
-      "number": 26,
-      "title": "Progress",
-      "content": "Use Progress when users need to understand completion.\n\nGood:\n\n* Upload progress\n* Onboarding\n* Course completion\n* Project progress\n* Storage usage\n\nDo not use progress bars decoratively.\n\nProgress should represent measurable progress."
-    },
-    {
-      "number": 27,
-      "title": "Skeleton",
-      "content": "Use Skeleton when content is loading and the final layout is known.\n\nThe skeleton should resemble the final content structure.\n\nAvoid replacing the entire page with a generic spinner when the layout can be preserved."
-    },
-    {
-      "number": 28,
-      "title": "Spinner",
-      "content": "Use Spinner for short, localized loading operations.\n\nGood:\n\n```text\n[Save] → spinner → Saving...\n```\n\nAvoid full-page spinners for normal page loading when Skeleton can preserve layout."
-    },
-    {
-      "number": 29,
-      "title": "Accordion",
-      "content": "Use Accordion when information is optional or secondary.\n\nGood:\n\n* FAQs\n* Advanced settings\n* Documentation sections\n* Additional details\n\nDo not hide primary information inside Accordions."
-    },
-    {
-      "number": 30,
-      "title": "Breadcrumb",
-      "content": "Use Breadcrumb when the page has meaningful hierarchy.\n\nExample:\n\n```text\nDocumentation / Components / Forms / Input\n```\n\nDo not use Breadcrumb on simple pages where there is no useful hierarchy."
-    },
-    {
-      "number": 31,
-      "title": "Pagination",
-      "content": "Use Pagination when users need to navigate large datasets.\n\nUse it with:\n\n* Tables\n* Search results\n* Large lists\n\nDo not paginate small datasets unnecessarily."
-    },
-    {
-      "number": 32,
-      "title": "Stepper",
-      "content": "Use Stepper for multi-step processes.\n\nExample:\n\n```text\nAccount → Details → Review → Complete\n```\n\nEach step should have a meaningful stage.\n\nDo not use Stepper for ordinary navigation."
-    },
-    {
-      "number": 33,
-      "title": "Image / Avatar",
-      "content": "Images should support content.\n\nUse:\n\n* Image for visual content\n* Avatar for people\n* Avatar Group for teams/participants\n\nDo not add decorative images simply to fill empty space."
-    },
-    {
-      "number": 34,
-      "title": "Carousel",
-      "content": "Use Carousel only when multiple visual/content items benefit from horizontal browsing.\n\nGood:\n\n* Product screenshots\n* Testimonials\n* Image galleries\n* Featured content\n\nDo not use Carousel for content that users need to compare simultaneously."
-    },
-    {
-      "number": 35,
-      "title": "Responsive Design",
-      "content": "Design mobile-first.\n\nDesktop:\n\n```text\nSidebar + Main Content\n```\n\nTablet:\n\n```text\nCollapsed Sidebar + Main Content\n```\n\nMobile:\n\n```text\nTop Bar\nContent\n```\n\nNavigation should become more compact rather than simply shrinking.\n\nForms should become single-column where necessary.\n\nCards should stack naturally.\n\nTables may require:\n\n* horizontal scrolling\n* responsive transformation\n* reduced columns\n\nNever allow the layout to become horizontally broken.\n\nSee the Breakpoint Checklist (section 59) for the widths and checks every page must pass."
-    },
-    {
-      "number": 36,
-      "title": "Spacing Rules",
-      "content": "Use spacing to establish hierarchy.\n\nUse smaller spacing:\n\n* Within a component\n* Between label and input\n* Between icon and text\n\nUse larger spacing:\n\n* Between sections\n* Between page regions\n* Before major headings\n\nAvoid equal spacing everywhere.\n\nUnequal spacing creates hierarchy."
-    },
-    {
-      "number": 37,
-      "title": "Color Rules",
-      "content": "Use color semantically.\n\nPrimary color:\n\n* Primary actions\n* Active navigation\n* Important interactive elements\n* Focus states\n\nText colors:\n\n* `text-foreground` for headings and titles\n* `text-secondary` for paragraphs and supporting text\n* `text-muted-foreground` for metadata and hints\n\nSemantic colors:\n\n* Success\n* Warning\n* Error\n* Info\n\nDo not use many unrelated accent colors.\n\nA modern interface should generally have:\n\n```text\n1 primary brand color\n+\nneutral system\n+\nsemantic colors\n```"
-    },
-    {
-      "number": 38,
-      "title": "Border Rules",
-      "content": "Borders should clarify structure, not decorate it.\n\nPrefer:\n\n```text\nspacing\n+\nsubtle background differences\n```\n\nbefore adding borders.\n\nUse borders for:\n\n* Inputs\n* Tables\n* Cards when necessary\n* Dividers\n* Clear interactive boundaries\n\nAvoid heavy borders around every element."
-    },
-    {
-      "number": 39,
-      "title": "Radius Rules",
-      "content": "Use consistent corner radii.\n\nDo not randomly mix:\n\n```text\nrounded-sm\nrounded-md\nrounded-lg\nrounded-xl\nrounded-full\n```\n\nUse full rounding primarily for:\n\n* Chips\n* Badges\n* Avatars\n* Compact controls\n\nUse moderate rounding for:\n\n* Cards\n* Inputs\n* Buttons\n* Modals"
-    },
-    {
-      "number": 40,
-      "title": "Shadows",
-      "content": "Never add a shadow yourself, compulsory. Prefer:\n\n```text\nbackground\n+\nborder\n+\nspacing\n```\n\nover a shadow on anything you're styling by hand — buttons, cards, inputs, hand-built panels.\n\nThis is about classNames/markup you author. A number of `@neuctra/ui` components ship their own built-in elevation shadow as part of their default design (overlay/floating components like Modal, Dropdown, Popover, Drawer, Tooltip, and others like Table, DatePicker's calendar panel, Avatar's status dot, Kbd, and the Toast notification, among others — this isn't an exhaustive list to memorize). Leave every component's shipped defaults exactly as they ship: never add a shadow yourself, and never strip a component's built-in one with an override either — both are the same mistake in opposite directions."
-    },
-    {
-      "number": 41,
-      "title": "Modern UI Rule",
-      "content": "Modern does NOT mean:\n\n* excessive gradients\n* glassmorphism everywhere\n* giant rounded cards\n* excessive shadows\n* huge text\n* neon colors\n* random icons\n* excessive animations\n\nModern means:\n\n* clear hierarchy\n* intentional spacing\n* restrained color\n* predictable interaction\n* strong typography\n* useful whitespace\n* consistent components\n* subtle motion\n* responsive behavior"
-    },
-    {
-      "number": 42,
-      "title": "Human-Designed UI Rule",
-      "content": "Before generating the final UI, mentally ask:\n\n> \"Would a professional product designer intentionally put this element here?\"\n\nIf the answer is no, remove it.\n\nDo not add UI simply because a component exists.\n\nThe component library is a toolbox, not a checklist."
-    },
-    {
-      "number": 43,
-      "title": "Avoid AI-Generated UI Patterns",
-      "content": "Never automatically generate:\n\n* Hero section + three cards + gradient\n* Excessive rounded containers\n* Random decorative icons\n* Unnecessary badges\n* Excessive centered text\n* Every section inside a Card\n* Multiple primary buttons\n* Huge empty spaces\n* Excessive shadows\n* Random gradients\n* Generic dashboard cards\n* Repeated identical layouts\n* Decorative statistics without meaning\n\nAvoid the recognizable \"AI-generated SaaS template\" appearance."
-    },
-    {
-      "number": 44,
-      "title": "Component Selection Principle",
-      "content": "When choosing a component, use this decision process:\n\n```text\nNeed navigation?\n→ Tabs / Breadcrumb / Pagination / Stepper\n→ For a sidebar or nav links: hand-build from Button (ghost/link variant) — no dedicated Navigation component exists\n\nNeed an action?\n→ Button / Icon Button\n\nNeed selection?\n→ Select / RadioGroup / Checkbox / Switch\n\nNeed compact metadata?\n→ Badge / Chip\n\nNeed grouped content?\n→ Card\n\nNeed persistent message?\n→ Callout\n\nNeed temporary message?\n→ the toast system (import { toast, ToastProvider } from \"@neuctra/ui\" — not a \"Toast\" component)\n\nNeed focused interaction?\n→ Modal / Drawer / Popover\n\nNeed clarification?\n→ Tooltip\n\nNeed structured records?\n→ Table / List\n\nNeed loading?\n→ Skeleton / Spinner\n\nNeed progress?\n→ Progress\n\nNeed hierarchy?\n→ Accordion / Breadcrumb / Stepper\n```\n\nNever select a component merely because it looks attractive."
-    },
-    {
-      "number": 45,
-      "title": "Documentation UI Rules",
-      "content": "For component documentation, prefer:\n\n```text\nSidebar\n+\nDocumentation Container\n+\nBreadcrumb / Section Context\n+\nComponent Title\n+\nDescription\n+\nLive Preview\n+\nCode\n+\nUsage Guidelines\n+\nProps\n+\nAccessibility\n+\nFAQ\n```\n\nThe documentation page should prioritize the component preview and developer understanding.\n\nKeep code visually distinct from prose."
-    },
-    {
-      "number": 46,
-      "title": "Component Preview Rules",
-      "content": "Every preview should feel like a real product interface.\n\nDo not make previews look like isolated component experiments.\n\nInstead of:\n\n```text\nButton\nButton\nButton\n```\n\nprefer contextual examples:\n\n```text\nProject Settings\n\nProject name\n[ My Project                  ]\n\n[ Cancel ] [ Save Changes ]\n```\n\nThis demonstrates how the component actually behaves in a product."
-    },
-    {
-      "number": 47,
-      "title": "Accessibility",
-      "content": "Accessibility is part of the design.\n\nAlways consider:\n\n* Keyboard navigation\n* Focus states\n* Screen readers\n* Color contrast\n* Semantic HTML\n* Clear labels\n* Button names\n* Input descriptions\n* Error messages\n* Touch target sizes\n\nNever communicate meaning using color alone."
-    },
-    {
-      "number": 48,
-      "title": "Interaction Design",
-      "content": "Every interactive element should provide feedback.\n\nExamples:\n\n```text\nDefault\n→ Hover\n→ Active\n→ Focus\n→ Disabled\n→ Loading\n→ Success/Error\n```\n\nDo not animate everything.\n\nUse subtle transitions for:\n\n* Hover\n* Opening/closing\n* State changes\n* Navigation\n* Feedback\n\nMotion should explain interaction, not distract."
-    },
-    {
-      "number": 49,
-      "title": "Final UI Quality Checklist",
-      "content": "Before considering the UI complete, verify:\n\n### Hierarchy\n\n* Is the primary purpose obvious within seconds?\n* Is the most important action visually dominant?\n\n### Layout\n\n* Is spacing intentional?\n* Are sections grouped logically?\n* Is the content width comfortable?\n\n### Components\n\n* Is every component necessary?\n* Is each component being used for its intended purpose?\n\n### Visual Design\n\n* Is the color palette restrained?\n* Are borders and shadows subtle?\n* Is typography consistent?\n\n### UX\n\n* Can users understand what to do?\n* Are loading, empty, error, and success states handled?\n\n### Responsive\n\n* Does it work on mobile?\n* Does navigation adapt correctly?\n* Do cards/forms/tables remain usable?\n\n### Human Design\n\n* Does it look intentionally designed?\n* Could removing a decorative element improve it?\n* Does anything feel like generic AI-generated SaaS UI?\n\nIf something feels unnecessary, remove it."
-    },
-    {
-      "number": 50,
-      "title": "Do Not Overwrite Built-in Component Design",
-      "content": "Use each `@neuctra/ui` component's built-in design — its default spacing, radius, colors, and layout — as-is.\n\nDo not pass a `className` just to restyle a component's built-in appearance because of personal preference. The component's own design is already the intended, consistent look.\n\nOnly override with Tailwind's `!` important-modifier (e.g. `!bg-red-500`, `!p-2`, `!rounded-lg`) when there is a real, specific need:\n\n* The component's default would otherwise break the current page's existing layout.\n* The default collides or conflicts with the current UI/design of the site.\n* The component has no prop for the needed variation, and leaving the default would visually damage the surrounding design.\n\nNever reach for `!important` overrides as a routine styling habit, a stylistic preference, or 'just because'.\n\nPrefer:\n\n> built-in component design → prop-based variation (variant, size, etc.) → `!important` override (rare, only to prevent breakage)\n\nover:\n\n> restyle every component by default with className overrides\n\nA component that has been overridden with `!important` on every use is a sign the component itself, or the way it's being used, is wrong — not that every instance needs forcing."
-    },
-    {
-      "number": 51,
-      "title": "Paragraph Text Color",
-      "content": "Use `text-secondary` for all paragraph text: body copy, section descriptions, card descriptions, and supporting text under headings.\n\nDo not use `text-muted-foreground` for paragraphs. It is too low-contrast for reading text.\n\nKeep `text-muted-foreground` for small, low-priority text only:\n\n* Timestamps\n* Metadata\n* Captions\n* Placeholders\n* Helper and hint text\n* Disabled states\n\nUse `text-foreground` for headings, titles, and anything that needs full emphasis.\n\n`secondary` is a text color only. Do not use it as a background (`bg-secondary`).\n\nOrder of emphasis:\n\n```text\ntext-foreground        ← headings\n↓\ntext-secondary         ← paragraphs\n↓\ntext-muted-foreground  ← metadata and hints\n```\n\nToken values:\n\n* Light theme: `--secondary: #3f3f46`\n* Dark theme: `--secondary: #d4d4d8`"
-    },
-    {
-      "number": 52,
-      "title": "Type Scale",
-      "content": "Use one fixed, responsive type scale on every page:\n\n```text\nDisplay / H1  text-4xl sm:text-5xl lg:text-6xl font-bold tracking-tight\nH2            text-3xl sm:text-4xl font-semibold tracking-tight\nH3            text-xl sm:text-2xl font-semibold\nBody          text-base\nSmall         text-sm\nMeta          text-xs\n```\n\nRules:\n\n* Never use more than 4 text sizes on one screen.\n* Add `text-balance` to headings so lines break evenly.\n* Add `text-pretty` to paragraphs to avoid single-word last lines.\n* Step headings down one level at a time. Do not jump from H1 straight to small text.\n* `tracking-tight` only on `text-3xl` and larger. Everything smaller stays at the default tracking.\n* Line-height comes from the text-size class. Do not add `leading-*` on top of it."
-    },
-    {
-      "number": 53,
-      "title": "Readable Measure",
-      "content": "Long lines are hard to read.\n\n* Paragraphs: `max-w-prose` or `max-w-2xl`.\n* Headings may run wider: `max-w-3xl`.\n* Never let body text stretch the full width of a wide container.\n\nThe layout can be wide. The reading column should not be."
-    },
-    {
-      "number": 54,
-      "title": "Spacing Rhythm",
-      "content": "Use the 4/8 spacing scale only. Space shrinks as you go deeper into the layout.\n\n```text\nPage gutters        px-4 sm:px-6 lg:px-8\nBetween sections    py-16 sm:py-20 lg:py-28\nBetween blocks      mt-10 / mt-12\nHeading to body     mt-4\nInside a component  gap-2 / gap-3\n```\n\nBig gaps separate ideas. Small gaps group them. If everything has the same gap, nothing is grouped."
-    },
-    {
-      "number": 55,
-      "title": "Grid & Layout Patterns",
-      "content": "Build layouts from a few reliable patterns:\n\n* **Card grid:** `grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 sm:gap-6`.\n* **Split:** text and visual side by side with `lg:grid-cols-2`, alternating sides from one section to the next.\n* **Bento:** one large tile (`lg:col-span-2`) with smaller tiles around it, instead of identical boxes.\n* **Asymmetric:** `lg:grid-cols-[2fr_1fr]` for main content plus a side column. Grid templates like this are the one allowed exception to the no-arbitrary-values rule.\n\nAdd `min-w-0` to flex and grid children that contain text, so truncation works instead of overflowing.\n\nAvoid the default \"three equal cards in a row\" on every section."
-    },
-    {
-      "number": 56,
-      "title": "Hero / Above the Fold",
-      "content": "The hero must answer \"what is this and why should I care\" within 5 seconds.\n\nRecommended order:\n\n```text\nBadge            short eyebrow (New, Beta, v2.0)\nH1               value proposition, under 10 words\nLead text        text-lg text-secondary, one or two sentences\nActions          one primary Button + one secondary Button\nProof            real product screenshot, stat row, or customer logos\n```\n\n* Left-align by default. Center only short, single-message heroes.\n* Use a split layout (text left, visual right) on `lg` and stack on mobile.\n* One primary action only. The second action is outline or ghost."
-    },
-    {
-      "number": 57,
-      "title": "Focal Point & Visual Interest",
-      "content": "Eye-catching does not mean effects. Gradients, shadows and blur stay banned.\n\nVisual interest comes from:\n\n* **Scale contrast:** a very large headline next to small, quiet metadata.\n* **One bold element per viewport:** a single `bg-primary` block, button or highlight that the eye lands on first.\n* **Surface layering:** alternate sections between `bg-background`, `bg-card` and `bg-accent` bands to create depth without shadows.\n* **Big numbers:** metrics in large type with `tabular-nums`.\n* **Real imagery:** product screenshots and photos, not decorative filler.\n* **Whitespace:** give the most important element more space than anything around it.\n\nColor ratio: roughly 60% neutral surfaces, 30% text and borders, 10% primary."
-    },
-    {
-      "number": 58,
-      "title": "Section Variety",
-      "content": "A page should feel composed, not stamped out.\n\n* Never use the same layout for two sections in a row.\n* Mix patterns: split, card grid, bento, full-width band, stat row, testimonial, FAQ, CTA band.\n* Alternate background surfaces between neighbouring sections.\n* End every landing page with a clear call-to-action section."
-    },
-    {
-      "number": 59,
-      "title": "Breakpoint Checklist",
-      "content": "Design mobile-first, then check every page at:\n\n```text\n360px   small phone\n768px   tablet\n1024px  small laptop\n1280px  desktop\n1536px  large desktop\n```\n\nAt every width:\n\n* No horizontal scroll.\n* Touch targets are at least 44px.\n* Navigation collapses into a Drawer below `md`.\n* Tables sit inside `overflow-x-auto`.\n* Images use an `aspect-*` class with `object-cover`, so nothing shifts while loading.\n* On mobile, stack content in order of importance (use `order-*` when the source order differs)."
-    },
-    {
-      "number": 60,
-      "title": "Imagery & Media",
-      "content": "* Use consistent aspect ratios: `aspect-video`, `aspect-square`, or `aspect-[4/3]` (allowed ratio).\n* Use one corner radius for all images on a page.\n* Always write real, descriptive `alt` text.\n* Lazy-load images below the fold.\n* Prefer real product screenshots over stock illustrations or abstract shapes."
-    },
-    {
-      "number": 61,
-      "title": "Iconography",
-      "content": "* Use lucide-react icons only.\n* Match icon size to the text beside it: 16px with `text-sm`, 20px with `text-base`, 24px next to headings.\n* Keep the same stroke width across the whole interface.\n* Icons support labels. They do not replace them, except in an IconButton with a Tooltip.\n* Do not wrap every icon in a colored circle."
-    },
-    {
-      "number": 62,
-      "title": "Motion Timing",
-      "content": "Motion explains a change. It is never decoration.\n\n```text\nHover / press     transition-colors duration-150\nOpen / close      200 to 300ms, ease-out\nPage load         no entrance animations\n```\n\n* Respect reduced motion with `motion-reduce:` variants.\n* Animate color and opacity. Do not animate layout or add hover-scale."
-    },
-    {
-      "number": 63,
-      "title": "Microcopy",
-      "content": "Words are part of the design.\n\n* Sentence case for headings, buttons and labels.\n* Buttons start with a verb: \"Create project\", not \"Submit\".\n* Headlines state the benefit, not the feature name.\n* One idea per sentence. Short sentences.\n* No em dashes. Use a period, comma or colon instead."
-    }
-  ],
-  "goldenRule": {
-    "title": "Golden Rule",
-    "content": "Do not ask:\n\n> \"Which components can I put on this page?\"\n\nAsk:\n\n> \"What does the user need to understand and do, and which Neuctra UI component communicates that most naturally?\"\n\nThe best Neuctra UI interface is not the one that uses the most components.\n\nIt is the one where **every component has a purpose.**"
-  }
-}

package/data/seoGuide.json

@@ -1,180 +0,0 @@
-{
-  "title": "Neuctra UI: SEO, AEO and GEO Guide",
-  "intro": "Complete SEO, AEO, and GEO rules for Neuctra UI projects, followed by practical implementation steps. Use the rules as the source of truth, identify the project framework before applying metadata, and adapt every implementation to that framework. The guidance covers crawlability, technical SEO, keywords, metadata, headings, content, structured data, FAQs, performance, trust, and measurement.",
-  "seoRules": [
-    {
-      "id": "technical",
-      "title": "Technical SEO Foundations",
-      "content": "Search engines and AI crawlers can only rank what they can fetch, render and understand.\n\n**Render on the server.** Titles, meta tags, JSON-LD and the main body text must be in the initial HTML (SSR or SSG). Google renders JavaScript late and not always; most AI crawlers (GPTBot, ClaudeBot, PerplexityBot) do not run JavaScript at all. A client-only SPA that patches `<title>` in a `useEffect` is effectively invisible to them.\n\n**Canonical URLs.** Every indexable page declares one absolute canonical: `<link rel=\"canonical\" href=\"https://example.com/docs/button\">`. Pick one host (with or without `www`), one protocol (`https`) and one trailing-slash style, and 301-redirect every other variant to it.\n\n**URLs.** Short, lowercase, kebab-case, readable: `/docs/date-picker`, not `/Docs/DatePicker?id=12`. Never change a live URL without a 301 redirect.\n\n**robots.txt.** Lives at `/robots.txt`, points to the sitemap, and blocks only what must never be crawled (admin, API, internal search results):\n\n```text\nUser-agent: *\nAllow: /\nDisallow: /api/\nDisallow: /admin/\n\nSitemap: https://example.com/sitemap.xml\n```\n\n`robots.txt` controls crawling, not indexing. To keep a crawlable page out of results use `<meta name=\"robots\" content=\"noindex\">` (and do not also block it in robots.txt, or the noindex is never seen).\n\n**XML sitemap.** Lists every canonical, indexable URL (never redirects, 404s or noindex pages) with an accurate `<lastmod>`. Regenerate it on every build (e.g. `next-sitemap`, `@astrojs/sitemap`) and submit it in Google Search Console and Bing Webmaster Tools.\n\n**Site architecture.** Every important page is reachable within 3 clicks of the home page and has at least one internal link pointing to it (no orphan pages). Use real `<a href>` links; buttons with `onClick` navigation are not crawled.\n\n**Status codes.** 200 for real pages, 301 for permanent moves, 404/410 for removed pages. A \"not found\" screen that returns 200 (soft 404) wastes crawl budget.\n\n**noindex** thin or utility pages: login, cart, account, internal search, tag pages with one post, paginated archives beyond page 1 if they add nothing.\n\n**International sites.** Use `hreflang` alternates (`<link rel=\"alternate\" hreflang=\"de\" href=\"...\">`) plus `x-default`, and keep one language per URL.\n\n**HTTPS and security.** HTTPS everywhere, no mixed content, HSTS enabled.\n\n**Only the widget may be client-only.** Interactive tools (editors, converters, canvas, file processing) often need `dynamic(() => import(\"./Tool\"), { ssr: false })` or a client-only island. Wrap only the widget that way. The page frame around it (breadcrumb, H1, lead paragraph, article sections, FAQ and JSON-LD) must render on the server. If the whole page is client-only, the built HTML has no H1, no text and no schema, and crawlers see an empty page.\n\n**One URL registry.** Keep every route in one data file (e.g. `lib/routes.js` with categories and pages, each with an `href`). Generate navigation, the sitemap, `llms.txt`, breadcrumbs and related links from it, so a renamed URL can't leave stale links behind.\n\n**Redirect old slugs.** When a URL changes, add a permanent 301 from the old path, update the registry, and regenerate the sitemap and `llms.txt`. They must list only final URLs, never URLs that redirect.\n\n**Sitemap dates.** Set `<lastmod>` to the date the content really changed, not the build time for every URL: a lastmod that always changes is ignored. Google ignores `<priority>` and `<changefreq>`, so don't spend effort tuning them. Exclude admin, API, 404 and other noindex routes."
-    },
-    {
-      "id": "performance",
-      "title": "Performance and Core Web Vitals",
-      "content": "Core Web Vitals are a ranking signal and a conversion factor. Targets at the 75th percentile of real users:\n\n```text\nLCP  (Largest Contentful Paint)   < 2.5s\nINP  (Interaction to Next Paint)  < 200ms\nCLS  (Cumulative Layout Shift)    < 0.1\n```\n\n**LCP**\n* The hero image is the usual LCP element: serve it in AVIF/WebP, sized to the viewport, and mark it high priority (`priority` on `next/image`, `fetchpriority=\"high\"` and no `loading=\"lazy\"` on a plain `<img>`).\n* Lazy-load everything below the fold.\n* Preconnect to critical third-party origins; self-host fonts where possible.\n\n**CLS**\n* Give every image, video and embed explicit `width`/`height` or an `aspect-*` class.\n* Reserve space for banners, ads and late-loading content.\n* Load fonts with `font-display: swap` and a size-matched fallback.\n\n**INP**\n* Keep main-thread tasks under 50ms: split large bundles, defer non-critical scripts, avoid heavy work in click handlers.\n* Load analytics and chat widgets after interaction or idle.\n\n**Measure** with PageSpeed Insights (field + lab data), the Search Console Core Web Vitals report and Lighthouse. Lab scores alone are not what Google ranks on.\n\n**Avoid layout shift from theme and ads**\n* Apply the saved light/dark theme with a tiny inline script in `<head>` before first paint, so the page doesn't flash and re-layout.\n* Reserve the height of ad slots and embeds before they load, and only load them when they near the viewport."
-    },
-    {
-      "id": "on-page",
-      "title": "On-Page SEO",
-      "content": "**Title tag** (the single strongest on-page signal)\n* 50 to 60 characters (Google truncates around 580px).\n* Primary keyword first, then a benefit or differentiator, then the brand: `React Date Picker Component: Accessible and Themeable | Neuctra UI`, `Merge PDF Online Free: Combine Files, No Sign-Up | Brand`.\n* Long-tail modifiers people actually search belong in the title when true: \"free\", \"online\", \"no sign-up\", \"without watermark\", \"for React\".\n* **One brand-suffix rule for the whole site.** Add ` | Brand` in exactly one place (a title template or one metadata builder) and never hand-type it into individual titles. Mixing the two produces missing suffixes on some pages and doubled ones (`| Brand | Brand`) on others.\n* Unique on every page. Never \"Home\", \"Untitled\" or the same title site-wide.\n* Home page: `Brand: what it is in plain words`.\n\n**Meta description** (not a ranking factor, but it drives click-through)\n* 140 to 155 characters.\n* Formula: primary keyword + what the page or tool does + trust points + call to action. Example: \"Merge PDF files online for free. Combine documents in seconds, right in your browser. No upload, no sign-up, no watermark. Merge your PDFs now.\"\n* Trust points that are true for the page (\"no sign-up\", \"files never leave your device\", \"free forever\") lift click-through.\n* Unique per page. If missing or weak, Google writes its own from page text.\n\n**Headings**\n* Exactly one `<h1>`, matching the search intent and close to the title (not identical is fine).\n* `<h2>`/`<h3>` in order, never skipping levels. Phrase several `<h2>`s as the questions people actually search.\n\n**Body**\n* Primary keyword (or a close variant) in the first 100 words.\n* Cover the topic completely: answer the main question, the follow-up questions and the obvious objections.\n* Short paragraphs, lists and tables where they fit. Write for people; no keyword stuffing.\n\n**Links**\n* Descriptive internal anchor text (\"React table component\", never \"click here\").\n* Link down to child pages and across to related pages. Link out to authoritative sources when you cite facts.\n\n**Images**\n* Descriptive `alt` text for meaningful images, empty `alt=\"\"` for decorative ones.\n* Descriptive file names (`react-date-picker-dark-mode.webp`).\n\n**Social previews**\n* OpenGraph and Twitter tags with a 1200x630 image on every shareable page.\n\n**Social copy.** OpenGraph title and description may be a shorter, punchier variant of the SEO title and description (`og:title` does not need the brand suffix). Every page still needs its own `og:image`.\n\n**Meta keywords.** Google ignores `<meta name=\"keywords\">`. Research long-tail variants (free, online, no sign-up, without watermark, for beginners, vs competitor) and use them in the title, H2s, body and FAQ questions instead. A keywords tag is harmless, but it does nothing for ranking."
-    },
-    {
-      "id": "keywords-intent",
-      "title": "Keywords, Search Intent and Site Structure",
-      "content": "**One page, one primary intent.** Decide what a page should rank for before writing it:\n\n```text\nInformational   \"what is a date picker\"         guide, docs, blog\nCommercial      \"best react ui library\"          comparison, landing\nTransactional   \"neuctra ui pricing\"             pricing, signup\nNavigational    \"neuctra ui docs\"                home, docs index\n```\n\n* Pick one primary keyword and a handful of close variants per page.\n* Two pages targeting the same keyword compete with each other (cannibalisation). Merge them or differentiate the intent.\n\n**Topic clusters.** Build a pillar page for each core topic (e.g. \"React UI Components\") and cluster pages for each subtopic (Button, Modal, Date Picker). The pillar links to every cluster page and every cluster page links back to the pillar and to its siblings. This is how topical authority is earned.\n\n**Research sources.** Google Search Console queries you already rank for on page 2, \"People also ask\", autocomplete, related searches, competitor pages that rank, and your own support and sales questions.\n\n**Map it.** Keep a simple keyword map (URL, primary keyword, intent, status) so no two pages chase the same query."
-    },
-    {
-      "id": "eeat",
-      "title": "E-E-A-T and Trust Signals",
-      "content": "Google's quality raters look for Experience, Expertise, Authoritativeness and Trust. AI engines prefer the same sources when choosing what to cite.\n\n* **Real authorship.** Named authors with a short bio and links to their profiles for articles and guides. Use `author` in the schema.\n* **Dates.** Show \"Published\" and \"Last updated\" dates on content that ages, and mirror them in `datePublished` / `dateModified`. Only bump `dateModified` when the content really changed.\n* **Evidence.** Original data, benchmarks, screenshots, code that runs, and citations to primary sources.\n* **Transparency.** About, Contact, Privacy Policy and Terms pages; a physical or company address where relevant.\n* **Consistency.** The same brand name, logo and description everywhere (site, GitHub, npm, social profiles, directories).\n* **Reputation.** Reviews and mentions on third-party sites count for more than claims on your own site."
-    },
-    {
-      "id": "aeo",
-      "title": "AEO: Answer Engine Optimisation",
-      "content": "AEO targets the answer surfaces: featured snippets, \"People also ask\", Google AI Overviews, voice assistants. The goal is to be the passage an engine lifts as the answer.\n\n**Answer-first structure**\n* Phrase key `<h2>`s as questions: \"How do I add a date picker in React?\"\n* Put a direct, self-contained answer of 40 to 60 words right under the question, then expand with detail.\n* Start definitions with the term: \"A date picker is a form control that ...\"\n\n**Snippet-friendly formats**\n* Steps: an ordered list (`<ol>`) with one action per item.\n* Comparisons: a real `<table>` with clear column headers.\n* Lists of options: an unordered list with the item name first.\n\n**FAQ block on every key page**\n* 4 to 8 real questions with concise answers (see the `faq` topic), marked up with `FAQPage` schema.\n\n**Voice and conversational queries**\n* Cover long, natural questions (\"which react ui library works with tailwind v4\").\n* Keep answers short and speakable; avoid tables-only answers for questions people ask aloud.\n\n**Make the answer easy to extract**\n* Plain HTML text, not text baked into images, canvas or tabs that only render on click.\n* One idea per paragraph. No filler introduction before the answer."
-    },
-    {
-      "id": "geo",
-      "title": "GEO: Generative Engine Optimisation",
-      "content": "GEO targets being retrieved and cited by generative engines: ChatGPT search, Perplexity, Claude, Gemini, Copilot and Google AI Mode. They pick sources that are crawlable, clear, specific and trusted.\n\n**1. Let them crawl.** Server-render the content (they rarely run JavaScript) and make an explicit robots.txt decision per bot:\n\n```text\n# Search / answer bots: allow these if you want to be cited\nUser-agent: OAI-SearchBot\nAllow: /\nUser-agent: ChatGPT-User\nAllow: /\nUser-agent: PerplexityBot\nAllow: /\nUser-agent: Claude-SearchBot\nAllow: /\nUser-agent: Claude-User\nAllow: /\n\n# Training bots: a business decision, allow or disallow\nUser-agent: GPTBot\nAllow: /\nUser-agent: ClaudeBot\nAllow: /\nUser-agent: Google-Extended\nAllow: /\nUser-agent: CCBot\nAllow: /\n```\n\nBlocking a search bot means that engine cannot cite you. Blocking a training bot does not stop citations from its search bot.\n\n**2. Publish llms.txt.** A markdown index at `/llms.txt` (spec: llmstxt.org): an H1 with the site name, a one-paragraph summary in a blockquote, then sections of `- [Page title](url): one-line description`. Optionally `/llms-full.txt` with the full text of key docs. Generate it at build time from the same route registry as the sitemap, so it never lists old URLs that now redirect.\n\n**3. Be the clearest source.**\n* State facts plainly and specifically: numbers, versions, dates, limits, prices.\n* Keep sections self-contained so a single passage makes sense when quoted alone.\n* Add comparison tables, definitions and step lists; engines quote these heavily.\n* Cite primary sources and include original data or benchmarks worth citing.\n\n**4. Strengthen the entity.**\n* Use the same brand name and one-line description everywhere.\n* `Organization` schema with `logo` and `sameAs` links (GitHub, npm, LinkedIn, X, YouTube, Wikipedia/Wikidata if you have them).\n* Earn mentions on sites the engines already trust: docs aggregators, GitHub, Reddit, Stack Overflow, industry publications, review sites.\n\n**5. Stay fresh.** Show and maintain \"Last updated\" dates; engines favour current sources for anything version-sensitive.\n\n**6. Get indexed by Bing.** ChatGPT search and Copilot lean on Bing's index: verify the site in Bing Webmaster Tools, submit the sitemap and ping IndexNow on publish.\n\n**7. Measure.** Track referral traffic from chatgpt.com, perplexity.ai, gemini.google.com and copilot.microsoft.com, and regularly ask those engines your target questions to see who they cite."
-    },
-    {
-      "id": "schema",
-      "title": "Structured Data and Schema Weaving",
-      "content": "Structured data (JSON-LD) tells engines exactly what a page is. **Schema weaving** means emitting one connected `@graph` per page instead of several disconnected blobs, with nodes referencing each other by stable `@id`.\n\n**Stable @id scheme** (reuse the exact same IDs on every page):\n\n```text\nOrganization    https://example.com/#organization\nWebSite         https://example.com/#website\nWebPage         https://example.com/docs/card#webpage\nBreadcrumbList  https://example.com/docs/card#breadcrumb\nMain entity     https://example.com/docs/card#article   (or #product, #software)\nFAQPage         https://example.com/docs/card#faq\n```\n\n**Every page** gets Organization + WebSite + a WebPage (or subtype) + BreadcrumbList, wired together:\n* `WebSite.publisher` -> Organization\n* `WebPage.isPartOf` -> WebSite, `WebPage.breadcrumb` -> BreadcrumbList\n* main entity `mainEntityOfPage` -> WebPage, `publisher` -> Organization\n\n**Type map**\n\n```text\nhome       WebPage (+ Organization, WebSite as the main entities)\ndocs       WebPage + TechArticle\nblog       WebPage + BlogPosting (author, datePublished, dateModified, image)\nproduct    WebPage + SoftwareApplication or Product\npricing    WebPage + Product with Offer items (real prices only)\nlanding    WebPage\nfaq        FAQPage (as the page type)\nabout      AboutPage\ncontact    ContactPage\ncategory   CollectionPage\n```\n\n**Example graph**\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@graph\": [\n    { \"@type\": \"Organization\", \"@id\": \"https://example.com/#organization\", \"name\": \"Example\", \"url\": \"https://example.com\", \"logo\": \"https://example.com/logo.png\", \"sameAs\": [\"https://github.com/example\"] },\n    { \"@type\": \"WebSite\", \"@id\": \"https://example.com/#website\", \"url\": \"https://example.com\", \"name\": \"Example\", \"publisher\": { \"@id\": \"https://example.com/#organization\" } },\n    { \"@type\": \"WebPage\", \"@id\": \"https://example.com/docs/card#webpage\", \"url\": \"https://example.com/docs/card\", \"name\": \"Card Component | Example\", \"isPartOf\": { \"@id\": \"https://example.com/#website\" }, \"breadcrumb\": { \"@id\": \"https://example.com/docs/card#breadcrumb\" } },\n    { \"@type\": \"BreadcrumbList\", \"@id\": \"https://example.com/docs/card#breadcrumb\", \"itemListElement\": [\n      { \"@type\": \"ListItem\", \"position\": 1, \"name\": \"Home\", \"item\": \"https://example.com/\" },\n      { \"@type\": \"ListItem\", \"position\": 2, \"name\": \"Docs\", \"item\": \"https://example.com/docs\" },\n      { \"@type\": \"ListItem\", \"position\": 3, \"name\": \"Card\", \"item\": \"https://example.com/docs/card\" }\n    ] },\n    { \"@type\": \"TechArticle\", \"@id\": \"https://example.com/docs/card#article\", \"headline\": \"Card Component\", \"mainEntityOfPage\": { \"@id\": \"https://example.com/docs/card#webpage\" }, \"publisher\": { \"@id\": \"https://example.com/#organization\" } }\n  ]\n}\n```\n\n**Rules**\n* Structured data must describe what is visible on the page. Never mark up content users cannot see.\n* Never invent reviews, ratings, prices or authors. Fake markup risks a manual action.\n* Since 2023 Google shows FAQ rich results only for well-known government and health sites, and HowTo rich results are gone. Still add `FAQPage` where there is a visible FAQ: it helps AI Overviews and generative engines understand the Q&A.\n* Emit JSON-LD in the server-rendered HTML. Escape `<` as `\\u003c` when injecting it into a `<script>` tag.\n* Validate every template with Google's Rich Results Test and validator.schema.org before shipping.\n\nFollow the implementation steps from `neuctra-ui-seo-setup` when adding a woven graph to a page.\n\n**One node per type per page.** A page must not emit two `SoftwareApplication`, two `FAQPage` or two `BreadcrumbList` nodes. This happens when a shared page shell emits schema and the individual page adds its own `<script type=\"application/ld+json\">` too. Pick one owner (the shell), pass the data into it, and delete the page-level duplicate.\n\n**One data source for visible content and schema.** Build the visible steps list and the `HowTo` node from the same array, and the visible FAQ accordion and the `FAQPage` node from the same array. They then can't drift apart, and nothing is shown twice.\n\n**Tool and web-app pages** (free online tools, converters, calculators, generators):\n* `SoftwareApplication` with `applicationCategory` (e.g. `UtilitiesApplication`, `DeveloperApplication`, `MultimediaApplication`), `operatingSystem` (\"Web\" or \"All\"), `featureList`, `isAccessibleForFree: true` and an `Offer` with `price: \"0\"` only if the tool really is free.\n* `HowTo` with the visible usage steps. Google no longer shows HowTo rich results, but engines still use the steps for answers.\n* `BreadcrumbList` (Home > Category > Tool) and `FAQPage`.\n\n**Listing pages**\n* Category or collection pages: `CollectionPage` + an `ItemList` of the pages it links to, in visible order.\n* Home page: `ItemList`s for the main categories and popular items, next to Organization and WebSite.\n\n**Optional extras, with honest expectations**\n* `WebSite` `potentialAction` `SearchAction`: fine if the site has search, but Google retired the sitelinks search box in 2024, so it no longer changes how results look.\n* `speakable`: a beta mostly limited to news publishers; low value for other sites."
-    },
-    {
-      "id": "faq",
-      "title": "Writing FAQs That Rank and Get Cited",
-      "content": "**Where the questions come from:** Google \"People also ask\", autocomplete, Search Console queries, Reddit and forum threads, support tickets and sales calls. Never invent questions nobody asks.\n\n**Per page**\n* 4 to 8 questions, specific to that page. Never reuse the same FAQ block across pages.\n* Question as the user would type or say it: \"Does the date picker support keyboard navigation?\"\n* Answer in 40 to 80 words: direct answer in the first sentence, then the key detail. Plain text, no marketing fluff.\n* Include the page's primary keyword or entity name naturally in at least one question.\n\n**Markup**\n* Render the FAQ visibly on the page (an Accordion is fine, as long as the text is in the HTML).\n* Mirror the exact same questions and answers in `FAQPage` schema (`mainEntity` of `Question` items with an `acceptedAnswer` `Answer`).\n* The visible text and the schema text must match word for word.\n\n**Maintenance**\n* Update answers when the product changes, and bump `dateModified`.\n* Add new questions as support and search data reveal them."
-    },
-    {
-      "id": "meta-checklist",
-      "title": "Per-Page Meta Checklist",
-      "content": "Every indexable page ships these tags in the server-rendered `<head>`:\n\n```html\n<html lang=\"en\">\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Primary Keyword: Qualifier | Brand</title>\n<meta name=\"description\" content=\"140 to 155 characters, unique, with the value and a reason to click.\">\n<link rel=\"canonical\" href=\"https://example.com/path\">\n<meta name=\"robots\" content=\"index, follow, max-image-preview:large\">\n\n<meta property=\"og:type\" content=\"website\">          <!-- \"article\" for blog posts -->\n<meta property=\"og:site_name\" content=\"Brand\">\n<meta property=\"og:title\" content=\"Same as or close to the title\">\n<meta property=\"og:description\" content=\"Same as or close to the description\">\n<meta property=\"og:url\" content=\"https://example.com/path\">\n<meta property=\"og:image\" content=\"https://example.com/og/path.png\">   <!-- 1200x630 -->\n<meta property=\"og:image:alt\" content=\"What the image shows\">\n\n<meta name=\"twitter:card\" content=\"summary_large_image\">\n<meta name=\"twitter:title\" content=\"...\">\n<meta name=\"twitter:description\" content=\"...\">\n<meta name=\"twitter:image\" content=\"https://example.com/og/path.png\">\n\n<link rel=\"icon\" href=\"/favicon.svg\" type=\"image/svg+xml\">\n<link rel=\"apple-touch-icon\" href=\"/apple-touch-icon.png\">\n<meta name=\"theme-color\" content=\"#ffffff\">\n\n<script type=\"application/ld+json\">{ \"@context\": \"https://schema.org\", \"@graph\": [ ... ] }</script>\n```\n\nChecks:\n* Title and description are unique across the whole site.\n* Canonical and `og:url` are absolute and identical.\n* OG image URL is absolute, 1200x630, under about 5MB, and readable at small sizes.\n* Blog posts also get `article:published_time` and `article:modified_time`.\n* Utility pages use `<meta name=\"robots\" content=\"noindex, follow\">`."
-    },
-    {
-      "id": "frameworks",
-      "title": "Where Metadata Goes in Each Framework",
-      "content": "Neuctra UI runs anywhere React 18+ and Tailwind v4 run. The rule is the same everywhere: metadata and JSON-LD must be in the server-rendered HTML. Use the implementation steps from `neuctra-ui-seo-setup` for the matching framework; do not apply metadata APIs from another framework.\n\n**Next.js App Router** (`framework: \"nextjs-app\"`)\n* `export const metadata = {...}` or `export async function generateMetadata()` in `page.js` or `layout.js`. Use `alternates.canonical`, `openGraph`, `twitter`, `robots`.\n* Set `metadataBase: new URL(\"https://example.com\")` in the root layout so relative URLs resolve.\n* A `\"use client\"` page cannot export metadata: put it in the route's `layout.js` instead.\n* **Metadata merging is shallow.** A child segment's `openGraph` object replaces the parent's completely. If a page sets `openGraph` at all, it must repeat `images` (and `siteName`, `locale`), or the page ships without an `og:image`. The same applies to `twitter`.\n* **Title template.** `title: { template: \"%s | Brand\", default: \"...\" }` in the root layout adds the suffix to child titles. Child titles must then not include the brand themselves, or it doubles. When a builder already returns a full title, use `title: { absolute: \"...\" }` so the template is skipped.\n* **Robots for Googlebot** uses kebab-case keys: `robots: { index: true, follow: true, googleBot: { index: true, follow: true, \"max-image-preview\": \"large\", \"max-snippet\": -1, \"max-video-preview\": -1 } }`. camelCase keys like `maxImagePreview` are ignored.\n* **Client-only widgets:** `dynamic(() => import(\"./Widget\"), { ssr: false })` must wrap only the widget. Keep the H1, text, FAQ and JSON-LD in the server-rendered `page.js`.\n* `output: \"export\"` (static export) is fully crawlable: everything above still applies, and you can check the result in the `out/` HTML.\n* JSON-LD: render `<script type=\"application/ld+json\" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, \"\\\\u003c\") }} />` in the page or layout.\n* `app/sitemap.js` and `app/robots.js` generate those files natively.\n\n**Next.js Pages Router** (`\"nextjs-pages\"`)\n* `import Head from \"next/head\"` and render the tags inside `<Head>`. Pages are pre-rendered, so crawlers see them.\n\n**Vite + React SPA** (`\"react-vite\"`)\n* React 19 hoists `<title>`, `<meta>` and `<link>` rendered anywhere in the tree into `<head>`. On React 18 use `react-helmet-async`.\n* Warning: a client-only SPA ships an empty HTML shell. Prerender the routes at build time or move to an SSR framework (Next.js, React Router, Astro, TanStack Start) for anything that must rank or be cited.\n\n**React Router v7 / Remix** (`\"react-router\"`)\n* Export `meta()` from the route module returning `[{ title }, { name: \"description\", content }, { tagName: \"link\", rel: \"canonical\", href }, { \"script:ld+json\": jsonLd }]`.\n\n**Astro** (`\"astro\"`)\n* Put the tags in the layout's `<head>`, passing title/description as props. JSON-LD: `<script type=\"application/ld+json\" set:html={JSON.stringify(jsonLd)} />`. Use React islands for Neuctra UI components. `@astrojs/sitemap` builds the sitemap.\n\n**TanStack Start** (`\"tanstack-start\"`)\n* Return `{ meta, links, scripts }` from the route's `head()` option; JSON-LD goes in `scripts` as `{ type: \"application/ld+json\", children: JSON.stringify(jsonLd) }`.\n\n**Gatsby** (`\"gatsby\"`)\n* `export const Head = () => (<>...tags...</>)` from the page component.\n\n**Plain HTML / other** (`\"html\"`)\n* Put the tags from the `meta-checklist` topic directly in `<head>`."
-    },
-    {
-      "id": "page-templates",
-      "title": "Page Templates for Tool, Category and Home Pages",
-      "content": "Consistent templates make every page crawlable, answerable and internally linked by default.\n\n**Tool / product page** (e.g. a free online tool or a single feature):\n\n```text\n<main>\n  <header>\n    Visible breadcrumb      Home > Category > Tool (matches BreadcrumbList)\n    Category Badge\n    H1                      primary keyword + differentiator\n    Lead paragraph          text-secondary, 1 to 2 sentences, keyword in it\n  </header>\n  The tool / product UI     client-only widget is fine here\n  <article>\n    <section> H2 intro      what it is, who it's for, keyword in first 100 words\n    <section> H2 \"How to <task>\"   <ol> steps (same data as the HowTo schema)\n    <section> H2 benefits    H3 per benefit\n    <section> H2 \"Who uses <tool>\"  use cases + 3 to 4 related links\n    <section> H2 privacy / trust    e.g. \"Your files stay on your device\"\n    <section> H2 FAQ         accordion, 6 to 8 questions (same data as FAQPage)\n  </article>\n</main>\n```\n\n**Category page**\n* H1 + lead paragraph, then an H2 above the grid of items (never jump from H1 to H3 card titles).\n* Each card links to its page with descriptive anchor text.\n* `CollectionPage` + `ItemList` + `BreadcrumbList` schema.\n\n**Home page**\n* H1 stating what the site is, a lead paragraph, the main categories and popular items, a short FAQ.\n* `Organization`, `WebSite`, `ItemList`s of categories and popular items, `FAQPage`.\n\n**Internal linking**\n* Render related links from the route registry with a shared `RelatedLinks` component and the framework's link component (`next/link`, `<Link>`), never hand-typed `<a>` tags that go stale.\n* Link each page to its category, 3 to 4 siblings, and the category to every child."
-    },
-    {
-      "id": "site-wide",
-      "title": "Site-Wide Essentials",
-      "content": "Set these once in the root layout and every page inherits them.\n\n* `<html lang=\"...\">`, `<meta name=\"viewport\">`, `<meta charset=\"utf-8\">`.\n* A default `og:image` (1200x630), overridden per page or per category where you can.\n* `Organization` with `logo` and `sameAs` (GitHub, LinkedIn, X, YouTube, ...) and `WebSite` with `publisher`, both with stable `@id`s.\n* Search engine verification: `google-site-verification` and `msvalidate.01` meta tags (or DNS verification).\n* `manifest.webmanifest`, `theme-color`, favicon (SVG + ICO) and `apple-touch-icon` (180x180).\n* Privacy-friendly analytics that separates organic and AI-referral traffic.\n* Fonts with `font-display: swap`; the theme set before first paint.\n* Trust pages linked in the footer: About, Contact (with a real email address), Privacy Policy, Terms, and a Disclaimer where relevant.\n* `robots.txt` and the sitemap generated by the build, not maintained by hand."
-    },
-    {
-      "id": "ads-readiness",
-      "title": "Ads and Monetisation Without Hurting SEO",
-      "content": "Ad networks (Google AdSense and others) review trust and content quality, and badly loaded ads hurt Core Web Vitals.\n\n* Publish `/ads.txt` at the site root, generated at build time from your publisher ID.\n* Add the network's account verification meta tag in the root layout.\n* Load ad scripts after the page is interactive (`strategy=\"afterInteractive\"` or `lazyOnload` with `next/script`), and only when the publisher ID is configured.\n* Reserve each slot's size before it loads, and fill slots only when they come near the viewport, to avoid layout shift.\n* Never push the main content or the tool below the fold with ads, and never place ads inside the H1/lead block.\n* Have About, Contact, Privacy (with the ads and cookie disclosure), Terms and Disclaimer pages live before applying.\n* Keep substantial, original content on every monetised page. Thin pages with ads are the most common rejection reason."
-    },
-    {
-      "id": "off-page-monitoring",
-      "title": "Off-Page Authority and Monitoring",
-      "content": "**Authority**\n* Earn links, don't buy them: publish genuinely useful resources (templates, benchmarks, free tools, open-source code), get listed in relevant directories and \"awesome\" lists, write guest posts and answer questions where your audience asks them.\n* Digital PR: original data and strong opinions get cited by journalists and by AI engines.\n* Keep the brand consistent across GitHub, npm, social profiles and directories.\n\n**Setup on launch**\n* Google Search Console: verify the domain property, submit the sitemap, check indexing and Core Web Vitals reports.\n* Bing Webmaster Tools: verify (you can import from Search Console), submit the sitemap, enable IndexNow.\n* Analytics that separate organic search and AI referrals (chatgpt.com, perplexity.ai, gemini.google.com, copilot.microsoft.com).\n\n**Ongoing**\n* Weekly: Search Console coverage errors, new queries on page 2 worth improving.\n* Monthly: rankings for target keywords, pages losing clicks, Core Web Vitals, broken links, which sources AI engines cite for your target questions.\n* Refresh top pages every few months: new facts, new FAQs, updated `dateModified`."
-    },
-    {
-      "id": "launch-checklist",
-      "title": "SEO / AEO / GEO Launch Checklist",
-      "content": "Run this before any page or site goes live. Every item is pass or fail.\n\n**Check the built HTML, not the source code.** Run the production build and inspect the output (`view-source:`, or grep the static `out/` / `dist/` HTML). Bugs like client-only pages, duplicate schema and missing images only show up there.\n\n**Crawl and index**\n- [ ] Content, meta and JSON-LD are in the server-rendered HTML (view source, not DevTools)\n- [ ] One absolute canonical per page; all host/protocol/slash variants 301 to it\n- [ ] robots.txt allows the site, references the sitemap, has an explicit AI bot policy\n- [ ] sitemap.xml lists only canonical 200 pages with accurate lastmod, submitted to Google and Bing\n- [ ] Utility and thin pages are noindex; no important page is noindex by mistake\n- [ ] No orphan pages; every key page within 3 clicks of home\n- [ ] Real 404 status for missing pages\n- [ ] Every page has exactly one H1 in the built HTML (a missing H1 usually means the page renders client-only)\n- [ ] Sitemap and llms.txt list only final URLs (no 301s), generated from one route registry\n- [ ] Sitemap lastmod reflects real content changes\n\n**On-page**\n- [ ] Unique title, 50 to 60 characters, keyword first, brand last\n- [ ] Unique meta description, 140 to 155 characters\n- [ ] Exactly one H1; H2/H3 in order; several H2s phrased as questions\n- [ ] Primary keyword in the first 100 words\n- [ ] Descriptive alt text on meaningful images\n- [ ] OpenGraph + Twitter tags with a 1200x630 image on every page, including category and static pages\n- [ ] Brand suffix identical on every title, never missing and never doubled\n\n**Structured data**\n- [ ] One woven `@graph`: Organization, WebSite, WebPage, BreadcrumbList + page type node\n- [ ] FAQPage only where the FAQ is visible, text identical\n- [ ] At most one node of each type per page (no duplicate SoftwareApplication, FAQPage, BreadcrumbList)\n- [ ] Visible steps/FAQs and their schema come from the same data, and nothing is rendered twice\n- [ ] No invented reviews, ratings or prices\n- [ ] Passes Rich Results Test and validator.schema.org\n\n**AEO / GEO**\n- [ ] 40 to 60 word direct answer under each question heading\n- [ ] 4 to 8 page-specific FAQs\n- [ ] /llms.txt published and generated from the route list\n- [ ] Organization `sameAs` links and consistent brand naming\n- [ ] Visible \"Last updated\" date on content that ages\n\n**Performance**\n- [ ] LCP < 2.5s, INP < 200ms, CLS < 0.1 on mobile\n- [ ] LCP image high priority, below-fold media lazy, all media sized\n\nUse `neuctra-ui-seo-setup` with action `audit` to check a page against the on-page and schema items automatically."
-    }
-  ],
-  "implementationSteps": {
-    "purpose": "Apply the SEO rules to the project in order. First identify framework, router, rendering mode, and current metadata conventions. Keep content and structured data consistent with what users can see.",
-    "steps": [
-      {
-        "number": 1,
-        "title": "Identify framework and rendering",
-        "details": "Inspect package.json, framework config, router, and build output. Determine whether each route is server rendered, statically generated, prerendered, or client only. Keep page title, description, canonical, visible content, and JSON-LD in the initial HTML whenever possible."
-      },
-      {
-        "number": 2,
-        "title": "Map search intent and keywords",
-        "details": "Assign one primary search intent and one primary keyword to each canonical URL. Record close variants, audience, and task. Check existing routes to prevent cannibalization; use variants naturally in the title, H1, introduction, subheadings, body, links, and real FAQ questions. Do not add a meta keywords tag for ranking."
-      },
-      {
-        "number": 3,
-        "title": "Write page content and headings",
-        "details": "Write a unique title and useful page content. Use exactly one descriptive H1 that matches intent and is close to the title. Keep H2/H3 hierarchy in order. Put the primary keyword or close variant in the opening 100 words. Answer question headings directly and completely; use semantic HTML, descriptive links, and useful image alt text."
-      },
-      {
-        "number": 4,
-        "title": "Set metadata and canonical URL",
-        "details": "Set a unique title (usually 50–60 characters) with primary topic first and the brand suffix exactly once. Set a unique 140–155 character description that accurately describes the page and reason to click. Add one absolute canonical, robots directives, language, and OpenGraph/Twitter metadata with a real 1200×630 social image. Noindex private or low-value utility pages; do not block a page in robots.txt if crawlers must read its noindex."
-      },
-      {
-        "number": 5,
-        "title": "Add JSON-LD for entities and GEO clarity",
-        "details": "Emit valid JSON-LD in the initial HTML. Use one connected @graph per page with Organization, WebSite, WebPage (or suitable subtype), BreadcrumbList, and the relevant main entity. Link nodes with stable @id values. Add FAQPage only for questions and answers visible on the page; use Product, Offer, SoftwareApplication, BlogPosting, TechArticle, HowTo, or ItemList only when the corresponding facts and content are visible. Never invent prices, ratings, reviews, authors, or features. Structured data helps machines understand entities but does not guarantee rankings or citations."
-      },
-      {
-        "number": 6,
-        "title": "Implement AEO with useful FAQs and direct answers",
-        "details": "For important questions, use a clear question heading followed immediately by a concise, self-contained answer, then supporting detail. Add around 4–8 genuine page-specific FAQs when they help users. Keep FAQ text identical between visible content and JSON-LD. Prefer semantic lists for steps and real tables for comparisons."
-      },
-      {
-        "number": 7,
-        "title": "Complete technical SEO",
-        "details": "Use stable lowercase URLs, working internal links, correct 200/301/404/410 status codes, HTTPS, a robots.txt with the sitemap location, and an XML sitemap containing only canonical indexable URLs with meaningful lastmod dates. Add redirects for changed URLs. Ensure important pages are reachable and not orphaned. Provide hreflang only for actual localized variants."
-      },
-      {
-        "number": 8,
-        "title": "Optimize performance and accessibility",
-        "details": "Measure field Core Web Vitals and target LCP under 2.5s, INP under 200ms, and CLS under 0.1 at the 75th percentile. Prioritize the actual LCP asset, lazy-load below-fold media, size images, reserve layout space, reduce main-thread work, and use semantic accessible HTML."
-      },
-      {
-        "number": 9,
-        "title": "Build trust and freshness",
-        "details": "Show real authorship, evidence, contact/about/policy information, and accurate published/updated dates where relevant. Update dateModified only after a material content change. Keep brand name, logo, and description consistent across the site and trusted profiles."
-      },
-      {
-        "number": 10,
-        "title": "Verify production output",
-        "details": "Build the site and inspect the generated or server-rendered HTML, not only source components or the browser DOM after JavaScript runs. Confirm title, description, canonical, robots, H1, links, social tags, JSON-LD validity, and sitemap URLs. Check status codes, mobile performance, Search Console, and Bing Webmaster Tools; fix issues and repeat."
-      }
-    ],
-    "frameworkSpecific": {
-      "nextjs-app": {
-        "identify": "Next.js App Router routes live under app/ or src/app/.",
-        "metadata": "Export metadata or generateMetadata from each server page/layout. Set metadataBase in the root layout. Use title.template once for the brand suffix; use title.absolute for a prebuilt full title. A page marked use client cannot export metadata, so place metadata in its server parent/layout.",
-        "jsonLd": "Render a script type application/ld+json from a Server Component. Serialize safely, escaping < as \\u003c. Keep JSON-LD aligned with visible page content.",
-        "technical": "Use app/sitemap.js and app/robots.js or equivalent route files. Set canonical with alternates.canonical; configure OpenGraph, Twitter, robots and images. With output: export, confirm every dynamic route is statically generated and inspect out/ HTML."
-      },
-      "nextjs-pages": {
-        "identify": "Next.js Pages Router routes live under pages/ or src/pages/.",
-        "metadata": "Use next/head in each page for title, description, canonical, robots and social meta tags. Ensure metadata is present during SSR/SSG, not only after client effects.",
-        "jsonLd": "Render a JSON-LD script in the page with dangerouslySetInnerHTML and safely escaped serialized data.",
-        "technical": "Use getStaticProps/getStaticPaths or SSR as appropriate. Generate sitemap and robots files from canonical route data, and inspect the built HTML."
-      },
-      "react-vite": {
-        "identify": "Vite with React is commonly a client-rendered SPA; inspect whether routes are prerendered or SSR.",
-        "metadata": "For React 19, native title/meta/link hoisting may be used; for React 18 use a head manager such as react-helmet-async. Client-only updates are not sufficient for crawler visibility: prerender routes or add SSR for indexable pages.",
-        "jsonLd": "Place the JSON-LD script in the rendered document head/body and verify it is present in the prerendered HTML. Avoid adding schema only in an effect.",
-        "technical": "Generate a static HTML page per indexable route or use an SSR/prerender solution. Configure host fallback and real 404 handling, canonical URLs, robots.txt, and sitemap.xml; inspect dist output."
-      },
-      "react-router": {
-        "identify": "Determine React Router version and whether framework/SSR mode, prerendering, or SPA mode is enabled.",
-        "metadata": "In React Router framework mode, export a route meta function returning title, description, canonical link and social metadata. Ensure route metadata is rendered server-side or during prerender.",
-        "jsonLd": "Render JSON-LD in the route component or root document using route data; escape serialized JSON and ensure it appears in built HTML.",
-        "technical": "Use framework-mode SSR/prerender where pages need indexing. Generate sitemap and robots from route data; inspect actual production responses and missing-route status codes."
-      },
-      "remix": {
-        "identify": "Inspect whether the project uses Remix conventions or React Router framework mode; follow its installed version and route structure.",
-        "metadata": "Export meta from each route module. Return title, description, canonical and social meta descriptors. Compose parent and route metadata deliberately so child routes do not lose required tags.",
-        "jsonLd": "Render a script tag in the route document using loader-backed page data and safely serialized JSON-LD.",
-        "technical": "Use server rendering for indexable route content. Build sitemap.xml and robots.txt from route definitions, return correct HTTP status codes, and verify the response HTML."
-      },
-      "other": {
-        "identify": "Confirm the framework, router, rendering strategy, and metadata API from the project files and installed version.",
-        "metadata": "Use the framework’s server-rendered or build-time head/metadata API. Do not rely solely on client-side effects for indexable pages.",
-        "jsonLd": "Add a valid JSON-LD script to initial HTML using safe serialization.",
-        "technical": "Generate canonical URLs, robots rules, sitemap and redirects using the framework or hosting platform, then verify production responses."
-      }
-    },
-    "assistantGuidance": "When framework is supplied, use only its matching implementation recipe plus shared rules. When framework is auto or unknown, inspect project files and infer the framework and render mode; ask the user only if repository evidence is ambiguous. Return implementation guidance tailored to the project rather than blindly applying snippets from another framework."
-  }
-}