# Lesstruct — Full Documentation

> Documentation site for Lesstruct.

> This file concatenates every documentation page on the site in section order.
> For a slim index, see `/llms.txt`. For per-page fetching, use each page's `/<path>/index.md` URL.
## Section: Docs

### Project Context

Source: [/docs/project-context/index.html](/docs/project-context/index.html)
Reference page for Project Context.


# Project Context for AI Agents

_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._

---

## Technology Stack & Versions

### Backend (Go)
- **Go** 1.26 — module: `github.com/aristorinjuang/lesstruct`
- **Chi** 5.2.5 — HTTP router; **httprate** 0.15.0 — per-route rate limiting
- **Databases** (driver selected via `DB_DRIVER` env: `sqlite` | `postgres` | `mysql`):
  - **SQLite** (modernc.org/sqlite v1.50.0) — default, embedded
  - **PostgreSQL** (jackc/pgx/v5 v5.10.0)
  - **MySQL** (go-sql-driver/mysql v1.9.2) — DSN MUST contain `parseTime=true` AND `multiStatements=true`
- **golang-migrate** 4.19.1 — DB migrations via `iofs` embedded filesystem, per-driver subdirs under `internal/database/migrations/{sqlite,postgresql,mysql}/`
- **BurntSushi/toml** 1.6.0 — `config.toml` parsing
- **joho/godotenv** 1.5.1 — `.env` loader (called from `config.Load()`)
- **fsnotify** 1.10.0 — config file hot-reload
- **golang-jwt** 5.3.1 — JWT auth (browser admin realm)
- **bluemonday** 1.0.27 — HTML sanitization
- **goldmark** 1.8.2 — Markdown parser (Markdown → TipTap JSON converter in `internal/content/markdown/`)
- **wazero** 1.11.0 — WebAssembly runtime (plugin system)
- **google.golang.org/genai** 1.59.0 — Google Imagen image generation
- **openai/openai-go** 1.12.0 — text generation (OpenAI-compatible APIs via `AI_TEXT_GENERATION_BASE_URL`)
- **deepteams/webp** 1.2.1 + **golang.org/x/image** 0.39.0 — image transcoding for media uploads
- **spf13/cobra** 1.10.2 — CLI framework (`cmd/lesstruct-cli`)
- **golang.org/x/crypto** 0.51.0, **golang.org/x/net** 0.55.0
- **stretchr/testify** 1.11.1 — test assertions
- **mockery** — mock generation (`make mock`)
- **govulncheck** — vulnerability scanning (`make vulncheck`)
- **golangci-lint** v2.11.4 — linter (`make lint`); config in `.golangci.yml`

### CLI (`cmd/lesstruct-cli`)
- Thin Cobra-based client over `/api/v1`; imports **no server internals**
- Subcommands: `content` (create/get/list/update/delete/publish/unpublish), `media` (upload/get/list), `config`
- Auth via `--api-key` flag, `LESSTRUCT_API_KEY` env, or config file (precedence in that order)
- Output mode: `--output text|json` (default `text`)
- Built via `make build-cli` → `bin/lesstruct-cli`; integration tests via `make test-cli` (tag `integration`)

### Admin Panel (Frontend) — `web/admin/`
- **Vue 3** 3.5.31 — Composition API + `<script setup>` only
- **TypeScript** 6.0 — strict mode
- **Vite** 8 — build tool; base: `/admin/`, output to `internal/api/static/admin/`
- **Pinia** 3.0.4 — state management
- **Vue Router** 5.0.4
- **TipTap** 3.22+ (Vue 3) — rich text editor (starter-kit + code-block-lowlight, emoji, image, link, mathematics, placeholder, table, table-cell, table-header, table-row, text-align, underline)
- **Headless UI** 1.7.23 — accessible primitives
- **KaTeX** 0.16.47 — math rendering
- **lowlight** 3.3.0 — syntax highlighting
- **Vitest** 4.1.2 + jsdom 29 — unit tests
- **Prettier** 3.8.1 + ESLint 10 + Oxlint ~1.57 — linting/formatting
- Node engine: `^20.19.0 || >=22.12.0`

### Content Theme
- Go `html/template` — server-rendered content site via `internal/api/template/` (layouts/pages) and `internal/api/contentpage/` (data assembly)
- Theme overrides via `THEME_DIR` env var or theme plugin architecture
- Default theme CSS minified via `make css` (tdewolff/minify)

### Architecture
- **Domain-Driven Design**: `internal/domain/<name>/` holds business logic, types, sentinel errors, interfaces. Current domains: `apikey`, `auth`, `content`, `customfield`, `dashboard`, `media`, `plugin`, `posttype`, `profilepicture`, `sanitize`, `seo`, `textgen`, `thumbnail`, `user`
- **Repository pattern**: interfaces in domain, per-driver implementations in `internal/repository/{sqlite,mysql,postgresql}/`. Shared cross-driver helpers (e.g., `soft_delete.go`, `user.go`) live directly in `internal/repository/`
- **HTTP handlers**: `internal/api/handlers/` (browser admin realm) and `internal/api/handlers/agent/` (Bearer API-key realm, `/api/v1`); routes registered in `internal/api/routes/routes.go`
- **Auth realms**: two co-exist on shared paths and are dispatched by `dispatchByAuth()` based on the `Authorization` header prefix (`Bearer lesstruct_…` = agent realm, JWT cookie or other Bearer = browser realm). Each chain carries its own auth middleware
- **Middleware** (`internal/api/middleware/`): `auth` (JWT), `apikey` (Bearer API key), `admin`, `commentator`, `cors`, `csrf`, `nocookie`, `ratelimit` (via httprate)
- **Response envelope** (`internal/api/response/`): `{"data": ..., "error": {...}, "meta": {...}}`. Lists use `SuccessList()` which uses a dedicated `listResponse` type WITHOUT `omitempty` on `data` so empty lists serialize as `"data":[]`
- **Plugin system**: wazero WASM runtime in `internal/plugin/` with hook execution (`before_save`, `after_save`, etc.). Subpackages: `bootstrap`, `capability`, `devmode`, `hostfunctions`, `loader`, `registry`, `runtime`
- **Content pipeline**: `internal/content/` holds format converters — `tiptap/` (canonical), `markdown/` (Markdown→TipTap via goldmark), `wordpress/` (WordPress importer)
- **Config**: `.env` + env vars loaded via `internal/config/config.go` (`Config` struct, `Load()`); user-facing `config.toml` in project root loaded at startup with hot-reload via fsnotify; post types/languages/thumbnails schemas in `internal/config/`
- **Migrations**: numbered `.up.sql`/`.down.sql` pairs in `internal/database/migrations/{driver}/`, embedded via `embed.go`

---

## Critical Implementation Rules

### Language-Specific Rules

#### Go
- Use `any`, never `interface{}`
- Never use `panic()` — use `log.Fatalf()`/`log.Panicf()` only in `main.go` (and only in `cmd/lesstruct-cli/main.go` for the CLI)
- Private structs/functions before public ones in every file
- Constructors (`New*`) go AFTER all methods on the struct
- Multi-line function arguments when ≥3 params (one arg per line)
- Always use constants for HTTP methods: `http.MethodDelete`, not `"DELETE"`
- `internal/config/` holds env-based config; `config.toml` holds user-facing config
- Domain errors are sentinel errors (`var ErrSomething = errors.New(...)`) in the domain package
- Handlers map domain errors to HTTP responses via `handleContentError()` pattern (browser realm) or the agent error mapper in `internal/api/handlers/agent/errors.go` (agent realm)
- JSON responses use the envelope from `internal/api/response/` — call `Success`, `Error`, or `SuccessList`; never hand-roll the envelope
- Cross-driver repository code must work for SQLite, PostgreSQL, AND MySQL — beware driver-specific SQL (placeholders, `RETURNING`, time handling). Use the per-driver subpackage when behavior must diverge

#### TypeScript/Vue
- Use `<script setup lang="ts">` exclusively
- Use `defineProps<T>()`, `defineEmits<T>()` typed interfaces
- `composables/` for reusable stateful logic (e.g., `useAuth`)
- `stores/` for Pinia stores, organized by domain under `stores/domain/` and UI under `stores/ui/`
- `types/` for shared TypeScript interfaces
- TipTap content is always a JSON string (`"{\"type\":\"doc\",\"content\":[...]}"`)

### Framework-Specific Rules

#### Backend (Chi + Domain-Driven Design)
- **No framework**: Chi is a lightweight router, not a framework — handlers receive `http.ResponseWriter, *http.Request`
- Routes registered in `internal/api/routes/routes.go`, grouped by resource and by auth realm
- Two auth realms co-own some `/api/v1/media` paths — when adding routes that may collide, register via `dispatchByAuth(agentChain, browserChain)` rather than duplicating the path
- Agent realm (`/api/v1/*`) requires Bearer `lesstruct_<keyID>_<secret>` tokens verified by `APIKeyAuthMiddleware`; identity is injected into context using the SAME context keys (`UserIDKey`, `UsernameKey`, `RoleKey`) as the JWT middleware so downstream code is auth-agnostic
- Content services require a `HookExecutor` — always pass plugin hooks through, don't bypass
- Custom field validation flows through `content.Service.validateCustomFields()` — never call `validateFieldValue()` directly from handlers
- Post types loaded from `config.toml` at startup via `internal/config/posttypes.go`; reloaded on file change via fsnotify
- SEO auto-extraction: `ExtractPlainText()` and `ExtractImageURL()` consume TipTap JSON from content
- Markdown bodies on the agent create surface are converted to canonical TipTap JSON via `internal/content/markdown` — raw Markdown is NEVER persisted
- Rate limits configurable per realm via `RATE_LIMIT_{AUTH,API,PUBLIC}_PER_MINUTE`; toggle via `RATE_LIMIT_ENABLED`

#### Frontend (Vue 3 + Pinia)
- **Atomic design**: `atoms/` → `molecules/` → `organisms/` → `views/` under `web/admin/src/components/` and `web/admin/src/views/`
- Content editor: `ContentEditor.vue` is the single organism for create + edit (shared component, not separate views)
- Custom field rendering: `CustomFieldRenderer.vue` in molecules handles all field types
- Media upload: `MediaPanel.vue` organism, opened as a slideover from `ContentEditor`
- SEO settings are collapsible within `ContentEditor` (`isSEOSettingsOpen`)
- Store actions (e.g., `contentStore.create()`) make API calls; components only call store actions
- Toast notifications via `Toast.vue` molecule with `displayToast(message, type)` pattern


---

### Lesstruct API Reference (`/api/v1`)

Source: [/docs/api-reference/index.html](/docs/api-reference/index.html)
Reference page for Lesstruct API Reference (`/api/v1`).

# Lesstruct API Reference (`/api/v1`)

Lesstruct exposes a versioned, API-key-authenticated REST API at `/api/v1` for creating, reading, updating, and deleting **Content** and **Media**. It is designed for programmatic consumers — the `lesstruct-cli`, MCP servers, AI agents (Claude Code, OpenCode, Hermes, …), and human integrators — and accepts Markdown as a first-class authoring format.

This reference documents the **implemented** surface. For the design intent, see `_bmad-output/planning-artifacts/architecture-ai-cli.md`.

## Overview

- **Base URL.** The API is served from the same origin as your Lesstruct server, under the `/api/v1` prefix. Example: `https://your-lesstruct.example/api/v1/content`.
- **Transport.** HTTPS in production. All request and response bodies are `application/json`, except media upload which is `multipart/form-data`.
- **Authentication.** Every `/api/v1` request carries an API key as a Bearer token (see [Authentication](#authentication)). `/api/v1` is **Bearer-only** — there is no cookie/JWT fallback.
- **Versioning.** The `v1` URL segment pins the contract. Breaking changes ship under a new version segment.
- **JSON conventions.** Keys are `camelCase`. Strings are UTF-8. Timestamps are ISO 8601 strings.

## Authentication

Requests authenticate with a personal API key in the `Authorization` header:

```http
Authorization: Bearer lesstruct_a1b2c3d4e5f6_<secret>
```

The key string has the format `lesstruct_<keyID>_<secret>`:

- `lesstruct_` — a recognizable prefix (like GitHub's `ghp_`), so keys are easy to detect in logs and scanners.
- `keyID` — 12 hex characters (e.g. `a1b2c3d4e5f6`). This is the public, safely-displayable identifier.
- `secret` — 32 hex characters (≥128 bits). It is stored only as a salted hash and is **never** logged.

### Creating keys

API keys are created in the admin panel under **Profile → API Keys** (this is a browser/JWT action, not part of `/api/v1`). When you create a key:

1. You give it a human-readable **name** (e.g. "Claude Code").
2. The **full key string** is shown **exactly once**, with a copy button and a "you won't see this again" warning. Save it immediately.
3. Thereafter, the key is displayed only as its prefix (`lesstruct_a1b2c3d4e5f6••••`).

You can **revoke** a key at any time from the same view; revoked keys immediately stop authenticating.

### Logging hygiene

Only the `keyID` is ever logged — the secret and the full key string are redacted in all log output. Integrators should apply the same redaction in their own logs.

### Authorization

A key acts **as the user who created it**. It inherits that user's role and permissions, and every operation is scoped to that user's own resources (you can only list/read your own content and media, unless your role is Admin). Lesstruct's existing role-based access control governs every request unchanged.

## Conventions

### Response envelope

All responses use a uniform envelope with three optional top-level keys: `data`, `error`, and `meta`.

**Single resource** (create / get / update, and single media get):

```json
{
  "data": { "content": { "id": 7, "title": "Hello", "..." : "..." } }
}
```

**List** (content list, media list) — `data` is a **bare array**, not wrapped in an object:

```json
{
  "data": [ { "id": 7, "..." : "..." }, { "id": 6, "..." : "..." } ],
  "meta": { "pagination": { "nextCursor": "Ng", "hasMore": true } }
}
```

> **Watch the asymmetry.** A single content item is `{"data":{"content":{…}}}` (wrapped under `content`), but a list is `{"data":[…]}` (bare array). This is intentional and is the most common source of client bugs. Empty lists render as `"data":[]` (the key is always present).

**Error:**

```json
{
  "error": { "code": "VALIDATION_ERROR", "message": "title is required and must be between 1 and 200 characters" }
}
```

### Pagination

List endpoints use **cursor** (keyset) pagination, which is stable across inserts and deletes (unlike offset pagination).

| Parameter | Default | Range | Notes |
|---|---|---|---|
| `limit` | `50` | `1`–`100` | Missing/invalid/negative → `50`; over `100` → clamped to `100`. |
| `cursor` | _(omit)_ | opaque | Omit for the first page. Pass the `nextCursor` from the previous response. |

The cursor is an opaque, unpadded base64url token encoding the id of the last item on the current page. Do not construct or inspect it — treat it as opaque and echo it back. An invalid cursor returns `400 VALIDATION_ERROR "Invalid cursor"`.

The response includes `meta.pagination`:

- `nextCursor` — present **only** when `hasMore` is `true`. Pass it as the next request's `cursor`.
- `hasMore` — whether another page exists.

```bash
# First page
curl -H "Authorization: Bearer lesstruct_a1b2c3d4e5f6_<secret>" \
  "https://your-lesstruct.example/api/v1/content?limit=50"

# Next page (use the nextCursor from the previous response)
curl -H "Authorization: Bearer lesstruct_<...>" \
  "https://your-lesstruct.example/api/v1/content?limit=50&cursor=Ng"
```

Lists are **scoped to the caller's own resources** — an API key cannot enumerate another user's content or media (Admin-role keys excepted, per the role inheritance above).

### Visibility (no-enumeration model)

To avoid disclosing which resources exist, operations on a resource you don't own (and aren't an Admin for) return `404 NOT_FOUND` — **never** `403 FORBIDDEN`:

- **Drafts** are readable only by their owner.
- **Published** content is readable by any authenticated key.
- `GET`/`PUT`/`DELETE` on a resource you don't own → `404 NOT_FOUND` (existence is not disclosed).

## Content

The Content resource lets you publish posts, pages, and other content types over the API. Content is stored as canonical **Tiptap JSON**; you may submit Markdown and let the server convert it (see [Authoring in Markdown](#authoring-in-markdown)).

### Content object

```json
{
  "id": 7,
  "title": "Hello world",
  "slug": "hello-world",
  "body": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",...}]}",
  "status": "published",
  "postType": "post",
  "language": "en",
  "tags": ["intro", "demo"],
  "customFields": { "subtitle": "My first post" },
  "author": "Ari",
  "createdAt": "2026-06-15T10:00:00Z",
  "updatedAt": "2026-06-15T10:00:00Z"
}
```

| Field | Type | Notes |
|---|---|---|
| `id` | int | Stable identifier. |
| `title` | string | 1–200 chars. |
| `slug` | string | URL slug. Auto-generated from the title; the `slug` you send in create/update is **not honored**. |
| `body` | string | The canonical content — a Tiptap JSON document string. |
| `status` | string | `"draft"` or `"published"`. |
| `postType` | string | Content type (e.g. `post`, `page`), from your configured post types. |
| `language` | string | Language code. Settable on create/update; must be in the server's configured `languages` list, else 400 `ErrInvalidLanguage`. |
| `tags` | string[] | Tags. Settable on create/update; normalized server-side (lowercased, trimmed, deduped, length-bounded) via `ValidateTags`. |
| `customFields` | object | TOML-defined, server-validated custom-field values. |
| `author` | string | Display name of the author. Read-only — derived from the API key's user. |
| `createdAt` / `updatedAt` | string | ISO 8601 timestamps. |

### Create content

```http
POST /api/v1/content
```

**Request body:**

```json
{
  "title": "Hello world",
  "body": "# Hello\n\nThis is my first post.",
  "format": "markdown",
  "postType": "post",
  "customFields": { "subtitle": "My first post" },
  "isPublished": true
}
```

| Field | Required | Notes |
|---|---|---|
| `title` | yes | 1–200 chars. |
| `body` | yes | The content. With `format: markdown` it is Markdown (converted server-side to Tiptap); with `format: tiptap` (the default) it must be a valid Tiptap JSON document string. |
| `format` | no | `"markdown"` or `"tiptap"`. Defaults to `"tiptap"`. Matched case-insensitively after trimming leading/trailing whitespace. |
| `postType` | no | Content type. |
| `tags` | no | Array of tag strings. Server normalizes (trim, lowercase, dedupe, length-bound) via `ValidateTags`; an invalid tag returns 400 `VALIDATION_ERROR`. |
| `language` | no | Language code (e.g. `"en"`, `"id"`). Must be in the server's configured languages list (`config.toml` `[languages]`); an unknown code returns 400 `VALIDATION_ERROR` (`ErrInvalidLanguage`). |
| `slug` | no | Accepted for API stability but **not honored** — the server auto-generates the slug from the title. |
| `customFields` | no | Custom-field values, validated through the same path the admin uses. |
| `isPublished` | no | `true` → `"published"`; `false`/omitted → `"draft"`. |

**Response** `200 OK`:

```json
{ "data": { "content": { "id": 7, "title": "Hello world", "slug": "hello-world", "..." : "..." } } }
```

> Create returns `200 OK` (not `201 Created`) by design — consistent with the other `/api/v1` success responses.

Errors: `400 VALIDATION_ERROR` (bad/missing fields, invalid Tiptap, custom-field validation, or Markdown that converts to Tiptap the server rejects — see [Authoring in Markdown](#authoring-in-markdown)).

### Get content

```http
GET /api/v1/content/{id}
```

**Response** `200 OK`: `{"data":{"content":{…}}}`.

Returns `404 NOT_FOUND` if the content does not exist **or** you are not allowed to read it (a draft owned by someone else). Published content is readable by any authenticated key.

### List content

```http
GET /api/v1/content?limit=50&cursor=<cursor>&tag=foo&tag=bar&language=en&status=draft&post_type=post&author=alice&search=golang
```

Returns the caller's own content (drafts and published), newest-first, using [cursor pagination](#pagination). All filters AND together with the cursor; pass multiple `tag` values to AND-of-tags (the post must carry every tag).

Query parameters:

| Param        | Type                | Notes |
|--------------|---------------------|-------|
| `limit`      | int                 | Default 50, max 100. |
| `cursor`     | string              | Opaque token from a previous list call. |
| `tag`        | string (repeatable) | AND-of-tags — the post must carry every tag. |
| `language`   | string              | Filter by language code. |
| `status`     | `draft` \| `published` | Unknown values return `400 VALIDATION_ERROR`. |
| `post_type`  | string              | Filter by post type. |
| `author`     | string              | **Admin only.** Non-admins receive `403 FORBIDDEN`. |
| `search`     | string              | Title / meta-description substring (case-insensitive). Min length 2; shorter values are dropped. |

**Response** `200 OK`:

```json
{
  "data": [ { "id": 7, "..." : "..." }, { "id": 6, "..." : "..." } ],
  "meta": { "pagination": { "nextCursor": "Ng", "hasMore": true } }
}
```

### Update content

```http
PUT /api/v1/content/{id}
```

Accepts `title`, `body`, `format`, `postType`, `customFields`, `isPublished`, `tags`, and `language`. SEO metadata (`metaDescription`, `ogTitle`, `ogDescription`), `allowComments`, and `translationGroupId` are **preserved from the existing item** and cannot be changed via this endpoint — any values you send for them are ignored. `slug` is accepted for API stability but not honored (the server auto-generates the slug from the title). `format: markdown` converts the body to Tiptap before storing.

**Response** `200 OK`: `{"data":{"content":{…}}}` with the updated item.

Returns `404 NOT_FOUND` if the item does not exist or you are not its owner (and not Admin) — existence is not disclosed (see [Visibility](#visibility-no-enumeration-model)). Errors: `400 VALIDATION_ERROR`.

### Delete content

```http
DELETE /api/v1/content/{id}
```

**Response** `204 No Content` (empty body) on success. A subsequent `GET` returns `404 NOT_FOUND`.

Returns `404 NOT_FOUND` if the item does not exist or you are not its owner (and not Admin).

### Publish content

```http
POST /api/v1/content/{id}/publish
```

Standalone status-toggle verb. No request body. On the **draft → published** transition the server auto-generates SEO metadata (when the SEO service is configured) and fires the `AfterPublish` plugin hook. Publishing an already-published post is a **200 no-op**: the row is persisted unchanged, no hook fires, no SEO is regenerated.

**Response** `200 OK`: `{"data":{"content":{…}}}` with the item now in `status: "published"`.

Returns `404 NOT_FOUND` if the item does not exist or you are not its owner (and not Admin) — existence is not disclosed. Errors: `400 VALIDATION_ERROR` (bad id).

```bash
curl -X POST -H "Authorization: Bearer lesstruct_a1b2c3d4e5f6_<secret>" \
  "https://your-lesstruct.example/api/v1/content/7/publish"
```

### Unpublish content

```http
POST /api/v1/content/{id}/unpublish
```

Standalone status-toggle verb. No request body. Sets `status: "draft"`. Never fires the `AfterPublish` hook (the hook is wired to the draft → published edge only). Unpublishing an already-draft post is a **200 no-op**.

**Response** `200 OK`: `{"data":{"content":{…}}}` with the item now in `status: "draft"`.

Returns `404 NOT_FOUND` if the item does not exist or you are not its owner (and not Admin). Errors: `400 VALIDATION_ERROR` (bad id).

```bash
curl -X POST -H "Authorization: Bearer lesstruct_a1b2c3d4e5f6_<secret>" \
  "https://your-lesstruct.example/api/v1/content/7/unpublish"
```

## Media

Upload, retrieve, and list media (images). Media is deduplicated by content hash and stored with generated variants (e.g. WebP + thumbnails).

### Media object

```json
{
  "id": 12,
  "filename": "a1b2c3d4.webp",
  "originalFilename": "photo.jpg",
  "mimeType": "image/jpeg",
  "fileSize": 204800,
  "width": 1200,
  "height": 800,
  "altText": "A scenic mountain view",
  "isWebp": true,
  "hash": "a1b2c3d4e5f6...",
  "url": "https://your-lesstruct.example/uploads/media/a1b2c3d4.webp",
  "variants": {
    "thumbnail": { "url": "https://your-lesstruct.example/uploads/media/a1b2c3d4-200.webp", "width": 200 }
  },
  "createdAt": "2026-06-15T10:00:00Z",
  "updatedAt": "2026-06-15T10:00:00Z"
}
```

| Field | Type | Notes |
|---|---|---|
| `id` | int | Stable identifier. |
| `filename` / `originalFilename` | string | Stored / uploaded filename. |
| `mimeType` | string | Source MIME type (JPG/PNG/GIF/WebP). |
| `fileSize` | int | Bytes. |
| `width` / `height` | int | Pixel dimensions. |
| `altText` | string | Accessibility text. |
| `isWebp` | bool | Whether the primary stored file is WebP. (Note the key `isWebp`, not `isWebP`.) |
| `hash` | string | Content hash used for dedup. |
| `url` | string | The absolute URL to reference this media in content (e.g. `https://your-lesstruct.example/uploads/media/<file>`). |
| `variants` | object | Map of variant name → `{ "url", "width" }` (e.g. `thumbnail`). |
| `createdAt` / `updatedAt` | string | ISO 8601 timestamps. |

### Upload media

```http
POST /api/v1/media
Content-Type: multipart/form-data
```

The body is `multipart/form-data` with:

- **`file`** (required) — the image part (JPG, PNG, GIF, or WebP). A missing `file` part returns `400 VALIDATION_ERROR "file part is required"`.
- **`metadata`** — a JSON part: `{"altText":"A scenic mountain view"}`. A non-empty **`altText` is required** for accessibility. The part is optional only in the multipart sense: omitting it (or sending empty `altText`) causes the service to reject the upload with `400 VALIDATION_ERROR`. **Always send it.**

```bash
curl -H "Authorization: Bearer lesstruct_a1b2c3d4e5f6_<secret>" \
  -F "file=@photo.jpg" \
  -F 'metadata={"altText":"A scenic mountain view"}' \
  "https://your-lesstruct.example/api/v1/media"
```

**Response** `200 OK`: `{"data":{"media":{…}}}`.

| Status | Code | When |
|---|---|---|
| `200` | — | Uploaded; a new media item was created and stored. |
| `400` | `VALIDATION_ERROR` | Missing `file` part; unsupported/oversized file; empty `altText`. |
| `409` | `CONFLICT` | A file with the same content hash already exists. The upload is not stored; upload a different file or use the existing media's `url`. |

> **Duplicate handling.** The API returns `409 CONFLICT` for a duplicate upload (rather than returning the existing item, as the admin panel does). This keeps the contract honest: the upload was not stored.

### Get media

```http
GET /api/v1/media/{id}
```

**Response** `200 OK`: `{"data":{"media":{…}}}`.

Returns `404 NOT_FOUND` if the media does not exist or you are not its owner (and not Admin) — existence is not disclosed.

### List media

```http
GET /api/v1/media?limit=50&cursor=<cursor>
```

Returns the caller's own media, newest-first, using [cursor pagination](#pagination). Same envelope as the [content list](#list-content): a bare `data` array plus `meta.pagination`.

> **Shared path note.** `GET /api/v1/media` and `GET /api/v1/media/{id}` are shared with the browser admin panel; the server dispatches to the agent handler when the request presents a `lesstruct_`-prefixed Bearer token, and to the browser handler otherwise. For agent clients this is transparent — always send the Bearer key. `POST /api/v1/media` (upload) is agent/Bearer-only.

## Errors

Errors use the envelope's `error` object: `{"error":{"code":"…","message":"…"}}`. (A `details` field is reserved on the object but is not currently populated by the `/api/v1` handlers.)

### Error catalog

| HTTP | Code | Meaning | Emitted by |
|---|---|---|---|
| `401` | `UNAUTHORIZED` | No / undecodable identity. | handler / middleware |
| `401` | `INVALID_API_KEY` | The key is malformed or unknown. | auth middleware |
| `401` | `REVOKED_KEY` | The key has been revoked. | auth middleware |
| `401` | `EXPIRED_KEY` | The key has expired. | auth middleware |
| `400` | `VALIDATION_ERROR` | Bad request body, invalid Tiptap, custom-field validation, invalid cursor, invalid id, missing `file` part, bad alt text, etc. | handler |
| `404` | `NOT_FOUND` | Resource does not exist, or you don't own it (and aren't Admin) — existence is not disclosed. | handler |
| `403` | `FORBIDDEN` | Reserved for service-layer rejections. Not the response for resources you don't own — those return `404` (no-enumeration). Rarely emitted on the agent surface. | handler |
| `409` | `CONFLICT` | Duplicate media upload. | media handler |
| `429` | `RATE_LIMITED` | You have exceeded the per-key rate limit. | rate-limit middleware |
| `500` | `INTERNAL_ERROR` | Unexpected server error. | handler |

### No-enumeration

Resource existence is never disclosed: a request for a resource you don't own (and aren't Admin for) returns `404 NOT_FOUND`, not `403 FORBIDDEN`. Treat `404` on `GET`/`PUT`/`DELETE` as "not found **or** not yours".

## Authoring in Markdown

Set `format: "markdown"` on create/update to author content in Markdown. The server parses it with [goldmark](https://github.com/yuin/goldmark) (core CommonMark) and converts it to canonical **Tiptap JSON**, which is what is stored. **Raw Markdown is never persisted.**

```bash
curl -X POST -H "Authorization: Bearer lesstruct_<...>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"# Hello\n\n**Bold** and *italic*.","format":"markdown","isPublished":true}' \
  "https://your-lesstruct.example/api/v1/content"
```

### Supported Markdown

| Markdown | Result |
|---|---|
| `# H1` … `###### H6` | Headings (levels 1–6). |
| Plain text | Paragraphs. |
| `**bold**`, `__bold__` | Bold. |
| `*italic*`, `_italic_` | Italic. |
| `` `code` `` | Inline code. |
| ` ```lang … ``` ` (fenced) | Code block, with `language` from the info string. |
| Indented code | Code block (no language). |
| `---`, `***`, `___` | Horizontal rule. |
| `> quote` | Blockquote (nestable). |
| `- a` / `* a` / `+ a` | Bullet list. |
| `1. a` | Ordered list. |
| `![alt](url "title")` | Image (`src`/`alt`/`title`). |
| `[text](url "title")` | Link (`href`/`title`). |
| `<https://example.com>` | Autolink (→ link). |
| Hard line break (`··\n` or `text\`) | Hard break. |

### Sanitized / not enabled

- **Raw HTML is sanitized.** Inline and block raw HTML is reduced to **safe plain text** (tags are stripped, visible text is kept) via [bluemonday](https://github.com/microcosm-cc/bluemonday). Raw HTML markup is never stored. Converting rich HTML formatting to Tiptap marks is out of scope — only the visible text survives.
- **Tables, task lists, and strikethrough** are not enabled (core CommonMark only). They render as plain text/paragraphs.

### URL safety

The converted document must pass Lesstruct's Tiptap validator, which restricts URL schemes:

- **Link `href`** must be `http`, `https`, `mailto`, or empty.
- **Image `src`** must be `http`, `https`, or empty.

A link or image with another scheme (`javascript:`, `data:`, `file:`, …) causes the converted document to fail validation and the request returns `400 VALIDATION_ERROR`. This is intentional and applies site-wide (including admin-authored content). Use an `http(s)` URL or upload the media first (see [Images](#images)).

> Markdown is an **ingest format only**. It is always converted to Tiptap JSON before storage; you cannot retrieve the original Markdown. Round-trip (Tiptap → Markdown) is out of scope.

## Images

- **External images** — `![alt](https://cdn.example.com/img.png)` passes through unchanged; the `src` is stored as-is (subject to the `http(s)` scheme rule above).
- **Local media** — to embed an image you upload, first upload it via `POST /api/v1/media`, then reference the returned `url` in your Markdown:

  ```bash
  # 1. Upload
  curl -H "Authorization: Bearer lesstruct_<...>" \
    -F "file=@photo.jpg" -F 'metadata={"altText":"..."}' \
    "https://your-lesstruct.example/api/v1/media"
  # → { "data": { "media": { "url": "https://your-lesstruct.example/uploads/media/a1b2c3d4.webp", ... } } }

  # 2. Reference the returned url
  ![A scenic view](https://your-lesstruct.example/uploads/media/a1b2c3d4.webp)
  ```

## Rate limiting

`/api/v1` is rate-limited **per API key** (not per IP) for attribution and fairness, using the same token-bucket limiter as the rest of the API. When you exceed the limit you receive `429 RATE_LIMITED`. Browser/admin routes are rate-limited per IP.

If you hit the limit, wait and retry with backoff. The limit is shared across all requests made with a given key.

## OpenAPI snippet

A machine-readable OpenAPI fragment for the Content create endpoint. A full OpenAPI specification is deferred to post-MVP; this snippet is suitable for agent tooling consumption.

```yaml
openapi: 3.0.3
info:
  title: Lesstruct API
  version: "1.0"
  description: >
    Versioned, API-key-authenticated Content and Media API.
    Auth: HTTP Bearer scheme with a `lesstruct_`-prefixed API key.
servers:
  - url: https://your-lesstruct.example
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: "Authorization: Bearer lesstruct_<keyID>_<secret>"
  schemas:
    Content:
      type: object
      description: "A content item (see Content object above for the full field set)."
      properties:
        id: { type: integer }
        title: { type: string }
        slug: { type: string }
        body: { type: string, description: "Canonical Tiptap JSON document string." }
        status: { type: string, enum: [draft, published] }
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code: { type: string }
                  message: { type: string }
security:
  - apiKey: []
paths:
  /api/v1/content:
    post:
      summary: Create content
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, body]
              properties:
                title: { type: string, minLength: 1, maxLength: 200 }
                body: { type: string, description: "Tiptap JSON (format=tiptap) or Markdown (format=markdown)" }
                format: { type: string, enum: [markdown, tiptap], default: tiptap, description: "Server matches case-insensitively after trimming whitespace." }
                postType: { type: string }
                slug: { type: string, description: "Accepted but not honored; slug is auto-generated." }
                customFields: { type: object, additionalProperties: true }
                isPublished: { type: boolean, default: false }
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      content: { $ref: "#/components/schemas/Content" }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Error" }
        "429": { $ref: "#/components/responses/Error" }
```

The same pattern extends to the remaining `/api/v1/content[/{id}]` and `/api/v1/media` operations described above. A complete OpenAPI document will be generated in a follow-up.


---

### Configuration

Source: [/docs/configuration/index.html](/docs/configuration/index.html)
Reference page for Configuration.

# Configuration

Lesstruct has two layers of configuration, each for a different concern:

- **`config.toml`** — your site's *content schema*: languages, custom post types, user profile fields, thumbnail variants. Edited by hand, version-controlled.
- **Environment variables** (in `.env` or the process env) — your *deployment configuration*: host, port, database, secrets, SMTP, AI integrations. Treated as deployment state, not committed.

This document covers both.

## Table of Contents

- [Where the Files Live](#where-the-files-live)
- [Environment Variables](#environment-variables)
- [config.toml Reference](#configtoml-reference)
- [Validation Rules](#validation-rules)
- [Worked Examples](#worked-examples)
- [What is NOT Configurable from config.toml](#what-is-not-configurable-from-configtoml)
- [Upgrading Lesstruct](#upgrading-lesstruct)
- [Troubleshooting](#troubleshooting)
- [Quick Reference](#quick-reference)

## Where the Files Live

| Concern | Default location | Override via env |
|---------|------------------|------------------|
| Content schema | `./config.toml` in the working directory | `CONFIG_DIR` (directory), `CONFIG_FILE` (filename) |
| Deployment config | `.env` in the working directory | process env wins over `.env` |
| Custom theme | empty (uses embedded theme) | `THEME_DIR=themes/<name>` |
| Plugins | `plugins/` in the working directory | not configurable (hard-coded) |
| Database | `data/lesstruct.db` (SQLite) | `DB_DRIVER`, `DB_PATH`, `DB_DSN` |

`config.toml` is loaded once at startup from `CONFIG_DIR/CONFIG_FILE`. The runtime does **not** auto-merge or auto-generate anything; the file is read as-is. If the file is missing, the runtime falls back to defaults (one language: English, default `post` and `page` post types, default thumbnail at 370 px). Validation errors at startup are reported with a clear message; the server does not start with an invalid `config.toml`.

> **Stale comment in older `config.toml` files.** Some early Lesstruct releases shipped a `config.toml` whose header says "this file is generated by merging all TOML files in `config/`". There is no such auto-merge. Edit `config.toml` directly.

## Environment Variables

All env vars are loaded by `internal/config/config.go:Load()` and override the corresponding defaults. The runtime also loads a `.env` file in the working directory via `godotenv` (env vars in the actual process env take precedence over `.env`).

### Server

| Variable | Default | Description |
|----------|---------|-------------|
| `HOST` | `0.0.0.0` | Bind address for the HTTP server. |
| `PORT` | `8080` | Bind port. Validated to be in `[1, 65535]`. |

### Database

| Variable | Default | Description |
|----------|---------|-------------|
| `DB_DRIVER` | `sqlite` | One of `sqlite`, `postgres`, `mysql`. |
| `DB_PATH` | `data/lesstruct.db` | SQLite file path (used when `DB_DRIVER=sqlite`). |
| `DB_DSN` | empty | Required for `postgres` and `mysql`. See per-driver requirements below. |
| `DB_POOL_MAX_CONNS` | `20` | Max connections in the pool (used with `postgres` and `mysql`). Must be ≥ 1 when set. |

**Per-driver requirements** (enforced at startup):

- **SQLite** — no extra requirements. Just set `DB_PATH` (or use the default).
- **Postgres** — `DB_DSN` is required. Format: `postgres://user:password@host:port/db?sslmode=disable`. `DB_POOL_MAX_CONNS` must be ≥ 1 if set.
- **MySQL** — `DB_DSN` is required. The DSN **must** contain `parseTime=true` and `multiStatements=true`. Without them, DATE columns scan as `[]byte` and migrations with multiple statements fail. Format: `user:password@tcp(host:port)/db?parseTime=true&multiStatements=true&charset=utf8mb4&collation=utf8mb4_general_ci`.

### Authentication

| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | empty (required) | HMAC secret for JWTs. **Required.** Must be at least 32 characters. |
| `API_KEY_PEPPER` | empty | Pepper prepended to API key secrets before hashing. Adding or changing it invalidates all existing API keys. |

### SMTP

| Variable | Default | Description |
|----------|---------|-------------|
| `SMTP_HOST` | empty | SMTP server hostname. When unset, the email-verification and password-reset flows will not work. |
| `SMTP_PORT` | `587` | SMTP port. |
| `SMTP_USER` | empty | SMTP auth username. |
| `SMTP_PASSWORD` | empty | SMTP auth password. |
| `SMTP_FROM` | empty | `From:` address for outbound emails. |

For local development, [Mailtrap](https://mailtrap.io/) or any sandbox SMTP service is a safe choice.

### CORS

| Variable | Default | Description |
|----------|---------|-------------|
| `CORS_ALLOWED_ORIGINS` | `http://localhost:5173` | Comma-separated list of allowed origins. Each must be a valid `http://` or `https://` URL with a non-empty host. The default is suitable for local admin dev. |

A typical production value:

```
CORS_ALLOWED_ORIGINS=https://example.com,https://www.example.com,https://admin.example.com
```

### Site

| Variable | Default | Description |
|----------|---------|-------------|
| `SITE_URL` | `http://localhost:8080` | Base URL of the public site. Used in email verification links, password reset links, and Open Graph tags. |
| `DEV_MODE` | `false` | When `true`, the admin panel is served from the Vite dev server (`ADMIN_DEV_URL`) instead of the embedded build. **Same env var enables plugin hot-reload** — see the plugin skill. |
| `ADMIN_DEV_URL` | `http://localhost:5173` | URL of the Vite dev server (only used when `DEV_MODE=true`). |
| `THEME_DIR` | empty | Path to a custom theme directory. Empty uses the embedded theme. See the theme skill. |

### Rate limits

| Variable | Default | Description |
|----------|---------|-------------|
| `RATE_LIMIT_ENABLED` | `true` | Master toggle. Set to `false` to disable all rate limiting (not recommended in production). |
| `RATE_LIMIT_AUTH_PER_MINUTE` | `5` | Per-IP cap on auth endpoints (login, register, forgot-password, reset-password). |
| `RATE_LIMIT_API_PER_MINUTE` | `100` | Per-token cap on authenticated API endpoints. |
| `RATE_LIMIT_PUBLIC_PER_MINUTE` | `60` | Per-IP cap on public endpoints (search, content listing, etc.). |

### Logging

| Variable | Default | Description |
|----------|---------|-------------|
| `LOG_LEVEL` | `info` | One of `debug`, `info`, `warn`, `error`. |

### AI image generation (optional)

When `AI_IMAGE_GENERATION_API_KEY` is set, the admin panel shows a "Generate with AI" button in the media library and content editor.

| Variable | Default | Description |
|----------|---------|-------------|
| `AI_IMAGE_GENERATION_API_KEY` | empty | API key for the image provider. |
| `AI_IMAGE_GENERATION_MODEL` | `imagen-4.0-fast-generate-001` | Model name. Examples: `imagen-4.0-fast-generate-001`, `imagen-4.0-ultra-generate-001`, `gpt-image-1`, `gpt-image-1-mini`, `gemini-2.5-flash-image`. |
| `AI_IMAGE_GENERATION_SIZE` | empty | Pixel size, e.g. `1024x1024`. |
| `AI_IMAGE_GENERATION_ASPECT_RATIO` | empty | Aspect ratio, e.g. `16:9`, `1:1`, `4:3`. |

### AI text generation (optional)

When `AI_TEXT_GENERATION_API_KEY` is set, the admin panel enables AI text enhancement and translation. Works with any OpenAI-compatible API.

| Variable | Default | Description |
|----------|---------|-------------|
| `AI_TEXT_GENERATION_API_KEY` | empty | API key for the text provider. |
| `AI_TEXT_GENERATION_BASE_URL` | empty | Override the API base URL. Default is OpenAI's API. For other providers: `https://api.deepseek.com`, `https://openrouter.ai/api/v1`, `http://localhost:11434/v1` (Ollama), etc. |
| `AI_TEXT_GENERATION_MODEL` | `gpt-5-mini` | Chat model name. Examples by provider: OpenAI `gpt-5-mini`, DeepSeek `deepseek-chat`, OpenRouter `openai/gpt-5-mini`, Together `meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`, Ollama `llama3`. |

### Duplicate-key gotcha

`.env` files are parsed by `godotenv`, which is a **last-value-wins** parser. If the same variable appears twice, only the second value is used:

```bash
THEME_DIR=themes/dark-warm
THEME_DIR=
```

The first line is silently overridden by the empty second line — Lesstruct ends up using the embedded theme. This is a common operator mistake. Check your `.env` for duplicate keys if a setting appears to have no effect.

## config.toml Reference

`config.toml` is loaded at startup. If the file is missing, the runtime uses defaults: English only, default `post` and `page` post types, default thumbnail at 370 px. If the file is present but invalid, the server fails to start with a validation error.

### Top-level keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `languages` | `[]string` | `["en"]` | ISO 639-1 language codes. The first is the primary language. Used by the i18n catalog, the admin language switcher, and the content language switcher. |
| `[user_fields]` | table | empty | Global user profile fields. Applies to all users. |
| `[[post_type]]` | array of tables | one default post type | Custom post types (see below). Add as many as needed. |
| `[[thumbnail]]` | array of tables | `[{max_width=370, suffix="_thumb"}]` | Image processing variants. See below. |

### `[user_fields]`

| Key | Type | Description |
|-----|------|-------------|
| `fields` | `[]FieldSchema` | User-editable fields shown in the user profile. |
| `system_fields` | `[]FieldSchema` | Read-only fields managed by plugins or operators. |

The schema for each field is the same as post-type fields (below).

### `[[post_type]]`

Each entry defines one custom post type. The default `post` and `page` post types are always present; you can extend them by adding custom fields (use the same slug as the default post type) or you can define entirely new post types.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | `string` | yes | Display name (e.g. `"Product"`). 1-200 characters. |
| `slug` | `string` | yes | URL slug (e.g. `"product"`). 1-200 characters. Kebab-case only: lowercase letters, digits, hyphens, underscores. No leading/trailing hyphens, no consecutive hyphens. |
| `description` | `string` | no | Human-readable description. Shown in the admin panel. |
| `supports` | `[]string` | yes (non-empty) | Features the post type supports. Each entry must be one of: `title`, `content`, `tags`, `featured_image`, `excerpt`. At least one is required. |
| `fields` | `[]FieldSchema` | no | User-editable custom fields. |
| `system_fields` | `[]FieldSchema` | no | Read-only system fields. Often set by plugins via `before_save` hooks. |

#### Field schema (`FieldSchema`)

Used in `[user_fields].fields`, `[user_fields].system_fields`, `[[post_type]].fields`, and `[[post_type]].system_fields`.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | `string` | yes | Display name. 1-200 characters. |
| `slug` | `string` | yes | Identifier. 1-200 characters, snake_case (regex-enforced). Must be unique within the parent (user fields or a post type). |
| `type` | `string` | yes | One of `text`, `textarea`, `number`, `date`, `select`, `checkbox`. |
| `required` | `bool` | no | When `true`, the field must have a value when saving. |
| `options` | `[]string` | for `select` | The list of allowed values. Required and non-empty for `select`. |
| `min` | `float` | for `number` | Minimum allowed value. |
| `max` | `float` | for `number` | Maximum allowed value. |
| `max_length` | `int` | for `text`/`textarea` | Maximum character count. |

### `[[thumbnail]]`

Each entry defines one image processing variant. When media is uploaded, Lesstruct generates one file per variant.

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `max_width` | `int` | yes | Maximum width in pixels. Must be > 0. |
| `suffix` | `string` | no | Filename suffix. Must be unique. The default thumbnail has suffix `_thumb`. |

If no `[[thumbnail]]` entries are defined, the runtime uses a single default variant: `max_width = 370`, `suffix = "_thumb"`.

## Validation Rules

These are enforced at startup by the runtime. Violations cause the server to fail to start with a clear error.

### Post type rules

- `name` must be 1-200 characters (`internal/domain/posttype/types.go:93-99`).
- `slug` must be 1-200 characters, contain only lowercase letters, digits, hyphens, and underscores; cannot start or end with a hyphen; cannot contain consecutive hyphens (`types.go:102-126`).
- `supports` must be non-empty and each entry must be one of: `title`, `content`, `tags`, `featured_image`, `excerpt` (`types.go:26-32`, `129-146`).
- Duplicate post-type slugs are rejected (`types.go:20`).

### Field rules

- `name` must be 1-200 characters (`internal/domain/customfield/types.go:98-104`).
- `slug` must be 1-200 characters and match the snake-case regex (`types.go:106-115`).
- `type` must be one of: `text`, `textarea`, `number`, `date`, `select`, `checkbox` (`types.go:35-41`, `118-123`).
- `select` fields must have a non-empty `options` list (`types.go:125-128`).
- `number` fields can have `min` and `max`; `text` and `textarea` fields can have `max_length`. Other combinations are rejected (`types.go:141-159`).
- Duplicate field slugs within the same parent (user fields or a single post type) are rejected (`types.go:90-93`).

### File rules

- `CONFIG_FILE` must not contain path separators or `..` (`internal/config/posttypes.go:19-21`).
- The config directory must exist and be readable; the file is optional (defaults apply if missing).

## Worked Examples

### Example A — Minimal blog

A personal blog with one language and the default post types. `config.toml` only sets the language; everything else falls back to defaults.

```toml
# ── Languages ───────────────────────────────────────────────────────
languages = ["en"]
```

That's it. You can omit `[[thumbnail]]` entirely (the runtime uses the default 370 px `_thumb` variant). No custom post types, no custom user fields, no custom themes, no plugins.

For a more useful starting point, add a `[[thumbnail]]` for medium-sized previews:

```toml
languages = ["en"]

[[thumbnail]]
max_width = 370
suffix = "_thumb"

[[thumbnail]]
max_width = 800
suffix = "_medium"
```

### Example B — Multilingual site (English + Indonesian)

A two-language site with a custom user profile (system fields for gamification, regular fields for bio/links).

```toml
# ── Languages ───────────────────────────────────────────────────────
# English is primary; Indonesian is supported.
# Both must have translation TOML files in internal/i18n/translations/
# (en.toml, id.toml) — these ship with Lesstruct.
languages = ["en", "id"]

# ── User Profile Fields ─────────────────────────────────────────────
[user_fields]
fields = [
  { name = "Job Title",  slug = "job_title",  type = "text" },
  { name = "Company",    slug = "company",    type = "text" },
  { name = "Website",    slug = "website",    type = "text" },
  { name = "Bio",        slug = "bio",        type = "textarea", max_length = 500 },
]
system_fields = [
  { name = "Points",        slug = "points",        type = "number",   min = 0, max = 100000 },
  { name = "Account Tier",  slug = "account_tier",  type = "select",   options = ["free", "basic", "pro", "enterprise"] },
  { name = "Internal Notes", slug = "internal_notes", type = "textarea", max_length = 1000 },
]

# ── Thumbnail Sizes ─────────────────────────────────────────────────
[[thumbnail]]
max_width = 370
suffix = "_thumb"

[[thumbnail]]
max_width = 800
suffix = "_medium"

[[thumbnail]]
max_width = 1600
suffix = "_large"
```

The runtime falls back to the default `post` and `page` post types (in both languages) for the content schema. Users can write posts and pages; the i18n switcher in the layout lets visitors pick English or Indonesian.

### Example C — Shop with custom post types

A two-post-type content schema: `product` for a storefront and `portfolio` for a work showcase. Both have realistic field combinations.

```toml
# ── Languages ───────────────────────────────────────────────────────
languages = ["en"]

# ── User Profile Fields ─────────────────────────────────────────────
[user_fields]
fields = [
  { name = "Job Title", slug = "job_title", type = "text" },
  { name = "Company",   slug = "company",   type = "text" },
  { name = "Website",   slug = "website",   type = "text" },
]
system_fields = [
  { name = "Points",        slug = "points",        type = "number", min = 0, max = 100000 },
  { name = "Account Tier",  slug = "account_tier",  type = "select", options = ["free", "basic", "pro", "enterprise"] },
]

# ── Custom Post Types ───────────────────────────────────────────────
# A product catalog with pricing, stock, and category.
[[post_type]]
name = "Product"
slug = "product"
description = "E-commerce product listings"
supports = ["title", "content", "excerpt"]

[[post_type.fields]]
name = "SKU"
slug = "sku"
type = "text"
required = true

[[post_type.fields]]
name = "Price"
slug = "price"
type = "number"
min = 0.01
max = 999999.99
required = true

[[post_type.fields]]
name = "Sale Price"
slug = "sale_price"
type = "number"
min = 0.01
max = 999999.99

[[post_type.fields]]
name = "Stock Quantity"
slug = "stock_quantity"
type = "number"
min = 0
max = 100000

[[post_type.fields]]
name = "Product Details"
slug = "product_details"
type = "textarea"
max_length = 2000

[[post_type.fields]]
name = "Release Date"
slug = "release_date"
type = "date"

[[post_type.fields]]
name = "Category"
slug = "category"
type = "select"
options = ["Electronics", "Clothing", "Home & Garden", "Books", "Toys"]
required = true

[[post_type.fields]]
name = "Size"
slug = "size"
type = "select"
options = ["XS", "S", "M", "L", "XL", "XXL"]

[[post_type.fields]]
name = "On Sale"
slug = "on_sale"
type = "checkbox"

[[post_type.fields]]
name = "Free Shipping"
slug = "free_shipping"
type = "checkbox"

[[post_type.system_fields]]
name = "Fulfillment Status"
slug = "fulfillment_status"
type = "select"
options = ["unfulfilled", "partial", "fulfilled", "returned"]

[[post_type.system_fields]]
name = "Warehouse Code"
slug = "warehouse_code"
type = "text"

# A portfolio / case-study post type with project metadata.
[[post_type]]
name = "Portfolio"
slug = "portfolio"
description = "Portfolio items to showcase work"
supports = ["title", "content", "tags", "featured_image", "excerpt"]

[[post_type.fields]]
name = "Client Name"
slug = "client_name"
type = "text"
required = true

[[post_type.fields]]
name = "Project Description"
slug = "project_description"
type = "textarea"
max_length = 1000

[[post_type.fields]]
name = "Project Date"
slug = "project_date"
type = "date"
required = true

[[post_type.fields]]
name = "Budget"
slug = "budget"
type = "number"
min = 0
max = 1000000

[[post_type.fields]]
name = "Project Type"
slug = "project_type"
type = "select"
options = ["Website", "Mobile App", "Desktop App", "API", "Consulting"]

[[post_type.fields]]
name = "Published"
slug = "published"
type = "checkbox"

[[post_type.system_fields]]
name = "Portfolio Status"
slug = "portfolio_status"
type = "select"
options = ["draft", "in_review", "approved", "archived"]

[[post_type.system_fields]]
name = "Internal Notes"
slug = "internal_notes"
type = "textarea"
max_length = 500

# ── Thumbnail Sizes ─────────────────────────────────────────────────
[[thumbnail]]
max_width = 370
suffix = "_thumb"

[[thumbnail]]
max_width = 800
suffix = "_medium"

[[thumbnail]]
max_width = 1600
suffix = "_large"
```

Pair this with a `.env` that enables the AI integrations, e.g.:

```bash
# Database (SQLite is fine for a small shop)
DB_DRIVER=sqlite
DB_PATH=data/shop.db

# JWT
JWT_SECRET=replace_me_with_a_32_plus_character_random_string

# SMTP
SMTP_HOST=sandbox.smtp.mailtrap.io
SMTP_PORT=587
SMTP_USER=your_user
SMTP_PASSWORD=your_pass
SMTP_FROM=orders@example.com

# CORS
CORS_ALLOWED_ORIGINS=https://shop.example.com,https://admin.example.com

# Site
SITE_URL=https://shop.example.com

# Theme (optional)
THEME_DIR=themes/custom

# AI image generation (optional)
AI_IMAGE_GENERATION_API_KEY=sk-...
AI_IMAGE_GENERATION_MODEL=gpt-image-1-mini

# AI text generation (optional, e.g. DeepSeek)
AI_TEXT_GENERATION_API_KEY=sk-...
AI_TEXT_GENERATION_BASE_URL=https://api.deepseek.com
AI_TEXT_GENERATION_MODEL=deepseek-chat
```

## What is NOT Configurable from `config.toml`

`config.toml` and the env vars cover deployment and content schema, but several other surfaces are configured elsewhere:

| Surface | How to configure | Reference |
|---------|------------------|-----------|
| Public site theme (CSS, JS, HTML templates) | `THEME_DIR=themes/<name>` env var → a `themes/<name>/` directory | `skills/lesstruct-theme-development/` |
| WASM plugins (custom hooks, external API calls) | `<name>.wasm` and `<name>.manifest` in `plugins/` | `skills/lesstruct-plugin-development/` |
| Admin panel branding (logo, colors, copy) | Edit `web/admin/` source and rebuild | `make build-admin` |
| API response shapes | Edit `internal/api/handlers/` | source only |
| CLI flags | `lesstruct-cli --help` | built-in |

Plugins and themes are loaded at startup and hot-reloaded only when `DEV_MODE=true` is set (and even then, only the plugin watcher is recursive; the theme is not). Admin and API changes always require a rebuild / redeploy.

## Upgrading Lesstruct

When you bump the Lesstruct version (via `go install github.com/aristorinjuang/lesstruct@<version>` or a new release tarball):

1. **Back up your `config.toml` and `.env`.** New versions may add fields that your old config doesn't have; the runtime applies sensible defaults for any field that is missing.
2. **Diff the new `config.toml.example` and `.env.example` against your files.** Lesstruct's release notes call out new env vars; copy them into your `.env` only if you need the feature.
3. **Validate before starting.** Start the server with the new binary. If `config.toml` has a new validation rule (e.g. a new field type), the runtime reports it at startup. Fix and retry.
4. **New field types or supported features** are documented here. If you see a new entry in the [Validation Rules](#validation-rules) section, your existing `config.toml` will keep working; only new post types you add will need to use the new field types.
5. **Theme and plugin skills** ship independently of the runtime. After a runtime upgrade, re-run the theme and plugin skills to compare your `themes/<name>/` and `plugins/<name>.wasm` against any new defaults.

## Troubleshooting

### `JWT_SECRET is required` at startup

You didn't set `JWT_SECRET` in `.env` (or it's empty). It must be present and at least 32 characters:

```bash
JWT_SECRET=$(head -c 48 /dev/urandom | base64)
```

### `unsupported DB_DRIVER "X"`

`DB_DRIVER` must be `sqlite`, `postgres`, or `mysql`. The runtime rejects other values at startup.

### `DB_DSN must contain parseTime=true` (MySQL)

The MySQL DSN is missing the `parseTime=true` query parameter. Without it, DATE columns scan as `[]byte`. Add it to the DSN:

```
user:pass@tcp(host:port)/db?parseTime=true&multiStatements=true&charset=utf8mb4&collation=utf8mb4_general_ci
```

### `DB_DSN must contain multiStatements=true` (MySQL)

Same fix as above — the `multiStatements=true` parameter is required for golang-migrate to run migrations with multiple SQL statements.

### `post type slug "X" is invalid`

`X` violates the slug rules: it must be kebab-case, lowercase letters/digits/hyphens/underscores only, no leading/trailing hyphens, no consecutive hyphens (`--`). Examples:

- ✓ `product`, `team-member`, `case_study`
- ✗ `Product` (uppercase), `-product` (leading hyphen), `team--member` (consecutive hyphens), `team.member` (period not allowed)

### `field "x": duplicate slug`

Two fields in the same parent (user fields, or a single post type) have the same `slug`. Slugs must be unique within a parent.

### `field type must be one of: text, textarea, number, date, select, checkbox`

Typo in the `type` field, or a new field type that this version of Lesstruct doesn't support. Check the [Field schema](#field-schema-fieldschema) table for the current list.

### `select field requires non-empty options`

A `select` field has no `options = [...]` list. Add at least one option.

### `CONFIG_FILE must not contain path separators`

You tried to set `CONFIG_FILE` to a path like `config/shop.toml`. The runtime only supports a flat filename in `CONFIG_DIR`; subdirectories are not allowed.

### Theme changes are not taking effect

Cross-reference the `lesstruct-theme-development` skill. Common causes: `THEME_DIR` is empty, points to a missing directory, or the server was not restarted after the last change.

### Plugin hooks are not firing

Cross-reference the `lesstruct-plugin-development` skill. The currently-invoked hooks are `before_save`, `after_create`, and `after_publish`. `on_plugin_loaded` and `before_delete` are defined but not invoked today.

### Env var appears to have no effect (`.env`)

Check for **duplicate keys** in `.env`. The `godotenv` parser uses last-value-wins, so a later `THEME_DIR=` line silently overrides an earlier `THEME_DIR=themes/dark-warm`.

## Quick Reference

### All env vars (with defaults)

```
HOST=0.0.0.0
PORT=8080
DB_DRIVER=sqlite
DB_PATH=data/lesstruct.db
DB_DSN=
DB_POOL_MAX_CONNS=20
JWT_SECRET=                  # required, ≥ 32 chars
API_KEY_PEPPER=
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM=
CORS_ALLOWED_ORIGINS=http://localhost:5173
SITE_URL=http://localhost:8080
DEV_MODE=false
ADMIN_DEV_URL=http://localhost:5173
THEME_DIR=
LOG_LEVEL=info
RATE_LIMIT_ENABLED=true
RATE_LIMIT_AUTH_PER_MINUTE=5
RATE_LIMIT_API_PER_MINUTE=100
RATE_LIMIT_PUBLIC_PER_MINUTE=60
AI_IMAGE_GENERATION_API_KEY=
AI_IMAGE_GENERATION_MODEL=imagen-4.0-fast-generate-001
AI_IMAGE_GENERATION_SIZE=
AI_IMAGE_GENERATION_ASPECT_RATIO=
AI_TEXT_GENERATION_API_KEY=
AI_TEXT_GENERATION_BASE_URL=
AI_TEXT_GENERATION_MODEL=gpt-5-mini
```

### All `config.toml` keys

```
languages = ["en"]

[user_fields]
fields = [{ name, slug, type, required, ... }]
system_fields = [{ name, slug, type, ... }]

[[post_type]]
name = ""                        # required, 1-200 chars
slug = ""                        # required, kebab-case
description = ""
supports = ["title", "content", "tags", "featured_image", "excerpt"]   # ≥ 1
fields = [{ name, slug, type, required, ... }]
system_fields = [{ name, slug, type, ... }]

[[thumbnail]]
max_width = 370                  # > 0
suffix = "_thumb"                # unique
```

### All field types

| Type | Required sub-keys | Optional sub-keys |
|------|-------------------|-------------------|
| `text` | `name`, `slug`, `type` | `required`, `max_length` |
| `textarea` | `name`, `slug`, `type` | `required`, `max_length` |
| `number` | `name`, `slug`, `type` | `required`, `min`, `max` |
| `date` | `name`, `slug`, `type` | `required` |
| `select` | `name`, `slug`, `type`, `options` (non-empty) | `required` |
| `checkbox` | `name`, `slug`, `type` | `required` |

### All supported `supports` values

`title`, `content`, `tags`, `featured_image`, `excerpt`.


---

### Plugin Capabilities

Source: [/docs/plugin-capabilities/index.html](/docs/plugin-capabilities/index.html)
Reference page for Plugin Capabilities.

# Plugin Capabilities

> **Audience.** This is the **developer-facing** reference for the Lesstruct
> plugin capability manifest and host functions. It references source-tree
> paths (e.g. `internal/plugin/`).
>
> If you are a Lesstruct user who has installed the binary and wants to add
> host function calls to a plugin, use the **user-facing** snapshot bundled
> with the `lesstruct-plugin-development` skill at
> `skills/lesstruct-plugin-development/references/plugin-capabilities.md`. It
> covers the same contract (manifest schema, host functions, security
> model) but with no source-tree references.

Plugins can request access to host resources (HTTP, database, logging) by declaring them in a **capability manifest** file placed alongside the `.wasm` file.

## Quick Start

Create `<plugin-name>.manifest` next to `<plugin-name>.wasm` in the `plugins/` directory:

```toml
name = "my-enrichment-plugin"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
database = ["read:content", "write:content"]
```

If no `.manifest` file exists, the plugin gets **zero** host functions — same as before.

## Manifest Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Plugin name (must be non-empty) |
| `version` | Yes | Semantic version of the plugin (must be non-empty) |
| `capabilities.http` | No | List of allowed URL patterns |
| `capabilities.database` | No | List of allowed database permissions |

### URL Patterns

URLs are matched using simple prefix matching. Use `*` as a suffix for wildcards:

```toml
http = [
    "https://api.example.com/*",         # Match all paths on api.example.com
    "https://jsonplaceholder.typicode.com/todos/1",  # Exact match only
]
```

- `https://api.example.com/*` matches `https://api.example.com/v1/data`, `https://api.example.com/foo/bar`, etc.
- Patterns are checked in order; the first match wins.
- The trailing `*` is the only wildcard supported. Regex patterns are not accepted.

### Database Permissions

Database permissions follow the format `<operation>:<table>`:

| Permission | Allows |
|-----------|--------|
| `read:content` | SELECT queries on the `content_items` table |
| `read:media` | SELECT queries on the `media_files` table |
| `read:users` | SELECT queries on the `users` table |
| `write:content` | INSERT/UPDATE/DELETE on the `content_items` table (including the `custom_fields` column) |
| `write:media` | INSERT/UPDATE/DELETE on the `media_files` table |
| `write:users` | INSERT/UPDATE/DELETE on the `users` table |

The host validates each SQL query to extract the target table name and checks it against the manifest.

#### Table Access Scope

Of the 11 tables in the Lesstruct database, only **three** are grantable to
plugins: `content_items` (normalised to `content`), `media_files`
(normalised to `media`), and `users`. The other eight tables —
`comments`, `blocked_emails`, `failed_login_attempts`, `verification_tokens`,
`password_reset_tokens`, `email_update_tokens`, `soft_deleted_content`, and
`api_keys` — are inaccessible to plugins by design. A plugin cannot query or
modify them via `db_query` or `db_exec`.

## Available Host Functions

### HTTP

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.http_get` | `(url_ptr, url_len, headers_json_ptr, headers_json_len) -> result_offset` | Perform an HTTP GET request |
| `lesstruct.http_post` | `(url_ptr, url_len, headers_json_ptr, headers_json_len, body_ptr, body_len) -> result_offset` | Perform an HTTP POST request |

### Database

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.db_query` | `(sql_ptr, sql_len, params_json_ptr, params_json_len) -> result_offset` | Execute a SELECT query |
| `lesstruct.db_exec` | `(sql_ptr, sql_len, params_json_ptr, params_json_len) -> result_offset` | Execute an INSERT/UPDATE/DELETE |

### Logging

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.log_info` | `(message_ptr, message_len) -> void` | Log an informational message to the host |
| `lesstruct.log_error` | `(message_ptr, message_len) -> void` | Log an error message to the host |

Logging functions are always available when any manifest exists — no capability declaration needed.

## Result Format

All host functions return results as JSON at offset `4096` in WASM memory.

### Success

```json
{
    "status": 200,
    "body": "...",
    "headers": {"Content-Type": "application/json"}
}
```

### Error

```json
{
    "error": "url_not_allowed",
    "message": "URL \"https://evil.com\" not in capability manifest http allowlist"
}
```

> **Offset collision.** All four data host functions (`http_get`,
> `http_post`, `db_query`, `db_exec`) write their result to the same fixed
> offset (`4096`). If your plugin calls `http_get` and then `db_query`
> before reading the first result, the second overwrites the first. Read
> each result before invoking the next host function.

## Security Model

| Concern | Mechanism |
|---------|-----------|
| URL allowlisting | Each HTTP call is checked against the manifest's `http` patterns before the request is made |
| Table-level DB access | SQL queries are parsed to extract the target table, then checked against `database` permissions |
| Response size limit | HTTP response bodies are capped at 1MB |
| Request timeout | HTTP requests have a 10-second timeout (set once at startup); DB queries use the parent request context |
| Memory isolation | Plugins remain in the WASM sandbox; host functions only write results to controlled offsets |
| Audit logging | Only **denied** host function calls are logged at the host level. Successful calls produce no log line. Use `log_info` from your plugin to record what you did. |

### SQL Parser Limitations

The host uses a hand-rolled substring parser to extract the target table
from each query. The parser looks for the first occurrence of `FROM`,
`INSERT INTO`, `UPDATE`, or `DELETE FROM` and reads the first identifier
after it.

The parser does **not** handle:

- Common Table Expressions (`WITH ... SELECT`).
- Subqueries.
- SQL comments (`--` or `/* */`).
- Quoted identifiers.
- Multi-statement queries.

Write a single explicit `SELECT`/`INSERT`/`UPDATE`/`DELETE` statement per
host function call.

## Example: HTTP Enrichment Plugin

A plugin that calls `lesstruct.http_get` to enrich a content item during
`before_save`:

```go
//go:wasmimport lesstruct http_get
func httpGet(urlPtr, urlLen, headersPtr, headersLen uint32) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    url := "https://api.example.com/items/lookup"
    // Write url to WASM memory, call httpGet, read result from offset 4096...
    // Parse JSON, extract a value, set it in customFields, write back to resultBuf.
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

Manifest:

```toml
name = "http-enrich"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
```

> **Note.** The Lesstruct SDK does not currently ship a `//go:wasmimport`
> declaration for `http_get` (or any other host function). The declarations
> are bundled with the `lesstruct-plugin-development` skill at
> `references/host-function-imports.go.txt` — copy that block into your
> `main.go` to use the host functions.

## Example: Database Plugin

A plugin that reads content metadata during a `before_save` hook:

```go
//go:wasmimport lesstruct db_query
func dbQuery(
    sqlPtr, sqlLen uint32,
    paramsPtr, paramsLen uint32,
) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    sql := "SELECT COUNT(*) FROM content_items WHERE post_type = ?"
    params := `["product"]`

    // Write SQL and params to WASM memory, call dbQuery, read result from offset 4096...
    resultOffset := dbQuery(sqlPtr, sqlLen, paramsPtr, paramsLen)
    // Parse JSON result from resultOffset...
}
```

Manifest:

```toml
name = "db-plugin"
version = "1.0.0"

[capabilities]
database = ["read:content"]
```


---

### Plugin Development Guide

Source: [/docs/plugin-development/index.html](/docs/plugin-development/index.html)
Reference page for Plugin Development Guide.

# Plugin Development Guide

> **Audience.** This is the **developer-facing** reference for Lesstruct
> plugin development. It references source-tree paths (e.g. `internal/plugin/`,
> `pkg/sdk/`).
>
> If you are a Lesstruct user who has installed the binary and wants to write
> a plugin against your installation, use the **user-facing** snapshot bundled
> with the `lesstruct-plugin-development` skill at
> `skills/lesstruct-plugin-development/references/plugin-development.md`. It
> covers the same contract (hooks, memory protocol, host functions, build
> instructions) but with no source-tree references.

Lesstruct supports WebAssembly (WASM) plugins that extend functionality through hooks. Plugins are compiled from Go, Rust, C/C++, or any language that targets WASI.

## How Plugins Work

1. Compile your plugin to a `.wasm` file targeting the WASI runtime.
2. Place the `.wasm` file (and an optional `.manifest` file) in the `plugins/` directory.
3. Lesstruct discovers and loads the plugin at startup.
4. The plugin system calls exported hook functions at the appropriate lifecycle points.

> **See also:** [Plugin Capabilities](plugin-capabilities.md) — host functions for HTTP, database, and logging. If your plugin needs to call external APIs or query the database, add a capability manifest.

The `plugins/` directory is the relative path `plugins/` from the Lesstruct working directory (`main.go:382`). It is not configurable via env or flag.

## Plugin Capabilities (Host Functions)

Plugins that need access to host resources (HTTP, database, logging) declare their requirements in a **capability manifest** — a TOML file placed alongside the `.wasm` file.

### Manifest File

Create `<plugin-name>.manifest` next to `<plugin-name>.wasm`:

```toml
name = "my-enrichment-plugin"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
database = ["read:content"]
```

If no `.manifest` file exists, the plugin runs with **zero** host functions — hooks only.

### Available Host Functions

| Function | Import Path | Description |
|----------|-------------|-------------|
| `lesstruct.http_get` | `lesstruct.http_get` | HTTP GET request (URL allowlist checked) |
| `lesstruct.http_post` | `lesstruct.http_post` | HTTP POST request (URL allowlist checked) |
| `lesstruct.db_query` | `lesstruct.db_query` | Execute SELECT query (table access checked) |
| `lesstruct.db_exec` | `lesstruct.db_exec` | Execute INSERT/UPDATE/DELETE (table access checked) |
| `lesstruct.log_info` | `lesstruct.log_info` | Log info message to host |
| `lesstruct.log_error` | `lesstruct.log_error` | Log error message to host |

The full reference lives in [Plugin Capabilities](plugin-capabilities.md).

### Host Function Import (Go/TinyGo)

Unlike hooks (which use `//export`), host functions use `//go:wasmimport`:

```go
//go:wasmimport lesstruct http_get
func httpGet(urlPtr, urlLen uint32, headersPtr, headersLen uint32) uint32

//go:wasmimport lesstruct log_info
func logInfo(msgPtr, msgLen uint32)
```

> **Note.** The Lesstruct SDK (`pkg/sdk/hostfunctions.go`) currently ships
> only the constant names for these host functions. It does **not** ship the
> `//go:wasmimport` declarations themselves. Plugin authors write their own
> bindings, or use the `references/host-function-imports.go.txt` block
> bundled with the `lesstruct-plugin-development` skill.

## Hook System

### Available Hooks

The host invokes three hooks today:

| Hook | WASM Export Name | Description |
|------|------------------|-------------|
| BeforeSaveContent | `hook_before_save` | Called before content is saved (create or update) |
| AfterCreateContent | `hook_after_create` | Called after content is created |
| AfterPublishContent | `hook_after_publish` | Called after content is published |

Two additional hooks are defined in the host registry but are **not currently invoked** by any production code path. If your plugin exports only one of these, the plugin will load successfully but the hook will never fire:

| Hook | WASM Export Name | Status |
|------|------------------|--------|
| OnPluginLoaded | `hook_on_plugin_loaded` | Defined, not invoked |
| BeforeDeleteContent | `hook_before_delete` | Defined, not invoked |

Do not rely on `hook_on_plugin_loaded` or `hook_before_delete` for production
behaviour. Use one of the three invoked hooks instead.

### Failure Mode

When a hook returns an error, the request fails. The content service maps
the error to a 500 response and the content is not saved (for `before_save`)
or the error is logged (for `after_create` / `after_publish`, whose results
are not stored). There is no automatic rollback of prior hooks in a chain.

## System Fields

System fields are special custom field values managed by plugins. They are defined in the post type TOML schema with the `system = true` flag and stored alongside regular custom fields in the `customFields` JSON map.

### Hook Data Format

When `before_save` or `after_create` hooks execute, the host sends a JSON object with eight fields:

```json
{
  "contentId": 0,
  "userId": 42,
  "title": "My Product",
  "content": "...",
  "tags": ["featured", "sale"],
  "status": "draft",
  "postType": "product",
  "customFields": {
    "price": 29.99,
    "internal_sku": "SKU-001",
    "sync_status": "synced"
  }
}
```

Field notes:

- `contentId` is `0` on create, the existing content's ID on update.
- `userId` is the authenticated user performing the action.
- `status` is one of `draft`, `published`, `archived`, or a custom value.
- `postType` is `post`, `page`, or a custom type.
- `customFields` contains both regular custom fields and system fields.

### Reading System Fields

In a `before_save` hook, read system field values from `customFields` in the JSON input:

```go
//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)

    var data map[string]any
    json.Unmarshal(input, &data)

    if cf, ok := data["customFields"].(map[string]any); ok {
        if sku, ok := cf["internal_sku"].(string); ok {
            // Read existing system field value: "SKU-001"
            _ = sku
        }
    }

    // Return the (possibly modified) data
    modified, _ := json.Marshal(data)
    copy(resultBuf[:], modified)
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

### Writing System Fields

A plugin can set or modify system field values in `customFields`. The host validates plugin-set system field values against their schema definition (type, required, options, min/max). Validation runs in the content service **after** the hook returns — the hook itself does not see validation errors.

> If the plugin writes an invalid system field value, the API call fails with a 500 and the content is not saved. The hook does not receive the validation error; the error is mapped to the API caller.

```go
//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)

    var data map[string]any
    json.Unmarshal(input, &data)

    cf, ok := data["customFields"].(map[string]any)
    if !ok {
        cf = make(map[string]any)
        data["customFields"] = cf
    }

    cf["internal_sku"] = "SKU-002"
    cf["sync_status"] = "pending"

    modified, _ := json.Marshal(data)
    copy(resultBuf[:], modified)
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

### What the Host Reads Back from the Result

The host only reads back the `customFields` key from the hook's result. The
plugin may write other keys (`title`, `tags`, etc.) into its result JSON, but
the host ignores them. To mutate the content item, the plugin must write
`customFields` and return a JSON object containing it.

### Important Notes

- System field values are only preserved when set through `before_save` hooks. User-submitted system field values are stripped for security.
- `after_create` and `after_publish` hooks can read but should not write system fields — their results are not stored (notification-style hooks).
- If no plugin handles a `before_save` hook, system fields are stripped as usual and content creation proceeds normally.

## Memory Protocol

### Hook Functions vs Host Functions

- **Hooks** use `//export` — the plugin exports them, the host calls them. Data flows via `(offset, length) -> resultOffset` at offset `65536` (64KB).
- **Host functions** use `//go:wasmimport` — the host exports them, the plugin calls them. The plugin manages offsets. The host writes results to a fixed offset of `4096`. See [Plugin Capabilities](plugin-capabilities.md).

### Hook Function Signature

Every hook function must follow this signature:

```
(offset: uint32, length: uint32) -> resultOffset: uint32
```

### Data Flow

1. The host writes input data to WASM linear memory at offset `65536` (64KB).
2. The host calls the hook function with `(65536, dataLength)`.
3. The plugin reads input from `(offset, offset+length)`.
4. The plugin writes the result to WASM memory.
5. The plugin returns the offset where the result starts.
6. The host reads the result from the returned offset.

If the plugin returns `0` (or empty bytes), the host treats the result as
"no change" and uses the original input.

### Variable-Length Results

If the result length differs from the input length, export `__hook_result_len`:

```
(inputLen: uint32) -> resultLen: uint32
```

The export is **optional**. If it is missing, the host assumes the result
length equals the input length.

### Data Format

All data passed through hooks is JSON-encoded bytes (UTF-8).

### Required Exports

Every plugin `.wasm` file must export:

- `memory` — Linear memory (auto-exported by most compilers).
- One or more `hook_*` functions from the [Available Hooks](#available-hooks) table.
- Optional: `__hook_result_len` (only when result length differs from input length).

## Development vs Production Mode

- **Production** (default): Plugins are loaded once at startup. To reload, restart the server.
- **Development** (`DEV_MODE=true`): Plugins are hot-reloaded when `.wasm` files change via filesystem watcher.

> **`DEV_MODE` is shared with the admin SPA.** Toggling the same env var to
> enable plugin hot-reload also enables admin-panel HMR. If you want
> production plugin loading but dev admin HMR, set `DEV_MODE=false`; if you
> want plugin hot-reload, the admin panel will also be in dev mode.

The watcher is non-recursive: subdirectories of `plugins/` are not watched.
It debounces filesystem events by 150 ms and reloads only the affected
`.wasm` files. On reload, the host unregisters the plugin's old hooks and
re-runs discovery.

## Go / TinyGo Guide

### Prerequisites

- Go 1.20+
- [TinyGo](https://tinygo.org/getting-started/install/) 0.28+

### Project Setup

```go
// go.mod
module example.com/my-plugin

go 1.21
```

```go
package main

import "unsafe"

var resultBuf [4096]byte

//export hook_on_plugin_loaded
func hookOnPluginLoaded(offset uint32, length uint32) uint32 {
	input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)
	// Process input, write result to resultBuf
	return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}

func main() {}
```

> **Note.** `hook_on_plugin_loaded` is **not currently invoked** by the host. Use `hook_before_save` or one of the other invoked hooks when authoring a plugin that needs to run.

### Build

```bash
tinygo build -o plugin.wasm -target=wasi main.go
```

### TinyGo Notes

- Use `-target=wasi` (not `wasm32-wasi`).
- Export functions with `//export function_name` directive (no space after `//`).
- `unsafe` package is needed for WASM memory operations.
- No standard library networking or file I/O in WASI sandbox.

## Rust Guide

### Prerequisites

- Rust 1.70+
- `wasm32-wasip1` target

### Install Target

```bash
rustup target add wasm32-wasip1
```

### Project Setup

```toml
# Cargo.toml
[package]
name = "lesstruct-plugin"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]
```

```rust
// src/lib.rs
static mut RESULT_BUF: [u8; 4096] = [0; 4096];

#[no_mangle]
pub extern "C" fn hook_before_save(offset: u32, length: u32) -> u32 {
    let memory = unsafe {
        std::slice::from_raw_parts(offset as *const u8, length as usize)
    };
    // Process memory, write result to RESULT_BUF
    unsafe { RESULT_BUF.as_mut_ptr() as u32 }
}
```

### Build

```bash
cargo build --release --target wasm32-wasip1
# Output: target/wasm32-wasip1/release/lesstruct_plugin.wasm
```

> **No official Rust examples ship in the Lesstruct repo today.** The
> memory protocol described above applies directly. Validate your
> `.wasm` with `wasm-tools validate plugin.wasm` before deploying.

## C/C++ Guide

### Prerequisites

- Clang or GCC with WASI support
- [WASI SDK](https://github.com/WebAssembly/wasi-sdk) (recommended)

### Project Setup

```c
// plugin.c
#include <stdint.h>
#include <string.h>

static uint8_t result_buf[4096];

__attribute__((export_name("hook_before_save")))
uint32_t hook_before_save(uint32_t offset, uint32_t length) {
    uint8_t *input = (uint8_t *)offset;

    const char *response = "{\"customFields\":{\"price\":0}}";
    memcpy(result_buf, response, strlen(response));

    return (uint32_t)result_buf;
}
```

### Build

```bash
# With WASI SDK
/opt/wasi-sdk/bin/clang --sysroot=/opt/wasi-sdk/share/wasi-sysroot \
    -O2 -o plugin.wasm plugin.c

# With clang and WASI target
clang --target=wasm32-wasi -o plugin.wasm plugin.c
```

> **No official C/C++ examples ship in the Lesstruct repo today.** The
> memory protocol described above applies directly. Validate your
> `.wasm` with `wasm-tools validate plugin.wasm` before deploying.

## Testing Plugins

1. Compile the plugin to `.wasm`.
2. Copy the `.wasm` file to the `plugins/` directory.
3. Restart Lesstruct (or use `DEV_MODE=true` for hot-reload).
4. Observe behaviour in the application logs.

For a manual smoke test per hook, see the `references/plugin-checklist.md`
file bundled with the `lesstruct-plugin-development` skill.

If you observe your hooks firing on create but not on delete, or
`on_plugin_loaded` not firing at all, you have hit a hook that is
defined but not currently invoked. See the [Available Hooks](#available-hooks)
section above.


---

### Theme Development Guide

Source: [/docs/theme-development/index.html](/docs/theme-development/index.html)
Reference page for Theme Development Guide.

# Theme Development Guide

> **Audience.** This is the **developer-facing** reference for Lesstruct theme
> development. It references source-tree paths (e.g. `internal/api/template/`).
>
> If you are an end user of Lesstruct — i.e. you have installed the binary and
> want to customise the public site via `themes/<name>/` — use the
> **user-facing** snapshot bundled with the `lesstruct-theme-development` skill
> at `skills/lesstruct-theme-development/references/theme-development.md`. It
> covers the same contract (CSS variables, template blocks, JS DOM contract,
> CDN assets) but with no source-tree references.

Lesstruct supports custom themes for the public-facing content site. Themes override the
default CSS, JavaScript, and (optionally) HTML templates without modifying the core source.

## How Themes Work

1. Create a theme directory with your custom files.
2. Set the `THEME_DIR` environment variable to point to it.
3. At startup, Lesstruct resolves each template and static file through a
   `compositeFS` (`internal/api/template/theme.go:44-58`) and `readThemeFile`
   (`internal/api/template/theme.go:30-41`):
   - If the file exists under `THEME_DIR`, that copy is used.
   - If it is missing, the embedded default from `internal/api/template/` is used.

This means you can ship a **partial** theme — a single `style.css`, or a full
`layout.html`, or anything in between — and the rest stays on the embedded defaults.

## Theme Directory Structure

```
themes/
  mytheme/
    static/          # Served at /static/*
      style.css
      auth.js
      comments.js
      nav-auth.js
      search.js
      math.js
      verify-email.js
      reset-password.js
      highlight.min.js
    templates/       # Go html/template files
      layout.html
      index.html
      content.html
      author.html
      tag.html
      not_found.html
      login.html
      register.html
      forgot_password.html
      verify_email.html
      reset_password.html
```

The theme can override **any subset** of these files. Any file not present falls
back to the embedded default at `internal/api/template/static/` or
`internal/api/template/pages/`.

## Quick Start: CSS-Only Theme

The simplest theme overrides only the CSS.

### 1. Create the theme directory

```bash
mkdir -p themes/mytheme/static
```

### 2. Start from the readable source

The minified `internal/api/template/static/style.css` is the file browsers receive.
The readable, documented source is `internal/api/template/static/style.src.css`
(commented, organised by section). Copy the readable source:

```bash
cp internal/api/template/static/style.src.css themes/mytheme/static/style.css
```

Theme authors do not need to run `make css`. Browsers receive your `style.css`
verbatim. (If you maintain a `.src.css` for your own authoring convenience and want
to ship a minified version, run `make css` against your source — but the theme
override is happy with any valid CSS.)

### 3. Override the design tokens

The default theme exposes every visual decision as a CSS custom property under
`:root`. Override the ones you want to change:

```css
:root {
  --color-bg: #ffffff;
  --color-text: #1a1a2e;
  --color-primary: #22d3ee;
  --max-width: 1200px;
}
```

> **Note on the brand tokens.** The `--color-*` brand tokens are marked **LOCKED** in
> the embedded `style.src.css:32-35` — that means the embedded source will not change
> those values, not that themes cannot override them. Your theme is free to redefine
> any token. The lock exists so the upstream visual identity stays stable.

### 4. Configure the theme

Set `THEME_DIR` in your `.env`:

```bash
THEME_DIR=themes/mytheme
```

### 5. Restart Lesstruct

Themes are loaded at startup. Restart the server to apply changes.

## CSS Variable Reference

The full set, defined in `internal/api/template/static/style.src.css:36-85`.

### Brand colors

| Variable | Default | Description |
|----------|---------|-------------|
| `--color-bg` | `#ffffff` | Page background color |
| `--color-text` | `#1a1a2e` | Main text color |
| `--color-text-muted` | `#6b7280` | Secondary / muted text |
| `--color-primary` | `#22d3ee` | Primary brand color (links, buttons, focus rings) |
| `--color-primary-hover` | `#06b6d4` | Primary color on hover |
| `--color-secondary` | `#2536eb` | Secondary brand color (logo, active nav, headings) |
| `--color-accent` | `#8b5cf6` | Accent color (tags, highlights) |
| `--color-border` | `#e5e7eb` | Border and divider color |
| `--color-card-bg` | `#f9fafb` | Card and elevated surface background |

### Status colors

| Variable | Default | Description |
|----------|---------|-------------|
| `--color-danger` | `#dc2626` | Error and validation messages |
| `--color-success` | `#16a34a` | Success messages |

### Layout

| Variable | Default | Description |
|----------|---------|-------------|
| `--max-width` | `1200px` | Outer container max width |
| `--content-width` | `768px` | Single-article reading width |
| `--header-height` | `80px` | Sticky header height (used for anchor offset) |

### Radii

| Variable | Default | Description |
|----------|---------|-------------|
| `--radius-sm` | `4px` | Small elements (badges) |
| `--radius-md` | `6px` | Buttons, inputs, alerts |
| `--radius-lg` | `8px` | Cards, modals |

### Elevation

| Variable | Default | Description |
|----------|---------|-------------|
| `--shadow-sm` | `0 1px 2px rgba(0, 0, 0, 0.05)` | Subtle lift |
| `--shadow-md` | `0 4px 16px rgba(0, 0, 0, 0.10)` | Cards, hovered inputs |
| `--shadow-lg` | `0 8px 24px rgba(0, 0, 0, 0.12)` | Modals, popovers |

### Spacing

| Variable | Default | Description |
|----------|---------|-------------|
| `--space-1` | `0.25rem` | Tightest gap |
| `--space-2` | `0.5rem` | |
| `--space-3` | `0.75rem` | |
| `--space-4` | `1rem` | Standard gap |
| `--space-5` | `1.5rem` | Container padding, card padding |
| `--space-6` | `2rem` | Section spacing |
| `--space-8` | `3rem` | Page-top spacing |

### Motion and focus

| Variable | Default | Description |
|----------|---------|-------------|
| `--transition-fast` | `0.2s ease` | Default transition timing |
| `--ring` | `0 0 0 3px color-mix(in srgb, var(--color-primary) 22%, transparent)` | Focus ring for all text fields |

### Typography

| Variable | Default | Description |
|----------|---------|-------------|
| `--font-sans` | `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` | Body and headings |
| `--font-mono` | `"JetBrains Mono", "Fira Code", "Cascadia Code", monospace` | Code blocks and inline `<code>` |

## Font Customization

The default theme imports Inter from Google Fonts at the top of `style.css`. To
switch:

1. Replace the `@import` line at the top of your `style.css` with the new font's
   `@import` (or self-host and `@font-face` it).
2. Override `--font-sans` on `:root`.
3. Override `--font-mono` if you want a different monospace stack.

```css
@import url('https://fonts.googleapis.com/css2?family=Fira+Sans:wght@400;600;700&display=swap');

:root {
  --font-sans: 'Fira Sans', -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-mono: 'Fira Code', monospace;
}
```

## Dark Theme Example

Invert the light/dark variables, then re-tune the shadows and surfaces for a dark
backdrop:

```css
:root {
  --color-bg: #0f172a;
  --color-text: #e2e8f0;
  --color-text-muted: #94a3b8;
  --color-primary: #f59e0b;
  --color-primary-hover: #d97706;
  --color-secondary: #14b8a6;
  --color-accent: #8b5cf6;
  --color-border: #334155;
  --color-card-bg: #1e293b;
  --color-danger: #f87171;
  --color-success: #4ade80;
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.40);
  --shadow-md: 0 4px 16px rgba(0, 0, 0, 0.45);
  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.55);
}
```

Also re-style form inputs (`background`, `color`, `caret-color`) and the
`<pre><code>` blocks if you want them distinct from the page background.

## Environment Variable

| Variable | Default | Description |
|----------|---------|-------------|
| `THEME_DIR` | `""` (empty) | Path to custom theme directory. Relative or absolute. Read at startup; restart required. |

`THEME_DIR` is loaded in `internal/config/config.go:117` and passed to
`template.NewTemplates` in `main.go:672-678`.

## Fallback Behavior

`compositeFS` (`internal/api/template/theme.go:44-58`) wraps the theme directory on
top of the embedded filesystem. For every request:

- If the file exists in `THEME_DIR/...`, that copy is served.
- Otherwise, the embedded default is served.

This is independent for static files and for each named template. You can override
`style.css` only and keep the embedded `search.js`, `auth.js`, `layout.html`, and
every other file. The fallbacks compose — partial themes are the normal case.

When `THEME_DIR` is empty or unset, no disk access happens for the content site;
all files come from the embedded filesystem.

## Template Overrides

Themes can override any of the 10 templates in `internal/api/template/pages/`. Place
your overrides in `themes/<name>/templates/`.

### Block contract

Templates use Go's `html/template` with two `{{define}}` blocks:

- **`layout.html`** must define `{{define "layout"}}…{{end}}` — the outer page
  shell (DOCTYPE, `<head>`, header, footer). It must call `{{template "body" .}}`
  inside a `<main>` element. Layouts are cloned per page in
  `internal/api/template/template.go:201-210`, so each page template is parsed
  against a fresh copy of the layout.
- **All other templates** must define `{{define "body"}}…{{end}}` — page-specific
  content that is rendered inside the layout's `<main>` element.

> If you override `layout.html`, the default `body` block from the embedded
> page templates still works. If you override only page templates, they continue
> to use the embedded `layout.html`. Either is supported; mix as you wish.

### Template Data Fields

The structs are defined in `internal/api/template/template.go:18-117`. Every page
embeds `LayoutData`, so the layout's `.` is always populated with the fields
below.

**`LayoutData`** — available to every page:

| Field | Type | Description |
|-------|------|-------------|
| `.PageTitle` | `string` | HTML `<title>` content |
| `.Title` | `string` | Page heading |
| `.Description` | `string` | Meta description |
| `.OGTitle` | `string` | Open Graph title |
| `.OGDesc` | `string` | Open Graph description |
| `.OGImage` | `string` | Open Graph image URL (may be empty) |
| `.NavigationItems` | `[]NavigationItem` | Nav items, each with `.Title`, `.URL`, `.IsActive` |
| `.CurrentPath` | `string` | Current request path |
| `.Lang` | `string` | Current language code (e.g. `"en"`, `"fr"`); **required** by `<html lang="…">` and `{{t}}` calls |
| `.LanguageLinks` | `[]LanguageLink` | Alternate-language links (`.Code`, `.Name`, `.URL`); empty if no translations exist |

**`IndexData`** — landing page:

| Field | Type | Description |
|-------|------|-------------|
| `.Posts` | `[]PostItem` | Post cards |
| `.Tags` | `[]string` | All available tags |

**`PostItem`** — a card in the post grid:

| Field | Type | Description |
|-------|------|-------------|
| `.Slug` | `string` | URL slug |
| `.Title` | `string` | Post title |
| `.MetaDescription` | `string` | Short description |
| `.ImageURL` | `string` | Cover image URL (may be empty) |
| `.ImageSrcset` | `string` | Responsive image `srcset` (may be empty) |
| `.ImageSizes` | `string` | Responsive image `sizes` (may be empty) |
| `.Author` | `string` | Author display name |
| `.Username` | `string` | Author username (for `/authors/<username>` links) |
| `.AuthorAvatarURL` | `string` | Avatar URL (may be empty) |
| `.CreatedAt` | `string` | Pre-formatted creation date |

**`ContentData`** — single post page:

| Field | Type | Description |
|-------|------|-------------|
| `.Slug` | `string` | Post URL slug |
| `.Body` | `template.HTML` | Rendered post body (safe HTML; do not re-escape) |
| `.Tags` | `[]string` | Post tags |
| `.Author` | `string` | Author display name |
| `.Username` | `string` | Author username |
| `.AuthorAvatarURL` | `string` | Avatar URL |
| `.CreatedAt` | `string` | Pre-formatted creation date |
| `.AllowComments` | `bool` | Whether comments are enabled |
| `.CustomFields` | `map[string]any` | Raw custom-field values keyed by name |
| `.CustomFieldsFormatted` | `[]FormattedField` | Display-formatted custom fields (`.Label`, `.Value`) |
| `.Comments` | `[]CommentItem` | Comments (`.Author`, `.Text`, `.CreatedAt`) |
| `.LanguageLinks` | `[]LanguageLink` | Inherited via `LayoutData`; also rendered inside the article for translated posts |

**`AuthorData`** — author page:

| Field | Type | Description |
|-------|------|-------------|
| `.AuthorName` | `string` | Author display name |
| `.Username` | `string` | Author username |
| `.AuthorAvatarURL` | `string` | Avatar URL |
| `.Posts` | `[]PostItem` | Author's posts |
| `.CustomFieldsFormatted` | `[]FormattedField` | Author "About" custom fields |

**`TagData`** — tag page:

| Field | Type | Description |
|-------|------|-------------|
| `.TagName` | `string` | Tag display name |
| `.Posts` | `[]PostItem` | Posts with this tag |

**`AuthPageData`** (`login.html`, `register.html`, `forgot_password.html`),
**`NotFoundData`** (`not_found.html`),
**`VerifyEmailData`** (`verify_email.html`),
**`ResetPasswordData`** (`reset_password.html`) — each embeds `LayoutData` only.
The dedicated structs exist so future per-page fields can be added without
breaking the layout contract.

### Example: Custom Layout

```html
{{define "layout"}}<!DOCTYPE html>
<html lang="{{.Lang}}">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{.PageTitle}}</title>
<meta name="description" content="{{.Description}}">
<meta property="og:title" content="{{.OGTitle}}">
<meta property="og:description" content="{{.OGDesc}}">
{{if .OGImage}}<meta property="og:image" content="{{.OGImage}}">{{end}}
<link rel="stylesheet" href="/static/style.css">
</head>
<body>
<header class="site-header">
<div class="container">
<a href="/" class="site-logo">My Custom Site</a>
</div>
</header>
<main class="container">{{template "body" .}}</main>
<footer class="site-footer">
<div class="container">
<p>Custom footer text</p>
</div>
</footer>
</body>
</html>{{end}}
```

> **Reminder:** if you change the math or syntax-highlighting libraries, your
> layout must load their CSS and JS instead of the katex / highlight.js ones
> pulled by the default. See [CDN Assets Pulled by the Default Layout](#cdn-assets-pulled-by-the-default-layout).

### Template Helper Functions

Registered in `internal/api/template/template.go:191-194`:

- `{{urlpath "string"}}` — URL-encodes a string. Used in tag links so non-ASCII
  tag names resolve correctly: `<a href="/tags/{{.TagName | urlpath}}">`.
- `{{t .Lang "ui.key"}}` — translates a UI string for the given language. Falls
  back through the configured languages and finally English; returns the key
  itself if no translation is found. The catalog lives in
  `internal/i18n/catalog.go` and the source strings in
  `internal/i18n/translations/*.toml`. Common keys:

  | Key | Default |
  |-----|---------|
  | `ui.login` | `Login` |
  | `ui.logout` | `Logout` |
  | `ui.register` | `Register` |
  | `ui.search` | `Search` |
  | `ui.search_posts` | `Search posts...` |
  | `ui.toggle_navigation` | `Toggle navigation` |
  | `ui.no_posts` | `No posts yet.` |
  | `ui.no_comments` | `No comments yet. Be the first to comment!` |
  | `ui.login_to_comment` | `Login to comment` |
  | `ui.by_author` | `by` |
  | `ui.comments` | `Comments` |
  | `ui.submit_comment` | `Submit Comment` |
  | `ui.back_to_home` | `Back to home` |
  | `ui.not_found_404` | `404` |
  | `ui.page_not_found` | `Page not found.` |
  | `ui.forgot_password` | `Forgot Password` |
  | `ui.reset_password` | `Reset Password` |
  | `ui.verify_email_title` | `Verify Email` |

  Run `ls internal/i18n/translations/` to see every supported language.

## Static File Overrides

Any file in `internal/api/template/static/` can be replaced by a same-named file
under `themes/<name>/static/`. The files are served at `/static/<filename>`.

| File | Used by | DOM contract |
|------|---------|--------------|
| `style.css` | All pages (linked from `layout.html`) | Defines every custom property and class the embedded templates rely on. Override freely. |
| `nav-auth.js` | `layout.html` | Expects `#nav-login`, `#nav-logout`; reads `localStorage.token` or `localStorage.auth_token`; handles `.nav-toggle` / `.site-nav` for mobile. |
| `search.js` | `layout.html` | Expects `.search-toggle`, `.search-box`, `#search-input`, `#search-dropdown`; fetches `/api/v1/public/search?q=…`. |
| `auth.js` | `login.html`, `register.html`, `forgot_password.html` | Expects `#login-form`/`#register-form`/`#forgot-form`, inputs named `username`/`name`/`email`/`password`, and `#auth-error` / `#auth-success` elements. POSTs to `/api/auth/login`, `/api/auth/register`, `/api/auth/forgot-password`. |
| `comments.js` | `content.html` (only when `AllowComments` is true) | Expects `#comment-form[data-slug]`, `#comment-error`, `#comment-success`, `#comment-login-link`; reads `localStorage.token`; POSTs to `/api/v1/content_items/<slug>/comments`. |
| `math.js` | `layout.html` | KaTeX auto-render; depends on katex from CDN (see below). |
| `verify-email.js` | `verify_email.html` | Reads `?token=` from the URL; calls `/api/auth/verify-email?token=…`; toggles `#auth-error` / `#auth-success`. |
| `reset-password.js` | `reset_password.html` | Reads `?token=` from the URL; POSTs to `/api/auth/reset-password`; expects `#new-password` input. |
| `highlight.min.js` | `layout.html` | Provides the global `hljs`. The default layout also runs `hljs.highlightAll()` on `DOMContentLoaded`. |

If you override any JS file, keep the DOM contract above — the default page
templates look for those exact ids and classes. If you change them, you must
also change the corresponding page template.

## CDN Assets Pulled by the Default Layout

The default `layout.html` (`internal/api/template/pages/layout.gohtml`) loads the
following from `cdn.jsdelivr.net`:

- `katex@0.16.11/dist/katex.min.css` and `katex.min.js` — math rendering.
- `highlight.js@11.11.1/styles/github-dark.min.css` — code-block theme.

If your theme drops katex and/or highlight.js (for example, you use a different
math library or a different syntax highlighter), update `layout.html` to drop the
matching `<link>` / `<script>` tags and override `math.js` and `highlight.min.js`
accordingly. Otherwise, the assets will be requested and unused.

## What Does NOT Theme

`THEME_DIR` only affects the public content site. It does not change:

- The admin SPA (`web/admin/`, served from `internal/api/static/admin/`).
- Any `/api/*` JSON response.
- Plugin behaviour, hooks, or capabilities.
- Email templates or other server-rendered channels.

To rebrand the admin panel, edit the Vue source under `web/admin/` and rebuild
with `make build-admin`. To change API responses, edit the handlers under
`internal/api/handlers/`.

## Theme Authoring Workflow

Recommended sequence for a new theme:

1. **Pick a base.** Decide whether you are re-skinning (CSS only), rearranging
   the layout (`layout.html` only), or rebuilding page templates individually.
2. **Create the directory.** `mkdir -p themes/mytheme/{static,templates}`.
3. **Copy only what you need.** Start with `static/style.css`; copy more files
   from `internal/api/template/static/` and `internal/api/template/pages/` only
   as your design requires.
4. **Author.** Use the [CSS Variable Reference](#css-variable-reference) and
   [Template Data Fields](#template-data-fields) sections as your contract.
5. **Restart Lesstruct.** `THEME_DIR` is read at startup; live edits to a theme
   file are not picked up until the server is restarted.
6. **Verify.** Hit each of the 10 pages (`/`, `/<slug>`, `/authors/<username>`,
   `/tags/<tag>`, `/404`, `/login`, `/register`, `/forgot-password`,
   `/verify-email?token=…`, `/reset-password?token=…`) and confirm your theme
   loads and the page renders. Run `go test ./internal/api/template/...` to
   confirm the embedded fallback paths still work.
7. **Maintain.** When upgrading Lesstruct, run the **theme development skill**
   (`lesstruct-theme-development`) to detect drift between your theme files and
   any new embedded defaults.

## Troubleshooting

| Symptom | Likely cause |
|---------|--------------|
| Theme changes have no effect | `THEME_DIR` is empty, points to a missing directory, or the server was not restarted. |
| Page renders, but no styles | `<link rel="stylesheet" href="/static/style.css">` is missing from your `layout.html`. |
| Search box or comment form is dead | You overrode `search.js` / `comments.js` / `layout.html` and the DOM ids no longer match. Restore the ids, or update the JS to match your new layout. |
| Tag links are broken for non-ASCII tags | The href was built with `.TagName` instead of `{{.TagName | urlpath}}`. |
| `{{t .Lang "ui.x"}}` shows the literal key | The translation is missing in `internal/i18n/translations/<lang>.toml`. Add it, or change the key. |
| KaTeX or highlight.js missing | Your `layout.html` does not load the CDN CSS/JS, or the assets are blocked by the network. |


---


## Section: Skills

### Development vs Production Mode

Source: [/skills/plugin-development/dev-vs-prod/index.html](/skills/plugin-development/dev-vs-prod/index.html)
Reference page for Development vs Production Mode.

# Development vs Production Mode

Lesstruct's plugin system supports two modes, toggled by the same
`DEV_MODE` env var used by the admin SPA.

## Production mode (default)

When `DEV_MODE` is unset, false, or any value other than the string
`"true"` (the runtime uses `getEnvBool`, which is permissive about the
exact spelling), the plugin system loads all `.wasm` files in
`plugins/` once at startup. To apply changes, restart the server.

This is the recommended mode for any non-development environment.

## Development mode (`DEV_MODE=true`)

When `DEV_MODE=true`, the plugin system starts a filesystem watcher
on the `plugins/` directory. When a `.wasm` file is created, modified,
or removed, the watcher:

1. Debounces filesystem events by 150 ms.
2. Reloads the affected `.wasm` file.
3. Unregisters the previous version's hooks.
4. Re-runs discovery on the new version.
5. Logs the reload.

The watcher is **non-recursive**: it only watches top-level files in
`plugins/`. Subdirectories are ignored. If you organise your plugins
into subdirectories (e.g. `plugins/team-a/foo.wasm`), they will not
be hot-reloaded; you will need to restart Lesstruct.

The watcher is also non-recursive for **deletions**: removing a
`.wasm` file unloads it, but the new state of `plugins/` is not
re-scanned for other changes.

## Shared with admin SPA HMR

`DEV_MODE=true` is the same env var the admin panel uses to enable
hot-module replacement (HMR) on the Vue dev server. Toggling it on for
plugin hot-reload also enables admin-panel HMR; toggling it off for
production plugin loading also disables admin HMR.

If you need plugin hot-reload but production admin (or vice versa),
you will need to either:

- Run a separate Lesstruct instance for dev and prod.
- Patch the runtime to read a separate env var (not currently supported).

## When to use DEV_MODE

- During plugin development: `DEV_MODE=true` to iterate without
  restarting the server.
- In CI / production: `DEV_MODE=false` (or unset) for stable plugin
  loading.

## Caveats

- Hot-reload is not atomic. If the new version of the plugin
  introduces a runtime error (e.g., a panicking hook), the watcher
  logs the error and the host's hook table is updated to skip the
  failed plugin. Subsequent content operations will not invoke the
  failed hook.
- The watcher does not reload manifest changes. If you change the
  `<name>.manifest` file, restart Lesstruct.
- The watcher does not reload changes to other files (e.g., adding a
  brand-new `.wasm` to `plugins/` while the server is running). It
  only watches the top-level entries of `plugins/`.

## Verifying the mode

To confirm which mode Lesstruct is running in, check the startup log:

- Production: `Production mode activated - startup-load enabled` (or
  similar; exact wording may vary).
- Development: `Dev mode activated - hot-reload enabled` (or similar).


---

### Content Transform Plugin

Source: [/skills/plugin-development/examples/go-content-transform/README/index.html](/skills/plugin-development/examples/go-content-transform/README/index.html)
Reference page for Content Transform Plugin.

# Content Transform Plugin

A Lesstruct plugin that transforms content before it is saved by uppercasing the title.

## Prerequisites

- [TinyGo](https://tinygo.org/getting-started/install/) 0.28+

## Build

```bash
tinygo build -o content-transform.wasm -target=wasi main.go
```

## Install

Copy the compiled WASM file to the Lesstruct plugins directory:

```bash
cp content-transform.wasm <lesstruct-project>/plugins/
```

## Expected Behavior

When content is saved, the plugin intercepts the `before_save` hook and uppercases the `"title"` field value. For example:

- Input: `{"title":"my blog post", "content":"..."}`
- Output: `{"title":"MY BLOG POST", "content":"..."}`


---

### Hello World Plugin

Source: [/skills/plugin-development/examples/go-hello-world/README/index.html](/skills/plugin-development/examples/go-hello-world/README/index.html)
Reference page for Hello World Plugin.

# Hello World Plugin

A minimal Lesstruct plugin that responds when loaded by the plugin system.

## Prerequisites

- [TinyGo](https://tinygo.org/getting-started/install/) 0.28+

## Build

```bash
tinygo build -o hello-world.wasm -target=wasi main.go
```

## Install

Copy the compiled WASM file to the Lesstruct plugins directory:

```bash
cp hello-world.wasm <lesstruct-project>/plugins/
```

## Expected Behavior

When Lesstruct starts, it loads the plugin and calls `hook_on_plugin_loaded`. The plugin returns a JSON response:

```json
{"status":"loaded","plugin":"hello-world","input_size":"..."}
```


---

### Validation Plugin

Source: [/skills/plugin-development/examples/go-validation/README/index.html](/skills/plugin-development/examples/go-validation/README/index.html)
Reference page for Validation Plugin.

# Validation Plugin

A Lesstruct plugin that validates content before it is saved by rejecting empty titles.

## Prerequisites

- [TinyGo](https://tinygo.org/getting-started/install/) 0.28+

## Build

```bash
tinygo build -o validation.wasm -target=wasi main.go
```

## Install

Copy the compiled WASM file to the Lesstruct plugins directory:

```bash
cp validation.wasm <lesstruct-project>/plugins/
```

## Expected Behavior

When content is saved, the plugin intercepts the `before_save` hook and checks if the `"title"` field is empty.

- If the title is empty, the plugin returns an error response:
  ```json
  {"error":"validation failed","message":"title must not be empty"}
  ```
- If the title is not empty, the original content passes through unchanged.


---

### Install Paths

Source: [/skills/plugin-development/install-paths/index.html](/skills/plugin-development/install-paths/index.html)
Reference page for Install Paths.

# Install Paths

> **Path note.** The exact skill directory location depends on the agent.
> The patterns below are based on common conventions; if your agent uses
> a different path, adjust accordingly. The `README.md` of this skill is
> the canonical install guide; this file is a quick reference.

## Claude Code

```bash
# Copy the skill into Claude Code's skill directory.
cp -r lesstruct-plugin-development ~/.claude/skills/lesstruct-plugin-development
```

Claude Code loads skills from `~/.claude/skills/` by default. If you have
configured a custom path, substitute it.

## OpenCode

```bash
# OpenCode uses the same skills directory as Claude Code.
cp -r lesstruct-plugin-development ~/.claude/skills/lesstruct-plugin-development
```

If you have multiple agents, you can symlink instead:

```bash
ln -s "$(pwd)/lesstruct-plugin-development" ~/.claude/skills/lesstruct-plugin-development
```

## OpenClaw

> **Note:** OpenClaw's skill directory path is hypothetical; check the
> OpenClaw documentation for the actual location.

```bash
cp -r lesstruct-plugin-development ~/.openclaw/skills/lesstruct-plugin-development
```

## Hermes

> **Note:** Hermes' skill directory path is hypothetical; check the
> Hermes documentation for the actual location.

```bash
cp -r lesstruct-plugin-development ~/.hermes/skills/lesstruct-plugin-development
```

## Generic agent

Any agent that loads Markdown files with YAML frontmatter from a
`skills/` directory should work. The minimum contract the agent must
support:

```yaml
---
name: lesstruct-plugin-development
description: <one-paragraph description>
---
```

Plus a `SKILL.md` filename (case-insensitive on most filesystems).

To install for a generic agent whose skill directory you know:

```bash
cp -r lesstruct-plugin-development "<agent-config-dir>/skills/lesstruct-plugin-development"
```

## Optional: `customize.toml`

This skill includes a `customize.toml` file for BMad agents. Agents that
do not understand BMad's customization format will ignore the file. You
can delete it without affecting the skill's behaviour in non-BMad
agents:

```bash
rm lesstruct-plugin-development/customize.toml
```

## Verifying the install

After installing, restart your agent and ask it to perform a trivial
task related to Lesstruct plugins. For example:

> "List the three hooks the Lesstruct plugin host currently invokes."

If the agent responds with `before_save`, `after_create`, and
`after_publish` (and notes that `on_plugin_loaded` and `before_delete`
are reserved), the skill is loaded correctly. If the agent does not
know what you are talking about, check the agent's skill directory
path and that the `SKILL.md` is in the right place.


---

### Plugin Capabilities

Source: [/skills/plugin-development/plugin-capabilities/index.html](/skills/plugin-development/plugin-capabilities/index.html)
Reference page for Plugin Capabilities.

# Plugin Capabilities

> **Snapshot notice.** This is the **user-facing** snapshot of the Lesstruct
> plugin capabilities reference, bundled with the `lesstruct-plugin-development`
> skill so the skill is self-contained. The canonical, developer-facing
> version lives in the Lesstruct repository at `docs/plugin-capabilities.md`
> and references source-tree paths; this version is rewritten for someone
> with a binary Lesstruct install and a `plugins/` directory.
>
> If you have a newer Lesstruct release, re-export this file from the repo to
> refresh the snapshot.

Plugins can request access to host resources (HTTP, database, logging) by declaring them in a **capability manifest** file placed alongside the `.wasm` file.

## Quick Start

Create `<plugin-name>.manifest` next to `<plugin-name>.wasm` in the `plugins/` directory:

```toml
name = "my-enrichment-plugin"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
database = ["read:content", "write:content"]
```

If no `.manifest` file exists, the plugin gets **zero** host functions — same as before.

## Manifest Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Plugin name (must be non-empty) |
| `version` | Yes | Semantic version of the plugin (must be non-empty) |
| `capabilities.http` | No | List of allowed URL patterns |
| `capabilities.database` | No | List of allowed database permissions |

### URL Patterns

URLs are matched using simple prefix matching. Use `*` as a suffix for wildcards:

```toml
http = [
    "https://api.example.com/*",         # Match all paths on api.example.com
    "https://jsonplaceholder.typicode.com/todos/1",  # Exact match only
]
```

- `https://api.example.com/*` matches `https://api.example.com/v1/data`, `https://api.example.com/foo/bar`, etc.
- Patterns are checked in order; the first match wins.
- The trailing `*` is the only wildcard supported. Regex patterns are not accepted.

### Database Permissions

Database permissions follow the format `<operation>:<table>`:

| Permission | Allows |
|-----------|--------|
| `read:content` | SELECT queries on the `content_items` table |
| `read:media` | SELECT queries on the `media_files` table |
| `read:users` | SELECT queries on the `users` table |
| `write:content` | INSERT/UPDATE/DELETE on the `content_items` table (including the `custom_fields` column) |
| `write:media` | INSERT/UPDATE/DELETE on the `media_files` table |
| `write:users` | INSERT/UPDATE/DELETE on the `users` table |

The host validates each SQL query to extract the target table name and checks it against the manifest.

#### Table Access Scope

Of the 11 tables in the Lesstruct database, only **three** are grantable
to plugins: `content_items` (normalised to `content`), `media_files`
(normalised to `media`), and `users`. The other eight tables —
`comments`, `blocked_emails`, `failed_login_attempts`,
`verification_tokens`, `password_reset_tokens`, `email_update_tokens`,
`soft_deleted_content`, and `api_keys` — are inaccessible to plugins by
design. A plugin cannot query or modify them via `db_query` or
`db_exec`.

## Available Host Functions

### HTTP

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.http_get` | `(url_ptr, url_len, headers_json_ptr, headers_json_len) -> result_offset` | Perform an HTTP GET request |
| `lesstruct.http_post` | `(url_ptr, url_len, headers_json_ptr, headers_json_len, body_ptr, body_len) -> result_offset` | Perform an HTTP POST request |

### Database

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.db_query` | `(sql_ptr, sql_len, params_json_ptr, params_json_len) -> result_offset` | Execute a SELECT query |
| `lesstruct.db_exec` | `(sql_ptr, sql_len, params_json_ptr, params_json_len) -> result_offset` | Execute an INSERT/UPDATE/DELETE |

### Logging

| Function | Signature | Description |
|----------|-----------|-------------|
| `lesstruct.log_info` | `(message_ptr, message_len) -> void` | Log an informational message to the host |
| `lesstruct.log_error` | `(message_ptr, message_len) -> void` | Log an error message to the host |

Logging functions are always available when any manifest exists — no capability declaration needed.

## Result Format

All host functions return results as JSON at offset `4096` in WASM memory.

### Success

```json
{
    "status": 200,
    "body": "...",
    "headers": {"Content-Type": "application/json"}
}
```

### Error

```json
{
    "error": "url_not_allowed",
    "message": "URL \"https://evil.com\" not in capability manifest http allowlist"
}
```

> **Offset collision.** All four data host functions (`http_get`,
> `http_post`, `db_query`, `db_exec`) write their result to the same
> fixed offset (`4096`). If your plugin calls `http_get` and then
> `db_query` before reading the first result, the second overwrites
> the first. Read each result before invoking the next host function.

## Security Model

| Concern | Mechanism |
|---------|-----------|
| URL allowlisting | Each HTTP call is checked against the manifest's `http` patterns before the request is made |
| Table-level DB access | SQL queries are parsed to extract the target table, then checked against `database` permissions |
| Response size limit | HTTP response bodies are capped at 1MB |
| Request timeout | HTTP requests have a 10-second timeout (set once at startup); DB queries use the parent request context |
| Memory isolation | Plugins remain in the WASM sandbox; host functions only write results to controlled offsets |
| Audit logging | Only **denied** host function calls are logged at the host level. Successful calls produce no log line. Use `log_info` from your plugin to record what you did. |

### SQL Parser Limitations

The host uses a hand-rolled substring parser to extract the target
table from each query. The parser looks for the first occurrence of
`FROM`, `INSERT INTO`, `UPDATE`, or `DELETE FROM` and reads the first
identifier after it.

The parser does **not** handle:

- Common Table Expressions (`WITH ... SELECT`).
- Subqueries.
- SQL comments (`--` or `/* */`).
- Quoted identifiers.
- Multi-statement queries.

Write a single explicit `SELECT`/`INSERT`/`UPDATE`/`DELETE`
statement per host function call.

## Example: HTTP Enrichment Plugin

A plugin that calls `lesstruct.http_get` to enrich a content item
during `before_save`:

```go
//go:wasmimport lesstruct http_get
func httpGet(urlPtr, urlLen, headersPtr, headersLen uint32) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    url := "https://api.example.com/items/lookup"
    // Write url to WASM memory, call httpGet, read result from offset 4096...
    // Parse JSON, extract a value, set it in customFields, write back to resultBuf.
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

Manifest:

```toml
name = "http-enrich"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
```

> **Note.** The Lesstruct SDK does not currently ship a
> `//go:wasmimport` declaration for `http_get` (or any other host
> function). The declarations are bundled with this skill at
> `references/host-function-imports.go.txt` — copy that block into
> your `main.go` to use the host functions.

## Example: Database Plugin

A plugin that reads content metadata during a `before_save` hook:

```go
//go:wasmimport lesstruct db_query
func dbQuery(
    sqlPtr, sqlLen uint32,
    paramsPtr, paramsLen uint32,
) uint32

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    sql := "SELECT COUNT(*) FROM content_items WHERE post_type = ?"
    params := `["product"]`

    // Write SQL and params to WASM memory, call dbQuery, read result from offset 4096...
    resultOffset := dbQuery(sqlPtr, sqlLen, paramsPtr, paramsLen)
    // Parse JSON result from resultOffset...
}
```

Manifest:

```toml
name = "db-plugin"
version = "1.0.0"

[capabilities]
database = ["read:content"]
```


---

### Plugin Pre-Flight Checklist

Source: [/skills/plugin-development/plugin-checklist/index.html](/skills/plugin-development/plugin-checklist/index.html)
Reference page for Plugin Pre-Flight Checklist.

# Plugin Pre-Flight Checklist

Use this checklist to audit a plugin before declaring it ready. Each
item is a hard pass / fail.

## File layout

- [ ] Plugin file is `<name>.wasm` in `plugins/`.
- [ ] Optional `<name>.manifest` is in the same directory as the `.wasm`.
- [ ] Plugin filename (without extension) and the manifest's `name` field
      match. The host does not enforce this today, but matching them is
      good hygiene.

## Hooks

- [ ] Plugin exports at least one of the three currently-invoked hooks:
      `hook_before_save`, `hook_after_create`, `hook_after_publish`.
- [ ] Plugin does **not** rely on `hook_on_plugin_loaded` or
      `hook_before_delete`. Both are defined in the host but not
      currently invoked. Plugins that only export one of these will
      load but never fire.
- [ ] Each hook's result is a JSON object containing (at most)
      `customFields` for mutation. The host reads only `customFields`
      back; other fields in the result are ignored.
- [ ] `__hook_result_len` is exported only if the result length differs
      from the input length. The export is optional; the host uses
      `inputLen` as the result length when the export is missing.

## Manifest

- [ ] `name` is set and non-empty.
- [ ] `version` is set and non-empty.
- [ ] `capabilities.http` is set to a list of URL patterns if the
      plugin uses `http_get` or `http_post`.
- [ ] `capabilities.database` is set to a list of
      `read|write:content|media|users` permissions if the plugin uses
      `db_query` or `db_exec`.
- [ ] URL patterns use trailing `*` only (no regex, no `?`).
- [ ] URL patterns are ordered so the most specific match comes first
      (the first match wins).

## Host function calls

- [ ] If the plugin uses `http_get` or `http_post`, the manifest's
      `http` patterns cover the actual URLs the plugin will request.
- [ ] If the plugin uses `db_query` or `db_exec`, the manifest's
      `database` permissions cover the actual table names in the
      queries (and the actual operation: `db_query` is always
      `read`, `db_exec` is always `write`).
- [ ] Every SQL query is a single explicit `SELECT` / `INSERT` /
      `UPDATE` / `DELETE` statement. No CTEs, no subqueries, no
      comments, no quoted identifiers, no multi-statement queries.
- [ ] The plugin reads each host function's result from offset `4096`
      before invoking the next host function. All four data host
      functions share the same result offset.

## Build

- [ ] Compiled with `tinygo build -target=wasi` (Go),
      `cargo build --target wasm32-wasip1` (Rust), or
      `clang --target=wasm32-wasi` (C/C++).
- [ ] Compiled `.wasm` is well under 64 MB (typical TinyGo plugin:
      < 1 MB).
- [ ] For Go plugins that use host functions, the
      `//go:wasmimport` block from
      `references/host-function-imports.go.txt` is copied into the
      plugin's `main.go`.

## Deployment

- [ ] Lesstruct was restarted after the last `plugins/` change
      (unless `DEV_MODE=true` is set; in that case, the watcher
      picks up new `.wasm` files automatically).
- [ ] The `.wasm` is the top-level file in `plugins/`. Subdirectories
      are not watched.

## Smoke test

- [ ] Run the smoke test from
      [`SKILL.md` Step 8](../../SKILL.md#step-8-verify-manual) and
      confirm the relevant hook fires and any `customFields`
      modification is reflected in the saved item.
- [ ] For host function calls, check the Lesstruct log for
      "blocked" messages. If the call was permitted, no log line is
      produced (audit logging is partial); use `log_info` from the
      plugin to record what it did.

## Documentation

- [ ] A `plugins/<name>.README` records the Lesstruct version the
      plugin was authored against, the hooks it uses, and the
      capabilities declared in the manifest.


---

### Plugin Development Guide

Source: [/skills/plugin-development/plugin-development/index.html](/skills/plugin-development/plugin-development/index.html)
Reference page for Plugin Development Guide.

# Plugin Development Guide

> **Snapshot notice.** This is the **user-facing** snapshot of the Lesstruct
> plugin development guide, bundled with the `lesstruct-plugin-development`
> skill so the skill is self-contained. The canonical, developer-facing
> version lives in the Lesstruct repository at `docs/plugin-development.md`
> and references source-tree paths; this version is rewritten for someone
> with a binary Lesstruct install and a `plugins/` directory.
>
> If you have a newer Lesstruct release, re-export this file from the repo to
> refresh the snapshot.

Lesstruct supports WebAssembly (WASM) plugins that extend functionality through hooks. Plugins are compiled from Go, Rust, C/C++, or any language that targets WASI.

## How Plugins Work

1. Compile your plugin to a `.wasm` file targeting the WASI runtime.
2. Place the `.wasm` file (and an optional `.manifest` file) in the `plugins/` directory.
3. Lesstruct discovers and loads the plugin at startup.
4. The plugin system calls exported hook functions at the appropriate lifecycle points.

> **See also:** [Plugin Capabilities](plugin-capabilities.md) — host functions for HTTP, database, and logging. If your plugin needs to call external APIs or query the database, add a capability manifest.

The `plugins/` directory is a relative path from the Lesstruct working directory. It is not configurable via env or flag.

## Plugin Capabilities (Host Functions)

Plugins that need access to host resources (HTTP, database, logging) declare their requirements in a **capability manifest** — a TOML file placed alongside the `.wasm` file.

### Manifest File

Create `<plugin-name>.manifest` next to `<plugin-name>.wasm`:

```toml
name = "my-enrichment-plugin"
version = "1.0.0"

[capabilities]
http = ["https://api.example.com/*"]
database = ["read:content"]
```

If no `.manifest` file exists, the plugin runs with **zero** host functions — hooks only.

### Available Host Functions

| Function | Import Path | Description |
|----------|-------------|-------------|
| `lesstruct.http_get` | `lesstruct.http_get` | HTTP GET request (URL allowlist checked) |
| `lesstruct.http_post` | `lesstruct.http_post` | HTTP POST request (URL allowlist checked) |
| `lesstruct.db_query` | `lesstruct.db_query` | Execute SELECT query (table access checked) |
| `lesstruct.db_exec` | `lesstruct.db_exec` | Execute INSERT/UPDATE/DELETE (table access checked) |
| `lesstruct.log_info` | `lesstruct.log_info` | Log info message to host |
| `lesstruct.log_error` | `lesstruct.log_error` | Log error message to host |

The full reference lives in [Plugin Capabilities](plugin-capabilities.md).

### Host Function Import (Go/TinyGo)

Unlike hooks (which use `//export`), host functions use `//go:wasmimport`:

```go
//go:wasmimport lesstruct http_get
func httpGet(urlPtr, urlLen uint32, headersPtr, headersLen uint32) uint32

//go:wasmimport lesstruct log_info
func logInfo(msgPtr, msgLen uint32)
```

> **Note.** The Lesstruct SDK currently ships only the constant names for
> these host functions, not the `//go:wasmimport` declarations themselves.
> The full block is bundled with this skill at
> `references/host-function-imports.go.txt` — copy that into your
> plugin's `main.go`.

## Hook System

### Available Hooks

The host invokes three hooks today:

| Hook | WASM Export Name | Description |
|------|------------------|-------------|
| BeforeSaveContent | `hook_before_save` | Called before content is saved (create or update) |
| AfterCreateContent | `hook_after_create` | Called after content is created |
| AfterPublishContent | `hook_after_publish` | Called after content is published |

> **Reserved hooks — do not rely on them.** Two additional hooks
> (`on_plugin_loaded`, `before_delete`) are defined in the host but are
> not currently invoked by any production code path. If your plugin
> exports only one of these, the plugin will load successfully but
> the hook will never fire. Use one of the three invoked hooks
> instead.

### Failure Mode

When a hook returns an error, the request fails. The content service
maps the error to a 500 response and the content is not saved (for
`before_save`) or the error is logged (for `after_create` /
`after_publish`, whose results are not stored). There is no automatic
rollback of prior hooks in a chain.

## System Fields

System fields are special custom field values managed by plugins. They
are defined in the post type TOML schema with the `system = true` flag
and stored alongside regular custom fields in the `customFields` JSON
map.

### Hook Data Format

When `before_save` or `after_create` hooks execute, the host sends a
JSON object with eight fields:

```json
{
  "contentId": 0,
  "userId": 42,
  "title": "My Product",
  "content": "...",
  "tags": ["featured", "sale"],
  "status": "draft",
  "postType": "product",
  "customFields": {
    "price": 29.99,
    "internal_sku": "SKU-001",
    "sync_status": "synced"
  }
}
```

Field notes:

- `contentId` is `0` on create, the existing content's ID on update.
- `userId` is the authenticated user performing the action.
- `status` is one of `draft`, `published`, `archived`, or a custom value.
- `postType` is `post`, `page`, or a custom type.
- `customFields` contains both regular custom fields and system fields.

A complete example is bundled with this skill at
`references/hook-data-example.json`.

### Reading System Fields

In a `before_save` hook, read system field values from `customFields` in the JSON input:

```go
//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)

    var data map[string]any
    json.Unmarshal(input, &data)

    if cf, ok := data["customFields"].(map[string]any); ok {
        if sku, ok := cf["internal_sku"].(string); ok {
            // Read existing system field value: "SKU-001"
            _ = sku
        }
    }

    modified, _ := json.Marshal(data)
    copy(resultBuf[:], modified)
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

### Writing System Fields

A plugin can set or modify system field values in `customFields`. The
host validates plugin-set system field values against their schema
definition (type, required, options, min/max). Validation runs in the
content service **after** the hook returns — the hook itself does not
see validation errors.

> If the plugin writes an invalid system field value, the API call
> fails with a 500 and the content is not saved. The hook does not
> receive the validation error; the error is mapped to the API
> caller.

```go
//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)

    var data map[string]any
    json.Unmarshal(input, &data)

    cf, ok := data["customFields"].(map[string]any)
    if !ok {
        cf = make(map[string]any)
        data["customFields"] = cf
    }

    cf["internal_sku"] = "SKU-002"
    cf["sync_status"] = "pending"

    modified, _ := json.Marshal(data)
    copy(resultBuf[:], modified)
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}
```

### What the Host Reads Back from the Result

The host only reads back the `customFields` key from the hook's
result. The plugin may write other keys (`title`, `tags`, etc.) into
its result JSON, but the host ignores them. To mutate the content
item, the plugin must write `customFields` and return a JSON object
containing it.

### Important Notes

- System field values are only preserved when set through `before_save` hooks. User-submitted system field values are stripped for security.
- `after_create` and `after_publish` hooks can read but should not write system fields — their results are not stored (notification-style hooks).
- If no plugin handles a `before_save` hook, system fields are stripped as usual and content creation proceeds normally.

## Memory Protocol

### Hook Functions vs Host Functions

- **Hooks** use `//export` — the plugin exports them, the host calls them. Data flows via `(offset, length) -> resultOffset` at offset `65536` (64KB).
- **Host functions** use `//go:wasmimport` — the host exports them, the plugin calls them. The plugin manages offsets. The host writes results to a fixed offset of `4096`. See [Plugin Capabilities](plugin-capabilities.md).

### Hook Function Signature

Every hook function must follow this signature:

```
(offset: uint32, length: uint32) -> resultOffset: uint32
```

### Data Flow

1. The host writes input data to WASM linear memory at offset `65536` (64KB).
2. The host calls the hook function with `(65536, dataLength)`.
3. The plugin reads input from `(offset, offset+length)`.
4. The plugin writes the result to WASM memory.
5. The plugin returns the offset where the result starts.
6. The host reads the result from the returned offset.

If the plugin returns `0` (or empty bytes), the host treats the
result as "no change" and uses the original input.

### Variable-Length Results

If the result length differs from the input length, export `__hook_result_len`:

```
(inputLen: uint32) -> resultLen: uint32
```

The export is **optional**. If it is missing, the host assumes the
result length equals the input length.

### Data Format

All data passed through hooks is JSON-encoded bytes (UTF-8).

### Required Exports

Every plugin `.wasm` file must export:

- `memory` — Linear memory (auto-exported by most compilers).
- One or more `hook_*` functions from the [Available Hooks](#available-hooks) table.
- Optional: `__hook_result_len` (only when result length differs from input length).

## Development vs Production Mode

- **Production** (default): Plugins are loaded once at startup. To reload, restart the server.
- **Development** (`DEV_MODE=true`): Plugins are hot-reloaded when `.wasm` files change via filesystem watcher.

> **`DEV_MODE` is shared with the admin SPA.** Toggling the same env
> var to enable plugin hot-reload also enables admin-panel HMR. If
> you want production plugin loading but dev admin HMR, set
> `DEV_MODE=false`; if you want plugin hot-reload, the admin panel
> will also be in dev mode.

The watcher is non-recursive: subdirectories of `plugins/` are not
watched. It debounces filesystem events by 150 ms and reloads only
the affected `.wasm` files. On reload, the host unregisters the
plugin's old hooks and re-runs discovery.

For the full set of DEV_MODE caveats, see
[`references/dev-vs-prod.md`](dev-vs-prod.md).

## Go / TinyGo Guide

### Prerequisites

- Go 1.20+
- [TinyGo](https://tinygo.org/getting-started/install/) 0.28+

### Project Setup

```go
// go.mod
module example.com/my-plugin

go 1.21
```

```go
package main

import "unsafe"

var resultBuf [4096]byte

//export hook_before_save
func hookBeforeSave(offset uint32, length uint32) uint32 {
    input := unsafe.Slice((*byte)(unsafe.Pointer(uintptr(offset))), length)
    var data map[string]any
    json.Unmarshal(input, &data)
    // ... modify data ...
    modified, _ := json.Marshal(data)
    copy(resultBuf[:], modified)
    return uint32(uintptr(unsafe.Pointer(&resultBuf[0])))
}

func main() {}
```

### Build

```bash
tinygo build -o plugin.wasm -target=wasi main.go
```

### TinyGo Notes

- Use `-target=wasi` (not `wasm32-wasi`).
- Export functions with `//export function_name` directive (no space after `//`).
- `unsafe` package is needed for WASM memory operations.
- No standard library networking or file I/O in WASI sandbox.

### Bundled Examples

This skill ships four Go/TinyGo example plugins under
`references/examples/`:

| Example | Hook | Use as starting point for |
|---------|------|---------------------------|
| `go-hello-world` | `on_plugin_loaded` (reserved) | Syntax reference only — the hook will not fire |
| `go-content-transform` | `before_save` | Simple in-place content modification |
| `go-system-fields` | `before_save` + `after_create` | Reading and writing system fields |
| `go-validation` | `before_save` | Validation that rejects the save |

Copy one of the working examples (any except `go-hello-world`) to
your source tree and modify it.

## Rust Guide

### Prerequisites

- Rust 1.70+
- `wasm32-wasip1` target

### Install Target

```bash
rustup target add wasm32-wasip1
```

### Project Setup

```toml
# Cargo.toml
[package]
name = "lesstruct-plugin"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]
```

```rust
// src/lib.rs
static mut RESULT_BUF: [u8; 4096] = [0; 4096];

#[no_mangle]
pub extern "C" fn hook_before_save(offset: u32, length: u32) -> u32 {
    let memory = unsafe {
        std::slice::from_raw_parts(offset as *const u8, length as usize)
    };
    // Process memory, write result to RESULT_BUF
    unsafe { RESULT_BUF.as_mut_ptr() as u32 }
}
```

### Build

```bash
cargo build --release --target wasm32-wasip1
# Output: target/wasm32-wasip1/release/lesstruct_plugin.wasm
```

> **No official Rust examples ship in the Lesstruct repo today.**
> The memory protocol above applies directly. Validate your `.wasm`
> with `wasm-tools validate plugin.wasm` before deploying.

## C/C++ Guide

### Prerequisites

- Clang or GCC with WASI support
- [WASI SDK](https://github.com/WebAssembly/wasi-sdk) (recommended)

### Project Setup

```c
// plugin.c
#include <stdint.h>
#include <string.h>

static uint8_t result_buf[4096];

__attribute__((export_name("hook_before_save")))
uint32_t hook_before_save(uint32_t offset, uint32_t length) {
    uint8_t *input = (uint8_t *)offset;

    const char *response = "{\"customFields\":{\"price\":0}}";
    memcpy(result_buf, response, strlen(response));

    return (uint32_t)result_buf;
}
```

### Build

```bash
# With WASI SDK
/opt/wasi-sdk/bin/clang --sysroot=/opt/wasi-sdk/share/wasi-sysroot \
    -O2 -o plugin.wasm plugin.c

# With clang and WASI target
clang --target=wasm32-wasi -o plugin.wasm plugin.c
```

> **No official C/C++ examples ship in the Lesstruct repo today.**
> The memory protocol above applies directly. Validate your `.wasm`
> with `wasm-tools validate plugin.wasm` before deploying.

## Testing Plugins

1. Compile the plugin to `.wasm`.
2. Copy the `.wasm` file to the `plugins/` directory.
3. Restart Lesstruct (or use `DEV_MODE=true` for hot-reload).
4. Observe behaviour in the application logs.

For a manual smoke test per hook, see
[`references/plugin-checklist.md`](plugin-checklist.md).

If you observe your hooks firing on create but not on delete, or
`on_plugin_loaded` not firing at all, you have hit a hook that is
defined but not currently invoked. See the
[Available Hooks](#available-hooks) section above.


---

### Install Paths

Source: [/skills/theme-development/install-paths/index.html](/skills/theme-development/install-paths/index.html)
Reference page for Install Paths.

# Install Paths

> **Path note.** The exact skill directory location depends on the agent. The
> patterns below are based on common conventions; if your agent uses a
> different path, adjust accordingly. The `README.md` of this skill is the
> canonical install guide; this file is a quick reference.

## Claude Code

```bash
# Copy the skill into Claude Code's skill directory.
cp -r lesstruct-theme-development ~/.claude/skills/lesstruct-theme-development
```

Claude Code loads skills from `~/.claude/skills/` by default. If you have
configured a custom path, substitute it.

## OpenCode

```bash
# OpenCode uses the same skills directory as Claude Code.
cp -r lesstruct-theme-development ~/.claude/skills/lesstruct-theme-development
```

If you have multiple agents, you can symlink instead:

```bash
ln -s "$(pwd)/lesstruct-theme-development" ~/.claude/skills/lesstruct-theme-development
```

## OpenClaw

> **Note:** OpenClaw's skill directory path is hypothetical; check the OpenClaw
> documentation for the actual location.

```bash
cp -r lesstruct-theme-development ~/.openclaw/skills/lesstruct-theme-development
```

## Hermes

> **Note:** Hermes' skill directory path is hypothetical; check the Hermes
> documentation for the actual location.

```bash
cp -r lesstruct-theme-development ~/.hermes/skills/lesstruct-theme-development
```

## Generic agent

Any agent that loads Markdown files with YAML frontmatter from a `skills/`
directory should work. The minimum contract the agent must support:

```yaml
---
name: lesstruct-theme-development
description: <one-paragraph description>
---
```

Plus a `SKILL.md` filename (case-insensitive on most filesystems).

To install for a generic agent whose skill directory you know:

```bash
cp -r lesstruct-theme-development "<agent-config-dir>/skills/lesstruct-theme-development"
```

## Optional: `customize.toml`

This skill includes a `customize.toml` file for BMad agents. Agents that do
not understand BMad's customization format will ignore the file. You can
delete it without affecting the skill's behaviour in non-BMad agents:

```bash
rm lesstruct-theme-development/customize.toml
```

## Verifying the install

After installing, restart your agent and ask it to perform a trivial task
related to Lesstruct themes. For example:

> "List the CSS variables in my Lesstruct default theme."

If the agent responds with the variables from this skill's
[`theme-development.md`](theme-development.md) (Brand colors, Status colors,
Layout, etc.), the skill is loaded correctly. If the agent does not know what
you are talking about, check the agent's skill directory path and that the
`SKILL.md` is in the right place.


---

### Page Render Smoke Test

Source: [/skills/theme-development/page-render-smoke-test/index.html](/skills/theme-development/page-render-smoke-test/index.html)
Reference page for Page Render Smoke Test.

# Page Render Smoke Test

This is a manual smoke test for a Lesstruct theme. Run it after every change
to `themes/<name>/` and after every Lesstruct upgrade. The skill does not have
access to the Lesstruct source, so this test must be run by you, against your
running install, in a browser or with `curl`.

## Setup

1. Confirm `THEME_DIR` is set and Lesstruct is running.
2. Confirm at least one post exists (the smoke test uses `/<slug>`).
3. Confirm at least one user with author profile exists (for the author page).
4. Confirm at least one post has at least one tag (for the tag page).
5. Replace `<slug>`, `<username>`, and `<tag>` in the URLs below with values
   from your install.

## Page-by-page test

For each URL: load it in a browser (or `curl` it), then check the column on
the right. The "Smoke signal" column is the smallest signal that the page
rendered and your theme took effect.

| # | Page | URL | What to verify | Smoke signal |
|---|------|-----|----------------|--------------|
| 1 | Index | `GET /` | Post grid, navigation, search toggle, footer all styled per your theme | At least one `<article class="post-card">` is visible and styled differently from the default |
| 2 | Content | `GET /<slug>` | Body renders, tags link, author header, optional comments, language switcher | `<article class="content-article">` renders and the post body is present |
| 3 | Author | `GET /authors/<username>` | Avatar, name, custom fields, posts list | `<h1>` shows the author name |
| 4 | Tag | `GET /tags/<tag>` | Tag name heading, filtered posts | `<h1>` shows `#<tag>` |
| 5 | 404 | `GET /this-does-not-exist` | 404 status, custom 404 body | HTTP status is `404` and the body contains your custom 404 message |
| 6 | Login | `GET /login` | Form renders; `auth.js` toggles `#auth-error` on bad creds | `<form id="login-form">` renders; submitting bad creds shows the error element |
| 7 | Register | `GET /register` | Form renders; success message hides form on success | `<form id="register-form">` renders; submitting valid creds shows `#auth-success` |
| 8 | Forgot password | `GET /forgot-password` | Form renders; success message hides form on submit | `<form id="forgot-form">` renders; submitting shows `#auth-success` |
| 9 | Verify email | `GET /verify-email?token=<valid>` | Success message appears | `#auth-success` is visible after the request completes |
| 10 | Reset password | `GET /reset-password?token=<valid>` | Form renders; submit posts to `/api/auth/reset-password` | `<form id="reset-form">` renders and the `#new-password` input is present |

## Static asset checks

- [ ] `GET /static/style.css` returns your theme's CSS (or the embedded
      default if you did not override it).
- [ ] `GET /static/<file>` returns 200 for every file in your
      `themes/<name>/static/`.
- [ ] No `404` in the browser network panel for `/static/*` or
      `/api/v1/public/search`.

## Browser console checks

- [ ] No JavaScript errors in the browser console on any of the 10 pages.
- [ ] No 404s for fonts, images, or scripts.
- [ ] The mobile nav toggle (if your theme has one) opens and closes
      `.site-nav` when the `.nav-toggle` button is clicked.

## Quick command-line version

If you prefer to script the test:

```bash
BASE=http://localhost:8080

for path in / /authors/admin /tags/news /login /register /forgot-password; do
  status=$(curl -s -o /dev/null -w "%{http_code}" "$BASE$path")
  echo "$status $path"
done

# 404 should return 404
curl -s -o /dev/null -w "%{http_code}\n" "$BASE/this-does-not-exist"
```

Expected: every URL returns `200` except `/this-does-not-exist`, which returns
`404`.

## Reporting a failure

If a page fails the smoke test:

1. Check the [Troubleshooting](theme-development.md#troubleshooting) table in
   the loaded reference.
2. Check `themes/<name>/CHANGELOG.md` for the Lesstruct version you are
   running; if it is older than the theme, you may have hit a Lesstruct
   upgrade.
3. Re-run this skill with intent **repair after upgrade** — it will diff your
   theme against the new embedded defaults.


---

### Theme Audit Checklist

Source: [/skills/theme-development/theme-audit-checklist/index.html](/skills/theme-development/theme-audit-checklist/index.html)
Reference page for Theme Audit Checklist.

# Theme Audit Checklist

Use this checklist to audit a `themes/<name>/` directory before declaring a
theme ready. Each item is a hard pass / fail.

## Environment

- [ ] `THEME_DIR` is set in `.env` or the environment the Lesstruct process
      runs in (not only in a shell session that has since closed).
- [ ] `THEME_DIR` resolves to an existing directory.
- [ ] Lesstruct was restarted after the most recent `THEME_DIR` change.
- [ ] The theme directory has a `static/` and a `templates/` subdirectory
      (even if empty).

## CSS (`static/style.css`)

- [ ] `static/style.css` is valid CSS (run it through a linter).
- [ ] `static/style.css` does not reference `style.src.css` (the source file
      is not served; only the minified `style.css` is).
- [ ] Every CSS variable the default theme defines is still defined in the
      override (or in a parent file the override loads). The full set is in
      the [CSS Variable Reference](theme-development.md#css-variable-reference).
- [ ] `@import` URLs (fonts, third-party CSS) resolve.

## Layout template (`templates/layout.html`)

- [ ] File defines `{{define "layout"}}…{{end}}` exactly once.
- [ ] The HTML element has `lang="{{.Lang}}"`.
- [ ] `<title>{{.PageTitle}}</title>` is present.
- [ ] `<link rel="stylesheet" href="/static/style.css">` is present.
- [ ] `<main>…{{template "body" .}}…</main>` is present.
- [ ] The Open Graph `<meta>` tags are present (otherwise share previews
      break).
- [ ] `<script src="/static/nav-auth.js"></script>` and
      `<script src="/static/search.js"></script>` are present (otherwise
      the nav login/logout toggle and search dropdown break).

## Page templates (any `templates/<page>.html` you ship)

- [ ] The template defines `{{define "body"}}…{{end}}` exactly once.
- [ ] The template uses the data fields listed in
      [Template Data Fields](theme-development.md#template-data-fields) by
      their documented names (`.Title`, `.PageTitle`, etc.).

## JavaScript DOM contract

If you override `static/comments.js`:

- [ ] The content template still has `<form id="comment-form" data-slug="…">`.
- [ ] The form has a `<textarea name="comment">`.
- [ ] `#comment-error` and `#comment-success` elements exist.
- [ ] `#comment-login-link` exists (shown to logged-out users).

If you override `static/auth.js`:

- [ ] The login template has `<form id="login-form">` with inputs named
      `username` and `password`.
- [ ] The register template has `<form id="register-form">` with inputs
      named `username`, `name`, `email`, and `password`.
- [ ] The forgot-password template has `<form id="forgot-form">` with an
      input named `email`.
- [ ] Each of the three templates has `#auth-error` and (for register and
      forgot) `#auth-success` elements.

If you override `static/verify-email.js`:

- [ ] `verify_email.html` has `#auth-error` and `#auth-success` elements.

If you override `static/reset-password.js`:

- [ ] `reset_password.html` has `<form id="reset-form">` with
      `<input id="new-password">`.
- [ ] `reset_password.html` has `#auth-error` and `#auth-success` elements.

If you override `static/nav-auth.js`:

- [ ] `layout.html` still has `<a id="nav-login">` and `<a id="nav-logout">`.
- [ ] If you keep the mobile nav toggle, `layout.html` still has
      `<button class="nav-toggle">` and `<nav class="site-nav">`.

If you override `static/search.js`:

- [ ] `layout.html` still has `<button class="search-toggle">`,
      `<input id="search-input">`, and `<div id="search-dropdown">`.

## CDN assets

- [ ] If your theme uses katex, `layout.html` loads
      `https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css` and
      `katex.min.js`.
- [ ] If your theme uses highlight.js, `layout.html` loads the matching CSS
      and `<script src="/static/highlight.min.js"></script>`.
- [ ] If your theme does **not** use katex or highlight.js, the matching
      `<link>` and `<script>` tags have been removed from `layout.html`.

## Smoke test

- [ ] Run the page-by-page smoke test from
      [`page-render-smoke-test.md`](page-render-smoke-test.md) and confirm
      all 10 pages render correctly.

## Documentation

- [ ] `themes/<name>/CHANGELOG.md` records the Lesstruct version the theme
      was authored against.
- [ ] The CHANGELOG lists every file the theme overrides.


---

### Theme Development Guide

Source: [/skills/theme-development/theme-development/index.html](/skills/theme-development/theme-development/index.html)
Reference page for Theme Development Guide.

# Theme Development Guide

> **Snapshot notice.** This is the **user-facing** snapshot of the Lesstruct
> theme development guide, bundled with the `lesstruct-theme-development` skill
> so the skill is self-contained. The canonical, developer-facing version lives
> in the Lesstruct repository at `docs/theme-development.md` and references
> source-tree paths; this version is rewritten for someone with a binary
> Lesstruct install and a `themes/<name>/` directory.
>
> If you have a newer Lesstruct release, re-export this file from the repo to
> refresh the snapshot.

Lesstruct supports custom themes for the public-facing content site. Themes override the
default CSS, JavaScript, and (optionally) HTML templates without modifying the core source.

## How Themes Work

1. Create a theme directory with your custom files.
2. Set the `THEME_DIR` environment variable to point to it.
3. At startup, Lesstruct resolves each template and static file through a
   composite filesystem: if the file exists under `THEME_DIR`, that copy is
   used; otherwise the embedded default is used.

This means you can ship a **partial** theme — a single `style.css`, or a full
`layout.html`, or anything in between — and the rest stays on the embedded
defaults.

## Theme Directory Structure

```
themes/
  mytheme/
    static/          # Served at /static/*
      style.css
      auth.js
      comments.js
      nav-auth.js
      search.js
      math.js
      verify-email.js
      reset-password.js
      highlight.min.js
    templates/       # Go html/template files
      layout.html
      index.html
      content.html
      author.html
      tag.html
      not_found.html
      login.html
      register.html
      forgot_password.html
      verify_email.html
      reset_password.html
```

The theme can override **any subset** of these files. Any file not present
falls back to the embedded default. The embedded defaults are not visible
files on your install — they live inside the Lesstruct binary — but you can
inspect the served versions at the URLs listed below in
[Reference URLs](#reference-urls).

## Quick Start: CSS-Only Theme

The simplest theme overrides only the CSS.

### 1. Create the theme directory

```bash
mkdir -p themes/mytheme/static
```

### 2. Start from the readable source

The file browsers receive is `/static/style.css` (the minified default). The
readable, documented source is bundled with this skill at
`references/default-style-reference.css` — copy it as your starting point:

```bash
cp references/default-style-reference.css themes/mytheme/static/style.css
```

You do not need to minify your override; Lesstruct serves your file verbatim.
(If you maintain a `.src.css` for your own authoring convenience and want to
ship a minified version, use any CSS minifier — but the theme override is happy
with any valid CSS.)

### 3. Override the design tokens

The default theme exposes every visual decision as a CSS custom property under
`:root`. Override the ones you want to change:

```css
:root {
  --color-bg: #ffffff;
  --color-text: #1a1a2e;
  --color-primary: #22d3ee;
  --max-width: 1200px;
}
```

> **Note on the brand tokens.** The default stylesheet marks the `--color-*`
> brand tokens as LOCKED in its own source — that means the embedded default
> will not change those values, not that themes cannot override them. Your
> theme is free to redefine any token. The lock exists so the upstream visual
> identity stays stable across releases.

### 4. Configure the theme

Set `THEME_DIR` in your `.env`:

```bash
THEME_DIR=themes/mytheme
```

### 5. Restart Lesstruct

Themes are loaded at startup. Restart the server to apply changes.

## CSS Variable Reference

The full set of custom properties the default theme defines.

### Brand colors

| Variable | Default | Description |
|----------|---------|-------------|
| `--color-bg` | `#ffffff` | Page background color |
| `--color-text` | `#1a1a2e` | Main text color |
| `--color-text-muted` | `#6b7280` | Secondary / muted text |
| `--color-primary` | `#22d3ee` | Primary brand color (links, buttons, focus rings) |
| `--color-primary-hover` | `#06b6d4` | Primary color on hover |
| `--color-secondary` | `#2536eb` | Secondary brand color (logo, active nav, headings) |
| `--color-accent` | `#8b5cf6` | Accent color (tags, highlights) |
| `--color-border` | `#e5e7eb` | Border and divider color |
| `--color-card-bg` | `#f9fafb` | Card and elevated surface background |

### Status colors

| Variable | Default | Description |
|----------|---------|-------------|
| `--color-danger` | `#dc2626` | Error and validation messages |
| `--color-success` | `#16a34a` | Success messages |

### Layout

| Variable | Default | Description |
|----------|---------|-------------|
| `--max-width` | `1200px` | Outer container max width |
| `--content-width` | `768px` | Single-article reading width |
| `--header-height` | `80px` | Sticky header height (used for anchor offset) |

### Radii

| Variable | Default | Description |
|----------|---------|-------------|
| `--radius-sm` | `4px` | Small elements (badges) |
| `--radius-md` | `6px` | Buttons, inputs, alerts |
| `--radius-lg` | `8px` | Cards, modals |

### Elevation

| Variable | Default | Description |
|----------|---------|-------------|
| `--shadow-sm` | `0 1px 2px rgba(0, 0, 0, 0.05)` | Subtle lift |
| `--shadow-md` | `0 4px 16px rgba(0, 0, 0, 0.10)` | Cards, hovered inputs |
| `--shadow-lg` | `0 8px 24px rgba(0, 0, 0, 0.12)` | Modals, popovers |

### Spacing

| Variable | Default | Description |
|----------|---------|-------------|
| `--space-1` | `0.25rem` | Tightest gap |
| `--space-2` | `0.5rem` | |
| `--space-3` | `0.75rem` | |
| `--space-4` | `1rem` | Standard gap |
| `--space-5` | `1.5rem` | Container padding, card padding |
| `--space-6` | `2rem` | Section spacing |
| `--space-8` | `3rem` | Page-top spacing |

### Motion and focus

| Variable | Default | Description |
|----------|---------|-------------|
| `--transition-fast` | `0.2s ease` | Default transition timing |
| `--ring` | `0 0 0 3px color-mix(in srgb, var(--color-primary) 22%, transparent)` | Focus ring for all text fields |

### Typography

| Variable | Default | Description |
|----------|---------|-------------|
| `--font-sans` | `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif` | Body and headings |
| `--font-mono` | `"JetBrains Mono", "Fira Code", "Cascadia Code", monospace` | Code blocks and inline `<code>` |

## Font Customization

The default theme imports Inter from Google Fonts at the top of its stylesheet.
To switch:

1. Replace the `@import` line at the top of your `style.css` with the new
   font's `@import` (or self-host and `@font-face` it).
2. Override `--font-sans` on `:root`.
3. Override `--font-mono` if you want a different monospace stack.

```css
@import url('https://fonts.googleapis.com/css2?family=Fira+Sans:wght@400;600;700&display=swap');

:root {
  --font-sans: 'Fira Sans', -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-mono: 'Fira Code', monospace;
}
```

## Dark Theme Example

Invert the light/dark variables, then re-tune the shadows and surfaces for a
dark backdrop:

```css
:root {
  --color-bg: #0f172a;
  --color-text: #e2e8f0;
  --color-text-muted: #94a3b8;
  --color-primary: #f59e0b;
  --color-primary-hover: #d97706;
  --color-secondary: #14b8a6;
  --color-accent: #8b5cf6;
  --color-border: #334155;
  --color-card-bg: #1e293b;
  --color-danger: #f87171;
  --color-success: #4ade80;
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.40);
  --shadow-md: 0 4px 16px rgba(0, 0, 0, 0.45);
  --shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.55);
}
```

Also re-style form inputs (`background`, `color`, `caret-color`) and the
`<pre><code>` blocks if you want them distinct from the page background.

## Environment Variable

| Variable | Default | Description |
|----------|---------|-------------|
| `THEME_DIR` | `""` (empty) | Path to custom theme directory. Relative or absolute. Read at startup; restart required. |

When `THEME_DIR` is empty or unset, no disk access happens for the content
site; all files come from the embedded defaults.

## Fallback Behavior

For every request, Lesstruct checks the theme directory first and falls back to
the embedded default if a file is missing. This is independent for static
files and for each named template. You can override `style.css` only and keep
the embedded `search.js`, `auth.js`, `layout.html`, and every other file. The
fallbacks compose — partial themes are the normal case.

## Template Overrides

Themes can override any of the 10 page templates. Place your overrides in
`themes/<name>/templates/`.

### Block contract

Templates use Go's `html/template` with two `{{define}}` blocks:

- **`layout.html`** must define `{{define "layout"}}…{{end}}` — the outer
  page shell (DOCTYPE, `<head>`, header, footer). It must call
  `{{template "body" .}}` inside a `<main>` element.
- **All other templates** must define `{{define "body"}}…{{end}}` —
  page-specific content that is rendered inside the layout's `<main>` element.

> If you override `layout.html`, the default `body` block from the embedded
> page templates still works. If you override only page templates, they
> continue to use the embedded `layout.html`. Either is supported; mix as you
> wish.

### Template Data Fields

Every page embeds `LayoutData`, so the layout's `.` is always populated with
the fields below.

**`LayoutData`** — available to every page:

| Field | Type | Description |
|-------|------|-------------|
| `.PageTitle` | `string` | HTML `<title>` content |
| `.Title` | `string` | Page heading |
| `.Description` | `string` | Meta description |
| `.OGTitle` | `string` | Open Graph title |
| `.OGDesc` | `string` | Open Graph description |
| `.OGImage` | `string` | Open Graph image URL (may be empty) |
| `.NavigationItems` | `[]NavigationItem` | Nav items, each with `.Title`, `.URL`, `.IsActive` |
| `.CurrentPath` | `string` | Current request path |
| `.Lang` | `string` | Current language code (e.g. `"en"`, `"fr"`); **required** by `<html lang="…">` and `{{t}}` calls |
| `.LanguageLinks` | `[]LanguageLink` | Alternate-language links (`.Code`, `.Name`, `.URL`); empty if no translations exist |

**`IndexData`** — landing page:

| Field | Type | Description |
|-------|------|-------------|
| `.Posts` | `[]PostItem` | Post cards |
| `.Tags` | `[]string` | All available tags |

**`PostItem`** — a card in the post grid:

| Field | Type | Description |
|-------|------|-------------|
| `.Slug` | `string` | URL slug |
| `.Title` | `string` | Post title |
| `.MetaDescription` | `string` | Short description |
| `.ImageURL` | `string` | Cover image URL (may be empty) |
| `.ImageSrcset` | `string` | Responsive image `srcset` (may be empty) |
| `.ImageSizes` | `string` | Responsive image `sizes` (may be empty) |
| `.Author` | `string` | Author display name |
| `.Username` | `string` | Author username (for `/authors/<username>` links) |
| `.AuthorAvatarURL` | `string` | Avatar URL (may be empty) |
| `.CreatedAt` | `string` | Pre-formatted creation date |

**`ContentData`** — single post page:

| Field | Type | Description |
|-------|------|-------------|
| `.Slug` | `string` | Post URL slug |
| `.Body` | `template.HTML` | Rendered post body (safe HTML; do not re-escape) |
| `.Tags` | `[]string` | Post tags |
| `.Author` | `string` | Author display name |
| `.Username` | `string` | Author username |
| `.AuthorAvatarURL` | `string` | Avatar URL |
| `.CreatedAt` | `string` | Pre-formatted creation date |
| `.AllowComments` | `bool` | Whether comments are enabled |
| `.CustomFields` | `map[string]any` | Raw custom-field values keyed by name |
| `.CustomFieldsFormatted` | `[]FormattedField` | Display-formatted custom fields (`.Label`, `.Value`) |
| `.Comments` | `[]CommentItem` | Comments (`.Author`, `.Text`, `.CreatedAt`) |
| `.LanguageLinks` | `[]LanguageLink` | Inherited via `LayoutData`; also rendered inside the article for translated posts |

**`AuthorData`** — author page:

| Field | Type | Description |
|-------|------|-------------|
| `.AuthorName` | `string` | Author display name |
| `.Username` | `string` | Author username |
| `.AuthorAvatarURL` | `string` | Avatar URL |
| `.Posts` | `[]PostItem` | Author's posts |
| `.CustomFieldsFormatted` | `[]FormattedField` | Author "About" custom fields |

**`TagData`** — tag page:

| Field | Type | Description |
|-------|------|-------------|
| `.TagName` | `string` | Tag display name |
| `.Posts` | `[]PostItem` | Posts with this tag |

**`AuthPageData`** (`login.html`, `register.html`, `forgot_password.html`),
**`NotFoundData`** (`not_found.html`),
**`VerifyEmailData`** (`verify_email.html`),
**`ResetPasswordData`** (`reset_password.html`) — each embeds `LayoutData`
only. The dedicated structs exist so future per-page fields can be added
without breaking the layout contract.

### Example: Custom Layout

```html
{{define "layout"}}<!DOCTYPE html>
<html lang="{{.Lang}}">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{.PageTitle}}</title>
<meta name="description" content="{{.Description}}">
<meta property="og:title" content="{{.OGTitle}}">
<meta property="og:description" content="{{.OGDesc}}">
{{if .OGImage}}<meta property="og:image" content="{{.OGImage}}">{{end}}
<link rel="stylesheet" href="/static/style.css">
</head>
<body>
<header class="site-header">
<div class="container">
<a href="/" class="site-logo">My Custom Site</a>
</div>
</header>
<main class="container">{{template "body" .}}</main>
<footer class="site-footer">
<div class="container">
<p>Custom footer text</p>
</div>
</footer>
</body>
</html>{{end}}
```

> **Reminder:** if you change the math or syntax-highlighting libraries, your
> layout must load their CSS and JS instead of the katex / highlight.js ones
> pulled by the default. See
> [CDN Assets Pulled by the Default Layout](#cdn-assets-pulled-by-the-default-layout).

### Template Helper Functions

Two helpers are registered for use in any template:

- `{{urlpath "string"}}` — URL-encodes a string. Used in tag links so
  non-ASCII tag names resolve correctly:
  `<a href="/tags/{{.TagName | urlpath}}">`.
- `{{t .Lang "ui.key"}}` — translates a UI string for the given language.
  Falls back through the configured languages and finally English; returns
  the key itself if no translation is found. Common keys:

  | Key | Default |
  |-----|---------|
  | `ui.login` | `Login` |
  | `ui.logout` | `Logout` |
  | `ui.register` | `Register` |
  | `ui.search` | `Search` |
  | `ui.search_posts` | `Search posts...` |
  | `ui.toggle_navigation` | `Toggle navigation` |
  | `ui.no_posts` | `No posts yet.` |
  | `ui.no_comments` | `No comments yet. Be the first to comment!` |
  | `ui.login_to_comment` | `Login to comment` |
  | `ui.by_author` | `by` |
  | `ui.comments` | `Comments` |
  | `ui.submit_comment` | `Submit Comment` |
  | `ui.back_to_home` | `Back to home` |
  | `ui.not_found_404` | `404` |
  | `ui.page_not_found` | `Page not found.` |
  | `ui.forgot_password` | `Forgot Password` |
  | `ui.reset_password` | `Reset Password` |
  | `ui.verify_email_title` | `Verify Email` |

## Static File Overrides

Any file in the embedded `static/` can be replaced by a same-named file under
`themes/<name>/static/`. The files are served at `/static/<filename>`.

| File | Used by | DOM contract |
|------|---------|--------------|
| `style.css` | All pages (linked from `layout.html`) | Defines every custom property and class the embedded templates rely on. Override freely. |
| `nav-auth.js` | `layout.html` | Expects `#nav-login`, `#nav-logout`; reads `localStorage.token` or `localStorage.auth_token`; handles `.nav-toggle` / `.site-nav` for mobile. |
| `search.js` | `layout.html` | Expects `.search-toggle`, `.search-box`, `#search-input`, `#search-dropdown`; fetches `/api/v1/public/search?q=…`. |
| `auth.js` | `login.html`, `register.html`, `forgot_password.html` | Expects `#login-form`/`#register-form`/`#forgot-form`, inputs named `username`/`name`/`email`/`password`, and `#auth-error` / `#auth-success` elements. POSTs to `/api/auth/login`, `/api/auth/register`, `/api/auth/forgot-password`. |
| `comments.js` | `content.html` (only when comments are enabled) | Expects `#comment-form[data-slug]`, `#comment-error`, `#comment-success`, `#comment-login-link`; reads `localStorage.token`; POSTs to `/api/v1/content_items/<slug>/comments`. |
| `math.js` | `layout.html` | KaTeX auto-render; depends on katex from CDN (see below). |
| `verify-email.js` | `verify_email.html` | Reads `?token=` from the URL; calls `/api/auth/verify-email?token=…`; toggles `#auth-error` / `#auth-success`. |
| `reset-password.js` | `reset_password.html` | Reads `?token=` from the URL; POSTs to `/api/auth/reset-password`; expects `#new-password` input. |
| `highlight.min.js` | `layout.html` | Provides the global `hljs`. The default layout also runs `hljs.highlightAll()` on `DOMContentLoaded`. |

If you override any JS file, keep the DOM contract above — the default page
templates look for those exact ids and classes. If you change them, you must
also change the corresponding page template.

## CDN Assets Pulled by the Default Layout

The default `layout.html` loads the following from `cdn.jsdelivr.net`:

- `katex@0.16.11/dist/katex.min.css` and `katex.min.js` — math rendering.
- `highlight.js@11.11.1/styles/github-dark.min.css` — code-block theme.

If your theme drops katex and/or highlight.js (for example, you use a
different math library or a different syntax highlighter), update
`layout.html` to drop the matching `<link>` / `<script>` tags and override
`math.js` and `highlight.min.js` accordingly. Otherwise, the assets will be
requested and unused.

## What Does NOT Theme

`THEME_DIR` only affects the public content site. It does not change:

- The admin panel (the Vue-based dashboard at `/admin/`).
- Any `/api/*` JSON response.
- Plugin behaviour, hooks, or capabilities.
- Email templates or other server-rendered channels.

## Reference URLs

When developing a theme, these URLs are useful for inspecting the embedded
defaults that your theme falls back to:

| Default | URL |
|---------|-----|
| Default stylesheet (minified) | `GET /static/style.css` |
| Default index page (with navigation) | `GET /` |
| Default content page | `GET /<existing-slug>` |
| Default 404 page | `GET /this-does-not-exist` |
| Default author page | `GET /authors/<username>` |
| Default tag page | `GET /tags/<tag-name>` |
| Login form | `GET /login` |
| Register form | `GET /register` |
| Forgot password form | `GET /forgot-password` |
| Verify email page | `GET /verify-email?token=<valid>` |
| Reset password page | `GET /reset-password?token=<valid>` |
| Public search endpoint (used by `search.js`) | `GET /api/v1/public/search?q=<query>` |
| Login endpoint (used by `auth.js`) | `POST /api/auth/login` |
| Register endpoint (used by `auth.js`) | `POST /api/auth/register` |
| Forgot-password endpoint (used by `auth.js`) | `POST /api/auth/forgot-password` |
| Verify email endpoint (used by `verify-email.js`) | `GET /api/auth/verify-email?token=<token>` |
| Reset password endpoint (used by `reset-password.js`) | `POST /api/auth/reset-password` |
| Comment submit endpoint (used by `comments.js`) | `POST /api/v1/content_items/<slug>/comments` |

## Theme Authoring Workflow

Recommended sequence for a new theme:

1. **Pick a base.** Decide whether you are re-skinning (CSS only),
   rearranging the layout (`layout.html` only), or rebuilding page templates
   individually.
2. **Create the directory.** `mkdir -p themes/mytheme/{static,templates}`.
3. **Copy only what you need.** Start with `static/style.css` (copy from
   `references/default-style-reference.css`); copy more files from the
   embedded defaults only as your design requires.
4. **Author.** Use the [CSS Variable Reference](#css-variable-reference) and
   [Template Data Fields](#template-data-fields) sections as your contract.
5. **Restart Lesstruct.** `THEME_DIR` is read at startup; live edits to a
   theme file are not picked up until the server is restarted.
6. **Verify.** Hit each of the 10 page URLs in
   [Reference URLs](#reference-urls) and confirm your theme loads and the
   page renders.
7. **Maintain.** When upgrading Lesstruct, fetch the new default CSS
   (`curl -s http://localhost:8080/static/style.css > /tmp/new-default.css`)
   and compare against your override. New template fields and JS DOM
   contracts are listed in this snapshot; new server endpoints show up in
   the embedded JavaScript.

## Troubleshooting

| Symptom | Likely cause |
|---------|--------------|
| Theme changes have no effect | `THEME_DIR` is empty, points to a missing directory, or the server was not restarted. |
| Page renders, but no styles | `<link rel="stylesheet" href="/static/style.css">` is missing from your `layout.html`. |
| Search box or comment form is dead | You overrode `search.js` / `comments.js` / `layout.html` and the DOM ids no longer match. Restore the ids, or update the JS to match your new layout. |
| Tag links are broken for non-ASCII tags | The href was built with `.TagName` instead of `{{.TagName | urlpath}}`. |
| `{{t .Lang "ui.x"}}` shows the literal key | The translation is missing for the current language. Add it, or change the key. |
| KaTeX or highlight.js missing | Your `layout.html` does not load the CDN CSS/JS, or the assets are blocked by the network. |


---