retold 4.0.1 → 4.0.3

package/docs/{modules.md → architecture/modules.md}

@@ -13,25 +13,24 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | [fable-uuid](/fable/fable-uuid/) | `fable-uuid` | UUID generator supporting RFC 4122 v4 and configurable random strings |
 | [fable-log-logger-bunyan](/fable/fable-log-logger-bunyan/) | `fable-log-logger-bunyan` | Bunyan structured logging provider for Fable-Log |
 
-## Meadow — Data Access Layer (13 modules)
+## Meadow — Data Access Layer (12 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
-| [meadow](/meadow/meadow/) | `meadow` | Provider-agnostic data broker with CRUD operations, audit tracking, and soft deletes |
-| [foxhound](/meadow/foxhound/) | `foxhound` | Fluent query DSL generating dialect-specific SQL for MySQL, MSSQL, SQLite, and ALASQL |
 | [stricture](/meadow/stricture/) | `stricture` | MicroDDL schema definition language generating JSON, SQL DDL, and documentation |
+| [foxhound](/meadow/foxhound/) | `foxhound` | Fluent query DSL generating dialect-specific SQL for MySQL, MSSQL, SQLite, and ALASQL |
+| [bibliograph](/meadow/bibliograph/) | `bibliograph` | Key-value record comprehension for change tracking in data ingestion pipelines |
+| [meadow](/meadow/meadow/) | `meadow` | Provider-agnostic data broker with CRUD operations, audit tracking, and soft deletes |
+| [parime](/meadow/parime/) | `parime` | Generic data lake behaviors and services |
 | [meadow-endpoints](/meadow/meadow-endpoints/) | `meadow-endpoints` | Automatic RESTful CRUD endpoint generation from Meadow entities with behavior injection |
 | [meadow-connection-mysql](/meadow/meadow-connection-mysql/) | `meadow-connection-mysql` | MySQL/MariaDB pooled connection provider for Meadow |
 | [meadow-connection-mssql](/meadow/meadow-connection-mssql/) | `meadow-connection-mssql` | Microsoft SQL Server connection provider for Meadow |
 | [meadow-connection-sqlite](/meadow/meadow-connection-sqlite/) | `meadow-connection-sqlite` | SQLite connection provider for Meadow via better-sqlite3 |
 | [retold-data-service](/meadow/retold-data-service/) | `retold-data-service` | All-in-one Fable service assembling schema → entity → endpoints → REST API |
 | [retold-harness](/meadow/retold-harness/) | `retold-harness` | Pre-built API harness with a bookstore demo (8 entities, 10,000+ records) |
-| [bibliograph](/meadow/bibliograph/) | `bibliograph` | Key-value record comprehension for change tracking in data ingestion pipelines |
-| [parime](/meadow/parime/) | `parime` | Generic data lake behaviors and services |
 | [meadow-integration](/meadow/meadow-integration/) | `meadow-integration` | Data integration tools for CSV import, schema mapping, and centralized formats |
-| [meadow-graph-client](/meadow/meadow-graph-client/) | `meadow-graph-client` | Client for pulling related record sets from relational database graphs |
 
-## Orator — API Server (6 modules)
+## Orator — API Server (7 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
@@ -41,35 +40,39 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | [orator-http-proxy](/orator/orator-http-proxy/) | `orator-http-proxy` | HTTP reverse proxy for forwarding requests to backend services |
 | [tidings](/orator/tidings/) | `tidings` | Extensible reporting system for generating HTML, PDF, and other format reports |
 | [orator-endpoint](/orator/orator-endpoint/) | `orator-endpoint` | Pluggable API endpoint base class for reusable route handlers |
+| [orator-conversion](/orator/orator-conversion/) | `orator-conversion` | File format conversion endpoints for Orator service servers |
 
-## Pict — MVC Tools (15 modules)
+## Pict — MVC Tools (19 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
 | [pict](/pict/pict/) | `pict` | Non-opinionated MVC module with template expression engine for text-based UIs |
-| [pict-view](/pict/pict-view/) | `pict-view` | View base class with full lifecycle (init, render, solve, marshal), renderables, and CSS |
 | [pict-template](/pict/pict-template/) | `pict-template` | Template handler base class for custom expression types |
+| [pict-view](/pict/pict-view/) | `pict-view` | View base class with full lifecycle (init, render, solve, marshal), renderables, and CSS |
 | [pict-provider](/pict/pict-provider/) | `pict-provider` | Data provider base class for delivering data to views |
 | [pict-application](/pict/pict-application/) | `pict-application` | Application base class coordinating views, state, and lifecycle |
-| [pict-section-form](/pict/pict-section-form/) | `pict-section-form` | Configuration-driven dynamic forms with 13+ input types and data marshaling |
+| [pict-panel](/pict/pict-panel/) | `pict-panel` | Hot-loadable control panel component for browser applications |
+| [pict-nonlinearconfig](/pict/pict-nonlinearconfig/) | `pict-nonlinearconfig` | Pict nonlinear configuration manager |
+| [pict-section-flow](/pict/pict-section-flow/) | `pict-section-flow` | Pict section flow diagram |
+| [pict-docuserve](/pict/pict-docuserve/) | `pict-docuserve` | Single-page documentation viewer built on Pict |
+| [cryptbrau](/pict/cryptbrau/) | `cryptbrau` | Simple in-browser symmetric encryption |
+| [informary](/pict/informary/) | `informary` | Dependency-free browser form marshaling with undo/redo and field-level deltas |
+| [pict-service-commandlineutility](/pict/pict-service-commandlineutility/) | `pict-service-commandlineutility` | CLI utility module built on Commander for Pict-based command-line tools |
 | [pict-section-recordset](/pict/pict-section-recordset/) | `pict-section-recordset` | CRUD record management views from Meadow endpoint schemas |
+| [pict-section-content](/pict/pict-section-content/) | `pict-section-content` | Markdown parsing and content rendering with Mermaid diagrams and KaTeX math |
+| [pict-section-form](/pict/pict-section-form/) | `pict-section-form` | Configuration-driven dynamic forms with 13+ input types and data marshaling |
 | [pict-section-tuigrid](/pict/pict-section-tuigrid/) | `pict-section-tuigrid` | Toast UI Grid integration for tabular data display and editing |
-| [pict-section-content](/pict/pict-section-content/) | `pict-section-content` | Content display sections for static and dynamic content blocks |
-| [pict-panel](/pict/pict-panel/) | `pict-panel` | Hot-loadable control panel component for browser applications |
 | [pict-router](/pict/pict-router/) | `pict-router` | Hash-based URL routing via Navigo with template string route functions |
-| [informary](/pict/informary/) | `informary` | Dependency-free browser form marshaling with undo/redo and field-level deltas |
-| [cryptbrau](/pict/cryptbrau/) | `cryptbrau` | Simple in-browser symmetric encryption |
 | [pict-serviceproviderbase](/pict/pict-serviceproviderbase/) | `pict-serviceproviderbase` | Base classes for Pict services with pre-initialization support |
-| [pict-service-commandlineutility](/pict/pict-service-commandlineutility/) | `pict-service-commandlineutility` | CLI utility module built on Commander for Pict-based command-line tools |
+| [pict-terminalui](/pict/pict-terminalui/) | `pict-terminalui` | Blessed-based terminal interface for Pict views |
 
-## Utility — Build & Documentation Tools (5 modules)
+## Utility — Build & Documentation Tools (4 modules)
 
 | Module | npm | Description |
 |--------|-----|-------------|
 | [indoctrinate](/utility/indoctrinate/) | `indoctrinate` | Documentation scaffolding with content cataloging, label-based filtering, and multi-format output |
 | [manyfest](/utility/manyfest/) | `manyfest` | JSON manifest for consistent data description, validation, and address-based access across layers |
 | [quackage](/utility/quackage/) | `quackage` | Standardized build tool for browser bundles, transpilation, testing, and packaging |
-| [choreographic](/utility/choreographic/) | `choreographic` | Scaffolding for single-run data processing scripts with organized output |
 | [ultravisor](/utility/ultravisor/) | `ultravisor` | Process supervision with scheduled tasks, distributed nodes, and LLM integration |
 
 ## Summary
@@ -77,11 +80,11 @@ An exhaustive list of every repository in the Retold suite, organized by group.
 | Group | Count | Focus |
 |-------|-------|-------|
 | Fable | 6 | Core ecosystem, DI, configuration, logging |
-| Meadow | 13 | Data access, ORM, query DSL, schema, connectors |
-| Orator | 6 | API server, HTTP, static files, proxy, reporting |
-| Pict | 15 | MVC, views, templates, forms, grids, routing |
-| Utility | 5 | Build tools, manifests, docs, process supervision |
-| **Total** | **45** | |
+| Meadow | 12 | Data access, ORM, query DSL, schema, connectors |
+| Orator | 7 | API server, HTTP, static files, proxy, reporting, conversion |
+| Pict | 19 | MVC, views, templates, forms, grids, routing, docs, TUI |
+| Utility | 4 | Build tools, manifests, docs, process supervision |
+| **Total** | **48** | |
 
 ## GitHub Repositories
 

package/docs/cover.md

@@ -10,6 +10,6 @@
 - **Pict** — MVC tools, views, templates, forms
 
 [Get Started](getting-started.md)
-[Architecture](architecture.md)
-[All Modules](modules.md)
+[Architecture](architecture/architecture.md)
+[All Modules](modules/modules.md)
 [GitHub](https://github.com/stevenvelozo/retold)

package/docs/css/docuserve.css

@@ -13,7 +13,7 @@ html, body {
 	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
 	font-size: 16px;
 	line-height: 1.5;
-	color: #333;
+	color: #423D37;
 	background-color: #fff;
 	-webkit-font-smoothing: antialiased;
 	-moz-osx-font-smoothing: grayscale;
@@ -26,12 +26,12 @@ h1, h2, h3, h4, h5, h6 {
 }
 
 a {
-	color: #42b983;
+	color: #2E7D74;
 	text-decoration: none;
 }
 
 a:hover {
-	color: #38a373;
+	color: #256861;
 }
 
 /* Application container */
@@ -45,16 +45,16 @@ a:hover {
 }
 
 ::-webkit-scrollbar-track {
-	background: #f1f1f1;
+	background: #F5F0E8;
 }
 
 ::-webkit-scrollbar-thumb {
-	background: #bdc3c7;
+	background: #D4CCBE;
 	border-radius: 4px;
 }
 
 ::-webkit-scrollbar-thumb:hover {
-	background: #95a5a6;
+	background: #B5AA9A;
 }
 
 /* Responsive adjustments */

package/docs/examples/examples.md

@@ -0,0 +1,71 @@
+# Examples
+
+The `examples/` directory contains complete, runnable applications that demonstrate how Retold modules work together. Each example is self-contained with its own `package.json` and README.
+
+## Quickstart Layers
+
+**Location:** `examples/quickstart/`
+
+A five-step progression that builds up the Retold stack one layer at a time, from a bare Fable instance to a full API with a Pict browser UI. Each layer adds one concept and is referenced from the [Getting Started](../getting-started.md) guide.
+
+| Layer | What it adds |
+|-------|-------------|
+| Layer 1 | Fable -- configuration, logging, dependency injection |
+| Layer 2 | Meadow -- define a data entity and connect to a database |
+| Layer 3 | Orator -- serve the entity over HTTP |
+| Layer 4 | Meadow-Endpoints -- auto-generate the full REST API |
+| Layer 5 | Pict + Manyfest -- add a browser UI and schema-driven data access |
+
+## Todo List Application
+
+**Location:** `examples/todo-list/`
+
+A complete full-stack application with four separate clients that all connect to the same REST API and SQLite database. This is the most comprehensive example in the repository and demonstrates nearly every major Retold pattern.
+
+```mermaid
+graph LR
+    server["API Server<br/><i>Orator + Meadow + SQLite</i>"]
+    web["Web Client<br/><i>Pict Application</i>"]
+    console["Console Client<br/><i>blessed TUI</i>"]
+    cli["CLI Client<br/><i>pict-service-commandlineutility</i>"]
+
+    web -- "fetch()" --> server
+    console -- "http.request()" --> server
+    cli -- "http.request()" --> server
+
+    style server fill:#e3f2fd,stroke:#42a5f5,color:#333
+    style web fill:#e8f5e9,stroke:#43a047,color:#333
+    style console fill:#fff3e0,stroke:#ffa726,color:#333
+    style cli fill:#f3e5f5,stroke:#ab47bc,color:#333
+```
+
+**Detailed documentation:**
+
+- **[Todo List Application](examples/todolist/todo-list.md)** -- Architecture overview and quickstart
+- **[Data Model](examples/todolist/todo-list-model.md)** -- Stricture MicroDDL, Meadow schema, seed data
+- **[API Server](examples/todolist/todo-list-server.md)** -- Orator + Meadow + SQLite wiring
+- **[Web Client](examples/todolist/todo-list-web-client.md)** -- Pict Application with views, providers, and routing
+- **[Console Client](examples/todolist/todo-list-console-client.md)** -- blessed TUI with pict-terminalui
+- **[CLI Client](examples/todolist/todo-list-cli-client.md)** -- Non-interactive command-line tool
+
+### Retold Patterns Demonstrated
+
+| Pattern | Where |
+|---------|-------|
+| Fable service provider | All components |
+| Stricture MicroDDL schema | `model/Task.mddl` |
+| Meadow DAL + SQLite | API server |
+| Meadow Endpoints (auto REST) | API server |
+| Orator HTTP server | API server |
+| CSV seeding through Meadow DAL | API server |
+| Pict Application lifecycle | Web client |
+| Pict Views + Templates | Web client |
+| Pict Providers | Web client |
+| Pict Router (hash routing) | Web client |
+| View CSS injection | Web client |
+| Quackage build system | Web client |
+| pict-terminalui + blessed | Console client |
+| ContentAssignment override | Console client |
+| pict-service-commandlineutility | CLI client |
+| Command-per-folder pattern | CLI client |
+| Fable custom service | CLI client |

package/docs/examples/todolist/todo-list-cli-client.md

@@ -0,0 +1,178 @@
+# Todo List: CLI Client
+
+> Part of the [Todo List Application](examples/todolist/todo-list.md) example.
+>
+> **Source:** [`examples/todo-list/cli-client/`](../examples/todo-list/cli-client/)
+
+The CLI client is a non-interactive command-line tool built on pict-service-commandlineutility. It demonstrates the command-per-folder pattern used by Quackage and other Retold CLI tools: each command lives in its own folder, shares a common API service, and registers itself with the Commander.js-based framework.
+
+## Running
+
+```bash
+cd examples/todo-list/cli-client
+npm install
+npx todo --help
+```
+
+The server must be running on port 8086 (or configure a different URL in `.todo-cli.json`).
+
+### Running with Docker
+
+From the `examples/todo-list/` directory, run `./docker-shell.sh` for an interactive shell inside the container. Start the server in the background, then use the CLI:
+
+```bash
+node server/server.cjs &
+cd /app/cli-client && npx todo list
+```
+
+See the [main quickstart](examples/todolist/todo-list.md) for details.
+
+## Commands
+
+### `todo list`
+
+List tasks with optional search, sort, and filter.
+
+```bash
+npx todo list                                   # Default: newest first, up to 50
+npx todo list --search garden --limit 10        # Search name + description
+npx todo list --column Name --direction ASC     # Sort alphabetically
+npx todo list --status Pending                  # Client-side status filter
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-s, --search [text]` | LIKE search across Name and Description | (none) |
+| `-c, --column [column]` | Sort column: DueDate, Name, Status, LengthInHours, IDTask | DueDate |
+| `-d, --direction [dir]` | Sort direction: ASC or DESC | DESC |
+| `-n, --limit [count]` | Maximum records to return | 50 |
+| `--status [status]` | Client-side filter by status (Pending, In Progress, Complete) | (none) |
+
+**Aliases:** `ls`, `l`
+
+### `todo add`
+
+Create a new task.
+
+```bash
+npx todo add "Water the plants" --due 2026-03-15 --hours 0.5
+npx todo add "Team standup" --status "In Progress" --description "Daily 9am sync"
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-D, --description [text]` | Task description | (empty) |
+| `-d, --due [date]` | Due date (YYYY-MM-DD) | (empty) |
+| `-h, --hours [hours]` | Estimated hours | 0 |
+| `-s, --status [status]` | Initial status | Pending |
+
+**Aliases:** `new`, `create`
+
+### `todo complete`
+
+Mark a task as complete by ID. Fetches the task first and skips if already complete.
+
+```bash
+npx todo complete 42
+```
+
+**Aliases:** `done`, `finish`
+
+### `todo remove`
+
+Delete a task by ID.
+
+```bash
+npx todo remove 42
+```
+
+**Aliases:** `rm`, `delete`, `del`
+
+### `todo explain-config`
+
+Built-in command from pict-service-commandlineutility. Shows the resolved configuration after merging defaults with any `.todo-cli.json` files found in the home directory or current working directory.
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph cli["TodoCLI-CLIProgram"]
+        commander["Commander.js<br/><i>Argument parsing</i>"]
+        config["Configuration<br/><i>.todo-cli.json</i>"]
+    end
+
+    subgraph service["TodoCLI-Service-API"]
+        http["http.request()<br/><i>JSON over HTTP</i>"]
+        urlbuilder["buildFilteredPath()<br/><i>Meadow query URL construction</i>"]
+    end
+
+    subgraph commands["Commands"]
+        list["list<br/><i>Tabular output</i>"]
+        add["add<br/><i>POST /1.0/Task</i>"]
+        remove["remove<br/><i>DELETE /1.0/Task/:id</i>"]
+        complete["complete<br/><i>GET then PUT</i>"]
+    end
+
+    cli --> service
+    cli --> commands
+    commands --> service
+    service --> server["API Server<br/>http://localhost:8086"]
+```
+
+### Command-per-folder Pattern
+
+Each command lives in its own folder under `source/commands/`:
+
+```
+source/commands/
+    list/       TodoCLI-Command-List.js
+    add/        TodoCLI-Command-Add.js
+    remove/     TodoCLI-Command-Remove.js
+    complete/   TodoCLI-Command-Complete.js
+```
+
+This is the same pattern used by Quackage and other Retold CLI tools. Each command file exports a class that extends `ServiceCommandLineCommand`, sets its keyword, description, arguments, and options in the constructor, and implements `onRunAsync(fCallback)` for the command logic.
+
+### Shared API Service
+
+`TodoCLI-Service-API.js` extends `fable-serviceproviderbase` and provides two methods used by all commands:
+
+- **`request(method, path, body, callback)`** -- makes an HTTP request to the API server, parses the JSON response, and returns it through the callback
+- **`buildFilteredPath(sortColumn, sortDirection, searchText, limit)`** -- constructs a Meadow FilteredTo URL with sort stanzas and optional LIKE search filters (with `%` wildcards)
+
+The service reads its base URL from `this.fable.settings.ApiBaseURL`, which defaults to `http://localhost:8086` and can be overridden in `.todo-cli.json`.
+
+### Bootstrap
+
+`TodoCLI-CLIProgram.js` creates a `pict-service-commandlineutility` instance with settings and an array of command class prototypes. The framework iterates the array, instantiates each command, and registers it with Commander.js. The `TodoAPI` service is registered separately using `addAndInstantiateServiceType`.
+
+`TodoCLI-Run.js` is the shebang entry point (`#!/usr/bin/env node`) that requires the program module and calls `.run()`.
+
+### Configuration
+
+The framework automatically searches for `.todo-cli.json` in the user's home directory and the current working directory. Configuration from all sources is merged in order (defaults, home, CWD). The only setting is the API base URL:
+
+```json
+{
+    "ApiBaseURL": "http://localhost:8086"
+}
+```
+
+## Dependencies
+
+| Module | Role |
+|--------|------|
+| `pict-service-commandlineutility` | CLI framework (Commander.js + Fable service container) |
+| `fable-serviceproviderbase` | Base class for the API service (transitive dependency) |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `source/TodoCLI-Run.js` | Shebang entry point for the `todo` bin command |
+| `source/TodoCLI-CLIProgram.js` | Bootstrap -- registers commands and the API service |
+| `source/services/TodoCLI-Service-API.js` | Shared HTTP client with JSON parsing and FilteredTo URL builder |
+| `source/commands/list/TodoCLI-Command-List.js` | `todo list` -- tabular output with search, sort, filter, limit |
+| `source/commands/add/TodoCLI-Command-Add.js` | `todo add <name>` -- create a task with options |
+| `source/commands/remove/TodoCLI-Command-Remove.js` | `todo remove <id>` -- delete a task |
+| `source/commands/complete/TodoCLI-Command-Complete.js` | `todo complete <id>` -- mark a task as complete |

package/docs/examples/todolist/todo-list-console-client.md

@@ -0,0 +1,152 @@
+# Todo List: Console Client
+
+> Part of the [Todo List Application](examples/todolist/todo-list.md) example.
+>
+> **Source:** [`examples/todo-list/console-client/`](../examples/todo-list/console-client/)
+
+The console client is a full-screen terminal UI built on blessed, bridged to Pict views through pict-terminalui. It demonstrates how the same Pict view/template architecture that drives the browser UI can render into a terminal -- views write templates, and the ContentAssignment bridge sends the output to blessed widgets instead of the DOM.
+
+## Running
+
+```bash
+cd examples/todo-list/console-client
+npm install
+npm start
+```
+
+The server must be running on port 8086.
+
+### Running with Docker
+
+From the `examples/todo-list/` directory, run `./docker-shell.sh` for an interactive shell inside the container. Start the server in the background, then launch the console client:
+
+```bash
+node server/server.cjs &
+node console-client/console-client.cjs
+```
+
+See the [main quickstart](examples/todolist/todo-list.md) for details.
+
+## Keyboard Controls
+
+| Key | Action |
+|-----|--------|
+| Up / Down | Navigate task selection |
+| Enter | View selected task (read-only detail) |
+| E | Edit selected task |
+| A | Add a new task |
+| D | Delete selected task |
+| S | Open sort picker (10 sort options) |
+| / | Search by name or description |
+| R | Refresh from server |
+| Q | Quit |
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph app["TodoListConsoleApplication"]
+        state["AppData.TodoList<br/><i>Tasks, SelectedIndex, ListState</i>"]
+        http["httpRequest()<br/><i>Node.js http module</i>"]
+        modals["Modal dialogs<br/><i>View, Edit, Sort, Search</i>"]
+    end
+
+    subgraph tui["pict-terminalui"]
+        bridge["ContentAssignment bridge<br/><i>Pict views → blessed widgets</i>"]
+    end
+
+    subgraph blessed["blessed screen"]
+        header["TUI-Header<br/><i>Title + keybindings</i>"]
+        content["TUI-TaskList<br/><i>Scrollable task rows</i>"]
+        status["TUI-StatusBar<br/><i>Count, sort, message</i>"]
+    end
+
+    app --> tui
+    tui --> blessed
+    http -- "GET/POST/PUT/DELETE" --> server["API Server"]
+```
+
+## How It Works
+
+The console client is a single `console-client.cjs` file that extends `pict-application`. On initialization it:
+
+1. **Creates a blessed screen** -- the terminal canvas managed by blessed
+2. **Builds the widget layout** -- header, content area, and status bar as blessed boxes
+3. **Registers widgets with pict-terminalui** -- the bridge maps CSS-style selectors (`#TUI-Header`, `#TUI-Content`, `#TUI-StatusBar`) to blessed widgets
+4. **Binds keyboard handlers** -- each key checks a `_modalOpen` flag to prevent conflicts between the main list and modal dialogs
+5. **Loads tasks** via HTTP and renders the initial view
+
+### pict-terminalui Bridge
+
+The key architectural pattern is the ContentAssignment override. In a browser, Pict views render templates and write the result into DOM elements using `innerHTML`. The pict-terminalui module replaces this mechanism: when a view writes to `#TUI-Content`, the bridge sends the text to the corresponding blessed widget's `setContent()` method instead.
+
+This means the four TUI view classes (`PictView-TUI-Layout`, `PictView-TUI-Header`, `PictView-TUI-TaskList`, `PictView-TUI-StatusBar`) use standard Pict templates with `{~Data:...~}` expressions. They don't know they're rendering into a terminal.
+
+### Modal System
+
+The console client has four modal dialogs, each created as a temporary blessed widget that overlays the main screen:
+
+- **View modal** (Enter) -- a `blessed.box` showing read-only task detail (name, status, due date, hours, description). Press Esc to close or E to jump to edit.
+- **Edit modal** (E) -- a sequential chain of `blessed.prompt` dialogs for each field (Name, Description, DueDate, LengthInHours, Status). Pressing Escape at any point cancels the edit.
+- **Sort modal** (S) -- a `blessed.list` with 10 sort options (DueDate, Name, Status, Hours, IDTask in both ASC and DESC). The current sort is pre-selected. Choosing an option reloads the task list from the API.
+- **Search modal** (/) -- a `blessed.prompt` for entering a search string. The search filters across both Name and Description using a LIKE query with OR. An empty string clears the filter.
+
+All modals set a `_modalOpen` flag on open and clear it on close. Every keyboard handler checks this flag before acting, preventing key conflicts (e.g., pressing Q in a modal closes the modal, not the application).
+
+### HTTP Communication
+
+The client uses Node.js `http.request()` with a simple wrapper function. The `_buildFilteredPath()` method constructs the same Meadow FilteredTo URL syntax that the web client uses, including `%` wildcards for LIKE searches:
+
+```javascript
+let tmpSearchEncoded = encodeURIComponent('%' + tmpState.SearchText + '%');
+tmpFilter = 'FBV~Name~LK~' + tmpSearchEncoded
+    + '~FBVOR~Description~LK~' + tmpSearchEncoded
+    + '~' + tmpFilter;
+```
+
+## Views
+
+### PictView-TUI-Layout
+
+Root container that triggers renders of the header, content, and status bar child views. Registered to `#TUI-Application-Container`.
+
+### PictView-TUI-Header
+
+Renders the application title and keybinding reference bar into the top blessed box:
+
+```
+Todo List Console Client
+[Enter]View  [E]dit  [A]dd  [D]elete  [S]ort  [/]Search  [R]efresh  [Q]uit
+```
+
+### PictView-TUI-TaskList
+
+Builds a formatted text table from `AppData.TodoList.Tasks` with columns for index, name, status, due date, and hours. The currently selected row is highlighted with `{inverse}` blessed tags.
+
+### PictView-TUI-StatusBar
+
+Shows the task count, status message, and current sort column/direction using a Pict template:
+
+```
+Tasks: {~D:Record.Tasks.length~} | {~D:Record.StatusMessage~} | Sort: {~D:Record.ListState.SortColumn~} {~D:Record.ListState.SortDirection~}
+```
+
+## Dependencies
+
+| Module | Role |
+|--------|------|
+| `blessed` | Terminal UI rendering (boxes, lists, prompts, key handling) |
+| `pict` | Core view and template engine |
+| `pict-application` | Application lifecycle |
+| `pict-view` | View base class |
+| `pict-terminalui` | ContentAssignment bridge from Pict views to blessed widgets |
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `console-client.cjs` | Application class -- screen setup, keyboard bindings, modals, HTTP client |
+| `views/PictView-TUI-Layout.cjs` | Root blessed layout (header + content + status bar) |
+| `views/PictView-TUI-Header.cjs` | Title bar with keybinding reference |
+| `views/PictView-TUI-TaskList.cjs` | Scrollable task list with selection highlighting |
+| `views/PictView-TUI-StatusBar.cjs` | Status line showing count, message, and current sort |

package/docs/examples/todolist/todo-list-model.md

@@ -0,0 +1,114 @@
+# Todo List: System Model
+
+> Part of the [Todo List Application](examples/todolist/todo-list.md) example.
+>
+> **Source:** [`examples/todo-list/model/`](../examples/todo-list/model/)
+
+The Task entity is defined once and consumed by every component in the application. This is a core Retold pattern: the data model is the source of truth, and everything else -- table creation, API endpoints, query generation -- flows from it.
+
+## Stricture MicroDDL
+
+The schema starts as a `.mddl` file -- Stricture's one-line-per-field notation:
+
+```
+!Task
+@IDTask
+%GUIDTask
+$Name 200
+*Description
+&DueDate
+.LengthInHours 10,2
+$Status 32
+&CreateDate
+#CreatingIDUser -> IDUser
+&UpdateDate
+#UpdatingIDUser -> IDUser
+^Deleted
+&DeleteDate
+#DeletingIDUser -> IDUser
+```
+
+Each sigil declares the column type:
+
+| Sigil | Meaning | Example |
+|-------|---------|---------|
+| `!` | Entity (table) name | `!Task` |
+| `@` | Auto-increment identity | `@IDTask` |
+| `%` | Auto-generated GUID | `%GUIDTask` |
+| `$` | String with max length | `$Name 200` |
+| `*` | Text (unlimited length) | `*Description` |
+| `&` | DateTime | `&DueDate` |
+| `.` | Decimal (precision, scale) | `.LengthInHours 10,2` |
+| `#` | Integer (foreign key) | `#CreatingIDUser -> IDUser` |
+| `^` | Boolean flag | `^Deleted` |
+
+The audit columns (CreateDate, CreatingIDUser, UpdateDate, UpdatingIDUser, Deleted, DeleteDate, DeletingIDUser) follow the standard Meadow audit trail convention. Meadow manages these automatically -- you never set them in application code.
+
+## Compiled DDL
+
+Running the Stricture compiler produces `Task-Compiled.json`, a JSON representation of the table structure that the SQLite provider uses to generate CREATE TABLE statements at startup:
+
+```json
+{
+  "Tables": [
+    {
+      "TableName": "Task",
+      "Columns": [
+        { "Column": "IDTask", "DataType": "AutoIdentity" },
+        { "Column": "GUIDTask", "DataType": "AutoGUID" },
+        { "Column": "Name", "DataType": "String", "Size": "200" },
+        ...
+      ]
+    }
+  ]
+}
+```
+
+The server passes this to `meadow-connection-sqlite`'s `createTables()` method, which generates and executes the appropriate SQLite DDL. You never write CREATE TABLE statements by hand.
+
+## Meadow Schema
+
+`MeadowSchema-Task.json` defines the ORM mapping that Meadow uses for all CRUD operations:
+
+- **Column definitions** with types, sizes, and defaults
+- **JSON Schema** for request validation
+- **Default identifier** (`IDTask`) and GUID identifier (`GUIDTask`)
+- **Default object** template for new records
+
+The server loads this schema and passes it to Meadow when creating the Task DAL instance. Meadow Endpoints then uses the same schema to auto-generate REST routes with proper type handling.
+
+## Field Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| IDTask | AutoIdentity | Primary key (auto-increment) |
+| GUIDTask | AutoGUID | UUID generated by Meadow on create |
+| Name | String(200) | Task name |
+| Description | Text | Task description (unlimited length) |
+| DueDate | DateTime | When the task is due |
+| LengthInHours | Decimal(10,2) | Estimated duration in hours |
+| Status | String(32) | One of: Pending, In Progress, Complete |
+| CreateDate | DateTime | Set automatically by Meadow on create |
+| CreatingIDUser | Integer | Set automatically by Meadow on create |
+| UpdateDate | DateTime | Set automatically by Meadow on update |
+| UpdatingIDUser | Integer | Set automatically by Meadow on update |
+| Deleted | Boolean | Soft-delete flag (Meadow never hard-deletes) |
+| DeleteDate | DateTime | Set automatically by Meadow on delete |
+| DeletingIDUser | Integer | Set automatically by Meadow on delete |
+
+## Seed Data
+
+The file `model/data/seeded_todo_events.csv` contains 1,000 realistic task records spanning four years of family life: personal errands, work tasks, birthdays, holidays, bills, vet appointments, and more.
+
+On first server start, the `DatabaseInitializationService` checks whether the Task table is empty. If it is, it reads the CSV and creates each record through the Meadow DAL using `doCreate()`. Because the records pass through Meadow, every row gets a proper GUID, audit timestamps, and default values -- exactly as if a user had created them through the API.
+
+To re-seed the database, delete `server/data/todo.sqlite` and restart the server.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `Task.mddl` | Stricture MicroDDL source definition |
+| `Task-Compiled.json` | Compiled DDL for SQLite table creation |
+| `MeadowSchema-Task.json` | Meadow ORM schema (columns, types, defaults, JSON Schema) |
+| `data/seeded_todo_events.csv` | 1,000 sample tasks for initial database population |