sqlite-hub 1.2.0 → 1.5.0

package/docs/API.md

@@ -0,0 +1,152 @@
+# SQLite Hub API
+
+SQLite Hub exposes a versioned JSON API at `/api/v1`. The server listens on
+`127.0.0.1`. `GET /api/v1/info` is public local app metadata; every database
+request requires a token created for that exact database in **Settings > API
+Tokens**.
+
+The token is shown only once when it is created. SQLite Hub stores a SHA-256
+hash, the token prefix, its name, and timestamps. Send the token as a bearer
+token:
+
+The `DATABASE_ID` is shown prominently in **Settings > API Tokens** for the
+active database. Use the **Copy ID** button there and replace `DATABASE_ID` in
+the request URL.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables
+```
+
+A missing, invalid, deleted, or database-mismatched token returns HTTP `401`
+with a structured JSON error.
+
+## Endpoints
+
+All path values must be URL encoded.
+
+```text
+GET  /api/v1/info
+POST /api/v1/query
+
+GET  /api/v1/databases/:databaseId
+GET  /api/v1/databases/:databaseId/tables
+GET  /api/v1/databases/:databaseId/tables/:tableName
+POST /api/v1/databases/:databaseId/tables/:tableName/row
+POST /api/v1/databases/:databaseId/tables/:tableName/types
+
+GET  /api/v1/databases/:databaseId/backups
+POST /api/v1/databases/:databaseId/backups
+
+GET  /api/v1/databases/:databaseId/queries
+GET  /api/v1/databases/:databaseId/queries/:queryName
+GET  /api/v1/databases/:databaseId/queries/:queryName/notes
+GET  /api/v1/databases/:databaseId/queries/:queryName/export?format=csv|tsv|md|json
+POST /api/v1/databases/:databaseId/queries/:queryName/execute
+
+GET  /api/v1/databases/:databaseId/documents
+GET  /api/v1/databases/:databaseId/documents/:documentName
+GET  /api/v1/databases/:databaseId/documents/:documentName/export
+```
+
+`GET /api/v1/info` returns the same app/version status shown by
+`sqlite-hub --info`, including the installed SQLite Hub version, SQLite runtime
+version, local URL, and npm update status.
+
+`POST /api/v1/query` executes raw SQL through the same SQL Editor execution path
+used by the app and records it in Query History. Send the database token as a
+bearer token and include `databaseId` plus `sql` in the JSON body. Add `store`
+or `name` to title the history item and mark it as saved. Raw query execution is
+rejected with HTTP `403` when the target database is marked read-only.
+
+Every `/api/v1` request is also recorded in the local Access Log with its API
+action, database id when available, target type/name, status, duration, and API
+token name/id. Tokens and request payloads are not stored in the Access Log.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{"databaseId":"DATABASE_ID","sql":"SELECT * FROM companies LIMIT 10","name":"Company Sample"}' \
+  http://127.0.0.1:4173/api/v1/query
+```
+
+Row lookup accepts a scalar key or a composite primary-key object:
+
+```json
+{ "key": 42 }
+```
+
+```json
+{ "key": { "id": 42, "locale": "en" } }
+```
+
+`POST /api/v1/databases/:databaseId/tables/:tableName/types` generates
+application types from the declared SQLite schema. It is read-only, uses the
+same generation service as the Structure Inspector and CLI, and returns code as
+JSON without writing server-side files.
+
+```bash
+curl \
+  -X POST \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target": "typescript",
+    "options": {
+      "propertyNaming": "camel",
+      "nullableMode": "native",
+      "includeComments": true
+    }
+  }' \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables/users/types
+```
+
+Supported targets are `typescript`, `rust`, `kotlin`, and `swift`. Warnings are
+returned in the top-level `warnings` array. Metadata includes column counts and
+CHECK-constraint counts.
+
+`GET /api/v1/databases/:databaseId/backups` lists managed backups for the
+token's database.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups
+```
+
+`POST /api/v1/databases/:databaseId/backups` creates and verifies a managed
+backup for the token's database. The request body may include `name` and `notes`.
+Backup creation uses SQLite's backup API and is allowed for read-only database
+connections because the source database is only read.
+
+```bash
+curl \
+  -X POST \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Before import","notes":"Before loading vendor data"}' \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups
+```
+
+Successful responses use this envelope:
+
+```json
+{
+    "success": true,
+    "message": "",
+    "data": {},
+    "metadata": {},
+    "warnings": []
+}
+```
+
+Errors use the same envelope with `success: false` and a structured `error`
+object containing `code`, `message`, `details`, and `sqliteCode`.
+
+## Example
+
+See [`examples/api/list-tables.js`](../examples/api/list-tables.js) for a small
+Node.js example using a token from the `SQLITE_HUB_API_TOKEN` environment
+variable.

package/docs/CLI.md

@@ -0,0 +1,249 @@
+# SQLite Hub CLI
+
+SQLite Hub ships with a built-in CLI that lets you start the app, inspect
+imported databases, execute raw or saved SQL, export query results, and work
+with Markdown documents from the terminal.
+
+CLI commands are recorded in the local Access Log with their action, target,
+database id when available, status, and duration. Raw SQL text is still handled
+by Query History for executed queries and is not duplicated in the Access Log.
+
+## Start The App
+
+```bash
+sqlite-hub                  # start on default port 4173
+sqlite-hub --port:4174      # start on a custom port
+sqlite-hub --open           # open SQLite Hub in the browser
+sqlite-hub --info           # show port, URL, versions, and update status
+sqlite-hub --help           # show help text
+sqlite-hub --version        # show version number
+```
+
+`--config` is still accepted as a legacy alias for `--info`.
+
+## Databases
+
+List all imported databases:
+
+```bash
+sqlite-hub --database
+sqlite-hub -d
+```
+
+The database list shows the name, file path, file size, last opened timestamp,
+and read-only status for databases that have been opened in SQLite Hub.
+
+Query details for one database by name or id:
+
+```bash
+sqlite-hub --database:Billly --path        # get the file path
+sqlite-hub --database:Billly --size        # get the file size
+sqlite-hub --database:Billly --lastopened  # get last opened timestamp
+```
+
+List all tables in a database:
+
+```bash
+sqlite-hub --database:Billly --tables
+```
+
+Inspect one table:
+
+```bash
+sqlite-hub --database:Billly --table:companies
+```
+
+Table inspection prints metadata such as columns, primary keys, foreign keys,
+indexes, row count, and row identity strategy.
+
+Generate application types from a table schema:
+
+```bash
+sqlite-hub --database:Unit-00 --table:users --types:typescript
+sqlite-hub --database:Unit-00 --table:users --types:rust
+sqlite-hub --database:Unit-00 --table:users --types:typescript --json
+sqlite-hub --database:Unit-00 --table:users --types:typescript --output:User.ts
+```
+
+Aliases are available for common targets: `ts`, `rs`, and `kt`. Without
+`--output` or `--json`, the CLI writes only generated code to stdout so shell
+redirection works cleanly. Warnings are written to stderr. Use `--force` to
+overwrite an existing output file.
+
+Create a verified managed backup for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --backups
+sqlite-hub --database:Unit-00 --backup
+sqlite-hub --database:Unit-00 --backup:"Before import" --backup-notes:"Before loading vendor data"
+sqlite-hub --database:Unit-00 --backup:"Nightly checkpoint" --json
+```
+
+Backup creation uses the same SQLite backup API and verification path as the UI
+Backup Manager. It works for read-only database connections because the source
+database is only read. `--backups` lists the managed backups for the selected
+database; add `--json` for structured output.
+
+## SQL Editor
+
+Execute raw SQL through the same SQL Editor execution path used by the app:
+
+```bash
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10"
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10" --store:"Company Sample"
+```
+
+Raw CLI queries are recorded in Query History. Add `--store:"name"` to title the
+history item and mark it as saved. Raw SQL execution is rejected when the target
+database is marked read-only.
+
+List all saved queries for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --queries
+```
+
+Execute a specific saved query by name:
+
+```bash
+sqlite-hub --database:Unit-00 --execute:"15min Posting Buckets without id 96"
+```
+
+This searches the query history for the selected database, finds the matching
+saved query by title, executes it, and returns results with metadata such as row
+count, columns, timing, and data.
+
+Show the saved query SQL without executing it:
+
+```bash
+sqlite-hub --database:Unit-00 --saved-query:"Stock Winners"
+```
+
+Show the saved notes for a query:
+
+```bash
+sqlite-hub --database:Unit-00 --notes:"TOP25 Loser and Winner EOD, T1, T3, T5"
+```
+
+Export a saved query using the same CSV, TSV, Markdown, and JSON export logic as
+the SQL Editor:
+
+```bash
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:csv
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:tsv
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:md
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:json
+```
+
+The export is written to the current working directory using the generated query
+export filename.
+
+## Documents
+
+List all Markdown documents stored for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --documents
+```
+
+Print one document's Markdown content:
+
+```bash
+sqlite-hub --database:Unit-00 --documents:"Research Notes"
+```
+
+Export one document as a `.md` file into the current working directory:
+
+```bash
+sqlite-hub --database:Unit-00 --documents:"Research Notes" --export
+sqlite-hub --database:Unit-00 --documents:"Research Notes--export"
+```
+
+Documents can be matched by id, filename, title, or a partial filename/title
+match.
+
+## Row JSON Export
+
+Export a single row as JSON by primary key or rowid, using the same row-shaping
+logic as the Row Editor:
+
+```bash
+sqlite-hub --database:Unit-00 --table:companies --export:0a754aba373d34972998792a0be4333c
+```
+
+## Available Flags
+
+| Flag                                                            | Description                                     |
+| --------------------------------------------------------------- | ----------------------------------------------- |
+| `--help`, `-h`                                                  | Show help text                                  |
+| `--version`, `-v`                                               | Show version number                             |
+| `--info`                                                        | Show port, URL, versions, and update status     |
+| `--open`                                                        | Open SQLite Hub in the browser                  |
+| `--port:PORT`                                                   | Start the server on a custom port               |
+| `--database`, `-d`                                              | List all imported databases                     |
+| `--database:name`                                               | Select a database by name or id                 |
+| `--database:name --path`                                        | Get the file path of a database                 |
+| `--database:name --size`                                        | Get the size of a database                      |
+| `--database:name --lastopened`                                  | Get the last opened timestamp                   |
+| `--database:name --tables`                                      | Get all table names from a database             |
+| `--database:name --queries`                                     | List saved queries for a database               |
+| `--database:name --query:"sql"`                                 | Execute raw SQL and record it in Query History  |
+| `--database:name --query:"sql" --store:"name"`                  | Save a raw query in Query History with a name   |
+| `--database:name --execute:"query"`                             | Execute a saved query by name                   |
+| `--database:name --saved-query:"query"`                         | Print a saved query by name                     |
+| `--database:name --notes:"query"`                               | Print saved notes for a query                   |
+| `--database:name --export:"query" --format:csv\|tsv\|md\|json` | Set query export format                         |
+| `--database:name --documents`                                   | List Markdown documents for a database          |
+| `--database:name --documents:"document"`                        | Print a document's Markdown content             |
+| `--database:name --documents:"document" --export`               | Export a document as Markdown                   |
+| `--database:name --backups`                                     | List managed backups for a database             |
+| `--database:name --backup`                                      | Create and verify a managed backup              |
+| `--database:name --backup:"name"`                               | Create a managed backup with a custom name      |
+| `--backup-notes:"text"`                                         | Add notes to a backup created by `--backup`     |
+| `--database:name --table:"table"`                               | Print table metadata                            |
+| `--database:name --table:"table" --export:"pk"`                 | Export one row as JSON                          |
+| `--database:name --table:"table" --types:typescript\|ts\|rust\|rs\|kotlin\|kt\|swift` | Generate application types |
+| `--type-name:"name"`                                            | Override generated type name                    |
+| `--naming:preserve\|camel\|pascal\|snake`                       | Select property naming                          |
+| `--nullable:native\|optional`                                   | Select nullable handling                        |
+| `--comments`                                                    | Include schema comments                         |
+| `--defaults-as-comments`                                        | Include default values as comments              |
+| `--json-type:unknown\|record\|json-value`                       | Select TypeScript JSON mapping                  |
+| `--include-generated`                                           | Include generated columns                       |
+| `--include-hidden`                                              | Include hidden columns                          |
+| `--output:"file"`                                               | Write generated types to a file                 |
+| `--json`                                                        | Print generated type result as JSON             |
+| `--force`                                                       | Overwrite existing `--output` file              |
+
+Legacy aliases such as `--config`, `--database-path:name`,
+`--database-size:name`, `--database-lastopened:name`, `--database-tables:name`,
+and `--database:name --sqleditor:"query"` still work.
+
+## Example
+
+Saved queries created in the graphical SQL Editor can also be executed through
+the CLI. To execute one, run:
+
+```bash
+sqlite-hub --database:Unit-00 --execute:"Group by creation Year"
+```
+
+Example output:
+
+```bash
+Executing: Group by creation Year
+SQL: SELECT STRFTIME('%Y', creation_time, 'unixepoch') AS creation_year, COUNT(*) AS channel_count FROM channels WHERE creation_time IS NOT NU...
+------------------------------------------------------------
+
+Statement count: 1
+Timing: 1ms
+
+Statement 1 (resultSet):
+Rows: 3
+Columns: creation_year, channel_count
+
+Results:
+  [0] 2024 | 11
+  [1] 2025 | 47
+  [2] 2026 | 40
+```

package/docs/CLI_API_PARITY.md

@@ -0,0 +1,61 @@
+# CLI / External API Parity
+
+This document compares the public CLI (`sqlite-hub ...`) with the versioned external API (`/api/v1`). It does not treat the internal browser routes under `/api/*` as stable automation surfaces.
+
+## Capability Matrix
+
+| Capability            | CLI                                                    | `/api/v1`                                                         | Parity   | Notes                                                                                             |
+| --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| App info              | `sqlite-hub --info`                                    | `GET /api/v1/info`                                                | Full     | Both return app/runtime/version status.                                                           |
+| Start/open app        | `sqlite-hub`, `--port`, `--open`                       | No                                                                | CLI only | API assumes the server is already running.                                                        |
+| List known databases  | `--database`                                           | No                                                                | CLI only | API requires a specific database id and token.                                                    |
+| Database detail       | `--database:name --path/--size/--lastopened`           | `GET /databases/:databaseId`                                      | Partial  | API returns structured detail for one authorized database. CLI can discover databases by name/id. |
+| List tables           | `--database:name --tables`                             | `GET /databases/:databaseId/tables`                               | Full     | Output format differs: terminal text vs JSON.                                                     |
+| Inspect table         | `--database:name --table:name`                         | `GET /databases/:databaseId/tables/:tableName`                    | Full     | Both expose columns, keys, indexes, counts, and identity metadata.                                |
+| Raw SQL execution     | `--query:"SQL"`                                        | `POST /api/v1/query`                                              | Full     | Both use SQL Editor execution and write Query History.                                            |
+| Save raw query        | `--query:"SQL" --store:"Name"`                         | `POST /api/v1/query` with `store` or `name`                       | Full     | Both title the history item and mark it saved.                                                    |
+| List saved queries    | `--queries`                                            | `GET /databases/:databaseId/queries`                              | Full     | Saved query collection only.                                                                      |
+| Get saved query SQL   | `--saved-query:"Name"`                                 | `GET /databases/:databaseId/queries/:queryName`                   | Full     | API returns structured query metadata.                                                            |
+| Get saved query notes | `--notes:"Name"`                                       | `GET /databases/:databaseId/queries/:queryName/notes`             | Full     | Same saved-query lookup behavior.                                                                 |
+| Execute saved query   | `--execute:"Name"`                                     | `POST /databases/:databaseId/queries/:queryName/execute`          | Full     | Both return result metadata and rows.                                                             |
+| Export saved query    | `--export:"Name" --format:csv\|tsv\|md\|json`          | `GET /databases/:databaseId/queries/:queryName/export?format=...` | Partial  | Same formats. CLI writes a file; API returns content in JSON.                                     |
+| List documents        | `--documents`                                          | `GET /databases/:databaseId/documents`                            | Full     | Read-only document listing.                                                                       |
+| Read document         | `--documents:"Name"`                                   | `GET /databases/:databaseId/documents/:documentName`              | Full     | API returns the document object.                                                                  |
+| Export document       | `--documents:"Name" --export`                          | `GET /databases/:databaseId/documents/:documentName/export`       | Partial  | CLI writes Markdown to disk; API returns content and filename.                                    |
+| Row JSON export       | `--table:name --export:"pk"`                           | `POST /databases/:databaseId/tables/:tableName/row`               | Full     | API body supports scalar or composite key objects.                                                |
+| Generate schema types | `--table:name --types:typescript\|rust\|kotlin\|swift` | `POST /databases/:databaseId/tables/:tableName/types`             | Partial  | Same generator. CLI supports stdout/file output and aliases; API returns JSON.                    |
+| List backups          | `--backups`                                            | `GET /databases/:databaseId/backups`                              | Full     | Both return managed backups for one database.                                                     |
+| Create backup         | `--backup`, `--backup:"name"`                          | `POST /databases/:databaseId/backups`                             | Full     | Both create and verify a managed backup through the same service.                                 |
+
+## Stable Surface Gaps
+
+These UI features currently have no public CLI or `/api/v1` equivalent:
+
+- Backups: verify, compare, restore, download, edit notes, delete, usage summary.
+- Table Advisor: run deterministic table analysis and copy SQL recommendations.
+- Synthetic Data: preview and insert generated rows.
+- Table Designer: create/edit tables, CSV-seed drafts, apply SQL preview.
+- Charts: create, edit, delete, resize, and export PNG.
+- Logs: filtered access/query history inspection.
+- Settings/API tokens: create, delete, inspect token usage.
+- Connections: open/create databases, edit labels/paths/icons/read-only mode, remove registry entries.
+- Documents mutation: create, edit, autosave, import, delete, insert saved-query tables/notes.
+- Row editing and table data mutation through the Data Browser.
+- Media Tagging setup and queue actions.
+- Overview Finder action.
+
+## Recommended Parity Order
+
+1. **Table Advisor**: read-only, deterministic, low risk, useful for automation.
+2. **Backups**: list and create are exposed; verify, restore, and download should follow.
+3. **Logs**: read-only observability with filters.
+4. **Synthetic Data**: useful for test automation; needs clear write safeguards.
+5. **Table Designer**: powerful but schema-mutating, so it needs dry-run/preview-first API design.
+6. **Charts**: lower priority for CLI, useful as API metadata/export later.
+
+## Design Notes
+
+- Keep `/api/v1` token-scoped by database.
+- Keep write operations explicit and reject read-only databases consistently.
+- Prefer JSON responses for API and file/stdout behavior for CLI.
+- Reuse existing services where possible so UI, CLI, and API stay behaviorally aligned.

package/docs/changelog.md

@@ -0,0 +1,149 @@
+# v1.5.0
+
+- synthetic data generation
+- logs for everything in the log menu
+- in api tokens you can now see last used and amount of api calls
+- removed legacy tables
+- new menu/view order
+
+# v1.4.0
+
+- Schema Diff / Database Diff in backups
+
+# v1.3.0
+
+- remove unused css and duplicates, css code rework
+- UX Audit from @corneliakocher
+- edit name and notes for backup
+- generate types from schema to typescript, kotlin, rust, swift
+- open row editor drawer with id hash http://127.0.0.1:4180/#/data#14a06a1ffa23e08ae86becec0c5d8b38
+
+# v1.1.2
+
+- documents overhaul
+- introducing the SQLite Hub dropdown button
+- backup manager
+
+# v1.1.1
+
+- table designer overhaul
+
+# v1.1.0
+
+- making the UI more consistent
+- structure overhaul, better UI
+- chart overhaul, better UI, search, etz
+- store last position of structure
+- join preview in structure
+- export JSON for Data, SQL Editor
+- export parquet for Data, SQL Editor
+- check updates for new versions in settings
+- Global Database Search
+
+# v1.0.0
+
+- Removed external Tailwind.
+- Fixed vibe-coding issues with https://github.com/oliverjessner/ItWorksBut.
+- Persisted saved/recent chart tabs in localStorage.
+- Updated dependencies.
+- Replaced innerHTML with DOM functions.
+- Display execution time in seconds when it exceeds 10 seconds.
+- The Performance panel in the SQL Editor shows query memory size.
+- The Structure view remembers the last selected table.
+- Removed pixel shift bug in SQL Editor on the bottom cards
+- title name changing depending on the menu
+- in messages you can see your executed query
+- secure execute for destructive queries
+- 250 page size, advanced search in data
+- export TSV, CSV, markdown, duplicate as table
+- copy from and export column function, with separator and wrapper
+- quick picks for database
+- export row as json
+- row editor shows urls and opens in browser, path detection, timestamp detection
+- format button in SQLEditor
+- API
+
+# v0.9.3
+
+- Improved re-rendering.
+- Fixed the sorting bug in Charts.
+- Stored the data row size in localStorage.
+- Saved charts.
+
+# v0.9.1
+
+- Tagging queue improvements.
+- Rotate right and rotate left.
+
+# v0.9.0
+
+- Tagging view.
+- Filtered Create, Update, and Delete queries out of the chart section.
+
+# v0.8.8
+
+- Fixed the delete-query modal window.
+- CSV export filenames are based on query names.
+- Unsaved query history tab.
+
+# v0.8.7
+
+- UX fixes.
+- Fixed a lot of vibe slop.
+- Started building reusable components.
+
+# v0.8.0
+
+- DDL copy button.
+- Open in Charts button in query details.
+- Clear makes the editor active.
+- UI fixes.
+- Overview improvements.
+
+# v0.7.0
+
+- Hide Query History and Hide Editor controls.
+- Better CLI interface.
+- Plotting and graphs.
+- Removed UI inconsistencies.
+
+# v0.6.0
+
+- Table Designer: create tables in SQLite Hub.
+
+# v0.5.1
+
+- Bug fix in the SQL Editor.
+
+# v0.5.0
+
+- SQL query history.
+- Open in Finder from Overview.
+- Sort columns in Data and the SQL Editor.
+- JSON view in the row editor.
+
+# v0.4.0
+
+- Search in Data.
+- Shift + Enter.
+- Database logos.
+- Cleaned up some chaotic code.
+
+# v0.3.2
+
+- Delete rows.
+- Modal windows for rows.
+
+# v0.3.1
+
+- Visualize tables.
+- Export CSV from Data and the SQL Editor.
+- Backup mode.
+
+# v0.2.0
+
+- Database fix.
+
+# v0.1.3
+
+- Edit in the SQL Editor.

package/docs/guidelines/AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+SQLite Hub is a local-first Node/Express app with a browser SPA. Backend code lives in `server/`: routes in `server/routes`, domain services in `server/services`, SQLite helpers in `server/services/sqlite`, and shared utilities in `server/utils`. Frontend code lives in `frontend/`: views in `frontend/js/views`, reusable UI in `frontend/js/components`, state/router logic in `frontend/js/store.js` and `frontend/js/router.js`, and styles in `frontend/styles`. CLI entrypoint code is in `bin/sqlite-hub.js`. Tests are in `tests/*.test.js`. Documentation is in `docs/`, with user-facing overview content in `README.md`.
+
+## Build, Test, and Development Commands
+
+- `npm run dev` starts the local server with Node watch mode on port `4180`.
+- `npm start` runs the packaged CLI entrypoint.
+- `npm test` runs all Node test files under `tests/`.
+- `npm run build` or `npm run build:css` regenerates `frontend/styles/tailwind.generated.css`.
+- `npm run screenshots` refreshes the standard screenshot set; use `npm run screenshots:backup-drawer` for the backup drawer capture.
+- `npm run audit` checks production dependencies for high-severity issues.
+
+## Coding Style & Naming Conventions
+
+Use plain JavaScript and existing local patterns. Frontend modules use ES modules; backend modules mostly use CommonJS. Prefer small, focused functions and reuse existing components before adding new UI primitives. Keep UI work aligned with `/docs/guidelines/DESIGN.md`; shared button, input, drawer, modal, and Escape-key behavior should stay consistent. Use descriptive camelCase for functions and variables, PascalCase only for classes/services, and route/view files named by feature, for example `tableAdvisor.js`.
+
+## Testing Guidelines
+
+Tests use the built-in Node test runner (`node:test`) with `node:assert/strict`. Name files `feature-name.test.js` and keep fixtures local to each test unless reuse is clearly helpful. Add focused tests for backend services, routes, state changes, and rendered view markup when behavior changes. Run the relevant focused test first, then `npm test` before handing off.
+You can use the test database id:conn_c3b310c3373fda5a
+for all tests.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short, informal messages, but contributors should keep commits clear and scoped, for example `add table advisor view` or `fix backup usage summary`. Pull requests should include a concise summary, test commands run, linked issue or context when available, and screenshots for visible UI changes. Note any generated files, especially `frontend/styles/tailwind.generated.css`, when CSS utilities change.
+
+## Security & Configuration Tips
+
+Do not commit local databases, tokens, or `.env` files. Use `.env.example` for documented configuration. Local API changes must preserve loopback-only and API-token protections in `server/middleware`.