retold 1.0.6 → 4.0.2

package/docs/architecture/architecture.md

@@ -0,0 +1,312 @@
+# Architecture
+
+Retold modules are designed to compose into layered application stacks. Each layer builds on the one below it through the Fable service provider pattern.
+
+## The Layer Model
+
+A fully-realized Retold application assembles five layers, from infrastructure at the bottom to your application logic at the top.
+
+```mermaid
+graph TB
+  L5["<b>Layer 5</b> — Your Application / Mid-Tier Service<br/><i>Authentication, business logic, custom endpoints</i>"]
+  L4["<b>Layer 4</b> — Orator (API Server)<br/><i>HTTP lifecycle, middleware, static files, proxy</i>"]
+  L3["<b>Layer 3</b> — Meadow-Endpoints<br/><i>Auto-generated CRUD routes, behavior hooks</i>"]
+  L2["<b>Layer 2</b> — Meadow + FoxHound + Stricture<br/><i>Data broker, SQL generation, schema definitions</i>"]
+  L1["<b>Layer 1</b> — Fable (Core Ecosystem)<br/><i>DI, configuration, logging, UUID, expressions</i>"]
+  Infra["<b>Infrastructure</b><br/><i>Config files, log streams, databases, filesystem</i>"]
+
+  L5 --> L4
+  L4 --> L3
+  L3 --> L2
+  L2 --> L1
+  L1 --> Infra
+
+  style L5 fill:#e8f5e9,stroke:#43a047,color:#333
+  style L4 fill:#e3f2fd,stroke:#42a5f5,color:#333
+  style L3 fill:#e3f2fd,stroke:#64b5f6,color:#333
+  style L2 fill:#fff3e0,stroke:#ffa726,color:#333
+  style L1 fill:#fce4ec,stroke:#ef5350,color:#333
+  style Infra fill:#f5f5f5,stroke:#bdbdbd,color:#333
+```
+
+Not every application uses every layer. A browser app might use Fable + Pict. A CLI tool might use Fable + Meadow. A full API service uses the complete stack.
+
+## The Service Provider Pattern
+
+Every Retold module extends `fable-serviceproviderbase`. This base class provides:
+
+- **Registration** — Services register with a Fable instance by type and hash
+- **Dependency access** — Any service can reach any other through `this.fable`
+- **Logging** — Built-in `this.log` from Fable-Log
+- **Configuration** — Shared settings through `this.fable.settings`
+- **Identity** — UUID generation through `this.fable.getUUID()`
+
+```javascript
+const libFable = require('fable');
+const libMeadow = require('meadow');
+const libOrator = require('orator');
+
+let _Fable = new libFable({ Product: 'MyApp', LogLevel: 3 });
+
+// Services register themselves with the Fable instance
+let _Meadow = _Fable.instantiateServiceProvider('Meadow');
+let _Orator = _Fable.instantiateServiceProvider('Orator');
+
+// Now every service can reach every other service
+// _Meadow.fable.Orator, _Orator.fable.Meadow, etc.
+```
+
+This pattern means modules are loosely coupled. You can swap database providers, change API server implementations, or add custom services without modifying existing code.
+
+## Layer 1: Fable — The Foundation
+
+Fable is the only module that every other module depends on. It provides the core services that all other modules consume.
+
+```mermaid
+graph TB
+  subgraph Fable["Fable (Core Ecosystem)"]
+    direction TB
+    settings["Fable-Settings<br/><code>.settings</code>"]
+    flog["Fable-Log<br/><code>.log</code>"]
+    uuid["Fable-UUID<br/><code>.getUUID()</code>"]
+    spb["Service<br/>Provider Base"]
+  end
+
+  settings --> configfiles["Config Files<br/>(.json, env)"]
+  flog --> logstreams["Log Streams<br/>(console, file, bunyan)"]
+
+  style Fable fill:#fce4ec,stroke:#ef5350,color:#333
+  style settings fill:#fff,stroke:#ef9a9a,color:#333
+  style flog fill:#fff,stroke:#ef9a9a,color:#333
+  style uuid fill:#fff,stroke:#ef9a9a,color:#333
+  style spb fill:#fff,stroke:#ef9a9a,color:#333
+  style configfiles fill:#f5f5f5,stroke:#bdbdbd,color:#666
+  style logstreams fill:#f5f5f5,stroke:#bdbdbd,color:#666
+```
+
+**Fable-Settings** loads and merges configuration from files, defaults, and runtime overrides into a single settings object.
+
+**Fable-Log** provides six log levels (trace, debug, info, warn, error, fatal) with extensible output streams. Logs go to console by default; add bunyan or custom loggers as needed.
+
+**Fable-UUID** generates RFC 4122 v4 UUIDs or configurable random strings for identity and uniqueness.
+
+**Fable-ServiceProviderBase** is the base class all Retold services extend. It provides the registration and dependency injection mechanics.
+
+Fable also bundles an expression parser, a REST client (Fable-RestClient), a template engine, date utilities, and data format helpers — all accessible as services.
+
+## Layer 2: Meadow — Data Access
+
+Meadow sits on top of Fable and provides a provider-agnostic data broker. You define entities once and access them through any supported database.
+
+```mermaid
+graph TB
+  subgraph Meadow["Meadow (Data Broker / ORM)"]
+    direction TB
+    foxhound["FoxHound<br/>(Query DSL)<br/><code>.addFilter() .setSort() .buildRead()</code>"]
+    stricture["Stricture<br/>(Schema DDL)<br/>JSON schema, CREATE TABLE, docs"]
+    conn["Connections<br/>meadow-connection-mysql<br/>meadow-connection-mssql<br/>meadow-connection-sqlite"]
+  end
+
+  foxhound --> sql["SQL Queries<br/>(MySQL, MSSQL, SQLite, ALASQL)"]
+  stricture --> ddl["DDL Scripts<br/>(CREATE TABLE, indexes)"]
+  conn --> db[("Database<br/>(pooled connections)")]
+
+  style Meadow fill:#fff3e0,stroke:#ffa726,color:#333
+  style foxhound fill:#fff,stroke:#ffcc80,color:#333
+  style stricture fill:#fff,stroke:#ffcc80,color:#333
+  style conn fill:#fff,stroke:#ffcc80,color:#333
+  style sql fill:#f5f5f5,stroke:#bdbdbd,color:#666
+  style ddl fill:#f5f5f5,stroke:#bdbdbd,color:#666
+  style db fill:#ffebee,stroke:#ef5350,color:#333
+```
+
+**Meadow** handles CRUD operations (Create, Read, Reads, Update, Delete, Count, Undelete), automatic audit columns (CreatingIDUser, UpdatingIDUser, timestamps), soft deletes, GUID uniqueness, and data marshalling.
+
+**FoxHound** generates dialect-specific SQL from a single chainable API. One query definition produces correct SQL for MySQL, MSSQL, SQLite, or ALASQL (for in-browser use).
+
+**Stricture** is an opinionated MicroDDL — define your data model in a simple text format and generate JSON schemas, MySQL CREATE statements, Meadow schema files, and documentation from a single source.
+
+**Connection modules** (meadow-connection-mysql, meadow-connection-mssql, meadow-connection-sqlite) provide pooled database connections as Fable services.
+
+## Layer 3: Meadow-Endpoints — Auto-Generated API
+
+Meadow-Endpoints takes a Meadow entity definition and automatically generates a full suite of RESTful routes.
+
+```mermaid
+graph LR
+  entity["Meadow Entity<br/><b>Book</b>"] --> endpoints["<b>Meadow-Endpoints</b>"]
+
+  endpoints --> r1["GET /Books → Reads"]
+  endpoints --> r2["GET /Books/Count → Count"]
+  endpoints --> r3["GET /Book/:id → Read"]
+  endpoints --> r4["GET /Book/Schema → Schema"]
+  endpoints --> r5["POST /Book → Create"]
+  endpoints --> r6["PUT /Book → Update"]
+  endpoints --> r7["DEL /Book/:id → Delete"]
+  endpoints --> r8["DEL /Book/:id/Undelete"]
+
+  entity --> hooks["+ Behavior injection hooks<br/>+ Dynamic filtering & pagination<br/>+ Bulk operations"]
+
+  style entity fill:#fff3e0,stroke:#ffa726,color:#333
+  style endpoints fill:#e3f2fd,stroke:#42a5f5,color:#333
+  style hooks fill:#f3e5f5,stroke:#ab47bc,color:#333
+  style r1 fill:#fff,stroke:#90caf9,color:#333
+  style r2 fill:#fff,stroke:#90caf9,color:#333
+  style r3 fill:#fff,stroke:#90caf9,color:#333
+  style r4 fill:#fff,stroke:#90caf9,color:#333
+  style r5 fill:#fff,stroke:#90caf9,color:#333
+  style r6 fill:#fff,stroke:#90caf9,color:#333
+  style r7 fill:#fff,stroke:#90caf9,color:#333
+  style r8 fill:#fff,stroke:#90caf9,color:#333
+```
+
+Behavior hooks let you inject authentication, authorization, validation, and transformation logic at any point in the request lifecycle — before or after each CRUD operation.
+
+## Layer 4: Orator — API Server
+
+Orator provides the HTTP server that hosts the endpoints from Layer 3 (and any custom routes).
+
+```mermaid
+graph TB
+  subgraph Orator["Orator (HTTP Server Abstraction)"]
+    direction TB
+    restify["orator-serviceserver-restify<br/>(Production HTTP)"]
+    static["orator-static-server<br/>(File Serving)"]
+    restify --> core["Orator Core<br/>Lifecycle hooks, middleware,<br/>content negotiation, IPC mode"]
+    static --> core
+    proxy["orator-http-proxy<br/>(Reverse Proxy)"]
+    tidings["Tidings<br/>(Reporting)"]
+  end
+
+  style Orator fill:#e3f2fd,stroke:#42a5f5,color:#333
+  style restify fill:#fff,stroke:#90caf9,color:#333
+  style static fill:#fff,stroke:#90caf9,color:#333
+  style core fill:#bbdefb,stroke:#42a5f5,color:#333
+  style proxy fill:#fff,stroke:#90caf9,color:#333
+  style tidings fill:#fff,stroke:#90caf9,color:#333
+```
+
+Orator is deliberately thin. It provides a consistent interface regardless of the underlying server, so you can swap Restify for another implementation or use IPC mode for testing — without changing your application code.
+
+## Pict — MVC Tools
+
+Pict sits alongside the server stack, providing Model-View-Controller tools for any text-based UI: browser DOM, terminal, or rendered strings.
+
+```mermaid
+graph TB
+  subgraph Pict["Pict (Non-Opinionated MVC)"]
+    direction TB
+    subgraph Core["Core"]
+      views["Views<br/><i>pict-view</i>"]
+      templates["Templates<br/><i>pict-template</i>"]
+      providers["Providers<br/><i>pict-provider</i>"]
+      appfw["Application<br/><i>pict-application</i>"]
+    end
+    subgraph Sections["Sections & Components"]
+      forms["Forms<br/><i>pict-section-form</i>"]
+      recordset["Recordset<br/><i>pict-section-recordset</i>"]
+      tuigrid["TUI Grid<br/><i>pict-section-tuigrid</i>"]
+      content["Content<br/><i>pict-section-content</i>"]
+    end
+    Core --> Sections
+  end
+
+  style Pict fill:#f3e5f5,stroke:#ab47bc,color:#333
+  style Core fill:#f3e5f5,stroke:#ce93d8,color:#333
+  style Sections fill:#f3e5f5,stroke:#ce93d8,color:#333
+  style views fill:#fff,stroke:#ce93d8,color:#333
+  style templates fill:#fff,stroke:#ce93d8,color:#333
+  style providers fill:#fff,stroke:#ce93d8,color:#333
+  style appfw fill:#fff,stroke:#ce93d8,color:#333
+  style forms fill:#fff,stroke:#ce93d8,color:#333
+  style recordset fill:#fff,stroke:#ce93d8,color:#333
+  style tuigrid fill:#fff,stroke:#ce93d8,color:#333
+  style content fill:#fff,stroke:#ce93d8,color:#333
+```
+
+Pict's core philosophy: UI is text. Views render templates into strings. Providers fetch data. The Application class coordinates lifecycle. Sections provide pre-built patterns for common UI needs (forms, record lists, grids).
+
+Pict connects to Fable for services and can use Meadow-Endpoints as its data source, but it has no hard dependency on the server stack.
+
+## Putting It All Together
+
+A full Retold application combines these layers. Here is the typical assembly order from the whiteboard architecture diagram:
+
+```mermaid
+graph LR
+  S1["<b>Step 1</b><br/>Fable<br/><i>Config, logging, DI</i>"]
+  S2["<b>Step 2</b><br/>Meadow<br/><i>Entities, DB connection</i>"]
+  S3["<b>Step 3</b><br/>Meadow-Endpoints<br/><i>Auto-generate REST</i>"]
+  S4["<b>Step 4</b><br/>Orator<br/><i>HTTP server</i>"]
+  S5["<b>Step 5</b><br/>Your Application<br/><i>Mid-tier service</i>"]
+
+  S1 --> S2 --> S3 --> S4 --> S5
+
+  style S1 fill:#fce4ec,stroke:#ef5350,color:#333
+  style S2 fill:#fff3e0,stroke:#ffa726,color:#333
+  style S3 fill:#fff3e0,stroke:#ffcc80,color:#333
+  style S4 fill:#e3f2fd,stroke:#42a5f5,color:#333
+  style S5 fill:#e8f5e9,stroke:#43a047,color:#333
+```
+
+```javascript
+const libFable = require('fable');
+const libOrator = require('orator');
+const libMeadowEndpoints = require('meadow-endpoints');
+
+let _Fable = new libFable({
+    Product: 'BookService',
+    LogLevel: 3,
+    "MySQL": { "Server": "localhost", "User": "root", "Database": "bookstore" }
+});
+
+// Layer 2: Data access
+let _MeadowEntity = _Fable.instantiateServiceProvider('Meadow',
+    { Scope: 'Book', DefaultSchema: BookSchema });
+
+// Layer 3: Auto-generate REST endpoints
+let _Endpoints = _Fable.instantiateServiceProvider('MeadowEndpoints',
+    { Entity: _MeadowEntity });
+
+// Layer 4: HTTP server
+let _Orator = _Fable.instantiateServiceProvider('Orator');
+
+// Wire endpoints to the server
+_Endpoints.connectRoutes(_Orator);
+
+// Start listening
+_Orator.startService((pError) =>
+{
+    _Fable.log.info('BookService is running on port 8086');
+});
+```
+
+## Utility Modules
+
+Supporting the application stack are utility modules:
+
+| Module | Purpose |
+|--------|---------|
+| **[Manyfest](/utility/manyfest/)** | JSON manifest for consistent data description across layers |
+| **[Quackage](/utility/quackage/)** | Standardized build tool for browser bundles, testing, and packaging |
+| **[Indoctrinate](/utility/indoctrinate/)** | Documentation scaffolding, catalog generation, and cross-module search |
+| **[Ultravisor](/utility/ultravisor/)** | Process supervision with scheduled tasks and LLM integration |
+| **[Choreographic](/utility/choreographic/)** | Scaffolding for single-run data processing scripts |
+
+## Design Principles
+
+### Convention Over Configuration
+
+Modules generate rich metadata automatically. A Meadow entity with a well-named schema and standard columns needs zero additional configuration to get a full REST API.
+
+### Provider Agnostic
+
+Data access, server implementations, and log destinations are all pluggable. Swap MySQL for SQLite, Restify for IPC, or console logging for Bunyan — without changing application code.
+
+### Composable, Not Monolithic
+
+Each module does one thing. Combine the modules you need; skip the rest. A CLI tool does not need Orator. A browser widget does not need Meadow.
+
+### Everything is a Service
+
+The service provider pattern means modules discover and use each other through dependency injection. No global state, no singletons, no import ordering problems.

package/docs/architecture/module-architecture.md

@@ -0,0 +1,234 @@
+# Ecosystem Architecture - Module Philosophy
+
+Retold modules each embody a specific design philosophy. Together they form a coherent system for building applications — from the stateless service core, through data access and API generation, up to state-driven UI rendering.  At the same time, each module is designed to be used (*and useful*) independently. You can adopt Fable's configuration and logging without using Pict. You can use Meadow for data access without Orator. These modules are decoupled by design, but also fit together in a complementary way.
+
+```mermaid
+graph TB
+	subgraph Clients["Client Applications"]
+		direction LR
+		browser["Browser App<br/><i>Pict + Pict-Application<br/>+ Pict-Views</i>"]
+		console["Console App<br/><i>Pict + Terminal UI</i>"]
+		cli["CLI Tool<br/><i>CommandLineUtility</i>"]
+	end
+
+	internet(("The Internet<br/>☁"))
+
+	subgraph Server["Server / Mid-Tier"]
+		direction TB
+		orator["Orator<br/><i>HTTP Server Abstraction</i>"]
+		endpoints["Meadow-Endpoints<br/><i>Auto-generated REST API</i>"]
+		meadow["Meadow<br/><i>Data Access Abstraction</i>"]
+
+		subgraph DataTools["Schema & Query Tools"]
+			direction LR
+			foxhound["FoxHound<br/><i>Query Generation</i>"]
+			stricture["Stricture<br/><i>MicroDDL → Schema</i>"]
+		end
+
+		orator --> endpoints
+		endpoints --> meadow
+		meadow --> DataTools
+	end
+
+	subgraph Foundation["Foundation (Stateless)"]
+		direction LR
+		fable["Fable<br/><i>DI, Config, Logging</i>"]
+		manyfest["Manyfest<br/><i>Address-Based<br/>Object Access</i>"]
+	end
+
+	Clients -- "HTTP requests" --> internet
+	internet -- "HTTP requests" --> orator
+
+	browser -. "Fable services" .-> Foundation
+	Server --> Foundation
+
+	style Clients fill:#e8f5e9,stroke:#43a047,color:#333
+	style browser fill:#fff,stroke:#66bb6a,color:#333
+	style console fill:#fff,stroke:#66bb6a,color:#333
+	style cli fill:#fff,stroke:#66bb6a,color:#333
+	style internet fill:#e1f5fe,stroke:#03a9f4,color:#333,stroke-width:2px
+	style Server fill:#e3f2fd,stroke:#42a5f5,color:#333
+	style orator fill:#fff,stroke:#64b5f6,color:#333
+	style endpoints fill:#fff,stroke:#64b5f6,color:#333
+	style meadow fill:#fff3e0,stroke:#ffa726,color:#333
+	style DataTools fill:#fff8e1,stroke:#ffcc80,color:#333
+	style foxhound fill:#fff,stroke:#ffcc80,color:#333
+	style stricture fill:#fff,stroke:#ffcc80,color:#333
+	style Foundation fill:#fce4ec,stroke:#ef5350,color:#333
+	style fable fill:#fff,stroke:#ef9a9a,color:#333
+	style manyfest fill:#fff,stroke:#ef9a9a,color:#333
+```
+
+Clients — browsers, terminals, CLI tools — communicate with the server over HTTP. Orator receives those requests, Meadow-Endpoints maps them to data operations, and Meadow executes them against the database. Fable provides the stateless service container that every module on both sides of the network depends on. Manyfest provides the consistent data-addressing language used everywhere.
+
+---
+
+## Fable Is Stateless
+
+Fable draws a hard line between **configuration** and **state**.
+
+In Retold's vocabulary, *state* is **application data** — the records in a database, the items in a shopping cart, the text a user has typed into a form. State changes as users interact with the system. It is the core subject matter of the application.
+
+Configuration is everything else: the address of the database server, the port the API listens on, the log level, the product name. Configuration describes how the application runs in its environment, not what the application is doing. Fable manages configuration. It does not manage state.
+
+This distinction matters because the "Out of the Tar Pit" problem — the paper Fable's design references — identifies uncontrolled state as the primary source of software complexity. By keeping the service container stateless, Fable ensures that the foundation layer has no opinion about your data. Services register with Fable, receive configuration and logging, and operate on whatever data flows through them without Fable holding onto it.
+
+Every Retold module extends `fable-serviceproviderbase` and registers with a Fable instance. That instance provides dependency injection, logging, UUID generation, and shared settings. But the Fable instance itself stores no application data. It is the wiring, not the warehouse.
+
+## Pict Is for State and Transformation
+
+If Fable is deliberately stateless, Pict is deliberately stateful. Pict's job is to hold application state and transform it consistently into output using a templating language.
+
+Pict provides three dedicated state containers:
+
+| Container | Purpose | Example Contents |
+|-----------|---------|------------------|
+| **AppData** | Primary application state | User records, form values, loaded entities |
+| **Bundle** | Supporting reference data | Lookup tables, dropdown options, translations |
+| **TempData** | Ephemeral intermediate data | Chart caches, calculated summaries, UI flags |
+
+All state lives in known locations. Templates reference state through address expressions like `AppData.Tasks[0].Name`. Code accesses the same state through the same addresses. There is one source of truth and one notation for reaching it.
+
+The key insight is that **state and lifecycle are coupled**. Pict's lifecycle phases — Solve, Render, Marshal — all operate on these state containers:
+
+1. **Solve** reads state and writes derived values back into state
+2. **Render** reads state and produces output through templates
+3. **Marshal** collects input and writes it back into state
+
+This cycle is predictable and debuggable. At any point in the lifecycle you can inspect the state containers and know exactly what data the application is working with.
+
+Pict intentionally separates logic from templates. Templates describe *what* to render; code (in views and providers) describes *when* and *how* data moves. You can override templates without altering behavior, and you can alter behavior without touching templates.
+
+## Pict-Application Manages the Lifecycle
+
+Pict-Application is the orchestration layer. It coordinates the startup, data loading, solving, rendering, and marshaling of an entire application composed of multiple views and providers.
+
+The lifecycle follows a defined sequence:
+
+```mermaid
+graph LR
+	init["Initialize<br/><i>Register views,<br/>providers, templates</i>"]
+	data["Load Data<br/><i>Fetch from APIs,<br/>populate AppData</i>"]
+	solve["Solve<br/><i>Calculate derived<br/>values</i>"]
+	render["Render<br/><i>Transform state<br/>into output</i>"]
+	marshal["Marshal<br/><i>Collect input<br/>back into state</i>"]
+
+	init --> data --> solve --> render --> marshal
+	marshal -. "user interaction" .-> solve
+
+	style init fill:#fce4ec,stroke:#ef5350,color:#333
+	style data fill:#fff3e0,stroke:#ffa726,color:#333
+	style solve fill:#e8f5e9,stroke:#43a047,color:#333
+	style render fill:#e3f2fd,stroke:#42a5f5,color:#333
+	style marshal fill:#f3e5f5,stroke:#ab47bc,color:#333
+```
+
+Each view and provider within the application participates in these phases. Pict-Application ensures they execute in the correct order (controlled by configurable ordinals) and provides auto-behaviors to reduce boilerplate — for example, automatically solving and rendering after initialization completes.
+
+The application also manages authentication flows, data loading sequences, and the coordination between views that need to share state. It is the conductor; views and providers are the musicians.
+
+## Pict-View Is Not Just a Screen
+
+A Pict view is any representation of information. It is not a page. It is not a screen. It is not a route.
+
+A single screen might contain dozens of views: a header view, a navigation view, a list view, a detail panel view, a status bar view. Or a single view might render to a log file, a terminal widget, or a test harness instead of a browser DOM. The view is the unit of *rendering*, not the unit of *navigation*.
+
+Each view contains **renderables** — individual render instructions that specify:
+
+- Which **template** to use
+- Which **data address** to read from state
+- Which **destination** to render into
+- Which **method** to use (replace, append, prepend)
+
+This makes views composable. Small views handle small concerns. Larger patterns emerge from combining them. A form section view renders input fields. A recordset view renders a list of records. A content view renders static markup. You assemble an application from these building blocks.
+
+Because views render through a content assignment abstraction, they are not bound to the browser DOM. The same view code can render to a blessed terminal widget, a log stream, or a mock environment for testing — by swapping the content assignment functions. The view does not know or care where its output ends up.
+
+## Orator Abstracts Web Servers
+
+Orator provides a thin abstraction over HTTP servers. Your application code interacts with Orator's interface — defining routes, middleware, and lifecycle hooks — without coupling to a specific server implementation.
+
+The default implementation uses Restify (`orator-serviceserver-restify`), but the abstraction means you could swap in a different HTTP library or use IPC mode for testing without changing application routes or middleware. Orator handles the HTTP lifecycle: receiving requests, running middleware, dispatching to handlers, and sending responses.
+
+Orator also provides static file serving (`orator-static-server`) and reverse proxy capabilities (`orator-http-proxy`), making it a complete server-side HTTP toolkit without being a heavyweight framework.
+
+The philosophy is deliberate thinness. Orator does not dictate application structure. It provides the plumbing for getting HTTP requests to your code and responses back to the client.
+
+## Meadow Abstracts Data Access
+
+Meadow is a provider-agnostic data broker. You define entities once — their fields, types, and relationships — and Meadow handles CRUD operations against whatever database is connected.
+
+The abstraction has real teeth: the same Meadow entity definition works with MySQL, MSSQL, SQLite, and ALASQL (for in-browser use). Switch databases by swapping a connection module. Your application code, entity definitions, and endpoint configurations do not change.
+
+Meadow automatically manages audit columns (who created a record, who last updated it, and when), soft deletes (marking records as deleted without removing them), GUID-based uniqueness, and data marshalling between JavaScript objects and database rows.
+
+The data access pattern is deliberately simple: Create, Read, Reads (list), Update, Delete, Count, and Undelete. These seven operations cover the vast majority of data access needs. When they do not, behavior hooks let you inject custom logic at any point in the operation lifecycle.
+
+## Meadow-Endpoints Connects Data Access to a Consistent API
+
+Meadow-Endpoints takes a Meadow entity and automatically generates a full REST API for it. Define an entity called `Book` and you immediately get `GET /Books`, `GET /Book/:id`, `POST /Book`, `PUT /Book`, `DEL /Book/:id`, and more — with filtering, pagination, sorting, and schema introspection built in.
+
+This is not code generation that produces files you maintain. The endpoints are generated at runtime from the entity definition. Change the schema, restart the server, and the API updates. Add a new entity, wire it to Meadow-Endpoints, and the routes appear.
+
+Behavior hooks provide the extension points. Need authentication? Add a `before` hook. Need to transform data before it reaches the client? Add an `after` hook. Need custom validation? Hook into the create and update paths. The auto-generated API is the foundation; hooks let you customize without replacing it.
+
+## FoxHound Generates Queries
+
+FoxHound is the query generation engine inside Meadow. It provides a chainable API for building queries — adding filters, setting sort order, configuring pagination — and then generates the correct SQL dialect for whichever database you are using.
+
+```javascript
+_Query.addFilter('Status', 'Complete')
+      .setSort('CreatedDate')
+      .setBegin(0).setCap(50)
+      .buildReadQuery();
+```
+
+This same code produces valid MySQL, MSSQL, SQLite, or ALASQL depending on the dialect. Application code never writes raw SQL. FoxHound's job is to be the single translation layer between a database-agnostic query description and dialect-specific SQL.
+
+FoxHound also powers the **FilteredTo** URL syntax used by Meadow-Endpoints, which encodes filters, sorts, and pagination into URL paths for GET requests. This means clients can express complex queries through standard HTTP URLs without POST bodies.
+
+## Stricture Transforms MicroDDL into Schemas
+
+Stricture provides a compact notation — MicroDDL — for defining data models. A MicroDDL file is a human-readable text format where each line defines a column using single-character sigils:
+
+```
+!ID
+@GUIDTask
+#Name
+#Description
+#Status
+&Hours
+%Due
+```
+
+From this terse input, Stricture generates:
+
+- **JSON schemas** for Meadow entity definitions
+- **CREATE TABLE statements** for MySQL, MSSQL, or SQLite
+- **Documentation** describing the data model
+- **Seed data templates** for testing
+
+The philosophy is *define once, generate everywhere*. The MicroDDL is the single source of truth for a data model. Every downstream artifact — database tables, API schemas, documentation — derives from it. Change the MicroDDL, regenerate, and all representations stay in sync.
+
+## Manyfest Provides Address-Based Object Access
+
+Manyfest solves a recurring problem: the same data structure is described and accessed differently at every layer of an application. The database has column names. The API has JSON keys. The frontend has display labels. Business logic has domain terms.
+
+Manyfest unifies this through **address-based access**. An address is a string like `Record.Contact.Email` that describes a location in a nested JavaScript object. Manyfest provides safe accessors that navigate the address without throwing exceptions on missing intermediate objects:
+
+```javascript
+// Safe read — returns undefined if any part of the path is missing
+let email = _Manyfest.getValueAtAddress(pRecord, 'Contact.Email');
+
+// Safe write — creates intermediate objects as needed
+_Manyfest.setValueAtAddress(pRecord, 'Contact.Email', 'new@example.com');
+```
+
+Beyond safe access, Manyfest provides **descriptors** — metadata that maps addresses to human-readable names, short names, descriptions, data types, and hashes. This means a single Manyfest definition can drive:
+
+- API field documentation
+- Form field labels and validation
+- Report column headers
+- Data transformation between layers
+
+The address notation is the same notation Pict uses for template expressions and state access. This consistency means a Manyfest schema defined for the data layer can flow all the way through to form labels in the browser without translation.

package/docs/architecture/modules.md

@@ -0,0 +1,99 @@
+# All Modules
+
+An exhaustive list of every repository in the Retold suite, organized by group. Each module is its own git repository hosted at `github.com/stevenvelozo/<module-name>`.
+
+## Fable — Core Ecosystem (6 modules)
+
+| Module | npm | Description |
+|--------|-----|-------------|
+| [fable](/fable/fable/) | `fable` | Service dependency injection, configuration, and logging library — the foundation of every Retold application |
+| [fable-serviceproviderbase](/fable/fable-serviceproviderbase/) | `fable-serviceproviderbase` | Base classes for Fable services providing registration, DI, and lifecycle |
+| [fable-settings](/fable/fable-settings/) | `fable-settings` | Tolerant configuration chain for loading and merging application settings |
+| [fable-log](/fable/fable-log/) | `fable-log` | Flexible logging wrapper with six levels and extensible output streams |
+| [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 (12 modules)
+
+| Module | npm | Description |
+|--------|-----|-------------|
+| [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) |
+| [meadow-integration](/meadow/meadow-integration/) | `meadow-integration` | Data integration tools for CSV import, schema mapping, and centralized formats |
+
+## Orator — API Server (7 modules)
+
+| Module | npm | Description |
+|--------|-----|-------------|
+| [orator](/orator/orator/) | `orator` | Unopinionated HTTP server abstraction with lifecycle hooks and route management |
+| [orator-serviceserver-restify](/orator/orator-serviceserver-restify/) | `orator-serviceserver-restify` | Production HTTP server implementation powered by Restify |
+| [orator-static-server](/orator/orator-static-server/) | `orator-static-server` | Static file serving with MIME detection, default files, and subdomain routing |
+| [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 (19 modules)
+
+| Module | npm | Description |
+|--------|-----|-------------|
+| [pict](/pict/pict/) | `pict` | Non-opinionated MVC module with template expression engine for text-based UIs |
+| [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-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-router](/pict/pict-router/) | `pict-router` | Hash-based URL routing via Navigo with template string route functions |
+| [pict-serviceproviderbase](/pict/pict-serviceproviderbase/) | `pict-serviceproviderbase` | Base classes for Pict services with pre-initialization support |
+| [pict-terminalui](/pict/pict-terminalui/) | `pict-terminalui` | Blessed-based terminal interface for Pict views |
+
+## 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 |
+| [ultravisor](/utility/ultravisor/) | `ultravisor` | Process supervision with scheduled tasks, distributed nodes, and LLM integration |
+
+## Summary
+
+| Group | Count | Focus |
+|-------|-------|-------|
+| Fable | 6 | Core ecosystem, DI, configuration, logging |
+| 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
+
+All modules are hosted at `github.com/stevenvelozo/<module-name>`:
+
+- [github.com/stevenvelozo/retold](https://github.com/stevenvelozo/retold) — This meta-repository
+- [github.com/stevenvelozo/fable](https://github.com/stevenvelozo/fable) — Core ecosystem
+- [github.com/stevenvelozo/meadow](https://github.com/stevenvelozo/meadow) — Data access
+- [github.com/stevenvelozo/orator](https://github.com/stevenvelozo/orator) — API server
+- [github.com/stevenvelozo/pict](https://github.com/stevenvelozo/pict) — MVC tools
+
+Each module follows the same structure: `package.json`, `source/`, `test/` (Mocha TDD), and optionally `docs/` (Docsify).