docs: expand README examples gallery and fix package count

README.md

@@ -47,7 +47,7 @@ A powerful TypeScript and JavaScript framework tailored for building rich termin
 - [Architecture](#architecture)
 - [Examples](#examples)
   - [Running the Examples](#running-the-examples)
-    - [Available Examples](#available-examples)
+    - [Examples Gallery](#examples-gallery)
 - [Project Structure](#project-structure)
 - [Development](#development)
 - [Requirements](#requirements)
@@ -119,6 +119,8 @@ render(
 
 ## Packages
 
+This README covers setup and the example apps in this repo. Full per-widget API reference — constructor options, props, and hooks — lives in the [Karanjot786/TermUI_Docs](https://github.com/Karanjot786/TermUI_Docs) repo, published at [termui.io](https://www.termui.io).
+
 | Package | What it does |
 |---------|-------------|
 | [`@termuijs/core`](./packages/core) | Screen buffer, input parsing, event system, flexbox layout, caps flags, WCAG utilities |
@@ -133,7 +135,9 @@ render(
 | [`@termuijs/data`](./packages/data) | Real-time system data: CPU, memory, disk, network, processes; raw API and reactive hooks |
 | [`@termuijs/dev-server`](./packages/dev-server) | Hot-reload dev server with graceful restart in under 200ms |
 | [`@termuijs/quick`](./packages/quick) | Fluent builder API for dashboards in ~20 lines |
+| [`@termuijs/adapters`](./packages/adapters) | Adapters for popular CLI libraries (git, execa, chalk) and AI/RAG helpers to integrate with TermUI |
 | [`create-termui-app`](./packages/create-termui-app) | Project scaffolding CLI |
+| [`termuijs`](./packages/cli) | Component-adding CLI — `npx termuijs add <name>` copies a widget's source into your project |
 
 ## Features
 
@@ -428,10 +432,15 @@ cd examples/ai-streaming
 bun run dev
 ```
 
-### Available Examples
+### Examples Gallery
+
+New to TermUI? Start with the tutorial ladder, then explore the rest by topic.
 
 | Example | Purpose | Features demonstrated | Path |
 |---------|---------|-----------------------|------|
+| 01 · Hello World | Smallest possible TermUI app | `App`, `Box`, `Text`, `Center`, key event handling | [`examples/01-hello-world`](./examples/01-hello-world) |
+| 02 · Simple Button | Focusable, clickable button | Custom `Widget` subclass, focus state, Enter/Space key handling | [`examples/02-simple-button`](./examples/02-simple-button) |
+| 03 · Form Inputs | Text input with live display | `TextInput`, `handleKey`, `onSubmit` | [`examples/03-form-inputs`](./examples/03-form-inputs) |
 | Auth Flow | Demonstrates authentication | Store, Text inputs, conditional rendering | [`examples/auth-flow`](./examples/auth-flow) |
 | Todo App | Interactive todo list | Store batching, Lists, Inputs | [`examples/todo-app`](./examples/todo-app) |
 | Forms and Validation | Form validation | Form widget, inputs, modals | [`examples/forms-and-validation`](./examples/forms-and-validation) |
@@ -443,6 +452,21 @@ bun run dev
 | Widget Gallery | All widgets in one place | Comprehensive widget showcase | [`examples/widget-gallery`](./examples/widget-gallery) |
 | CLI Wrapper | Live log streaming | Subprocesses, streaming output | [`examples/cli-wrapper-live`](./examples/cli-wrapper-live) |
 | AI Assistant | Interactive AI chat with streaming | ChatMessage, StreamingText, ToolCall, ToolApproval, useAI, dual-mode operation | [`examples/ai-assistant`](./examples/ai-assistant) |
+| Chat App | Streaming chat UI | Widget, ScrollView, TextInput | [`examples/chat-app`](./examples/chat-app) |
+| Kanban Board | Kanban board | Custom Widget, Box, Text | [`examples/kanban-board`](./examples/kanban-board) |
+| REST Client | Postman-style REST client | Form, Tabs, JSONView | [`examples/rest-client`](./examples/rest-client) |
+| Log Viewer | Log viewer with realtime logs and filtering | Widget composition, custom header/filter/sidebar components | [`examples/log-viewer`](./examples/log-viewer) |
+| Process Monitor | Process monitor using chart widgets and data hooks | JSX runtime, Table, LineChart, BarChart, `@termuijs/data` hooks | [`examples/process-monitor`](./examples/process-monitor) |
+| Flashcard App | Flashcard study app | Widget, Box, Text, Center | [`examples/flashcard-app`](./examples/flashcard-app) |
+| Quiz App | Multiple-choice quiz app | Widget, Box, Text, Center | [`examples/quiz-app`](./examples/quiz-app) |
+| Markdown Viewer | Scrollable terminal markdown reader | Markdown widget, ScrollView, word wrap | [`examples/markdown-viewer`](./examples/markdown-viewer) |
+| DB Browser | SQLite database browser | `bun:sqlite`, Tree, Table, ScrollView | [`examples/db-browser`](./examples/db-browser) |
+| Git Client | Git client | List, DiffView | [`examples/git-client`](./examples/git-client) |
+| File Manager | File manager | DirectoryTree, FilePicker | [`examples/file-manager`](./examples/file-manager) |
+| Pomodoro Timer | Pomodoro timer | Widget, Box, Text, Center, `@termuijs/motion` transitions | [`examples/pomodoro-timer`](./examples/pomodoro-timer) |
+| Calculator | Calculator | Widget, Box, Text, Grid, Center | [`examples/calculator`](./examples/calculator) |
+
+See [`examples/`](./examples) for the full list — 34 example applications plus 3 standalone demo scripts (37 runnable programs).
 
 ## Project structure
 
@@ -482,7 +506,7 @@ examples/
 
 ```bash
 bun install
-bun run build      # Build all 14 packages
+bun run build      # Build all 15 packages
 bun run test        # Run all 5018 tests
 bun run coverage    # Generate test coverage report
 bun run typecheck  # Type-check all packages

examples/README.md

@@ -0,0 +1,87 @@
+# Examples
+
+Every folder in this directory is a standalone, runnable TermUI app with its own `package.json`. To run one:
+
+```bash
+cd examples/<name>
+bun install
+bun run dev     # watch mode, or:
+bun run start   # single run
+```
+
+Looking for full API docs (props, constructor options) instead of example code? See [termui.io](https://www.termui.io) / [TermUI_Docs](https://github.com/Karanjot786/TermUI_Docs).
+
+## Getting started
+
+The tutorial ladder — start here if you're new to TermUI.
+
+| Example | Purpose |
+|---------|---------|
+| [`01-hello-world`](./01-hello-world) | Beginner example: basic text display |
+| [`02-simple-button`](./02-simple-button) | Beginner example: button with click |
+| [`03-form-inputs`](./03-form-inputs) | Beginner example: text input with live display |
+
+## Dashboards & data
+
+| Example | Purpose |
+|---------|---------|
+| [`dashboard`](./dashboard) | Example dashboard app using TermUI |
+| [`jsx-dashboard`](./jsx-dashboard) | JSX-based system dashboard — React-like components for the terminal |
+| [`system-monitor`](./system-monitor) | System monitor — built with `@termuijs/quick` in ~25 lines |
+| [`process-monitor`](./process-monitor) | Process monitor using chart widgets and `@termuijs/data` hooks |
+| [`data-grid`](./data-grid) | Sortable, navigable data grid built with the `DataGrid` widget |
+| [`weather`](./weather) | Weather dashboard for a given lat/lon, built with the `@termuijs/quick` fluent API |
+| [`widget-gallery`](./widget-gallery) | TermUI Widget Gallery — themes, grid, skeleton, notifications |
+| [`showcase`](./showcase) / [`ai-streaming`](./ai-streaming) | Showcase apps demonstrating all framework packages |
+
+## AI & real-time
+
+| Example | Purpose |
+|---------|---------|
+| [`ai-assistant`](./ai-assistant) | AI assistant with mock and real modes — `ChatMessage`, `StreamingText`, `ToolCall`, `ToolApproval` |
+| [`chat-app`](./chat-app) | Streaming chat UI |
+| [`rss-reader`](./rss-reader) | RSS/Atom feed reader that fetches and parses a live feed |
+| [`cli-wrapper-live`](./cli-wrapper-live) | Live log streaming from a wrapped CLI subprocess |
+
+## Productivity & tools
+
+| Example | Purpose |
+|---------|---------|
+| [`todo-app`](./todo-app) | Todo app — built with `@termuijs/quick` in ~20 lines |
+| [`forms-and-validation`](./forms-and-validation) | Forms and validation example app |
+| [`auth-flow`](./auth-flow) | Auth flow example using `@termuijs/store` and TermUI widgets |
+| [`kanban-board`](./kanban-board) | Kanban board example app |
+| [`pomodoro-timer`](./pomodoro-timer) | Pomodoro timer example app |
+| [`flashcard-app`](./flashcard-app) | Flashcard study app — built with `@termuijs/widgets` |
+| [`quiz-app`](./quiz-app) | Multiple-choice quiz app — built with `@termuijs/widgets` |
+| [`markdown-editor`](./markdown-editor) | Live markdown editor with a side-by-side preview pane |
+| [`markdown-viewer`](./markdown-viewer) | Scrollable terminal markdown reader |
+| [`json-explorer`](./json-explorer) | Interactive JSON file explorer — file picker plus a collapsible, scrollable JSON tree view |
+| [`file-manager`](./file-manager) | File manager example app |
+| [`db-browser`](./db-browser) | SQLite database browser |
+| [`git-client`](./git-client) | Git client example app |
+| [`rest-client`](./rest-client) | Postman-style REST client |
+| [`log-viewer`](./log-viewer) | Log viewer with realtime logs and filtering |
+| [`calculator`](./calculator) | Calculator example app |
+
+## Games
+
+| Example | Purpose |
+|---------|---------|
+| [`snake-game`](./snake-game) | Classic Snake game rendered in the terminal |
+
+## Architecture
+
+| Example | Purpose |
+|---------|---------|
+| [`multi-screen-router`](./multi-screen-router) | Multi-screen routing with `@termuijs/router` |
+
+## Standalone demo scripts
+
+A few single-file demos live at the top level of `examples/` (no `package.json`, no per-demo install step). They import `@termuijs/core`, `@termuijs/widgets`, and `@termuijs/ui` directly, so run the root [`bun install` / `bun run build`](../README.md#running-the-examples) steps first, then run them directly from the repo root:
+
+```bash
+bun examples/braille-chart.ts    # LineChart + BrailleCanvas rendering
+bun examples/demo-animations.ts  # Checkbox / Switch animation demo
+bun examples/menubar-demo.ts     # MenuBar widget demo
+```