Bump flat and mocha; reorganize docs and add AGENTS.md and SKILLS.md

AGENTS.md

@@ -0,0 +1,151 @@
+# AGENTS.md — Guide for AI Coding Agents
+
+This file helps AI coding agents (GitHub Copilot, Claude, GPT, etc.) understand
+the SQLTT repository and work with it effectively.
+
+---
+
+## What is SQLTT?
+
+**SQLTT** (*SQL Tagged Templates*) is a Node.js library for managing SQL queries
+using ES6+ Tagged Template Literals. It:
+
+- Keeps SQL readable and maintainable in JavaScript projects.
+- Renders the same query for multiple database engines (PostgreSQL, Oracle, …)
+  from a single template source.
+- Generates both application-driver SQL and database-CLI SQL from the same template.
+- Provides a rich interpolation API for argument handling, query composition, and more.
+
+It is **not an ORM** — it does not generate SQL from JavaScript objects. It is
+a template engine for hand-written SQL.
+
+---
+
+## Repository Layout
+
+```
+sqltt/
+├── index.js                  # Public entry point (re-exports lib/)
+├── lib/
+│   ├── definitions.js        # Shared constants and type definitions
+│   ├── engines.js            # Database engine implementations (add new engines here)
+│   ├── helpers.js            # Internal utility functions
+│   ├── interpolation.js      # Core tagged-template interpolation logic
+│   ├── compiler_base.js      # Base SQL compiler
+│   ├── compiler_common.js    # Shared compiler helpers
+│   ├── compiler_sql.js       # SQL-specific compiler
+│   ├── compiler_args.js      # Arguments compiler
+│   ├── cli_mode.js           # CLI execution handling
+│   ├── privateMethods.js     # Private template methods
+│   ├── tplAPI.js             # Template API (.sql(), .args(), .concat(), …)
+│   └── staticAPI.js          # Static API (.publish(), …)
+├── test/
+│   ├── test.js               # Main test runner
+│   └── unit_tests.js         # Unit tests (lib/engines.js, etc.)
+├── examples/                 # Example template files (.sql.js)
+├── docs/                     # Detailed documentation (see below)
+├── README.md                 # Quick-start overview
+├── AGENTS.md                 # This file
+└── SKILLS.md                 # How to use SQLTT as a Copilot Skill
+```
+
+---
+
+## Documentation Structure
+
+| File | Contents |
+|:-----|:---------|
+| [`README.md`](README.md) | Overview and quick-start |
+| [`docs/EXAMPLES.md`](docs/EXAMPLES.md) | Annotated code examples |
+| [`docs/USAGE.md`](docs/USAGE.md) | Installation, setup, and usage guide |
+| [`docs/ENGINES.md`](docs/ENGINES.md) | Engine system and flavour selection |
+| [`docs/TEMPLATE_FORMAT.md`](docs/TEMPLATE_FORMAT.md) | Template source syntax reference |
+| [`docs/API.md`](docs/API.md) | Complete API reference (Template API, Tag API, Static Methods) |
+| [`docs/ADVANCED.md`](docs/ADVANCED.md) | Hooks, SQL alternatives, mutations, CTEs |
+| [`docs/ABOUT.md`](docs/ABOUT.md) | Project background and roadmap |
+
+---
+
+## Running the Tests
+
+```sh
+npm install
+npm test
+```
+
+Tests use [Mocha](https://mochajs.org/). Test files live in `test/`.
+
+---
+
+## Adding a New Engine
+
+1. Open `lib/engines.js`.
+2. Follow the pattern of an existing engine (e.g. `postgresql`).
+3. Each engine object specifies how to render positional parameters, variable
+   declarations for CLI mode, and any other engine-specific transforms.
+4. Add your engine to the exported map with a unique key.
+5. Add a test in `test/unit_tests.js` if appropriate.
+6. Document it in [`docs/ENGINES.md`](docs/ENGINES.md).
+
+---
+
+## Making Code Changes
+
+Key rules to follow:
+
+- **Tests first** — run `npm test` after any change to `lib/` or `index.js`.
+- **No new dependencies** — the library has minimal dependencies by design.
+  Propose adding one only if there is no reasonable alternative.
+- **Engine parity** — if you change how arguments or keywords are rendered,
+  make sure the change works correctly across all existing engines.
+- **Backwards compatibility** — this is a prerelease, but try not to break the
+  public API (`.sql()`, `.args()`, `.concat()`, `.options()`, `.publish()`).
+
+---
+
+## Useful Grep Patterns
+
+```sh
+# Find where engines are defined
+grep -n "postgresql\|oracle" lib/engines.js
+
+# Find where positional params are rendered
+grep -rn "param\|placeholder\|\$1\|:1" lib/
+
+# Find all Tag API methods
+grep -n "tag\.\|proto\." lib/tplAPI.js lib/interpolation.js
+
+# Find CLI handling
+grep -rn "cli_mode\|publish" lib/staticAPI.js lib/cli_mode.js
+```
+
+---
+
+## Using SQLTT in a Project (Quick Reference)
+
+```javascript
+const sqltt = require("sqltt");
+
+// Single template
+const q = new sqltt($=>$`
+    select id, name
+    from users
+    where id = ${"userId"}
+`);
+
+// Render SQL
+const sql  = q.sql("postgresql");  // "select id, name from users where id = $1"
+const args = q.args({ userId: 42 }); // [42]
+
+// db.query(sql, args);
+```
+
+For full details see [`docs/USAGE.md`](docs/USAGE.md) and
+[`docs/API.md`](docs/API.md).
+
+---
+
+## Using SQLTT as a Copilot Skill
+
+See [`SKILLS.md`](SKILLS.md) for instructions on loading SQLTT as a GitHub
+Copilot Skill to get in-editor query generation and review assistance.