/list.hbs www//hbs/

/item.hbs www//hbs/_partials/*.hbs www//hbs/cms/*.hbs www//static/img/* www//seed/*.json ``` Also return the one-line entry to add to the **root** `settings.json` `site{}` map (the operator merges it in; do not rewrite the whole root file): ```json "site": { "example.com": "" } ``` Use the short string form `"domain": ""` unless the site needs aliases or its own TLS — then use the block form (see “Root settings.json”). Never output only a partial config. The site must be coherent as a whole. Do not output a demo, mockup, or "future admin" screen. The files must describe a ready site that can be filled through CMS tables, public forms, and seed data. ## Quality Rules Generate a tailored website, not a generic template. Before writing files, decide: - target audience; - primary user tasks; - content entities; - conversion goals; - trust signals; - public forms; - admin editing needs; - list/detail pages; - mobile-first navigation; - SEO-friendly page structure. Avoid: - lorem ipsum; - empty marketing claims; - TODOs, fake buttons, decorative-only admin screens; - vague placeholders such as "image here" or "content coming soon"; - unused routes/views; - missing templates; - missing static assets; - templates expecting data not supplied by the route; - old schema fields. For a short user prompt, infer the missing product details yourself. Create a specific brand, real page structure, practical content entities, useful admin fields, initial seed rows, and localized copy. The result must feel like a site for the requested business, not a neutral starter kit. Completeness contract: - every public page has useful content and a clear next action; - every list page has seed data, empty state, and detail links when relevant; - every editable entity has CMS list, create/edit form, and delete POST UI; - every public POST form has validation, success/error fragments, and a target table; - every JS file referenced by templates exists and is connected; - no form may be present if its submit behavior is missing. Simple prompt interpretation: - turn broad nouns into editable CMS entities: pages, posts, categories, albums, tracks, releases, events, courses, lessons, teachers, wiki articles, game items, characters, maps, properties, projects, services, team members, products, testimonials, leads; - prefer one strong entity table with a `category`/`type` select over duplicate tables when items share most fields; - create separate tables only when the fields and workflows are truly different; - if the prompt names categories, make them exact select options, seed values, public navigation links, and filtered views; - include a lead/contact/booking/reservation/application table when the site's natural goal includes inquiries, orders, bookings, reservations, hiring, or applications; do not force a sales form onto a pure archive or publication site unless contact is useful; - create enough seed rows to show every category and page state. Common legal site archetypes: - personal/profile: pages, timeline, works, links, contact messages; - small business/local service: services, projects/cases, team, testimonials, news, leads; - portfolio/creator/agency: works/projects, services, clients, testimonials, contact/brief requests; - artist/media: albums/releases, tracks, videos, events, press, booking; - blog/magazine/news: posts, categories, authors, tags, newsletter; - school/education/course: programs, courses, lessons, teachers, events, applications; - documentation/wiki/knowledge base: articles, sections, categories, versions, guides; - game/fan wiki: articles, characters, items, maps, quests, guides; - restaurant/hospitality: menu items, rooms/tables, events, reservations; - store/catalog/showroom: products, categories, availability, inquiries; - real estate/classified catalog: listings, categories, locations, inquiries; - construction/industrial/portfolio: objects/projects, services, equipment, news, leads; - healthcare/legal/finance informational: services, specialists, articles, appointments/inquiries, compliance-friendly copy; - nonprofit/community/religious/civic: programs, events, news, team, donations/volunteer requests; - travel/tourism/sports/club: destinations/tours/events, schedules, teams, galleries, booking/contact; - recipe/hobby/library/archive: items/entries, categories, authors/sources, guides, favorites or contact when useful. If the requested theme is not listed, choose the closest archetype, then define the CMS entities, public pages, filters, seed data, and admin screens from the user's actual subject. Do not force every site into a business lead funnel. Do not generate sites or content that facilitate illegal activity, evasion, fraud, malware, credential theft, hate/harassment, sexual exploitation, weapons harm, or other unsafe conduct. For regulated domains such as healthcare, legal, finance, alcohol, gambling, supplements, or adult-oriented content, keep the site informational and compliant, avoid unsupported claims, add appropriate disclaimers, and do not create workflows that would violate local law. ## Settings Shape (two files) The config is split. Process-wide settings live in the **root** `settings.json`; everything about ONE site lives in that site's `www//settings.json`. You author the site file and one `site{}` line; the process file already exists on the server. The root file may also carry `new_site{}` — how the `site_create` tool builds a site: `template` (`def-help` | `empty`), `guard`, `mcp`, `tls` (`off` | `acme`). It is the node's policy; the tool call takes the same four keys to deviate from it once. You never edit this block — read it to know what a site you were asked to create will start from. ### Site settings.json (`www//settings.json`) — you generate this Only site sections: `db`, `static`, `partials`, `tables`, `routes`, `errors`, `cms`, `media`. **No** `server`, `cache`, `access_log`, `soe` — those are process-wide (root file). Storage paths are fixed by the folder layout, so there are **no** `path` keys anywhere. Only `static` is required. In particular `db` may be omitted entirely: a site of pages rendered from templates needs no database, and then none is opened — no file, no channel, no threads. Such a site has no `tables`, no `views`, no forms and no `cms` (the admin keeps its users in the first database, so it is refused without one). ```json { "db": [ { "name": "main" } ], "static": { "url_prefix": "/static" }, "partials": { "_layout": { "hbs": "_layout.hbs" }, "_cms": { "hbs": "cms/_layout.hbs" } }, "cms": { "path": "/cms", "auth": { "session_ttl_minutes": 120, "cookie_name": "cms_session" }, "menu": [ { "path": "/", "title": "Dashboard", "hbs": "cms/index.hbs", "permissions": ["user"] } ] }, "tables": {}, "routes": [], "errors": { "400": { "hbs": "errors/400.hbs" }, "404": { "hbs": "errors/404.hbs" }, "413": { "hbs": "errors/413.hbs" }, "429": { "hbs": "errors/429.hbs" }, "500": { "hbs": "errors/500.hbs" } } } ``` Fixed layout inside `www//`: databases at `db/.db`, templates in `hbs/`, assets in `static/`, uploads in `media/`, seed in `seed/`, TLS material in `tls/`. Never write a `path` key — `db[].name`, `static.url_prefix`, `media.url_prefix` are all that remain. ### Root settings.json — you contribute one `site{}` line Already on the server; shown so you know where your site plugs in and which options are process-wide, not per-site: ```json { "server": { "host": "0.0.0.0", "port": 8080, "trusted_proxies": [], "tls_port": 443, "default": "example.com" }, "access_log": { "mode": "duckdb", "keep_days": 30 }, "cache": { "enabled": true, "mem_percent": 20 }, "soe": { "path": "/soe", "row_limit": "100k", "session_ttl_minutes": 60 }, "site": { "example.com": { "dir": "", "alias": [ { "domain": "www.example.com", "mode": "redirect" } ], "tls": { "acme": { "email": "admin@example.com" } } }, "blog.example.com": "blog" } } ``` - `site{}` — main domain → site. Short form `"domain": ""`, or a block `{ "dir", "alias"[], "tls" }`. One folder serves one main domain; every domain and alias across the server must be unique. - `alias[]`: `{ "domain", "mode" }` — `"redirect"` → 301 to the main domain; `"clone"` → serve the same site as-is. An alias may carry its own `tls` block (a bought cert / CDN on the old domain). - `tls` (per site): exactly one source — `{ "acme": { "email"? } }` for Let's Encrypt (covers the main domain + every alias without its own tls; `email` optional), or `{ "cert": "tls/fullchain.pem", "key": "tls/privkey.pem" }` (paths inside the site folder). No block → the site is HTTP (behind a proxy). The shared HTTPS port is `server.tls_port`; `server.port` becomes the HTTP redirect + ACME-challenge port and must differ. - `server.default` — the domain serving unknown Host / by-IP requests (may be omitted when `site{}` has a single entry). - `access_log` (process-wide): `mode` is `"duckdb"` (the default — the internal columnar `log/duckdb/access.db`, built for analytics), `"sqlite"` (the internal `log/sqlite/access.db`) or `"file"` (daily files in `log/file/`, zstd-compressed, `keep_days` retention). The db sinks are queryable through `/soe` under the reserved name `log`. Only `mode` and `keep_days` — no paths, no `db` name. - `cache`, `soe` (process-wide): see the option sections below; they are set once in the root, not per site. Key rules of the shape: - There is NO layout entity in the config. A skeleton is an ordinary partial (declare `_layout` / `_cms` in `partials`), and every page template wraps ITSELF: it opens with `{{#> _layout}}`, puts its markup into `{{#*inline "content"}} … {{/inline}}` and closes with `{{/_layout}}`. Admin templates wrap themselves in `{{#> _cms}}`. - There is NO root `views` or `auth` section: views and forms live inside their tables (`tables..views` / `tables..forms`), the auth block lives inside cms (`cms.auth`). No `cms` block → no users table, no sign-in, no admin at all. - Security limits (sign-in and form-intake rate limits, flood caps) have NO config keys — they are fixed in the engine. Never invent them. - A page route with `"path": "/"` is required; with a cms block, a menu item with `"path": "/"` (the admin index) is required too. **`soe` (root, process-wide).** Lets the sqliteonline.com frontend connect to a site's SQLite databases (each site needs `cms`; access is off by default — an admin grants it per user via the `soe` checkbox on the Users page; role `user` gets true read-only, `admin` gets write). The wire db name is namespaced `domain/dbname` — the domain picks the site, its own users authorize; a bare name means the default site; `log` is the access log. Set once in the root: ```json "soe": { "path": "/soe", "row_limit": "100k", "session_ttl_minutes": 60 } ``` **`media` (site).** File uploads from the CMS (requires `cms`). Files live in the site's `media/` under server-generated id names; the file type is detected from content (allowed: png, jpg, gif, webp, pdf — svg is not supported). Give a form a `{ "name": "", "widget": "file" }` field on a plain text column — it stores the uploaded file url; add a menu item `{ "path": "/media", "title": "Media", "hbs": "cms/media.hbs", "view": "media" }` for the file list. No `path` key — the folder is fixed: ```json "media": { "url_prefix": "/media", "max_file_size": "5m", "types": ["png", "jpg", "gif", "webp", "pdf"] } ``` **`access_log` (root, process-wide).** One request log for the whole server; the `site` column/field records which site served each request. `mode: "file"` — one file per UTC day in `log/file/`, finished days zstd-compressed, older than `keep_days` deleted. `mode: "sqlite"` — rows in the internal `log/sqlite/access.db` (columns: ts, ip, method, proto, host, path, status, dur_us, ua, referer, site; indexed by ts/ip/status/path). It is reachable through `/soe` under the reserved db name `log` and is read-only there even for admins — the audit trail cannot be cleaned over SQL; retention runs server-side. `mode: "duckdb"` (the default) — the same rows in the internal columnar `log/duckdb/access.db`: built for analytical queries over months of traffic (top pages, sources, status breakdowns), also served in `/soe` as `log` and read-only there as well (SELECT-only, enforced by the engine's own parser). Only `mode` and `keep_days` — the storage path is fixed, there is no `db` name to declare: ```json "access_log": { "mode": "duckdb", "keep_days": 30 } ``` **`cache` (root, process-wide)** — the built-in accelerator. Hot public GET responses (pages, api JSON, static, media) are served from memory, zstd-compressed for browsers that accept it; any admin/API/reload write invalidates them instantly. Cold (not yet hot) text responses are also zstd-compressed on the fly while the accelerator is on. **No block ⇒ the accelerator is on with the defaults below**; add the block only to tune it or to opt out with `"enabled": false`: ```json "cache": { "enabled": true, "mem_percent": 20, "ttl_minutes": 10, "hot_per_minute": 30, "max_entry": "512k" } ``` `mem_percent` — share of free system memory the cache may use (1–80); `ttl_minutes` — max age of an entry; `hot_per_minute` — requests to one URL before it is cached; `max_entry` — largest single response kept (≤16m). `/cms` and `/soe` are never cached. All keys are hot-reloadable. **TLS is per site, in the root `site{}` block** (not a site-file section): native HTTPS only when facing the internet directly (behind a proxy the proxy terminates TLS). Pick exactly one source — your own PEM files under the site's `tls/` folder, or `acme` for Let's Encrypt. The `acme` block covers the site's main domain + every alias without its own tls; there is no `domains` list (they come from `site{}`) and no `dir` (fixed to the site folder): ```json "site": { "example.com": { "dir": "", "tls": { "cert": "tls/fullchain.pem", "key": "tls/privkey.pem" } } } ``` ```json "site": { "example.com": { "dir": "", "alias": [ { "domain": "www.example.com", "mode": "redirect" } ], "tls": { "acme": { "email": "admin@example.com" } } } } ``` With any TLS declared, `server.port` becomes the HTTP redirect + ACME-challenge port and must differ from `server.tls_port` (the shared HTTPS port for all sites; SNI picks each site's certificate). Hard rules enforced by config validation (any failure = startup error): - `db` is optional (a site without databases serves pages only); `db[].name` must be unique, non-empty, valid SQL identifier `[A-Za-z_][A-Za-z0-9_]*`; never `log` (reserved for the access log). No `db[].path` — the file is fixed at `db/.db`; - table and column names are compared IGNORING letter case, because SQLite does: `Users`, `SyS_KeYs` and `MEDIA` are refused as system tables, names starting with `sqlite_` belong to SQLite, and two tables (or two columns of one table) that differ only in case are one object in the database; - `static.url_prefix` must start with `/`, must not equal `/`, must not contain whitespace / control chars / `..`, must not sit on or under a reserved zone (`/cms`, `/mcp`, `/static/wasm`) or overlap any user route; - `tables..col[].name` must be unique within a table (case ignored, see above); - view and form names are GLOBAL across all tables (routes and the menu reference them by bare name) — no duplicates anywhere; - a view's `select[]` must be non-empty; `users`/`media` are reserved view names (the engine's built-in admin sources); - every `{{> x}}` / `{{#> x}}` reference must be declared in `partials` (inline slot names like `content` are the only exception) and its file must exist; - `routes[].path` must start with `/`, must not contain whitespace/control, must not sit on or under a reserved zone (`/cms`, `/mcp`, `/static/wasm`); a page route `"/"` (the site index) is required; `(method, path)` pairs must be unique; - api POST routes require `form` naming an existing table form; - `cms.menu`: paths are single segments with a leading `/`, unique; exactly one item with path `"/"`; `/api`, `/login`, `/invite`, `/logout`, `/passwd` are reserved; an item's `form` needs the item's view (or `form.view` with `views{}`) and must name a form of that view's table; the users section is always admin-only — a `permissions` key there is an error; - `cms.auth.cookie_name` must be a valid HTTP token (RFC 6265); - `soe.path` (root) must start with `/`, must not sit on a reserved zone or overlap `static.url_prefix` or any route (of ANY site — /soe answers on every domain); a site's `/soe` use requires its `cms`; - `media.url_prefix` must not overlap static/soe/routes or sit on a reserved zone; `media.types` ⊆ png/jpg/gif/webp/pdf; a `file` form field needs the `media` section and a text column; `media` requires `cms`; table name `media` is reserved (no `media.path` — the folder is fixed); - `site{}` (root): every `dir` is a plain folder name (`[a-z0-9_-]`) and unique; every domain and alias across the server is unique and lowercase; a `tls` block has exactly one source (cert+key XOR acme); with any TLS, `server.tls_port` must differ from `server.port`; acme domains are real public hostnames (not IPs / localhost / wildcards); `server.default` names an existing `site{}` key (required when there is more than one); - `access_log.mode` (root) is `file`, `sqlite` or `duckdb` (the default; the old `db` is gone — the db sinks store themselves, no `db` name); `keep_days` ∈ [1, 3650]; - `cache` (root): `mem_percent` ∈ [1,80], `ttl_minutes` ≥ 1, `hot_per_minute` ≥ 1, `max_entry` ≤ 16m (validated even when `enabled` is false). Do not use obsolete fields: - top-level `hbs`; - `where`; - `op`; - `from`; - `paginate`; - `order_by`. Use `fixed_filter` for protected filters and `filter_by` for public path/query filters. ## Docker There is no separate container mode: the image CMD is plain `/cms`. With `settings.json` present it just starts the server; with the config absent the first start bootstraps the example (root config bound to `0.0.0.0:8080`, the site under `www/default/`, the one-time first-run summary on stdout — password, /cms enrollment link, MCP token). A non-empty working directory is never reset, so a recreated container never wipes volume data. What you must keep in mind when writing the config by hand: - `server.host` must be `"0.0.0.0"` in a container (bound to `127.0.0.1` the app is unreachable from outside). - Mutable state is the working directory's fixed layout — `www//` (each site's db/media/tls) and `log/` (process log). Mount that working directory as the volume; there are no configurable storage paths to point at `./data`. - `trusted_proxies` may contain CIDR entries (e.g. `"172.16.0.0/12"`), not just exact IPs. Trust the docker subnet ONLY when the app port is not published directly and requests come through a proxy container on the same network; with the port published, docker NAT masks every external client as the gateway IP — keep `trusted_proxies` at `[]`. ## Path Parameter Syntax CMSnap-LITE uses ntex routing: path parameters are written as `{name}`, **not** `:name`. ```json { "type": "page", "path": "/items/{id}", "hbs": "items/item.hbs", "view": "item_detail" } { "type": "api", "path": "/api/items/{slug}", "view": "item_detail", "format": "json" } ``` Templates read params as `{{params.id}}` / `{{params.slug}}`. View `filter_by` matches a column with the same name as the path parameter. ## Tables Allowed column types: - `id` — integer primary id, one per editable/write target table; - `int`; - `real`; - `text`; - `blob`; - `bool` (stored as integer 0/1). Per-column flag: `index: true` (build a non-unique index, required for `filter_by` columns). Rules: - Do not create table `users`; it is system-managed by CMSnap-LITE itself. - Public POST target tables need an `id` column. - A table editable in the CMS needs a form in its `forms{}` and a menu item binding it; a table shown anywhere needs a view in its `views{}`. - Do not include id fields in form `fields` — the server assigns ids. - Use text fields like `image_url`, `file_url`, `icon_url`, `media_url` for static asset paths. - Several images per record: ONE text column (e.g. `photos`) with comma-separated URLs — no extra column type. In templates the `split` helper turns it into an array at render time: `{{lookup (split row.photos) 0}}` for the hero shot, `{{#each (split row.photos)}}

{{/each}}` for a gallery. - The server casts form values by column type: `int`/`real` reject non-numeric input with 400 (empty optional input becomes NULL), `bool` accepts `on`/`true`/`1`, `blob` cannot be submitted through forms. - Boolean flags (`published`, `featured`, `available`) must use column type `bool` — a checkbox posts `on`, which fails the `int` cast. - Avoid declaring `unique: true`; uniqueness for `users.login` is the only unique index in the system and it is built-in. Entity field guidance: - musician/artist: `albums` with `title`, `release_year` or `release_date`, `genre`, `cover_image_url`, `summary`, `description`, `spotify_url`, `apple_music_url`, `youtube_url`, `featured`, `published`; optional `tracks` with `album_id`, `track_no`, `title`, `duration`, `audio_url`, `published`; optional `events` with `title`, `event_date`, `venue`, `city`, `ticket_url`, `published`; - creator/portfolio: `projects` or `works` with `category`, `client`, `year`, `summary`, `description`, `image_url`, `external_url`, `featured`, `published`; - restaurant/cafe: `menu_items` with `category`, `price`, `description`, `image_url`, `available`, `featured`; optional `events` and `reservations`; - real estate: `category`, `city`, `district`, `address`, `price`, `area_m2`, `rooms`, `floor`, `status`, `summary`, `description`, `image_url`, `featured`, `published`; - construction/portfolio: `category` or `object_type`, `city`, `address`, `status`, `area_m2`, `year`, `summary`, `description`, `image_url`, `featured`, `published`; - education/course: `courses` with `category`, `level`, `duration`, `price`, `summary`, `description`, `image_url`, `published`; optional `teachers` with `name`, `role`, `bio`, `photo_url`, `published`; optional `events`, `news`, and `applications`; - school/university: `programs`, `teachers`, `news`, `events`, `admissions` or `applications`; include fields for age/grade/level, schedule, location, contact person, and published status where relevant; - catalog/store: `category`, `price`, `sku`, `short_description`, `description`, `image_url`, `available`, `featured`, `published`; - news/blog: `category`, `summary`, `body`, `image_url`, `published`, `created_at`; optional `authors` when multiple writers matter; - documentation/knowledge base: `articles` with `category`, `summary`, `body`, `version`, `sort_order`, `published`; optional `sections`; - game wiki: `articles`, `characters`, `items`, `locations`, `quests`, `guides`; use fields such as `category`, `rarity`, `level`, `region`, `summary`, `description`, `image_url`, `published` depending on entity type; - community/nonprofit: `programs`, `events`, `news`, `volunteer_requests`, `donation_links`, `team_members`, `testimonials`; - leads/inquiries: `name`, `phone` or `email`, `message`, interest/context, `created_at`, `ip_address`, `user_agent`. Use `int` for numeric values that users filter/sort by. CMSnap-LITE views support equality filters only — for ranges, expose controlled bands such as `price_band` or `area_band` as text/select values rather than promising min/max search. Pattern: ```json "items": { "db": "main", "col": [ { "name": "id", "type": "id" }, { "name": "title", "type": "text" }, { "name": "slug", "type": "text", "index": true }, { "name": "category", "type": "text", "index": true }, { "name": "summary", "type": "text" }, { "name": "body", "type": "text" }, { "name": "image_url", "type": "text" }, { "name": "published", "type": "bool" }, { "name": "created_at", "type": "int" } ], "views": { "item_list": { "select": ["id", "title", "slug", "summary", "image_url"], "fixed_filter": { "published": 1 }, "filter_by": ["category"], "limit": 12 }, "items_admin": { "select": ["id", "title", "category", "published", "created_at"], "formats": { "created_at": "date dd.mm.yyyy" }, "limit": 50 } }, "forms": { "item_edit": { "access": "user", "fields": [ { "name": "title", "widget": "text", "required": true, "max_length": 200 }, { "name": "slug", "widget": "text", "max_length": 200 }, { "name": "category", "widget": "text", "max_length": 80 }, { "name": "summary", "widget": "textarea", "max_length": 500 }, { "name": "body", "widget": "textarea", "max_length": 20000 }, { "name": "image_url", "widget": "text", "max_length": 500 }, { "name": "published", "widget": "checkbox" } ] } } } ``` Columns referenced by `view.filter_by[]` must have `index: true` (or be the `id` column). `column type` in the schema is the literal string `"id"`, `"int"`, `"real"`, `"text"`, `"blob"`, or `"bool"`. ## CMS Admin `cms.menu` is the admin's own router — every item binds a path to an hbs template with data views, exactly like a public route binds a site page. The item with `"path": "/"` is the admin index (required, exactly one). ```json "cms": { "path": "/cms", "auth": { "session_ttl_minutes": 120, "cookie_name": "cms_session" }, "menu": [ { "path": "/", "title": "Dashboard", "hbs": "cms/index.hbs", "permissions": ["user"] }, { "path": "/items", "title": "Items", "hbs": "cms/list.hbs", "view": "items_admin", "permissions": ["user"], "form": { "name": "item_edit", "hbs": "cms/form.hbs" } }, { "path": "/leads", "title": "Leads", "hbs": "cms/list.hbs", "view": "leads_admin" }, { "path": "/media", "title": "Media", "hbs": "cms/media.hbs", "view": "media" }, { "path": "/users", "title": "Users", "hbs": "cms/users.hbs", "view": "users" } ] } ``` Menu item fields: - `path` — single segment with a leading `/`; the page opens at `/cms{path}`. `/api`, `/login`, `/invite`, `/logout`, `/passwd` reserved. - `title` — label in the nav and on index tiles. - `hbs` — the section template. Ship one generic `cms/list` and point every table section at it, or write custom templates per section. - `view` / `views` — data, same semantics as page routes. Give each section a dedicated admin view (short columns + `formats` for readable dates/prices). The built-in view names `users` and `media` serve the system tables. - `form` — the edit binding: `{ "name": "item_edit", "hbs": "cms/form.hbs" }`. `name` is a form of the view's table; `hbs` renders the row page (`/cms/{path}/new`, `/cms/{path}/{id}`). No `form` → a read-only section (right for leads/feedback). With `views{}` add `form.view`. - `permissions` — roles that can see and open the section (`admin` always can; omitted = admin only). The users section is admin-only regardless — do not put `permissions` there (validation error). Optional `cms.guard` — hide the admin behind a device cookie. With the gate on, the whole /cms zone (login included) answers the generic 404 to any browser without an enrolled device: the admin is invisible, not just locked. Do NOT hand-write `guard` entries — the running server owns the list; the site owner manages it from the CLI (`cms guard add ` prints a one-time enrollment link, `guard list` / `guard remove`; every command takes `--site domain` to manage a named site of the map). Leave `guard` out of generated configs unless the user explicitly asks to hide the admin; if they do, emit `"guard": []` (gate on, no devices) and tell them to run `cms guard add` for the first device. It is a curtain over, not a replacement for, the OPAQUE sign-in. Form field widgets (in `tables..forms..fields`): - `text` — single-line ``; - `textarea`; - `number` — ``; - `checkbox` — boolean (posts `0`/`1` via the hidden-input pattern); - `file` — media upload (needs the `media` section; stores the url in a text column). There is **no built-in `select` widget**. To present a fixed-options field, use `widget: "text"` and render a `

``` ## Session Auth uses an HTTP-only cookie set by `/cms/login/finish`. Rules: - JS must not read or store session tokens; - do not use `localStorage` / `sessionStorage` / query strings for sessions; - `fetch` calls to `/cms/*` use `credentials: 'same-origin'`; - logout posts to `/cms/logout`, then redirects to `/cms/login`. ```javascript await fetch('/cms/logout', { method: 'POST', credentials: 'same-origin' }); window.location.assign('/cms/login'); ``` ## Auth JS Include when CMS login / invite / password flows exist: ```text static/js/cms-login.js static/js/cms-invite.js static/js/cms-user-password.js ``` CMSnap-LITE serves the WASM runtime from fixed built-in paths. Do not generate, copy, rename, fingerprint, or move these files in site output: ```text /static/wasm/cmsnap_wasm.js /static/wasm/cmsnap_wasm_bg.wasm ``` Always import from `/static/wasm/cmsnap_wasm.js`. Exports available: - `init` (default) — initializes the WASM module; - `login_start(password) → { client_msg1, state }`; - `login_finish(state, server_msg1) → client_msg2`; - `register_start(password) → { client_msg1, state }`; - `register_finish(state, server_msg1) → client_msg2`; - `passwd_start(password) → { client_msg1, state }` (alias of register_start); - `passwd_finish(state, server_msg1) → client_msg2` (alias of register_finish). `state` and `client_msg*` are base64url strings; pass them to the server unchanged inside the JSON payloads documented above. ### Login JS ```javascript import init, { login_start, login_finish } from '/static/wasm/cmsnap_wasm.js'; async function postJson(url, payload) { const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'same-origin', body: JSON.stringify(payload), }); const body = await r.json().catch(() => ({})); if (!r.ok) throw new Error(body.error || `request_failed_${r.status}`); return body; } export async function cmsLogin(login, password) { await init(); const c1 = login_start(password); const s1 = await postJson('/cms/login/start', { login, client_msg1: c1.client_msg1, }); const c2 = login_finish(c1.state, s1.server_msg1); await postJson('/cms/login/finish', { login, client_msg2: c2, state: s1.state, }); } ``` Do not send `password` or `user_id` to the server. ### Invite JS (set password from invite link) ```javascript import init, { register_start, register_finish } from '/static/wasm/cmsnap_wasm.js'; async function postJson(url, payload) { /* same helper as above */ } export async function setInvitePassword(token, password) { await init(); const c1 = register_start(password); const s1 = await postJson('/cms/invite/start', { token, client_msg1: c1.client_msg1, }); const c2 = register_finish(c1.state, s1.server_msg1); await postJson('/cms/invite/finish', { token, client_msg2: c2 }); } ``` The `token` is read from `URLSearchParams` on `/cms/invite?token=...`. The server already knows the user's `login` and `role` — they are not sent in the body. ### Password change JS (self or admin) ```javascript import init, { passwd_start, passwd_finish } from '/static/wasm/cmsnap_wasm.js'; async function postJson(url, payload) { /* same helper as above */ } export async function changePassword(newPassword, targetUserId /* optional */) { await init(); const c1 = passwd_start(newPassword); const startBody = { client_msg1: c1.client_msg1 }; if (typeof targetUserId === 'number') startBody.target_user_id = targetUserId; const s1 = await postJson('/cms/passwd/start', startBody); const c2 = passwd_finish(c1.state, s1.server_msg1); await postJson('/cms/passwd/finish', { client_msg2: c2, state: s1.state }); } ``` `target_user_id` is allowed only for `admin` sessions; otherwise the server returns 403 `forbidden`. ## Static and Seed Use: ```text static/css/site.css static/js/site.js static/img/ ``` Rules: - asset URLs start with `/static/`; - include every image referenced by templates, or a real placeholder asset committed to `static/img/`; - store media paths as text fields; - uploads are **admin-only and built in**: a form field with `"widget": "file"` posts to `/cms/api/media`, which verifies the type by content, stores the file under `media/` and returns its URL — keep that URL in a text column; - public forms accept text fields only: a visitor cannot upload anything, and no upload endpoint of your own may be invented for the public side; - do not output `static/wasm/`; auth WASM/JS is served by CMSnap-LITE itself. Seed: - `settings.json` defines schema, **not** content rows; - create `seed/.json` for initial content; - seed JSON must be raw valid JSON, not Markdown fenced code; - `seed/README.md` must match actual seed files. ## Design Requirements Match the domain: - business: credible, direct, conversion-focused; - SaaS/admin: dense, calm, efficient; - musician/artist/media: visual, editorial, release-focused; - restaurant/hospitality: visual and warm; - school/education: trustworthy, parent/student-oriented; - blog/publication: reading-first; - game wiki/knowledge base: dense, taxonomy-first, cross-linked; - healthcare/legal/finance: restrained and trustworthy; - portfolio: distinctive but readable; - store/catalog: product-first and scannable. Required: - mobile-first responsive layout; - clear navigation; - real content, not placeholders; - useful empty states (`{{else}}` branch in every `{{#each}}`); - good labels and visible success/error feedback; - no overlap or clipped text. Accessibility and performance (these reach a clean Lighthouse 100 on mobile — the reference site does): - body text ≥ 4.5:1 against its background, large text ≥ 3:1; the common miss is muted grey text on a tinted near-white — darken it until it passes, do not keep light grey "for elegance"; - links embedded in a paragraph carry an underline (colour alone is not enough); nav and buttons are exempt; - a `.skip` link to `#main` as the first focusable element, and a visible `:focus-visible` outline on links, buttons, and inputs; - `color-scheme` on `:root` (and per theme) plus a `theme-color` meta for each scheme, so native controls and the mobile address bar match; - every `` has `alt` (empty `alt=""` if decorative) and, for non-hero images, `loading="lazy"`; - system-font stack, no web-font download; one small CSS file, JS deferred, no CDN — that is what keeps the performance score at 100. Admin design requirements: - CMS screens are work tools: compact tables, clear actions, stable form layout; - form controls must match the schema widgets exactly; - destructive actions are visually separate from save actions; - admin copy must be direct and localized. ## Common Mistakes - using `:id` in route paths (must be `{id}`); - POSTing to `/auth/login/*`, `/auth/logout`, `/auth/password/*` — those paths do not exist; everything is under `/cms/*`; - inventing `/cms/users/new`, `/cms/users/{id}/password`, `/cms/me/password` page routes — only `/cms/users` (HTML) and `/cms/api/users[/{id}]` (JSON) + `/cms/passwd/{start,finish}` exist; - sending `password` or `user_id` to the server in any flow; - creating a `users` table; - declaring widget `select` and expecting CMSnap-LITE to render a `