@centia-io/mcp-server 1.0.16 → 1.0.17

package/AGENTS.md

@@ -0,0 +1,72 @@
+# AGENT.md - Centia BaaS Core Rules
+
+> Last updated: 2026-02-22
+
+This file only contains global hard rules.
+Task-specific guidance has been moved into `skills/*/SKILL.md`.
+
+## 1) Prime Directive
+
+- Prefer Centia MCP tools when available.
+- Use `@centia-io/sdk` for all JS/TS runtime code.
+- Use raw HTTP only for provisioning or SDK gaps.
+- Never re-implement SDK functionality with `fetch`/`axios` in runtime app code.
+
+## 2) Tool Priority (Hard Rule)
+
+Use this order:
+
+1. Centia MCP tools
+2. `@centia-io/sdk`
+3. OpenAPI-defined HTTP calls
+4. Docs-backed HTTP calls
+
+Never invent endpoints or payloads.
+
+## 3) Runtime vs Provisioning (Hard Rule)
+
+- Runtime application code must not perform schema provisioning.
+- Schema changes are provisioning/codegen tasks only.
+- Runtime apps must assume schema already exists.
+
+## 4) Security and Auth Baselines
+
+- Never hardcode credentials or tokens.
+- Never commit secrets in `.env`.
+- Frontend/browser code must not embed service tokens.
+- Browser auth must use SDK OAuth flows; do not implement OAuth manually.
+
+## 5) Destructive Operations Policy (Hard Rule)
+
+Before destructive changes, present method/tool/purpose and require explicit user confirmation.
+
+Destructive includes:
+
+- `DROP`, `TRUNCATE`, destructive `DELETE`
+- schema/table/column/constraint/index deletes
+- policy overwrite operations
+
+## 6) Required Skill Routing
+
+Use the minimal matching skill(s) below for each task:
+
+- Runtime SDK patterns: `skills/centia-runtime-sdk/SKILL.md`
+- Provisioning and migrations: `skills/centia-provisioning/SKILL.md`
+- JSON-RPC lifecycle and typed API: `skills/centia-json-rpc/SKILL.md`
+- Auth model by runtime context: `skills/centia-auth-model/SKILL.md`
+- PostgreSQL types and output formats: `skills/centia-types-formats/SKILL.md`
+- Map view config and layer styling (classes/styles/labels): `skills/centia-map-styling/SKILL.md`
+- Sub-user privileges and rights inheritance: `skills/centia-privileges/SKILL.md`
+- Key/value store (app state, flags, preferences): `skills/centia-keyvalue/SKILL.md`
+- Feature CRUD as GeoJSON by primary key: `skills/centia-feature/SKILL.md`
+- Realtime WebSocket events: `skills/centia-realtime/SKILL.md`
+- File import workflow: `skills/centia-file-import/SKILL.md`
+- OpenAPI and docs fallback: `skills/centia-openapi-docs/SKILL.md`
+- Delivery checklist and MCP reference: `skills/centia-delivery/SKILL.md`
+- Danish address/matrikel search component: `skills/danish-search/SKILL.md`
+
+## 7) Default Paths
+
+- SDK client: `src/baas/client.ts`
+- HTTP fallback layer: `src/baas/http.ts`
+- Provisioning assets: `provision/`, `migrations/`, `schema/` 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centia-io/mcp-server",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,9 @@
   },
   "files": [
     "dist",
-    "centia-api.json"
+    "centia-api.json",
+    "AGENTS.md",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",

package/skills/README.md

@@ -0,0 +1,29 @@
+# Skills Index
+
+This folder contains task-specific skills referenced from `AGENT.md`.
+
+## Quick Routing
+
+Use the smallest matching skill set for the task.
+
+| Skill | Use when |
+|---|---|
+| `centia-runtime-sdk` | Building or refactoring JS/TS runtime code with `@centia-io/sdk` |
+| `centia-provisioning` | Changing schema, tables, columns, constraints, indexes, policies, migrations |
+| `centia-json-rpc` | Creating/updating/calling JSON-RPC methods and generating TypeScript interfaces |
+| `centia-auth-model` | Implementing or reviewing auth across browser, backend, CLI, and provisioning |
+| `centia-types-formats` | Choosing PostgreSQL types, casts, `type_hints`, `type_formats`, output formats |
+| `centia-file-import` | Importing files with `postFileUpload` and `postFileProcess` |
+| `centia-openapi-docs` | Using OpenAPI/docs as fallback when MCP/SDK are insufficient |
+| `centia-map-styling` | Configuring map center/zoom/extent or layer cartography: classes, styles, labels |
+| `centia-privileges` | Granting sub-user privileges, groups, rights inheritance, layer authentication levels |
+| `centia-keyvalue` | Storing/reading JSON state (settings, flags, preferences) in the key/value store |
+| `centia-feature` | Reading/creating/updating/deleting single features as GeoJSON by primary key |
+| `centia-realtime` | Realtime WebSocket events, subscriptions with shapes, enabling table change events |
+| `centia-delivery` | Final delivery checklist, MCP coverage check, and handoff quality gate |
+| `danish-search` | Danish address/matrikel typeahead search component (`@centia-io/danish-search`) |
+
+## Core Rule
+
+Global hard rules stay in `AGENT.md`.
+Task-specific workflows and references stay in `skills/*/SKILL.md`.

package/skills/centia-auth-model/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: centia-auth-model
+description: Authentication policy for Centia BaaS across browser, backend, CLI, and provisioning contexts, including required SDK flows and environment variable usage.
+---
+
+# Auth Model Policy
+
+Use this skill whenever authentication is implemented or reviewed.
+
+## Identify runtime context
+
+Determine one of:
+
+- browser app (SPA/frontend)
+- server/backend/CLI
+- provisioning script
+
+## Browser apps
+
+Use SDK OAuth PKCE flow only.
+
+Required SDK classes:
+
+- `CodeFlow` for sign-in/sign-out/callback handling
+- `SignUp` for signup redirect flow
+
+Forbidden:
+
+- `CENTIA_ACCESS_TOKEN` in frontend code
+- service tokens in browser app code
+- manual OAuth implementation
+- provisioning API calls from browser runtime
+
+## Server and CLI
+
+Allowed methods:
+
+- `PasswordFlow`
+- `CENTIA_ACCESS_TOKEN` for MCP/HTTP fallback
+
+Typical use:
+
+- provisioning
+- admin/service-to-service operations
+- CLI tools
+
+## Provisioning scripts
+
+Provisioning runs server-side only.
+
+Allowed:
+
+- access token
+- `PasswordFlow`
+- MCP tools
+- OpenAPI calls
+
+Forbidden:
+
+- browser auth flows
+
+## Responsibility matrix
+
+- Browser app: `CodeFlow`
+- Browser signup: `SignUp`
+- Backend app: `PasswordFlow`
+- Provisioning: `PasswordFlow` or access token
+- CLI: `PasswordFlow`
+
+## Environment variables
+
+Server/provisioning:
+
+- `CENTIA_HOST`
+- `CENTIA_CLIENT_ID`
+- `CENTIA_CLIENT_SECRET`
+- `CENTIA_USERNAME`
+- `CENTIA_PASSWORD`
+- `CENTIA_DATABASE`
+- optional: `CENTIA_ACCESS_TOKEN`
+
+Browser (Vite):
+
+- `VITE_CENTIA_HOST`
+- `VITE_CENTIA_CLIENT_ID`
+- `VITE_CENTIA_DATABASE`
+
+Never commit secrets. Keep `.env.example` with placeholders.

package/skills/centia-delivery/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: centia-delivery
+description: Delivery and validation checklist for Centia tasks, including required output sections, MCP tool reference, geospatial mapping library selection, and final self-check criteria.
+---
+
+# Delivery Checklist
+
+Use this skill before finalizing Centia-related implementation work.
+
+## Required delivery content
+
+Include:
+
+- setup steps
+- env vars used
+- install and run commands
+- SDK usage explanation
+- provisioning steps (if applicable)
+- validation steps
+- HTTP calls made (without secrets)
+
+## MCP tool reference
+
+Schema and tables:
+
+- `getSchema`, `postSchema`, `patchSchema`, `deleteSchema`
+- `getTable`, `postTable`, `patchTable`, `deleteTable`
+- `getColumn`, `postColumn`, `patchColumn`, `deleteColumn`
+- `getConstraint`, `postConstraint`, `deleteConstraint`
+- `getIndex`, `postIndex`, `deleteIndex`
+- `getSequence`, `postSequence`, `patchSequence`, `deleteSequence`
+
+Query and API:
+
+- `postSql`
+- `postGraphQL`
+- `getRpc`, `postRpc`, `patchRpc`, `deleteRpc`
+- `postCall`, `postCallDry`, `getTypeScript`
+
+Auth and access:
+
+- `postOauth`, `postDevice`
+- `getUser`, `postUser`, `patchUser`, `deleteUsers`
+- `getRule`, `postRule`, `patchRule`, `deleteRule`
+- `getPrivileges`, `patchPrivileges`
+- `getClient`, `postClient`, `patchClient`, `deleteClient`
+
+Metadata:
+
+- `getMetaData`, `patchMetaData`
+
+Import and misc:
+
+- `postFileUpload`, `postFileProcess`
+- `postCommit`
+- `getStats`
+
+## Mapping library selection
+
+For map UIs:
+
+- Default to MapLibre GL JS for straightforward map display and interaction.
+- Use Leaflet or OpenLayers for advanced interaction or GIS-heavy needs.
+- Prefer current docs lookup (for example Context7 MCP when available) before writing mapping code.
+
+## Final self-check
+
+- Used MCP tools where possible.
+- Used SDK for runtime JS/TS.
+- Kept provisioning separate from runtime.
+- Avoided runtime schema changes.
+- Used correct auth flow for context.
+- Kept secrets out of source control.
+- Followed OpenAPI/docs contract where HTTP was used.

package/skills/centia-feature/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: centia-feature
+description: Use when reading, creating, updating, or deleting individual geographic features (rows) as GeoJSON by primary key in Centia BaaS tables, or when working with /api/v4/schemas/{schema}/tables/{table}/features endpoints, getFeature/postFeature/patchFeature/deleteFeature tools, the Features SDK class, WFS-T feature editing, or the srs/SRID of feature geometry.
+---
+
+# Feature API (GeoJSON CRUD by primary key)
+
+Use this skill for the v4 Feature API (`/api/v4/schemas/{schema}/tables/{table}/features/{feature}`): GeoJSON CRUD on single table rows, addressed by primary key, executed through the in-process WFS-T engine (versioning, workflow, geofence rules and tile-cache busting all apply). Successor of v2 `/api/v2/feature`.
+
+## Availability
+
+Lives on the GeoCloud2 branch `dev/multiple_styles` (commits `25900b64`…`844d8fd6`, 2026-08-25/26). As of 2026-08 it is **not** on production `api.centia.io` — assume dev-only. SDK support: `@centia-io/sdk` **>= 0.2.11** (published on npm; the `Features` class is absent in <= 0.2.10).
+
+## Endpoints and semantics
+
+**Token-only** (Bearer JWT on every request; there is NO anonymous read, even for public layers). Sub-users allowed, governed by per-table privileges (see `centia-privileges`). The table must be a registered layer with a **single-column primary key** (400 `NO_PRIMARY_KEY` otherwise) and WFS enabled (400 `WFS_NOT_ENABLED`).
+
+| Operation | Route / MCP tool | Result |
+|---|---|---|
+| Get by key(s) | `GET .../features/{feature}` / `getFeature` — `{feature}` is one key **or a comma list** (`1,2,3`); `?srs` = output SRID (default 4326) | `200`: **one match → bare GeoJSON `Feature`; several → `FeatureCollection`**; `404` `FEATURE_NOT_FOUND` if none match (partial matches return `200` with the found ones) |
+| Create | `POST .../features` (no key in path); body = `Feature` or `FeatureCollection`; `?srs` = SRID of incoming geometry / `postFeature` | `201` + `Location: .../features/{keys}` (comma list of the new keys — parse it for generated keys); `400` `NOTHING_INSERTED` if the layer is not editable |
+| Update | `PATCH .../features/{feature}` (key optional) / `patchFeature` | `303 See Other` + `Location`; `404` `FEATURE_NOT_FOUND` if nothing updated |
+| Delete | `DELETE .../features/{feature}` (one key **or a comma list**, like GET) / `deleteFeature` | `204`; `404` `FEATURE_NOT_FOUND` if nothing was deleted (partial matches delete the found ones → `204`) |
+
+No PUT/upsert. No collection GET — reading a whole table is a SQL API or WFS job (`GET .../features` without a key → 400 `FEATURE_ID_REQUIRED`). Keys containing `'` are rejected (400 `INVALID_FEATURE_ID`).
+
+## Body and write rules
+
+- Body must be a GeoJSON `Feature` or a **non-empty** `FeatureCollection` (else 400 `INVALID_GEOJSON`). Geometry is optional — a feature without geometry inserts/updates properties only, and reads back with `geometry: null`.
+- `srs` is asymmetric: output SRID on GET, **incoming**-geometry SRID on POST/PATCH, always defaulting to 4326 (GeoJSON lon/lat). Sending e.g. 25832 coordinates without `?srs=25832` stores garbage geometry.
+- POST: a primary-key value in `properties` is used as the new key; otherwise one is generated. No upsert — posting an existing key fails the WFS transaction.
+- PATCH: the path key wins; without it every feature must carry its primary key in `properties` (400 `PRIMARY_KEY_MISSING`). You **cannot PATCH one path key with a collection** (400 `INVALID_DATA`) — omit the key to batch-update. Omitted properties stay untouched.
+- Property encoding (WFS-T): booleans become `t`/`f`, **JSON arrays are converted to PostgreSQL array literals automatically** — send plain JSON values, do not pre-format `"{1,2,3}"` strings.
+
+## SDK (>= 0.2.11)
+
+Standalone class **`Features`** (plural — `Feature` is the GeoJSON type), explicit-client pattern: `new Features(client.http)`. Methods: `getFeature<P>(schema, table, key | keys[], {srs?})` → `GeoJsonFeature<P> | GeoJsonFeatureCollection<P>` (union — normalize the shape yourself); `postFeature(schema, table, body, {srs?})` and `patchFeature(schema, table, body, {feature?, srs?})` → `{location}`; `deleteFeature(schema, table, key)`. Own minimal GeoJSON types (`GeoJsonFeature`, `GeoJsonFeatureCollection`, `GeoJsonGeometry`), no `@types/geojson`. Errors: `CentiaApiError` (`.status`/`.code`).
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Assuming production availability | dev/multiple_styles only; MCP tools need a server restart against the updated spec |
+| Reading public layers without a token | v4 Feature API always requires a Bearer JWT (unlike the OGC routes) |
+| Expecting one response shape from GET | one match = bare `Feature`, several = `FeatureCollection` |
+| Listing a table via `GET .../features` | 400 `FEATURE_ID_REQUIRED` — use the SQL API or WFS for collections |
+| Pre-formatting array columns as `"{a,b}"` strings | send JSON arrays; the server builds the PG array literal |
+| PATCHing `/features/42` with a `FeatureCollection` | 400 `INVALID_DATA` — drop the path key and put keys in `properties` |
+| Forgetting `?srs` on POST/PATCH of projected coordinates | geometry is read as EPSG:4326 by default |
+| Expecting `200` from PATCH / a JSON body from POST | `303`/`201` with empty bodies; the keys are in the `Location` header |

package/skills/centia-file-import/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: centia-file-import
+description: Two-step Centia file import workflow using MCP tools, covering upload, processing options, validation mode, geospatial projection settings, and supported input formats.
+---
+
+# File Import Workflow
+
+Use this skill for importing tabular or geospatial files into Centia.
+
+## Hard rule
+
+Use MCP tools first:
+
+1. `postFileUpload`
+2. `postFileProcess`
+
+Do not call raw HTTP import endpoints unless MCP is unavailable.
+
+## Step 1: Upload
+
+Call `postFileUpload` and capture returned file id/name.
+
+## Step 2: Process
+
+Call `postFileProcess` with uploaded file and target schema.
+
+Key options:
+
+- `import`: `false` for validation-only, `true` to commit
+- `append`: append to existing table
+- `truncate`: clear table before append
+- `timestamp`: add timestamp column
+- `s_srs` and `t_srs`: source/target projection fallback
+- `p_multi`: promote single to multipart geometries
+- `x_possible_names` and `y_possible_names`: CSV lon/lat hints
+
+## Validation flow
+
+Run with `import: false`, inspect response, then rerun with `import: true`.
+
+## Supported formats
+
+- GeoJSON (`.geojson`)
+- Shapefile zip (`.zip` with sidecar files)
+- GeoPackage (`.gpkg`)
+- GML (`.gml`)
+- CSV (`.csv`)
+
+## Typical imported table shape
+
+- primary key `gid`
+- geometry column `the_geom`
+- GiST index on `the_geom`
+- inferred field types

package/skills/centia-json-rpc/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: centia-json-rpc
+description: JSON-RPC method lifecycle for Centia BaaS, including method creation, invocation, dry-run type inference, TypeScript interface generation, and runtime usage with createApi or Rpc.
+---
+
+# JSON-RPC Workflow
+
+Use this skill when creating, updating, testing, or calling Centia JSON-RPC methods.
+
+## Purpose
+
+JSON-RPC wraps SQL in named server-side methods for reuse, consistency, and central control.
+
+## Define method (provisioning)
+
+Use `postRpc`.
+
+Parameter style:
+
+- `:param`
+- `:param::type` (required for type inference)
+
+Example:
+
+```txt
+postRpc({
+  method: "addDays",
+  q: "select date(:date) + :days::int as result",
+  type_hints: { date: "timestamptz" },
+  type_formats: { result: "l jS F Y" }
+})
+```
+
+Manage definitions with:
+
+- `getRpc`
+- `postRpc`
+- `patchRpc`
+- `deleteRpc`
+
+## Call method
+
+Use `postCall` with JSON-RPC 2.0 envelope.
+
+```txt
+postCall({
+  jsonrpc: "2.0",
+  method: "addDays",
+  params: { date: "2025-05-01", days: 7 },
+  id: "1"
+})
+```
+
+- Omit `id` for notification mode.
+- `params` can be object or array of objects for batch calls.
+
+## Dry-run and TypeScript inference
+
+1. Dry-run method with `postCallDry`.
+2. Fetch generated interfaces with `getTypeScript`.
+3. Save interface (for example `src/baas/api.ts`).
+4. Use at runtime with `createApi<Api>()`.
+
+Important: SQL params must include explicit casts (`:param::type`) to infer method signatures reliably.
+
+## Runtime usage
+
+Preferred typed call:
+
+```ts
+const api = createApi<Api>();
+const rows = await api.getX({ x: 1 });
+```
+
+Fallback generic call:
+
+```ts
+await rpc.call({ jsonrpc: "2.0", method: "getX", params: { x: 1 }, id: 1 });
+```
+
+## Error codes to recognize
+
+- `-32600` invalid request
+- `-32601` method not found
+- `-32602` invalid params
+- `-32603` internal error

package/skills/centia-keyvalue/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: centia-keyvalue
+description: Use when storing or reading small JSON state (app settings, feature flags, user preferences, drafts, snapshots) in the Centia BaaS key/value store, or when working with /api/v4/keyvalue endpoints, the Keyvalue SDK class, keys, owner/public flags, or paths projection.
+---
+
+# Key/Value Store
+
+Use this skill for the v4 Keyvalue API (`/api/v4/keyvalue/{key}`): per-database storage of arbitrary JSON under globally unique keys, with an owner/public access model.
+
+## Availability
+
+Lives on the GeoCloud2 branch `dev/multiple_styles` (commits `2213a099`, `3897be13`) and requires the v3 migration run (`GET /api/v3/admin/migrations` adds `owner`/`public` columns to `settings.key_value`). As of 2026-08 it is **not** confirmed on production `api.centia.io` — assume dev-only. SDK support: `@centia-io/sdk` **>= 0.2.10** (not 0.2.9). The legacy v2 `/api/v2/keyvalue` is unchanged and separate.
+
+## Endpoints and semantics
+
+Token-only (Bearer JWT on every request). Keys are **globally unique per database** — no schema namespacing, no format rules (SDK URL-encodes).
+
+| Operation | Route / MCP tool | Result |
+|---|---|---|
+| List all visible keys | `GET /api/v4/keyvalue` / `getKeyvalue` (no key) | `200`, **plain JSON array** of entries (no wrapper) |
+| Get one key | `GET /api/v4/keyvalue/{key}` | `200` entry; `404` `KEY_NOT_FOUND` if absent/not visible |
+| Create | `POST .../{key}`, body `{value, public?}` / `postKeyvalue` | `201` + `Location`; `409` `KEY_EXISTS` if key exists |
+| Update value and/or public | `PATCH .../{key}`, body `{value?, public?}` / `patchKeyvalue` | `303 See Other` + `Location` (see `centia-provisioning`) |
+| Delete | `DELETE .../{key}` / `deleteKeyvalue` | `204`; `404` if absent/not owned |
+
+Entry shape: `{id: int, key, value: <decoded JSON>, owner: string|null, public: bool}`. `value` is arbitrary JSON, required on POST — the spec declares `type: object`, but the server applies no type check, so scalars and arrays round-trip too. There is **no PUT/upsert**: create with POST, update with PATCH (on unknown state: POST, fall back to PATCH on 409). The `201`/`303` bodies are empty; their `Location` is `/api/v4/keyvalue/{key}` — GET it to read the entry back.
+
+## Access model
+
+- `owner` is **always set server-side from the JWT uid** — never send it in the body; ownership never changes.
+- Super user: full CRUD on every key. Sub-user: reads own keys + `public: true` keys; creates/updates/deletes **only own** keys (violations surface as `404`, not `403`).
+- Legacy rows with `owner IS NULL` are treated as public and super-owned: everyone reads, only the super user modifies.
+
+## `paths` projection (GET single key only)
+
+`GET .../{key}?paths=user.name,active` returns only the named sub-trees: comma separates paths, dot navigates; the result `value` is keyed by the path strings, e.g. `{"value": {"user.name": "Alice", "active": true}}`. Empty path or segment → `400` `INVALID_PATHS`. No other query params exist — **no `like`/`filter`** listing (that was v2 only); filter key names client-side.
+
+## SDK (>= 0.2.10)
+
+Standalone class, explicit-client pattern: `new Keyvalue(client.http)`. Methods `getKeyvalue()` (list) / `getKeyvalue<T>(key)` / `getKeyvalue(key, paths)` / `postKeyvalue<T>(key, {value, public?})` / `patchKeyvalue<T>(key, {value?, public?})` / `deleteKeyvalue(key)`; errors are `CentiaApiError` (`.status`/`.code`). Types: `KeyvalueEntry<T>`, `KeyvalueProjection`.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Assuming production availability | dev/multiple_styles + migration required; not confirmed on api.centia.io |
+| PUT or POST to overwrite an existing key | No upsert; POST on existing key → `409` — use PATCH |
+| Sending `owner` in the body | Owner comes from the JWT; body allows only `value` and `public` |
+| `like=`/`filter=` query params on v4 | v2-only; v4 lists everything visible, filter client-side |
+| Expecting `200` from PATCH | Returns `303 See Other` — disable auto-redirect |
+| Expecting `403` when touching another user's key | Non-owned rows are invisible to writes → `404 KEY_NOT_FOUND` |
+| Using `@centia-io/sdk` 0.2.9 for Keyvalue | The `Keyvalue` class ships in 0.2.10+ |

package/skills/centia-map-styling/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: centia-map-styling
+description: Map view configuration and layer cartography for Centia BaaS, including per-schema map center/zoom/extent, layers, classes, styles, and labels, MapServer-backed rendering, id round-trip rules, and payload value conventions.
+---
+
+# Map, Layers, Classes, Styles, and Labels
+
+Use this skill when configuring the per-schema map view or the cartographic styling of layers (classes, styles, labels) via MCP tools or the v4 API.
+
+## Availability
+
+The Map API and the granular class/style/label sub-routes live on the GeoCloud2 branch `dev/multiple_styles`. As of 2026-08 they are **not** on production `api.centia.io`. SDK support: `@centia-io/sdk` >= 0.2.5 has `provisioning.maps.getMap/patchMap` and the `MapConfig` type.
+
+## Data model
+
+```txt
+Map      per-SCHEMA view config (center, zoom, extent) — orthogonal to layers
+Layer    one relation, key = schema.table.geometry_column, carries `properties` (def JSON)
+ └─ classes[]      one rendering rule each: expression + scale range + sortid
+     ├─ styles[]   one symbolizer each (MapServer STYLE parameters)
+     └─ labels[]   one text label each (MapServer LABEL parameters)
+```
+
+Classes, styles, and labels are converted server-side into a MapServer mapfile; they control WMS/tile rendering. The schema's Map `extent` is also used as the schema bbox in OGC GetCapabilities.
+
+## Map view config
+
+- `GET`/`PATCH /api/v4/map/schema/{schema}` — MCP tools `getMap` / `patchMap`.
+- Shape: `{ center: [lon, lat] | null, zoom: number | null, extent: [minx, miny, maxx, maxy] | null }`.
+- **CRS is EPSG:4326** (lon/lat). Older copies of the OpenAPI spec say EPSG:3857 — that is outdated; the API surface transforms to/from the 3857 storage at the boundary.
+- PATCH is partial: only provided keys are updated; explicit `null` clears a key. Returns `303 See Other` (see `centia-provisioning` for redirect handling).
+
+## Layer endpoints — two edit models
+
+| Model | Route / MCP tool | Semantics |
+|---|---|---|
+| Atomic configure | `POST /api/v4/layers` / `postLayer` | Sets `properties` and **replaces the entire `classes` array** |
+| Layer properties | `PATCH /api/v4/layers/{layer}` / `patchLayer` | Key-merge on the def JSON only (no classes) |
+| Granular create | `POST .../classes`, `.../styles`, `.../labels` / `postLayerClass`, `postStyle`, `postLabel` | Additive; body is one object or an array |
+| Granular update | `PATCH .../classes/{id}`, etc. / `patchLayerClass`, `patchStyle`, `patchLabel` | Key-merge on that entry |
+| Granular delete | `DELETE .../{id}` / `deleteLayerClass`, `deleteStyle`, `deleteLabel` | `{id}` accepts comma-separated ids |
+
+`POST /api/v4/layers` configures **existing** layers (relations already registered); it does not create tables. Preferred bulk workflow: `getLayer` → edit the document locally → one atomic `postLayer`.
+
+## Id and round-trip rules
+
+- Ids on classes, styles, and labels are fixed, server-assigned (8 hex chars). Send **new** entries *without* `id` — a client-supplied id on class creation is rejected with 400.
+- When using atomic `postLayer`, send **existing ids back unchanged**; entries arriving without id are treated as new and get freshly minted ids (identity cannot be guessed).
+- Round-trip unknown keys untouched: legacy classes can carry flat label keys (e.g. a top-level `force`). Do not strip them.
+
+## Value conventions
+
+- Numeric fields are **strings**; empty string `''` means unset. `sortid` is a real integer (convention: steps of 10; defaults to highest existing + 10).
+- Colors are hex `#RRGGBB`. Opacity is `'0'`–`'100'`.
+- Many style/label numeric fields accept a `[column]` reference for data-driven values (size, angle, offsets).
+
+## Class expressions and label text
+
+- Do **not** use the layer properties `theme_column` (CLASSITEM) and `label_column` (LABELITEM). They are the legacy mechanism and must not be combined with class expressions / label `text` — leave both empty (`''`).
+- Classify with a standalone logical MapServer `expression` on each class, and label with the label's `text` expression (e.g. `[name]`).
+- Quoting in class expressions depends on the column type:
+  - **String columns:** quote *both* sides, including the `[column]` reference: `'[Status]'='Forslag'` (`'string'='string'`).
+  - **Numeric columns:** no quotes on either side: `[tal]=1` (`1=1`).
+
+## Enum quick reference
+
+| Field | Values |
+|---|---|
+| style `linecap` | `round` `butt` `square` |
+| style `geomtransform` | `bbox` `centroid` `end` `labelpnt` `labelpoly` `start` `vertices` |
+| style `symbol` (built-ins) | `circle` `square` `triangle` `hatch1` `dashed1` `dot-dot` `dashed-line-short` `dashed-line-long` `dash-dot` `dash-dot-dot` `arrow` `arrow2` |
+| label `position` | `auto` `ul` `uc` `ur` `cl` `cc` `cr` `ll` `lc` `lr` |
+| label `angle` keywords | numeric, `auto`, `auto2`, `follow`, or `[column]` |
+| label `fontweight` | `normal` `bold` `italic` `bolditalic` |
+| layer `geotype` | `Default` `POINT` `LINE` `POLYGON` |
+| layer `format` | `PNG` `jpeg_low` `jpeg_medium` `jpeg_high` |
+| layer `cache` | `disk` `sqlite` `s3` `memcache` |
+
+## Scale gates (all "Numeric value stored as a string")
+
+`minscaledenom`/`maxscaledenom` exist at layer, class, and label level; layer-level `label_min_scale`/`label_max_scale` gate all labels. Min = most-zoomed-in bound, max = most-zoomed-out bound.
+
+## Common mistakes
+
+| Mistake | Reality |
+|---|---|
+| Sending map `center`/`extent` in EPSG:3857 | The surface is EPSG:4326 (lon/lat); 3857 in old spec copies is wrong |
+| `postLayer` without existing class/style/label ids | Whole `classes` array is replaced; missing ids are re-minted, breaking references |
+| Client-generated ids on new entries | Server assigns ids; class creation with an id returns 400 |
+| Numeric values as JSON numbers | Most def/class/style/label numerics are strings; `''` = unset |
+| Adding a class via `PATCH /layers/{layer}` | That route key-merges layer properties only; use `postLayerClass` or atomic `postLayer` |
+| Stripping unrecognized keys before writing back | Legacy flat keys must round-trip unchanged |
+| Setting `theme_column`/`label_column` alongside class expressions or label `text` | The two mechanisms must not be combined — leave both properties empty and use expressions/`text` |
+| String expression written `[Status]='Forslag'` | Quote the column reference too for string columns: `'[Status]'='Forslag'`; numeric columns stay unquoted: `[tal]=1` |
+
+## WMS preview
+
+Preview rendering with `GET /api/v4/ows/schema/{schema}/database/{database}?SERVICE=WMS&...&LAYERS={schema}.{table}`. Since GC2 `cd168572` (`dev/multiple_styles`) this single endpoint serves Bearer, HTTP Basic, and anonymous clients; the old token-only route `/api/v4/ows/schema/{schema}` is **removed**. A Bearer token must match `{database}` — a mismatch returns 401 (OGC ServiceException), never a silent downgrade to anonymous. Binary GetMap responses are a documented SDK gap — use raw HTTP there (see `centia-runtime-sdk` for the fallback boundary).
+
+Access control for layers and OWS is covered in `centia-privileges`.