@yuktishaalaa/yuktai 5.0.1 → 5.2.0

package/README.md

@@ -1,121 +1,205 @@
 # @yuktishaalaa/yuktai
 
-> Universal Next.js plugin for accessibility, AI, and data. One install brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, and an accessible data grid with Agentic AI + WebMCP — zero API keys, zero cost, works offline.
+> Universal Next.js plugin for accessibility, AI, and data. One install brings WCAG 2.2 auto-fix, in-browser RAG, an AI agent, code generation, an accessible data grid with Agentic AI + WebMCP, and an agentic toolkit that audits, explains and fixes pages and answers questions about your data. Zero API keys, zero cost, works offline.
 
 [![npm](https://img.shields.io/npm/v/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
-
 [![downloads](https://img.shields.io/npm/dm/@yuktishaalaa/yuktai)](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
-
 [![license](https://img.shields.io/badge/license-ISC-brightgreen)](./LICENSE)
-
 [![node](https://img.shields.io/badge/node-%3E%3D18-blue)](https://nodejs.org)
+[![Next.js](https://img.shields.io/badge/Next.js-13%2B-black)](https://nextjs.org)
 
-[![Next.js](https://img.shields.io/badge/Next.js-16%2B-black)](https://nextjs.org)
+Built in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03).
 
-**7,000+ developers** already installed yuktai. Built entirely in free time by [Sandeep Miriyala](https://github.com/sandeepmiriyala03) with help from Claude, GPT, and Gemini.
-
-Live demo → [https://aksharatantra.miriyala.in/staffdirectory](https://aksharatantra.miriyala.in/staffdirectory)
+**Live demos:**
+- Staff directory: https://aksharatantra.miriyala.in/staffdirectory
+- Ratnalabala, a Telugu poetry app built on YuktAI Grid: https://ratnalabala.vercel.app/poems?view=grid
 
 ---
 
 ## The story
 
-I have been building web apps since 2013. In all those years the same things kept breaking on almost every website I touched. Missing ARIA labels. No keyboard navigation. Forms that senior citizens couldn't figure out. Data grids that broke on mobile. Accessibility tools that cost money. AI tools that needed API keys.
-
-I wanted something without any of those barriers.
+I have been building web apps since 2013. In all those years, the same things kept breaking on almost every website I touched: missing ARIA labels, no keyboard navigation, forms that senior citizens couldn't figure out, data grids that broke on mobile, accessibility tools that cost money, and AI tools that needed API keys.
 
-Free. Open source. One install. Works on every device. No account. No key. No server.
+I wanted something without any of those barriers. Free. Open source. One install. Works on every device. No account. No key. No server.
 
-So I built yuktai — one weekend and one late-night at a time. This README is the map of everything that shipped.
+So I built yuktai, one weekend and one late night at a time.
 
 ---
 
 ## What's inside
 
-Five modules ship in the single npm package:
+Six modules ship in a single npm package:
 
 | Module | Features | What it does |
-
 |---|---|---|
-
 | **1. Accessibility Engine** | 16 | WCAG 2.2 auto-fix, speak on focus, colour-blind modes, dyslexia font, skip links |
+| **2. YuktaiGrid** ⭐ | 19 | Accessible data grid with Agentic AI, WebMCP, 5 WCAG themes, English/Telugu UI |
+| **3. In-Tab RAG** | 11 | Ask questions about any page, offline, no API |
+| **4. Autonomous AI Agent** | 13 | Natural-language browser guidance |
+| **5. Vibe Coder** | 19 | Generate full Next.js projects from plain English |
+| **6. Agentic AI Toolkit** 🆕 | 10 | Accessibility copilot, QA reports, form and design review, smart grid queries, BI answers, multi-step tasks, voice settings |
 
-| **2. YuktaiGrid** ⭐ NEW | 12 | Accessible data grid with 5 WCAG themes, search, sort, pagination, mobile card view |
+---
 
-| **3. In-Tab RAG** | 11 | Ask questions about any page — offline, no API |
+## What's new in v5.1: Agentic AI Toolkit
 
-| **4. Autonomous AI Agent** | 13 | Natural-language browser automation |
+Ten agentic features, all running in the browser. No API keys, and no page or grid data leaves the device unless you plug in your own model through a `generate` or `summarize` hook.
 
-| **5. Vibe Coder** | 19 | Generate full Next.js projects from plain English |
+| # | Feature | What it does | Main export |
+|---|---|---|---|
+| 1 | Accessibility Copilot | Watches the page live, explains each issue in plain English, applies safe fixes and undoes them | `createA11yCopilot` |
+| 2 | Page Understanding | Answers "What does this page do?" and "Which form fields are missing labels?" | `analyzePage`, `askAboutPage` |
+| 3 | Smart Data Grid | Turns "overdue and over ₹10,000" into real filters, finds unusual rows, summarises data | `runGridQuery`, `detectAnomalies`, `summarizeRows` |
+| 4 | Voice Accessibility | "Turn on high contrast", "bigger text", "next row", plus Telugu phrases like "పెద్ద అక్షరాలు" | `createVoiceA11yController` |
+| 5 | QA Tester | 15 checks with WCAG references, a score, pass/fail, and a Markdown or JSON report | `runQaAudit`, `auditToMarkdown` |
+| 6 | Forms Agent | Reviews labels, autocomplete, error messages and senior-friendliness | `reviewForms` |
+| 7 | Page + Data RAG | Answers from page text and grid rows, Telugu-aware, offline | `createContextIndex` |
+| 8 | Multi-Step Tasks | "Show overdue, highlight the errors, then summarise what changed" | `runTasks` |
+| 9 | BI Copilot | "Which region had the highest drop in conversion this week?" | `askInsight`, `comparePeriods` |
+| 10 | Design Review | Hierarchy, readability, focus states, clutter, consistency | `reviewDesign` |
 
-Plus Grid Assistant capabilities, Grid Agent tools, WebMCP integration, 7 custom SVG icons, and a voice + chat assistant.
+### Page tools in one panel
 
----
+```tsx
+"use client";
+import { AgenticPanel } from "@yuktishaalaa/yuktai";
+
+export default function A11yTools() {
+  return <AgenticPanel defaultTab="copilot" voiceLang="en-IN" />;
+}
+```
 
-## What's new
+Tabs: **Copilot**, **QA report**, **Forms**, **Design**, **Ask page**, **Voice**. The panel marks itself with `data-yuktai-panel`, so it never audits its own UI.
 
-### v4.6.4 — YuktaiGrid Agentic AI + WebMCP
+### Ask your grid
 
-YuktaiGrid now brings Grid UI, Grid AI Assistant, reusable Grid Tools, Agent execution, and WebMCP registration together.
+```tsx
+"use client";
+import { YuktaiGrid, useAgenticGrid, AgenticGridBar } from "@yuktishaalaa/yuktai";
+
+const columns = [
+  { key: "name", label: "Customer" },
+  { key: "status", label: "Status" },
+  { key: "region", label: "Region" },
+  { key: "balance", label: "Balance", type: "number" as const },
+  { key: "dueDate", label: "Due date", type: "date" as const },
+];
+
+export default function Customers({ rows }: { rows: Customer[] }) {
+  const grid = useAgenticGrid({ data: rows, columns, rowKey: "id" });
+
+  return (
+    <>
+      <AgenticGridBar
+        grid={grid}
+        examples={[
+          "overdue and over ₹10,000",
+          "anything unusual?",
+          "total balance by region",
+          "show overdue, then sort by balance desc, then summarize what changed",
+        ]}
+      />
+      <YuktaiGrid
+        data={grid.gridData}
+        columns={columns}
+        rowKey="id"
+        highlightIds={grid.highlightIds}
+        autoScrollToHighlight
+      />
+    </>
+  );
+}
+```
 
-- Shared Grid Tools for Agent and WebMCP execution
+`grid.ask(text)` picks the right tool for the question:
 
-- Search grid rows
+| Question type | Example | Handled by |
+|---|---|---|
+| Filters and lookups | "customer starting with A and balance between 1k and 9k" | Smart grid query |
+| Unusual data | "anything unusual?" | Outliers and duplicate rows |
+| Group and period questions | "which region had the highest drop in conversion this week?" | BI copilot |
+| Several steps | "show overdue, then highlight errors, then summarise" | Task runner, with a before/after report |
 
-- Count grid rows
+Amounts like `₹10,000`, `10k`, `1.5 lakh` and `2 crore` are understood.
 
-- Get grid columns
+### Use the functions directly
 
-- Get a row by ID
+```ts
+import { runQaAudit, auditToMarkdown, askInsight, runGridQuery } from "@yuktishaalaa/yuktai";
 
-- Highlight rows
+// In the browser: accessibility QA report
+const report = runQaAudit();
+console.log(report.score, report.passed);
+const md = auditToMarkdown(report); // attach to a ticket or PR
 
-- Select a row
+// Anywhere: data questions
+askInsight("which region had the highest drop in conversion this week", rows, columns).answer;
+runGridQuery("overdue and over 10k", { data: rows, columns }).ids;
+```
 
-- Open a row
+### Plug in your own model (optional)
 
-- WebMCP registration through document.modelContext
+Everything works offline with rules and keyword search. To get model-written answers, pass a `generate` hook, for example Gemini Nano or your own API:
 
-- useYuktaiGridAgent for programmatic Grid tool execution
+```tsx
+<AgenticPanel generate={async (question, context) => myModel(question, context)} />
+```
 
-- Embedded Grid AI Assistant inside YuktaiGrid
+### Honest limits
 
-- English and Telugu AI UI
+- Questions are understood with rules, not a language model, so unusual phrasing may need rewording. The parser returns `notes` explaining any assumption it made.
+- The QA and design checks are automatic heuristics. They catch common problems but don't replace testing with real users and assistive technology.
 
-- English voice input by default with Telugu voice-input support
+---
 
-- language, inputLanguage, and embedded AI options
+## What's new in v4.6.4: YuktaiGrid Agentic AI + WebMCP
 
-- Functional page-size switching such as 10 → 20 → 50 → 100
+- Shared Grid Tools used by both the Agent and WebMCP
+- Tools: search, count, columns, get row, highlight, select, open
+- WebMCP registration through `document.modelContext`
+- `useYuktaiGridAgent` hook for programmatic tool execution
+- Embedded Grid AI Assistant inside YuktaiGrid
+- English and Telugu AI UI, with English or Telugu voice input
+- Working page-size switching (10 → 20 → 50 → 100)
+- Seven inline SVG icons, no external icon dependency
 
-- Inline SVG Grid icons with no external icon dependency
+**Architecture:** User → Agent / WebMCP → Grid Tools → YuktaiGrid → Data
 
-- Public seven-icon package API
+---
 
-Architecture: User → Agent → WebMCP → YuktaiGrid → Data
+## Works on every device
 
-### v4.6.3
+| Device | Browser | Core features | AI engine |
+|---|---|---|---|
+| 🖥 Desktop | Chrome 147+ | ✅ All | Gemini Nano |
+| 🖥 Desktop | Firefox / Edge / Safari | ✅ All | Transformers.js |
+| 📱 Android | Chrome Mobile | ✅ All | Transformers.js |
+| 📱 iOS | Safari Mobile | ✅ All | Transformers.js |
+| 📲 PWA offline | All browsers | ✅ All | Offline after first load |
 
-Previous published release before the v4.6.4 Grid fixes and polish.
+yuktai picks the best AI engine automatically. Users never need to know which one is running.
 
 ---
 
 ## Install
 
-### Next.js 16 + React 19 (recommended)
+**Next.js 16 + React 19 (recommended)**
 
 ```bash
-
 npm install @yuktishaalaa/yuktai --legacy-peer-deps
-
 ```
 
-### Older Next.js (13, 14, 15)
+**Next.js 13, 14, 15**
 
 ```bash
-
 npm install @yuktishaalaa/yuktai
+```
+
+**Yarn / pnpm**
 
+```bash
+yarn add @yuktishaalaa/yuktai
+pnpm add @yuktishaalaa/yuktai
 ```
 
 Requirements: Node.js 18+, npm 8+, Next.js 13+.
@@ -124,771 +208,531 @@ Requirements: Node.js 18+, npm 8+, Next.js 13+.
 
 ## Quick start
 
-### Step 1 — `next.config.js`
+### Step 1: `next.config.js`
 
 ```js
-
 const nextConfig = {
-
-  transpilePackages: ["@yuktishaalaa/yuktai"],
-
+  transpilePackages: ["@yuktishaalaa/yuktai"],
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          // Needed for voice control and voice input
+          { key: "Permissions-Policy", value: "microphone=*, speaker=*" },
+        ],
+      },
+    ];
+  },
 };
 
 module.exports = nextConfig;
-
 ```
 
-### Step 2 — Client wrapper
+### Step 2: Client wrapper
 
 ```tsx
-
 // components/YuktaiClient.tsx
-
 "use client";
 
 import { useState, useEffect, type ReactNode } from "react";
-
 import { YuktAIWrapper } from "@yuktishaalaa/yuktai";
 
 export default function YuktaiClient({ children }: { children: ReactNode }) {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
 
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => setMounted(true), []);
-
-  if (!mounted) return <>{children}</>;
-
-  return (
-
-    <YuktAIWrapper position="left">
-
-      {children}
-
-    </YuktAIWrapper>
-
-  );
+  if (!mounted) return <>{children}</>;
 
+  return (
+    <YuktAIWrapper position="left" showRag showAgent>
+      {children}
+    </YuktAIWrapper>
+  );
 }
-
 ```
 
-### Step 3 — `app/layout.tsx`
+### Step 3: `app/layout.tsx`
 
 ```tsx
-
 import YuktaiClient from "@/components/YuktaiClient";
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-
-  return (
-
-    <html lang="en">
-
-      <body>
-
-        <YuktaiClient>
-
-          <main>{children}</main>
-
-        </YuktaiClient>
-
-      </body>
-
-    </html>
-
-  );
-
+  return (
+    <html lang="en">
+      <body>
+        <YuktaiClient>
+          <main>{children}</main>
+        </YuktaiClient>
+      </body>
+    </html>
+  );
 }
-
 ```
 
-That's it. Three AI-powered buttons appear on every page. Click the ♿ button bottom-right to open the accessibility panel.
-
----
-
-## Module 1 — Accessibility Engine
-
-Scans every element and injects missing accessibility attributes automatically.
-
-Covers: headings, images, forms, tables, lists, landmarks, ARIA widgets. Watches for new DOM elements via `MutationObserver`.
+That's it. Floating buttons appear on every page: ♿ opens the accessibility panel, 💬 opens "Ask this page", and the agent button opens the AI agent.
 
-### Features (16)
+To add the v5.1 agentic tools, place `<AgenticPanel />` or `useAgenticGrid` in any client component (see [What's new in v5.1](#whats-new-in-v51-agentic-ai-toolkit)).
 
-- WCAG 2.2 auto-fix — ARIA, roles, tabindex, scope, autocomplete
+### Wrapper props
 
-- Speak on focus — browser speech synthesis
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `position` | `"left" \| "right"` | `"left"` | Which side the buttons appear on |
+| `showRag` | `boolean` | `false` | Show the 💬 Ask-this-page button |
+| `showAgent` | `boolean` | `false` | Show the AI agent button |
+| `config` | `Partial<A11yConfig>` | `undefined` | Accessibility config overrides |
+| `children` | `ReactNode` | required | Your app content |
 
-- Voice control — say commands to navigate
-
-- High contrast · Dark mode · Reduce motion · Large targets (44×44)
-
-- Colour-blind modes — Deuteranopia, Protanopia, Tritanopia, Greyscale
+---
 
-- Dyslexia font — Atkinson Hyperlegible (research-backed)
+## Module 1: Accessibility Engine
 
-- Local font picker, font scaling 80–130%
+Scans every element and injects missing accessibility attributes automatically. Covers headings, images, forms, tables, lists, landmarks, and ARIA widgets. Watches for new DOM elements with `MutationObserver`.
 
-- Audit badge — WCAG score 0–100 (localhost only)
+**Features**
 
-- Skip links, focus trap, preference persistence, reset
+- WCAG 2.2 auto-fix: ARIA, roles, tabindex, scope, autocomplete, alt text
+- Speak on focus using browser SpeechSynthesis
+- Voice control using the SpeechRecognition API
+- Visual alerts for deaf and hard-of-hearing users
+- High contrast, dark mode, reduce motion, large targets (44×44)
+- Colour-blind modes: Deuteranopia, Protanopia, Tritanopia, Greyscale
+- Dyslexia font: Atkinson Hyperlegible
+- Local font picker and font scaling from 80% to 130%
+- Audit badge with a WCAG score from 0 to 100 (localhost only)
+- Skip links, focus trap, saved preferences, reset
 
-### Direct API
+**Direct API**
 
 ```ts
+import { wcagPlugin, type A11yConfig } from "@yuktishaalaa/yuktai";
 
-import { wcagPlugin } from "@yuktishaalaa/yuktai";
-
-// Apply fixes
-
-const report = wcagPlugin.applyFixes({
-
-  enabled:       true,
-
-  highContrast:  false,
-
-  darkMode:      false,
-
-  reduceMotion:  false,
-
-  largeTargets:  false,
-
-  speechEnabled: false,
-
-  colorBlindMode:"none",
-
-  autoFix:       true,
-
-});
+const config: A11yConfig = {
+  enabled: true,
+  highContrast: false,
+  darkMode: false,
+  reduceMotion: false,
+  largeTargets: false,
+  speechEnabled: false,
+  colorBlindMode: "none", // none | deuteranopia | protanopia | tritanopia | achromatopsia
+  autoFix: true,
+  showPreferencePanel: true,
+  showSkipLinks: true,
+  showAuditBadge: false, // dev only (localhost)
+  fontSizeMultiplier: 1,
+  timeoutWarning: 0, // seconds, 0 = off
+};
 
-console.log(report.fixed);   // number of fixes applied
+const report = wcagPlugin.applyFixes(config);
+console.log(report.fixed); // number of fixes applied
+console.log(report.score); // 0–100
+```
 
-console.log(report.score);   // 0–100
+### WCAG coverage
 
-```
+| Standard | Criteria | Examples |
+|---|---|---|
+| WCAG 2.0 | 19 | Alt text, roles, labels, tables, landmarks, focus |
+| WCAG 2.1 | 7 | Touch targets, reflow, motion, orientation |
+| WCAG 2.2 | 3 | Focus appearance, target size, timeout warning |
+| Beyond WCAG | Extras | Speech, visual alerts, colour-blind modes, dyslexia font, audit score |
 
 ---
 
-## Module 2 — YuktaiGrid ⭐
+## Module 2: YuktaiGrid ⭐
 
-An accessible data grid built for Next.js. Handles small tables and large datasets. Works with any API. Ships with the 5 accessibility themes.
+An accessible data grid for Next.js, with an embedded AI assistant, agent tools, and WebMCP support.
 
-### Usage
+### Basic usage
 
 ```tsx
-
 "use client";
 
 import { YuktaiGrid } from "@yuktishaalaa/yuktai";
 
 const data = [
-
-{ id: 1, name: "Sandeep", role: "Developer", salary: 85000 },
-
-{ id: 2, name: "Priya", role: "Designer", salary: 90000 },
-
+  { id: 1, name: "Sandeep", role: "Developer", salary: 85000 },
+  { id: 2, name: "Priya", role: "Designer", salary: 90000 },
 ];
 
 export default function EmployeesPage() {
+  return (
+    <YuktaiGrid
+      data={data}
+      rowKey="id"
+      columns={[
+        { key: "name", label: "Name", sortable: true },
+        { key: "role", label: "Role" },
+        { key: "salary", label: "Salary", type: "number", align: "right" },
+      ]}
+      theme="default" // default | high-contrast | dark | color-blind | dyslexia
+      locale="en-US" // en-US | te-IN
+      view="auto" // auto | table | card
+      search
+      ai
+      pagination={{
+        pageSize: 20,
+        showSizeChanger: true,
+        sizeOptions: [10, 20, 50, 100],
+      }}
+    />
+  );
+}
+```
 
-return (
-
-\<YuktaiGrid
-
-  data={data}
-
-  columns={[
-
-    { key: "name", label: "Name", sortable: true },
-
-    { key: "role", label: "Role" },
-
-    { key: "salary", label: "Salary", type: "number", align: "right" },
-
-  ]}
-
-  theme="default"                         // default | high-contrast | dark | color-blind | dyslexia
-
-  locale="en-US"                          // en-US | te-IN
-
-  search={true}                           // real-time filtering
+### Grid features
 
-  ai={true}                               // embedded Grid AI Assistant
+- Real-time search, column sorting, client-side pagination with page-size switching
+- Mobile card view below a configurable breakpoint
+- Loading and empty states
+- 5 WCAG themes
+- Row selection, custom cell render, `rowKey`
+- Row highlighting with optional auto-scroll
+- Keyboard navigation, ARIA grid semantics, 44×44 targets
+- English and Telugu UI
+- Embedded Grid AI Assistant with voice and chat
+- **New in v5.1:** compound natural-language questions, anomaly detection and BI answers through `useAgenticGrid`
 
-  view="auto"                             // auto | table | card
+### Grid AI Assistant
 
-  pagination={{
-    pageSize: 20,
-    showSizeChanger: true,
-    sizeOptions: [10, 20, 50, 100],
-  }}
+Runs embedded in the grid or as a standalone component. Intent parsing runs locally and supports search, sort, count, highest, lowest, average, total, and row lookup.
 
+```tsx
+<YuktaiGridAI
+  data={data}
+  columns={columns}
+  onSearch={handleSearch}
+  onSort={handleSort}
+  language="te-IN" // AI UI and responses: en-US | te-IN
+  inputLanguage="te-IN" // voice input: en-US | te-IN
+  embedded
 />
-
-);
-
-}
-
 ```
 
-### Grid features
+Voice recognition depends on browser Web Speech API support.
 
-- Search bar with inline SVG icon
+### Agent tools
 
-- Sort — click a column header to toggle ascending / descending
+Generic, reusable grid operations shared by the Agent and WebMCP:
 
-- Functional client-side pagination
+```ts
+import {
+  searchGrid,
+  countGrid,
+  getColumns,
+  getRow,
+  highlightRows,
+  selectRow,
+  openRow,
+} from "@yuktishaalaa/yuktai";
+```
 
-- Configurable page-size switching such as 10, 20, 50, 100
+Run tools programmatically:
 
-- Mobile card view below the configured breakpoint
+```tsx
+import { useYuktaiGridAgent, type GridAgentTool } from "@yuktishaalaa/yuktai";
 
-- Loading and empty states
+const tools: GridAgentTool[] = [
+  {
+    name: "search",
+    description: "Search grid rows by a text query",
+    execute: async ({ query }) => searchGrid(data, query),
+  },
+];
 
-- 5 WCAG themes
+const { executeTool, loading } = useYuktaiGridAgent({ tools });
+```
 
-- Row selection, custom render, and rowKey
+**Design principle:** keep generic tools in the package and put app-specific rules in your app.
 
-- Row highlighting and optional auto-scroll to highlighted rows
+```text
+Generic YuktAI tools  +  Your domain rules  =  Your application agent
+```
 
-- Embedded Grid AI Assistant
+### WebMCP
 
-- English and Telugu Grid UI
+Exposes grid tools to browser AI agents through `document.modelContext`, so agents call real operations instead of guessing from the DOM. Registration is invisible in the UI.
 
-- Inline SVG search, sort, selection, and pagination icons
+```tsx
+<YuktaiGrid
+  data={rows}
+  columns={columns}
+  ai
+  webmcp
+  toolName="my_grid"
+  toolDescriptions={TOOL_DESCRIPTIONS}
+  onWebMCPStatusChange={setStatus} // unsupported | registering | ready | partial | error
+/>
+```
+
+Or standalone:
 
-- No external icon dependency
+```tsx
+<YuktaiGridWebMCP data={data} columns={columns} />
+```
 
-### Handling large datasets (100K, 200K, 300K rows)
+WebMCP is not available in every browser, so always handle the `unsupported` status gracefully.
 
-**Client-side pagination handles a few thousand rows well.** For anything larger, use **server-side pagination** — fetch only the page you need.
+### Large datasets (100K+ rows)
 
-Here's the pattern with a Next.js API proxy that also solves CORS.
+Client-side pagination handles a few thousand rows well. For anything larger, use server-side pagination and disable the grid's built-in search and pagination.
 
-**`src/app/api/employees/route.ts`** — the proxy:
+`src/app/api/employees/route.ts`:
 
 ```ts
-
 import { NextRequest, NextResponse } from "next/server";
 
 let cachedData: any[] | null = null;
-
 let cacheTime = 0;
-
 const TTL_MS = 60_000;
 
 async function fetchAll(): Promise<any[]> {
-
-  const now = Date.now();
-
-  if (cachedData && now - cacheTime < TTL_MS) return cachedData;
-
-  const res  = await fetch("https://your-api.com/employees", { cache: "no-store" });
-
-  const json = await res.json();
-
-  cachedData = Array.isArray(json) ? json : (json.employees ?? json.data ?? []);
-
-  cacheTime  = now;
-
-  return cachedData;
-
+  const now = Date.now();
+  if (cachedData && now - cacheTime < TTL_MS) return cachedData;
+  const res = await fetch("https://your-api.com/employees", { cache: "no-store" });
+  const json = await res.json();
+  cachedData = Array.isArray(json) ? json : json.employees ?? json.data ?? [];
+  cacheTime = now;
+  return cachedData;
 }
 
 export async function GET(req: NextRequest) {
-
-  const p = req.nextUrl.searchParams;
-
-  const page     = Math.max(1, parseInt(p.get("page")     || "1"));
-
-  const pageSize = Math.max(1, parseInt(p.get("pageSize") || "5000"));
-
-  const search   = (p.get("search") || "").toLowerCase().trim();
-
-  const all      = await fetchAll();
-
-  const filtered = search
-
-    ? all.filter(r => Object.values(r).some(v => String(v).toLowerCase().includes(search)))
-
-    : all;
-
-  const total = filtered.length;
-
-  const rows  = filtered.slice((page - 1) * pageSize, page * pageSize);
-
-  return NextResponse.json({
-
-    rows,
-
-    pagination: { page, pageSize, totalRows: total, totalPages: Math.ceil(total / pageSize) },
-
-  });
-
+  const p = req.nextUrl.searchParams;
+  const page = Math.max(1, parseInt(p.get("page") || "1"));
+  const pageSize = Math.max(1, parseInt(p.get("pageSize") || "5000"));
+  const search = (p.get("search") || "").toLowerCase().trim();
+
+  const all = await fetchAll();
+  const filtered = search
+    ? all.filter((r) => Object.values(r).some((v) => String(v).toLowerCase().includes(search)))
+    : all;
+
+  const total = filtered.length;
+  const rows = filtered.slice((page - 1) * pageSize, page * pageSize);
+
+  return NextResponse.json({
+    rows,
+    pagination: { page, pageSize, totalRows: total, totalPages: Math.ceil(total / pageSize) },
+  });
 }
-
 ```
 
-**Page — call the paginated API and disable the grid's built-in pagination:**
+Page:
 
 ```tsx
-
-const [apiResp, setApiResp]     = useState<any>(null);
-
-const [currentPage, setPage]    = useState(1);
+const [apiResp, setApiResp] = useState<any>(null);
+const [currentPage, setPage] = useState(1);
 
 useEffect(() => {
-
-  fetch(`/api/employees?page=${currentPage}&pageSize=5000`)
-
-    .then(r => r.json())
-
-    .then(setApiResp);
-
+  fetch(`/api/employees?page=${currentPage}&pageSize=5000`)
+    .then((r) => r.json())
+    .then(setApiResp);
 }, [currentPage]);
 
 <YuktaiGrid
-
-  data={apiResp?.rows ?? []}
-
-  columns={columns}
-
-  search={false}         // disable — we handle search server-side
-
-  pagination={false}     // disable — we handle pagination server-side
-
-  loading={!apiResp}
-
-/>
-
+  data={apiResp?.rows ?? []}
+  columns={columns}
+  search={false} // handled server-side
+  pagination={false} // handled server-side
+  loading={!apiResp}
+/>;
 ```
 
-Then render your own pagination bar backed by `apiResp.pagination`. This pattern works for 100K, 200K, 300K rows — the browser only ever holds 5,000 rows in memory.
-
----
+Render your own pagination bar from `apiResp.pagination`. The browser only ever holds one page in memory.
 
 ---
 
-## Grid Agentic AI + WebMCP
-
-YuktaiGrid exposes reusable Grid operations so an Agent can work with grid data through a shared tool layer and WebMCP.
-
-### Grid tools
-
-```ts
-
-import {
-searchGrid,
-countGrid,
-getColumns,
-getRow,
-highlightRows,
-selectRow,
-openRow,
-} from "@yuktishaalaa/yuktai";
-
-```
-
-These operations form the common execution layer for programmatic Agent tools and WebMCP.
-
-### Agent execution
-
-```tsx
-
-import {
-useYuktaiGridAgent,
-type GridAgentTool,
-} from "@yuktishaalaa/yuktai";
-
-const tools: GridAgentTool[] = [
-{
-name: "search",
-description: "Search grid rows",
-execute: async ({ query }) => {
-return { query };
-},
-},
-];
-
-const { executeTool, loading } =
-useYuktaiGridAgent({ tools });
-
-```
-
-### WebMCP
-
-```tsx
-
-import {
-YuktaiGridWebMCP,
-} from "@yuktishaalaa/yuktai";
+## Showcase: Ratnalabala (Telugu poetry)
 
-<YuktaiGridWebMCP
-data={data}
-columns={columns}
-/>
+[Ratnalabala](https://ratnalabala.vercel.app/poems?view=grid) shows that an agentic grid is more than a chatbot next to a table. Users type or speak in Telugu, and the grid acts.
 
+| User says | Agent action |
+|---|---|
+| `ఎన్ని పద్యాలు` (how many poems) | `count` → "మొత్తం 36 పద్యాలు ఉన్నాయి." |
+| `గర్వం తెరువు` (open "Garvam") | `open` |
+| `"బుద్ధి" ఉన్న పద్యాలు` (poems with "buddhi") | `search` + highlight |
+| `అక్షర క్రమంలో` (alphabetical) | `sort(title, asc)` |
+| `ఈరోజు పద్యం` (poem of the day) | custom rule + highlight |
+
+**Stack:** Next.js · React + TypeScript · MUI · YuktAI Grid · FastAPI (Python) · PostgreSQL on Neon · Vercel · Web Speech API · WebMCP
+
+```text
+PostgreSQL → FastAPI → Next.js API proxy → Ratnalabala UI → YuktAI Grid
+                                                              ├── Agent
+                                                              └── WebMCP
 ```
 
-WebMCP registration is invisible in the UI and uses document.modelContext when available.
-
-### Embedded Grid AI Assistant
-
 ```tsx
-
-<YuktaiGrid
-data={data}
-columns={columns}
-locale="te-IN"
-ai={true}
-pagination={{
-pageSize: 20,
-showSizeChanger: true,
-sizeOptions: [10, 20, 50, 100],
-}}
+<YuktaiGrid<PoemRow>
+  data={rows}
+  columns={COLUMNS}
+  rowKey="id"
+  locale="te-IN"
+  inputLanguage="te-IN"
+  customRules={POEM_RULES}
+  search
+  highlightIds={highlightIds}
+  autoScrollToHighlight
+  onRowClick={(row) => onOpenPoem(row.title)}
+  ai
+  webmcp
+  toolName="ratnalabala_poems"
+  toolDescriptions={TOOL_DESCRIPTIONS}
+  onWebMCPStatusChange={setWebmcp}
 />
-
 ```
 
-Grid AI supports:
-
-- language="en-US" or language="te-IN" for AI UI and responses
-
-- inputLanguage="en-US" or inputLanguage="te-IN" for voice input
-
-- embedded mode for rendering AI inside the Grid
-
-- Local intent parsing for search, sort, count, highest, lowest, average, total, and lookup
-
 ---
 
-## Module 3 — In-Tab RAG (Ask This Page)
-
-Retrieval-Augmented Generation running entirely in the browser. Extracts semantic chunks from the current DOM, embeds them, finds the best match for the user's question, and answers — offline, no API key.
-
-### Features (11)
-
-- Ask any question about any page
-
-- Gemini Nano on desktop Chrome — zero download, zero API
-
-- Transformers.js on mobile — 30 MB one-time model load
+## Module 3: In-Tab RAG (Ask This Page)
 
-- Auto engine detection and switching
+Retrieval-Augmented Generation running entirely in the browser. It extracts text chunks from the current page, embeds them, finds the best match for the question, and answers. Offline, no API key.
 
-- Works offline after first load
-
-- q4 quantization on mobile (32-bit → 4-bit weights)
-
-- `flan-t5-small` for full-sentence answers
-
-- Cosine similarity semantic search
+| Device | Engine | How it works |
+|---|---|---|
+| Desktop Chrome with Gemini Nano | `window.LanguageModel` | Page text sent as context, instant answer |
+| Mobile and all other browsers | Transformers.js | Embeddings + `flan-t5-small`, q4 quantized |
 
-- Deduped DOM text extraction
+- About 30 MB one-time model download on mobile, cached in IndexedDB
+- Works fully offline after first load
+- All processing on device, no data sent anywhere
 
-### What I learned
+**What I learned:** Transformers.js kept crashing on iOS Safari with out-of-memory errors. Quantization (same model, 75% smaller) fixed it. DistilBERT gave short, useless spans; `flan-t5-small` gives real sentences.
 
-The hardest part was mobile. Transformers.js kept crashing on iOS Safari with out-of-memory errors. Learning about quantization — same model, 75% smaller — fixed it. DistilBERT gives short useless spans; flan-t5-small gives real sentences. None of that was in any tutorial. Found on a Saturday by breaking things until something worked.
+**New in v5.1:** `createContextIndex` also searches grid rows (including rows on other pages of the grid) and your own documents, with keyword search that handles Telugu and Hindi script correctly.
 
 ---
 
-## Module 4 — Autonomous AI Agent
-
-User types a goal in plain English. Yuktai reads the DOM, finds the right elements, plans steps, and highlights what to do.
+## Module 4: Autonomous AI Agent
 
-### Features (13)
-
-- Plain-English goal input
-
-- Reads full page DOM — 9 traversal strategies
-
-- Scans all form fields — 11 label strategies
+Type a goal in plain English. yuktai reads the page, finds the right elements, plans the steps, and highlights what to do.
 
+- 9 DOM traversal strategies and 11 form-label strategies
 - Works on static HTML, React, WordPress, and old government portals
+- Gemini Nano planning on desktop, Transformers.js on mobile, rule-based fallback
+- Highlights target fields, scrolls to sections, shows a numbered plan, handles iframes
 
-- Gemini Nano planning on desktop, Transformers.js on mobile
-
-- Rule-based fallback if AI fails
-
-- Highlights target field with teal outline
-
-- Scrolls to relevant section by keyword
-
-- Numbered step-by-step plan
-
-- Handles iframes
-
-The 11 label strategies came from real websites — old government portals put labels in the previous table cell, modern apps use `aria-label`, static pages use `placeholder`. Every strategy solved a problem I had actually hit.
+Every label strategy came from a real website: old portals put labels in the previous table cell, modern apps use `aria-label`, static pages use `placeholder`.
 
 ---
 
-## Module 5 — Vibe Coder
-
-Type a business requirement. Yuktai generates a full Next.js 16 project as a downloadable ZIP.
-
-### Features (19)
+## Module 5: Vibe Coder
 
-- Detects website type (12 types), pages needed (21 types), features (14 types)
-
-- Detects theme colour (8), extracts site name
+Type a business requirement and download a full Next.js 16 project as a ZIP.
 
+- Detects website type (12), pages (21), features (14), theme colour (8), and site name
 - Preview before generating
+- TypeScript, Tailwind + CSS Modules, mobile responsive
+- Navbar, Footer, Home, About, Contact, Services, Pricing, Auth, Dashboard
+- `npm run dev` works immediately
 
-- Full Next.js 16 project — Tailwind + CSS Modules, TypeScript, mobile responsive
-
-- Navbar, Footer, Home, About, Contact, Services, Pricing, Auth, Dashboard pages
-
-- Downloads as ZIP · `npm run dev` works immediately
-
-- Pure templates — no AI writes the code
-
-No AI writes a single line. Pure template engineering. Same reusable-utility thinking from 2013 jQuery — now generating entire Next.js projects.
+No AI writes the code. It's pure template engineering.
 
 ---
 
-## Grid AI Assistant — Voice + Chat
-
-The Grid AI Assistant can run embedded inside YuktaiGrid or as a standalone component.
-
-Voice input uses the browser Web Speech API. AI responses can be spoken with SpeechSynthesis. Intent parsing runs locally for the supported Grid operations.
-
-Supports:
-
-- Search
-
-- Sort
-
-- Count
+## Module 6: Agentic AI Toolkit 🆕
 
-- Highest / maximum
+The ten v5.1 features, described in detail in [What's new in v5.1](#whats-new-in-v51-agentic-ai-toolkit).
 
-- Lowest / minimum
+- **Copilot and QA:** 15 WCAG checks, plain-English explanations, safe fixes with undo, downloadable reports
+- **Forms and design review:** labels, autocomplete, error messages, focus states, hierarchy, clutter, senior-friendly tips
+- **Data:** compound grid questions, outliers and duplicates, group-by, period comparison, trends
+- **Automation:** multi-step instructions with a before/after summary
+- **Voice:** accessibility settings and grid row navigation by voice, in English and Telugu
+- **React:** `AgenticPanel`, `AgenticGridBar`, `useAgenticGrid`
 
-- Average
-
-- Total
-
-- Row lookup
-
-- English and Telugu AI UI
+---
 
-- English voice input by default
+## Gemini Nano setup (desktop Chrome, one time)
 
-- Telugu voice input with inputLanguage="te-IN"
+Needed only for Gemini Nano features on desktop Chrome. Mobile and other browsers use Transformers.js automatically.
 
-Example:
+1. Open `chrome://flags` and enable: Prompt API for Gemini Nano, Summarization API, Writer API, Rewriter API, Translation API.
+2. Click **Relaunch**.
+3. Open `chrome://components`, find **Optimization Guide On Device Model**, and click **Check for update**.
+4. Refresh your page. AI features unlock automatically.
 
-```tsx
+**Gemini Nano features:** plain-English rewriting, 3-sentence page summary, AI-generated ARIA labels, page translation in 18 languages.
 
-<YuktaiGridAI
-data={data}
-columns={columns}
-onSearch={handleSearch}
-onSort={handleSort}
-language="te-IN"
-inputLanguage="en-US"
-embedded
-/>
-
-```
-
-Voice recognition depends on browser Web Speech API support.
+> Chrome 147 moved the APIs from `window.ai` to standalone globals such as `window.LanguageModel`. yuktai supports both.
 
 ---
 
-## Icon library
+## Icons
 
-7 custom SVG icons. Zero external dependency. All seven remain part of the public package API.
+Seven custom SVG icons with no external dependency.
 
 ```tsx
-
 import {
-
-  SearchIcon,
-
-  SortUpIcon,
-
-  SortDownIcon,
-
-  ChevronLeftIcon,
-
-  ChevronRightIcon,
-
-  CheckIcon,
-
-  CloseIcon,
-
+  SearchIcon,
+  SortUpIcon,
+  SortDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CheckIcon,
+  CloseIcon,
 } from "@yuktishaalaa/yuktai";
 
-<SearchIcon        size={20} />
-
-<SortUpIcon        size={20} color="#0D9488" />
-
-<CheckIcon         size={20} color="#10b981" label="Task complete" />
-
-<CloseIcon         size={20} color="#dc2626" />
-
-<ChevronLeftIcon   size={24} label="Previous" />
-
-<ChevronRightIcon  size={24} label="Next" />
-
+<SearchIcon size={20} />
+<CheckIcon size={20} color="#10b981" label="Task complete" />
 ```
 
-Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (default 2.5), `label` (adds ARIA — decorative if omitted).
-
----
-
-## Gemini Nano (Chrome 147+)
-
-- Plain-English mode — rewrites complex text
-
-- Summarise page — 3-sentence summary
-
-- Smart ARIA labels — AI generates labels
-
-- Translate page — 18 languages
-
-- Chrome 147+ standalone globals (`window.LanguageModel`)
-
-- Fallback to old `window.ai` namespace
-
-Chrome 147 silently removed `window.ai` and moved everything to standalone globals. Debugged for an evening before finding it in the release notes.
-
----
-
-## Technical (17 features)
-
-Zero API keys · Zero cost · Zero telemetry · Works on all browsers · Works on mobile (Android + iOS) · Works offline after first load · PWA compatible · Next.js 16 compatible · React 19 compatible · TypeScript throughout · SSR safe (no window errors) · Escape closes all panels · Each panel closes others · `data-yuktai-panel` — never reads own UI · Three stacked FAB buttons · Mobile full-screen panels · Tablet responsive · `showRag`, `showAgent`, `position` props.
-
----
-
-## Configuration
-
-```ts
-
-import { wcagPlugin, A11yConfig } from "@yuktishaalaa/yuktai";
-
-const config: A11yConfig = {
-
-  enabled:             true,   // required
-
-  highContrast:        false,
-
-  darkMode:            false,
-
-  reduceMotion:        false,
-
-  largeTargets:        false,
-
-  speechEnabled:       false,
-
-  colorBlindMode:      "none", // none | deuteranopia | protanopia | tritanopia | achromatopsia
-
-  autoFix:             true,
-
-  showPreferencePanel: true,
-
-  showSkipLinks:       true,
-
-  showAuditBadge:      false,  // dev only (localhost)
-
-  fontSizeMultiplier:  1,
-
-  timeoutWarning:      0,      // seconds (0 = off)
-
-};
-
-await wcagPlugin.execute(config);
-
-```
-
----
-
-## WCAG coverage
-
-| Standard | Criteria covered |
-
-|---|---|
-
-| WCAG 2.0 | 19 criteria |
-
-| WCAG 2.1 | 7 criteria |
-
-| WCAG 2.2 | 3 criteria (focus appearance, target size, timeout) |
-
-| Beyond WCAG | SpeechSynthesis, visual alerts, keyboard cheatsheet, audit score, colour-blind modes, dyslexia font |
+Props: `size` (default 20), `color` (default `currentColor`), `strokeWidth` (default 2.5), `label` (adds ARIA; decorative if omitted).
 
 ---
 
 ## Design principles
 
-- **Zero id attributes** — no injected node ever gets an `id`. Tracked via module-level JavaScript references. Never collides with host app ids.
-
-- **Zero API keys** — runs entirely in the browser. No external calls, no telemetry, no cost.
-
-- **Zero framework lock-in** — `core/renderer.ts` has no framework imports. Works in Node.js, browsers, and test environments.
-
-- **Honest limits** — client-side grid pagination works for a few thousand rows. Beyond that, use server-side pagination (pattern shown above).
+- **Zero API keys, zero cost, zero telemetry.** Everything runs in the browser.
+- **Zero injected ids.** Injected nodes are tracked by JavaScript references, so they never collide with your app's ids.
+- **Zero framework lock-in.** `core/renderer.ts` has no framework imports.
+- **Never reads its own UI.** Panels are marked with `data-yuktai-panel`.
+- **SSR safe.** No `window` errors on the server.
+- **Every automatic fix can be undone.** The v5.1 copilot records each change it makes.
+- **Honest limits.** Client-side pagination is for a few thousand rows; use server-side beyond that.
 
 ---
 
 ## Compatibility
 
-### Next.js versions
-
-| Version | Supported |
-
+| | Supported |
 |---|---|
-
-| Next.js 16 | ✅ |
-
-| Next.js 15 | ✅ |
-
-| Next.js 14 | ✅ |
-
-| Next.js 13 | ✅ |
-
-### React versions
-
-| Version | Supported | Install flag |
-
-|---|---|---|
-
-| React 19 | ✅ | `--legacy-peer-deps` |
-
-| React 18 | ✅ | none |
-
-| React 17 | ✅ | none |
-
-### Browsers
-
-Chrome 90+ · Firefox 90+ · Safari 15+ · Edge 90+ · Samsung Internet 14+
+| Next.js | 13, 14, 15, 16 |
+| React | 17, 18, 19 (19 needs `--legacy-peer-deps`) |
+| Node.js | 18+ |
+| Browsers | Chrome 90+, Firefox 90+, Safari 15+, Edge 90+, Samsung Internet 14+ |
 
 ---
 
 ## Roadmap
 
-Shipped: v4.6.4 — YuktaiGrid Agentic AI + WebMCP integration, embedded Grid AI Assistant, English/Telugu Grid UI, functional page-size switching, and Grid icon polish.
+- **Shipped (v5.1):** Agentic AI Toolkit: accessibility copilot, QA reports, form and design review, smart grid queries, BI answers, multi-step tasks, page + data RAG, voice accessibility commands
+- **Shipped (v4.6.4):** YuktaiGrid Agentic AI + WebMCP, embedded Grid AI Assistant, English/Telugu UI, page-size switching, icon polish
+- **Next:** expose the v5.1 agentic tools through WebMCP, more Grid Agent tools, multilingual RAG (Telugu, Hindi, Tamil, Bengali)
+- **Later:** RTL support, richer browser-native AI, multimodal grid experiences
+
+---
 
-Next: expand Grid Agent tools and WebMCP capabilities.
+## Contributing
 
-Long term: richer browser-native AI and multimodal Grid experiences.
+Issues and pull requests are welcome at [github.com/sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai). For security issues, see [SECURITY.md](./SECURITY.md).
 
 ---
 
 ## Links
 
-- npm — [@yuktishaalaa/yuktai](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
-
-- GitHub — [sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai)
-
-- Live demo — [aksharatantra.vercel.app](https://aksharatantra.vercel.app)
+- npm: [@yuktishaalaa/yuktai](https://www.npmjs.com/package/@yuktishaalaa/yuktai)
+- GitHub: [sandeepmiriyala03/yuktai](https://github.com/sandeepmiriyala03/yuktai)
+- Demo: [aksharatantra.miriyala.in/staffdirectory](https://aksharatantra.miriyala.in/staffdirectory)
+- Showcase: [ratnalabala.vercel.app](https://ratnalabala.vercel.app/poems?view=grid)
 
 ---
 
 ## License
 
-ISC © Sandeep Miriyala — [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
+ISC © Sandeep Miriyala, [Yuktishaalaa AI Lab](https://github.com/sandeepmiriyala03)
 
-Built in free time. With help from Claude, GPT, and Gemini for learning — but every line written, every bug fixed, every decision made by me.
+Built in free time. AI coding assistants (Claude, GPT and Gemini) helped me learn, and helped write and test parts of the code. Every design decision, review and release is mine.
 
-Free forever. Open source.
+**Free forever. Open source. Built for every user.** 🏺