release: v1.12.3 — dashboard table title fix + cold-start onramp polish (#203)

Cuts v1.12.3, folding the two fixes merged to main after v1.12.2 into a
published release. Lockstep bump of the 8 published packages
1.12.2 -> 1.12.3, with the per-release image-tag pins (quickstart +
scaffold docker-compose) and README (docker examples, runtime-requirements
heading, roadmap) following — no source change of its own.

Ships (back-compatible, no API surface change):

- #202 — the Admin UI Dashboard's Tables list now uses the table name as
  the title and the COMMENT as the description, matching the Views list. A
  commented table previously rendered the COMMENT in both slots and hid the
  name; the shared table detail / list / new / edit headings are fixed too.
- #201 — cold-start onramp polish: the scaffolded .env.example drops a
  redundant DATABASE_URL line that silently desynced from POSTGRES_PASSWORD,
  and a bad/missing argument to the MCP describe_table / describe_view tools
  now returns an actionable message instead of a generic tool-failed error.

Tag v1.12.3 on the merge commit triggers release.yml (verify -> npm OIDC ->
GHCR multi-arch + cosign -> GitHub Release). A follow-up kozou-site PR bumps
packages to 1.12.3 and regenerates docs, per the established post-release flow.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: takashi-matsuyama

README.md

@@ -97,8 +97,8 @@ Advisory only: enforcement stays in PostgreSQL (GRANTs + your RLS). See
 Use the runtime image directly:
 
 ```bash
-docker pull ghcr.io/kozou-dev/kozou:v1.12.2
-docker run --rm ghcr.io/kozou-dev/kozou:v1.12.2 mcp --help
+docker pull ghcr.io/kozou-dev/kozou:v1.12.3
+docker run --rm ghcr.io/kozou-dev/kozou:v1.12.3 mcp --help
 ```
 
 Or install the packages for library / embedded use:
@@ -133,7 +133,7 @@ via JWKS, or a minimal self-hosted issuer. See
 
 ## Requirements
 
-Runtime requirements for v1.12.2:
+Runtime requirements for v1.12.3:
 
 - **PostgreSQL 16 or later** — the canonical source of truth
 - **Docker 24 or later** (optional) — recommended for the `docker compose up` stack, which brings up PostgreSQL and a `kozou` service running `kozou dev` (the bundled Admin UI + MCP HTTP server, plus Kozou's in-house REST backend served in-process) from `ghcr.io/kozou-dev/kozou` (a multi-arch image, native on linux/amd64 and linux/arm64). The default stack needs **no separate REST container**; to opt out and use an external PostgREST instead, set `adapter.type: postgrest` and add the (commented) service in the scaffold's `docker-compose.yml`.
@@ -168,6 +168,7 @@ Contributors additionally need **pnpm 9 or later**. See [CONTRIBUTING.md](CONTRI
 - v1.12.0 (shipped): `kozou docs` now emits a **Mermaid entity-relationship diagram** as a schema overview, built entirely from the existing schema context (read-only, stateless, no new introspection). It is meaning-laden, not a bare foreign-key graph: tables *and* views are entities (views are Kozou's named business concepts, linked by a dotted "derives from" edge to the tables they are built on), columns are attributes with `PK` / `FK` markers, foreign keys are crow's-foot edges whose cardinality reflects NOT NULL / uniqueness, and a legend plus an entity-level `@ai` / `@policy` notes block sits under the diagram, so a source-of-truth view and the schema's meaning are co-located with the structure. The README and docs also now state that **Kozou is migration-tool-agnostic** — it compiles the schema your migrations produce and never runs DDL or owns migration state.
 - v1.12.1 (shipped): documentation and dependency hygiene. The scaffolded `migrations/0001_init.sql` now ships a worked example of the COMMENT conventions — an `orders` table and a `vw_recognized_revenue` view exercising `@ai` / `@widget` / `@policy` / `@example` and the view-as-domain-concept pattern — instead of a single-line stub, so a freshly scaffolded project shows how to encode schema meaning from the start. Also pins a transitive dev/test-only dependency (`undici`) to a patched line for a published security advisory; no runtime dependency of any published package changes.
 - v1.12.2 (shipped): a patch release of input-validation hardening, all back-compatible. `@kozou/api` pre-flights two more client-mistake classes to a `400` up front instead of letting them reach PostgreSQL as a data exception (a `500`): a value outside a **native `ENUM`** column's labels — on every path (list filter, `in.(...)`, write body, item-id segment, and a forged pagination cursor) — and an **out-of-range pagination offset** (a `page` so large the computed `OFFSET` overflows). CHECK-constraint columns (text / date / …) are deliberately left to PostgreSQL: their value set is not exhaustive, so a predicate outside it (`status=eq.legacy`, `like.…`, a date range) stays a valid query, not a 400. The same change also stops an **empty-string text filter** (`?col=eq.`) being wrongly 400'd, since `''` is a valid value. Plus dependency hygiene: a transitive build-only dependency (`ts-deepmerge`) is pinned for an OSV-Scanner advisory; no runtime dependency of any published package changes.
+- v1.12.3 (shipped): a patch release of reference Admin UI and cold-start fixes, all back-compatible. The Dashboard's **Tables** list now shows the table name as the title and its `COMMENT` as the description — a commented table previously rendered the comment in both slots and never showed the name, while the **Views** list already did the right thing; the table detail / list / new / edit headings shared the same label and are fixed too (`@kozou/core`). Plus onramp papercuts found running the scaffold end to end: the scaffolded `.env.example` no longer carries a redundant `DATABASE_URL` line that silently desynced from `POSTGRES_PASSWORD` (a first-run auth failure), and a bad or missing argument to the MCP `describe_table` / `describe_view` tools now returns an actionable message naming the argument instead of a generic tool-failed error.
 - Beyond v1.12: React UI exploration — optional write-path parity (a second UI driving create / edit / delete across both adapters)
 
 ## Name

examples/quickstart/docker-compose.yml

@@ -36,7 +36,7 @@ services:
       retries: 10
 
   kozou:
-    image: ghcr.io/kozou-dev/kozou:v1.12.2
+    image: ghcr.io/kozou-dev/kozou:v1.12.3
     command: ["dev"]
     environment:
       DATABASE_URL: postgres://${POSTGRES_USER:-kozou}:${POSTGRES_PASSWORD:-kozou}@postgres:5432/${POSTGRES_DB:-kozou}

packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/api",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou's own REST layer: serves table CRUD / VIEW reads / OpenAPI from a SchemaContext.",
   "license": "Apache-2.0",
   "repository": {

packages/codegen/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/codegen",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou TypeScript codegen: emit row / entity types from a SchemaContext (experimental).",
   "license": "Apache-2.0",
   "repository": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/core",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou core: Schema Context, type definitions, UI Hints zod schema, DataAdapter interface.",
   "license": "Apache-2.0",
   "repository": {

packages/introspect/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/introspect",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "PostgreSQL DDL / COMMENT / VIEW introspection.",
   "license": "Apache-2.0",
   "repository": {

packages/kozou/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kozou",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou CLI: scaffolding, schema introspection, and MCP server entry points.",
   "license": "Apache-2.0",
   "repository": {

packages/kozou/src/templates/docker-compose.yml

@@ -37,7 +37,7 @@ services:
     # `kozou dev` spawns the bundled @kozou/svelte-ui Admin UI, the MCP HTTP
     # server, and Kozou's in-house REST backend (all in-process). Each binds
     # 0.0.0.0 inside the container so the port mappings below reach your host.
-    image: ghcr.io/kozou-dev/kozou:v1.12.2
+    image: ghcr.io/kozou-dev/kozou:v1.12.3
     command: ["dev"]
     environment:
       DATABASE_URL: postgres://${POSTGRES_USER:-kozou}:${POSTGRES_PASSWORD:-kozou}@postgres:5432/${POSTGRES_DB:-kozou}

packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/mcp",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou MCP server for AI agents (stdio + HTTP)",
   "license": "Apache-2.0",
   "repository": {

packages/svelte-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kozou/svelte-ui",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "Kozou reference Admin UI. SvelteKit + Svelte 5 admin UI that consumes SchemaContext via @kozou/core and talks to a backend via the DataAdapter interface.",
   "license": "Apache-2.0",
   "repository": {