# Cicadel 0.2.7: complete application documentation

Build applications using Cicadel. Start with the quick start or AI-agent guide; fetch focused Markdown guides as needed.

Source: 2678611d308376ca8045c8741ee9d4d7814a3fec.

---

Source: `CHANGELOG.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/releases/changelog/index.md

# Changelog

## Unreleased

Nothing yet.

## v0.2.7 — 2026-11-13

Production request handling for browser applications: HTML error pages, login
redirects, per-route body limits and htmx response helpers. No breaking changes. Upgrade all five modules to v0.2.7 together.

- Added `errorpages` (DX-04): `errorpages.Middleware` replaces plain-text 4xx/5xx
  responses (the router's 404/405, `http.Error`, CSRF failures) with a rendered
  HTML page for clients that accept HTML, and recovers panics as a 500 page,
  logging the stack with the request ID and calling an optional `Report` hook.
  Pages show fixed copy, never the handler's message. htmx partial requests get
  `HX-Reswap: none` and a `cicadel:error` event instead of a page. Generated
  projects install it through `project/errors.go` (`GlobalMiddleware`,
  `ErrorPage`) with a styled `project/errors.templ`. See `docs/error-pages.md`.
- Added `bodylimit` (DX-29): `settings.MaxBodyBytes` is now a per-request default
  that `bodylimit.Limit(n)` or `bodylimit.Set` raise or lower before the body is
  read. `forms/upload` uses `Config.MaxBytes` as the request limit, so upload
  routes accept large files while other routes keep the small default. See
  `docs/request-limits.md`.
- `contrib/accounts` (DX-02, DX-03): `Browser.LoginRequired(loginURL)` redirects
  anonymous visitors to sign in with a safe `?next=` (unsafe methods without it,
  htmx via `HX-Redirect`), and the sign-in page returns there.
  `Browser.Middleware` no longer caps every wrapped body at 8 KiB; the account
  pages keep their own 8 KiB bound. The anonymous account and change-password
  pages also redirect with `next`.
- Added htmx response helpers (DX-08): `htmx.Trigger`, `TriggerDetail`,
  `Redirect`, `Location`, `Refresh`, `Retarget`, `Reswap`, `Reselect`, `PushURL`,
  `ReplaceURL` and `CSRFHeaders`. Navigation helpers accept only local paths.
- `layout.Props` gains `Lang` and `Dir` (DX-10; `<html lang dir>`, validated) and
  `CSRFToken`, which sends the token as `X-CSRF-Token` on every htmx request.
- Added `response.LocalPath`. `response.Redirect` now also rejects targets with
  whitespace or control characters, such as `/\t/evil.test`, which browsers
  turn into the protocol-relative `//evil.test`.
- Added `security.CSRFFailureMessage`.
- `startproject` and `startapp` emit gofmt-formatted Go (DX-25).

## v0.2.6 — 2026-11-12

The accounts app emits typed, transactional events. No breaking changes. Upgrade all five modules to v0.2.6 together.

- `contrib/accounts` declares and emits typed events: `UserCreated`, `LoggedIn`, `LoginFailed`, `LoggedOut` and `PasswordChanged` (listed by `accounts.Events()` and included in `Descriptor`/`Service.App`). Payloads carrying `Tx` are emitted inside the account transaction, so handler writes commit with the change, a handler error rolls it back, and `database.OnCommit(e.Tx, fn)` defers side effects. `Service.Create`, `Login`, `Logout`, `ChangePassword` and `ResetPassword` now run through `database.Atomic`; `Create` returns a zero `User` when it fails. Accounts now requires core v0.2.5. See `docs/events.md`.

## v0.2.5 — 2026-11-12

Adds typed application events, the event-hook contract for installable packages. No breaking changes. Upgrade all five modules to v0.2.5 together.

- Added typed application events (SVC-08), the package-system event-hook contract. The new `events` package declares an event with `events.New[T](owner, name)`; an app lists the events it emits in `App.Events` and its handlers, created with `Event.Handle`, in `App.Subscriptions`. `cicadel.New` builds an immutable dispatcher and fails when an app declares another app's event, a declaration is duplicated or its name reused, or a subscription names an event no installed app declares. `Event.Emit` runs handlers synchronously in app dependency order, stops at the first error (`*events.HandlerError`), checks cancellation before each handler and bounds nested emission (`events.MaxDepth`, `events.ErrDepth`). Requests, `Start` and cleanup hooks, app commands and every `manage.go` command carry the dispatcher; the new `Application.Context(ctx)` attaches it, the signing keys and the static manifest for other work such as jobs, and `Application.Events()` returns the dispatcher. `manage.go apps` lists `emits` and `handles` lines. See `docs/events.md`.
- First-party app manifests (`accounts`, `formsets`, `migrations`, `querygen`) report the module version selected by the build, read from Go build information, instead of a fixed `v0.1.0`. `manage.go apps` now shows the real version; checkout builds without a released version report `v0.0.0`.
- Generated projects subscribe in the new `project/events.go`, and the `startpackage` template declares and emits a typed `Greeted` event with a subscriber test.

## v0.2.4 — 2026-11-11

Adds typed per-package settings and completes the readiness checklist. No breaking changes. Upgrade all five modules to v0.2.4 together.

- Formset saves (`contrib/formsets`) now run through `database.Atomic`, so model-form hooks registered with `database.OnCommit` during a formset `Save` run after the formset commits instead of failing with `database.ErrNoTransaction`.
- Added the typed per-package settings contract (DEV-04). An app declares a struct whose `setting:"NAME"` fields (`,secret` for credentials) may be overridden by `CICADEL_<APP>_<NAME>`; it returns `App.Settings: settings.NewPackage(options)` and reads `Package.Value()`. `cicadel.New` resolves settings from `Settings.Env` before `Start`, rejects key collisions with project settings and other apps, and `check`/`check --json` report `<app>:settings:invalid` naming the key, never the value. `manage.go apps` lists keys and values with secrets redacted. New: `settings.NewPackage`, `Package`, `LoadPackage`, `PackageSettings`, `Field`, `PackagePrefix`, `CoreKeys`, `Redacted`, `Settings.Env`, `App.Settings`, `Application.PackageSettings`, `AppSettings`. The `startpackage` scaffold uses it, and `contrib/accounts` `Options` now declares `CICADEL_ACCOUNTS_SESSION_LIFETIME`, `_RECOVERY_LIFETIME`, `_IDLE_TIMEOUT` and `_BCRYPT_COST` with `Options.Validate`; generated projects wire them through `AccountOptions`. No breaking changes. See `docs/package-settings.md`.

## v0.2.3 — 2026-11-11

Adds transaction post-commit hooks and moves to Go 1.26.11 for a standard-library security fix. No breaking changes. Upgrade all five modules to v0.2.3 together and raise your project's `go` line to 1.26.11.

- Added transaction post-commit hooks (DB-03): `database.Atomic` runs a function in a PostgreSQL transaction (a savepoint when nested) and `database.OnCommit(tx, fn)` registers a callback that runs after the outermost transaction commits, in registration order. Hooks are discarded on rollback, on failed commit and with a rolled-back savepoint; outside an `Atomic` transaction `OnCommit` returns `database.ErrNoTransaction`. Hook errors and panics are logged and cannot undo the commit; hooks receive a context without the caller's cancellation. Model form (`Bound.Create`/`Update`) and administration saves now run through `database.Atomic`, so `AfterSave` hooks can register post-commit work; formsets adopt it once that module requires this release. See `docs/transactions.md`.
- Require Go 1.26.11 (was 1.26.10) in every module and in generated projects, picking up the standard-library `net/http` fix for GO-2026-6859. Projects should raise the `go` line in `go.mod` to 1.26.11; with the default `GOTOOLCHAIN=auto` the toolchain is downloaded automatically.

## v0.2.2 — 2026-11-11

Adds signed, expiring tokens with secret-key rotation. No breaking changes: existing projects keep working, and `check --deploy` warns until `CICADEL_SECRET_KEY` is set. Upgrade all five modules to v0.2.2 together.

- Added the `signing` package (SEC-04): purpose-bound, timestamped, URL-safe tokens signed with HMAC-SHA256 under per-purpose derived keys; `Verify` with a maximum age, `VerifyNoExpiry`, typed `SignJSON`/`VerifyJSON[T]`, `ErrInvalid`/`ErrExpired`/`ErrNoKey`, a one-minute clock-skew bound and `WithClock` for tests. New settings `SecretKey` (`CICADEL_SECRET_KEY`) and `SecretKeyFallbacks` (`CICADEL_SECRET_KEY_FALLBACKS`) sign with the current key and verify with previous ones during rotation. Handlers use `signing.For(r.Context(), purpose)`; commands and jobs use `Application.Signer`. `cicadel secretkey` generates a key, `check --deploy` reports `settings:secret_key` when none is set, and `apptest.Settings()` uses the fixed `apptest.TestSecretKey`. See `docs/signing.md`.

## v0.2.1 — 2026-11-10

Adds security headers and HTTPS policy. No breaking changes: existing projects keep their behavior until they opt in. Upgrade all five modules to v0.2.1 together.

- Added security-header defaults and HTTPS policy (SEC-03). New settings: `HSTSSeconds` (`CICADEL_HSTS_SECONDS`), `SecureRedirect` (`CICADEL_SECURE_REDIRECT`), `TrustedProxies` (`CICADEL_TRUSTED_PROXIES`) and `ContentSecurityPolicy` (`CICADEL_CONTENT_SECURITY_POLICY`), with `settings.DefaultContentSecurityPolicy` and `settings.HSTSYear`. `security.IsHTTPS` reports HTTPS through TLS or a trusted proxy. Generated projects enable HSTS and the default policy; existing projects keep their behavior and get `check --deploy` warnings until they opt in. See `docs/security-headers.md`.
- Added the versioning standard to `docs/releases.md`: patches carry fixes and backward-compatible additions, the minor version moves only when a milestone is complete, and v1.0 requires Django-level completeness.

## v0.2.0 — 2026-11-10

Adds pagination and flash messages, the first two open core gaps, and fixes
two v0.1.0 problems. No breaking changes: upgrade all five modules to v0.2.0
together.

- Added `paginate`: validated page parsing, ordered GORM pagination in one read-only snapshot, slice pagination, query-preserving relative links, Django-style elided page ranges and the accessible `paginate.Nav` component.
- Fixed `management.ExitCode` returning success for errors whose wrapped cause is nil. `cicadel ui check` now exits 1 on type errors instead of 0, and `manage.go` commands report such failures.
- The core modules now require each other at v0.1.0, so each builds on its own with `GOWORK=off`; v0.1.0's modules pinned an older framework revision without `App.Static`. CI builds the migrations and query-generation modules standalone.
- Added `flash`: session-backed, consume-once messages with info/success/warning/error levels, size limits and the accessible `flash.List` component. See `docs/pagination-and-messages.md`.

## v0.1.0 — 2026-11-10

First release. The core framework is ready for building applications: projects
and apps, settings, routing, GORM models with recorded PostgreSQL migrations,
typed components with Tailwind and htmx, forms, accounts with sessions and CSRF,
static files, email, logging, test helpers and installable packages. From this
release, APIs follow the stability guarantee in `docs/releases.md`; the root module
and the `contrib/accounts`, `contrib/formsets`, `contrib/migrations` and
`contrib/querygen` modules are released together at the same version. Next:
pagination and flash messages.

Install: `go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.1.0 startproject myapp example.com/myapp`.

### Changes included in v0.1.0

- Added typed static-file contributions: `App.Static` publishes app-owned public files at `/static/<app>/` with content-hashed, immutably cached URLs, revalidated authored names, `static.URL` request resolution, `settings.StaticURL`/`CICADEL_STATIC_URL` (local path or https CDN prefix) and an offline `collectstatic` command writing hashed files plus `manifest.json`. Accounts, the starter project, `startapp`, `startpackage` and the component-library example now use it; the `/accounts/style.css` and `/static/app.css` routes are replaced and `ComponentAssets` paths are now relative to `App.Static`. See `docs/static-files.md`.
- Made accounts and formsets standard project defaults; added offline `makemigrations` and `generatequeries` management commands from the shared model registry.
- Consolidated migration application, planning, verification, adoption and recovery on the recorded-history runner. Removed the separate `database.Migrate`/`Migrator` executor; existing Goose histories require verified adoption.
- Preserved first-party handwritten SQL with reviewed historical manifests and verified legacy serial/unique/timestamp-default support. Updated application guides and installable contracts to describe core defaults.


- Breaking: renamed Yutqin to Cicadel, including Go modules and packages, CLI executables, environment variables, generated artifacts, cache paths, and framework-owned database identifiers.

- Added typed installable runtime model catalogs with explicit app/table/type ownership, offline validation and isolated discovery. Recorded migrations remain authoritative.

- Completed application foundation tooling: all operational settings overrides and redacted diagnostics, sorted command help and exit statuses, structured/deployment checks, and safe component/CSS rebuild/restart through `cicadel dev`. Added generated-executable and reload acceptance tests; see `docs/foundation.md`.

- Added a green-and-black Tailwind default theme and optional `startproject --accounts` browser starter with compiled login/recovery/reset/account/password-change pages, CSRF protection, PostgreSQL cookie sessions and shared account revocation.
- Added SMTP with verified STARTTLS/implicit TLS, batch connection reuse, MIME alternatives and attachments, CC/BCC, reply-to and console/file/capture/discard backends.
- Added named logging configuration with levels, filters, propagation, JSON/text/custom handlers, file rotation, optional error email, grouped credential redaction, correlated panic records and private GORM timing.
- Reconciled current authentication, component, PostgreSQL migration, mail and logging documentation; administration remains a separate later battery.

- Completed standalone typed forms and accessible widgets; added revision-based stale-edit detection, bounded upload fields with compensating cleanup and multipart CSRF integration, and atomic model-form/formset administration. See `docs/forms-completion.md`.

- Added core `contrib/formsets`: bounded related-row collections with scoped identities, add/delete limits, parent locking, transactional hooks and atomic saves; added the core `Form.InTransaction` composition API.

- Added `forms/model`: explicit GORM field allowlists, typed binding, scoped relationship checks, authorized row-locked updates, safe constraint errors and transactional validation/save hooks. Verified with PostgreSQL concurrency and rollback tests; see `docs/model-forms.md`.

- Added the installable-app foundation: manifests, API/dependency compatibility checks, namespaced commands/checks/resources, route-scoped middleware and per-host startup/cleanup.
- Added `startpackage`, generated `project/apps.go`, `manage.go apps`, and `apptest.Check`; tested independent Go-module install/upgrade/removal and PostgreSQL migration/data retention.

- Implemented React/Cotton-inspired compiled component UI; retained legacy Go templates for compatibility and completed the component-engine acceptance checks.

- Added a source-linked Django battery inventory with explicit support decisions and completion criteria.
- Reclassified existing integrations as partial batteries; model-driven PostgreSQL migrations now have a documented supported subset, other database backends are excluded, and broader package-system contracts remain planned.
- Removed the experimental native `locale` package; i18n/l10n and GIS are third-party-only by design.

- Django-familiar project/app scaffolding, typed settings, explicit app registration and management commands.
- Standard HTTP routing with namespaced reversal, escaped embedded templates, response helpers and static assets.
- PostgreSQL/GORM integration and locked, versioned Goose migrations.
- Sessions, password primitives, CSRF protection, bounded forms and explicit authorization.
- Working articles and catalog/admin examples with real HTTP/database tests.
- API helpers, mail transport/capture, bounded storage/cache, observability hooks and River jobs.
- PostgreSQL integration/race tests, fuzz targets, generated-project validation, vulnerability checks and performance baselines.

Requires Go 1.26.10+ to incorporate standard-library security fixes. No upgrade migration is required from a prior Cicadel release because none has been published by this implementation.


---

Source: `SECURITY.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/SECURITY.md

# Security reporting

This repository is currently private. Report vulnerabilities to the repository owner through a confidential channel or a security issue within this private repository, accessible only to its authorized collaborators. Do not post exploit details, credentials, or user data to public mirrors or unrelated issue trackers. If repository access is unavailable, contact the owner privately rather than publishing details.

Maintainers should reproduce the report, assess affected versions, prepare a fix and regression test, coordinate disclosure with the reporter, and publish upgrade instructions when the fix is released. Avoid copying private reports into public release notes before coordinated disclosure.

Before making the repository public, enable GitHub private vulnerability reporting and replace this private-repository process with its security-advisory reporting URL. The GitHub private-reporting endpoint is not available for this private repository; no public reporting address is claimed here.

Cicadel is experimental. Local tests and automated scanning do not substitute for independent security review or application-specific authorization, rate limiting, deployment hardening, and account lifecycle controls. Supported security fixes initially target the latest prerelease only. Stable-release support windows will be defined before 1.0.


---

Source: `contrib/accounts/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/ref/accounts/index.md

# Accounts

Optional PostgreSQL accounts using installable app API 1. This source module uses
`replace github.com/fauzaanu/cicadel => ../..` for repository development; no remote
module release is claimed.

In a generated application's `project.InstalledApps(db)`, construct
`accounts.New(accounts.Options{DB: db, DeliverRecovery: deliver})`, handle its
error, and append `service.HTTPApp("/accounts")`. Run `manage.go migrate` before
serving. The migration is recorded SQL, never AutoMigrate. Removing registration
preserves data. The host owns its database pool.

The HTTP endpoints accept POST JSON with `Content-Type: application/json`:

| Path | Fields | Authentication |
| --- | --- | --- |
| login | Username, Password | Credentials; returns token |
| logout | empty object | Bearer token |
| change-password | OldPassword, Password | Bearer token |
| request-recovery | Username | Public; invokes delivery callback |
| reset-password | Token, Password | Recovery token |
| revoke | empty object | Bearer token; revokes every session |

Clients send `Authorization: Bearer <token>`. These routes use no ambient cookies.
Install `service.Middleware` explicitly on host routes requiring current-user
context; use `UserFromContext` and reject anonymous requests where needed. The
middleware does not itself require authentication. For browser applications, construct `service.Browser(sessions)` and wrap routes
with `browser.Middleware`. This composes SCS LoadAndSave, CSRF validation and
account resolution in order. Use `browser.Login`, `browser.Logout`,
`browser.CSRFToken` and `browser.LoginRequired(loginURL)` in HTML handlers
(`browser.RequireLogin` answers 401 for JSON routes). The account token
is held only in the server-side session; disablement and revocation are checked
on every request. Do not additionally wrap these routes with SCS/CSRF middleware.
SCS login alone does not create an accounts session. Existing
SCS APIs remain compatible. This package does not change forms, uploads or admin.

Tokens contain cryptographic randomness and only SHA-256 digests are stored.
Password changes and recovery revoke all sessions and recovery tokens in one
transaction. Recovery consumption locks the user and rechecks token deletion,
so concurrent redemption succeeds once. Session creation serializes with password
changes. `SetActive(false)` revokes sessions and recovery tokens. Disabled users cannot
log in, resolve current-user context or use permissions.

Passwords must contain 12–72 bytes. `Policy` adds application validation; bcrypt
cost defaults to 12 (configurable 10–16). Successful password authentication
upgrades lower costs without downgrading stronger hashes or overwriting a
concurrent password change. `Backend` can verify another credential source but
must return an existing local account; central disabled-user checks still apply.

`SessionLifetime` defaults to 24 hours and `RecoveryLifetime` to 30 minutes;
both are absolute lifetimes of at least one minute. Optional `IdleTimeout` expires
sessions after inactivity; successful current-user resolution refreshes activity. PostgreSQL is the persistent
store. Schedule `manage.go accounts:cleanup` to remove expired sessions/recovery
records. No background worker is started. Transport security, request rate limits,
and recovery delivery belong to the host. Delivery must send the raw token only
to the account's previously verified recovery destination; never to an arbitrary
request-supplied address. Avoid logging tokens or credentials.

Groups use `CreateGroup`, `AddMember`, `RemoveMember`, `Grant`, and `Deny`.
`HasPermission` checks exact application-defined model/action strings such as
`posts.change`. There is no superuser bypass or implicit object access. Apply an
explicit host policy for each object in addition to model permissions.

OAuth/OIDC, social login and MFA remain outside scope. The `accountui` package supplies compiled HTML account screens. Administration integration remains separate.

Run `CICADEL_TEST_DATABASE_URL=postgres://...?... go test -race ./...` with a
disposable PostgreSQL database and schema creation privileges. Tests isolate and
remove their schema. Parent module tests do not include this nested module.

`sh contrib/accounts/verify-host.sh` generates a separate application, registers
the package via local module replacements, applies its public migration contract,
and verifies login/logout over HTTP. Use a disposable database; the verification
applies accounts migrations and removes its test user afterward.


## Events

The app declares `UserCreated`, `LoggedIn`, `LoginFailed`, `LoggedOut` and
`PasswordChanged` (`accounts.Events()`). Subscribe from any installed app, for
example `accounts.LoggedIn.Handle(fn)` in its `App.Subscriptions`. Payloads with
`Tx` are emitted inside the account transaction: write through `e.Tx` to commit
with the change, return an error to roll it back, and use
`database.OnCommit(e.Tx, fn)` for effects after commit. `LoginFailed` carries
only the submitted username. Events reach subscribers when the service is called
with an application context (requests, commands, `Application.Context`). See
the [events guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md).

## Browser pages

Use `service.Browser(sessions)` and `browser.HTMLApp(Pages{Brand: "My app"})`
for the default compiled HTML screens. Register that app once and migrate before
serving. It owns its cookie/CSRF middleware and embedded CSS; other protected
routes apply `browser.Middleware` followed by `browser.LoginRequired("/accounts/login")`,
which redirects anonymous visitors to sign in and returns them to a safe local
`next` path afterwards.
`UserFromContext` is shared with the bearer adapter. The browser stores the
account token only in the server-side SCS store, rotates login cookies and checks
revocation/disablement on every request.

Migration 002 adds the PostgreSQL `accounts_browser_sessions` table used by the
starter. Custom session stores remain supported. Use
`cicadel startproject DIRECTORY MODULE` for a wired project, including
verified account provisioning and SMTP recovery delivery. Read the
[complete authentication guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md) for the route table,
configuration, middleware ownership and testing. There is no public signup or
administrator panel in this starter.

This module owns `.templ` source and generated Go/CSS. Run `ui build` and
`ui check --json` using the matching framework CLI, in addition to its tests.


---

Source: `contrib/formsets/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/ref/formsets/index.md

# Formsets

Core FORM-03 battery for bounded collections of model forms and atomic inline
related-object editing. PostgreSQL 18 and GORM are supported. This is a separate
Go module, using experimental Cicadel app API 1 and the new `forms/model` API.
The declared app version is `v0.1.0`; no published module release is claimed.

For local development, require `github.com/fauzaanu/cicadel/contrib/formsets v0.0.0`
and replace it with this directory; also replace the framework module with the
repository root. Go does not inherit a dependency's replace directives. Consumers
must pin a real framework/module release once published. The generated consumer
test verifies local source integration, not remote versioned installation.

Standard projects register `formsets.App()` in `project/apps.go` for inventory
and provider validation. Retain this entry when adding local apps. The package owns no routes, schemas, assets, workers or migrations;
removing it never deletes application data. The default project includes this module through the public installable contract.

## Define and submit a collection

```go
set, err := formsets.New[LineItem](db, formsets.Config[LineItem]{
    Model: model.Config[LineItem]{Fields: []model.Field{
        {Name: "Description", Required: true, MaxRunes: 200},
        {Name: "Quantity", Required: true},
    }},
    Prefix: "lines", MaxForms: 100, MinItems: 1, MaxItems: 50,
    AllowDelete: true,
})
// Handle configuration errors during setup.
collection := formsets.Inline[Order, LineItem](orderID, "OrderID",
    func(tx *gorm.DB) *gorm.DB { return tx.Where("owner_id = ?", userID) })
posted, err := forms.Parse(r)
// Handle parse failure; use body limits, authentication and CSRF middleware.
bound := set.Bind(posted.Values)
result, err := bound.Save(r.Context(), collection)
```

Use imports `github.com/fauzaanu/cicadel/contrib/formsets`,
`github.com/fauzaanu/cicadel/forms`, and `model
"github.com/fauzaanu/cicadel/forms/model"`. Define parent/child models and recorded
PostgreSQL migrations normally, including foreign keys and unique constraints.
Never include the parent foreign key in editable fields. The parent identity is
trusted route/application input; parent authorization is mandatory.

The URL-encoded wire format is:

```text
lines-TOTAL_FORMS=3
lines-0-id=12
lines-0-description=Updated description
lines-0-quantity=2
lines-1-id=
lines-1-description=New item
lines-1-quantity=1
lines-2-id=15
lines-2-DELETE=on
```

Indexes are zero-based and contiguous. `TOTAL_FORMS` is required exactly once,
canonical decimal, and limited before allocating rows. MaxForms defaults to 100
and must be between 1 and 1000. MaxItems defaults to MaxForms; it limits stored
items, including existing rows omitted from this submission. MinItems defaults
to zero. IDs must be canonical positive integers within the model key type;
blank means new. Integer primary keys are supported; composite/UUID/string keys
are explicitly rejected in this first formset contract.

Duplicate identities, repeated control values, malformed/out-of-range indexes,
invalid typed input and unauthorized rows fail the whole batch. Unknown model
fields cannot cause mass assignment. A deleted row bypasses ordinary required
field validation; deleting an unsaved extra row simply discards it. Blank extra
rows are otherwise validated normally. Omitting a stored row preserves it.
Deletes are disabled unless AllowDelete is true. Boolean delete values are
`on`, `1`, `true`, `0`, `false`, or empty. Prefixes are ASCII identifiers; editable
input names cannot be `id`, `DELETE`, or contain hyphens.

`Bound.Errors()` returns nil or an independent `*formsets.Errors` snapshot.
`Rows[index]` contains field messages (empty field key is row-wide); `General`
contains collection messages. `Values(index)` and `Len()` support redisplay in
your existing typed components. No widget/HTML generation is added. Save-time
validation can also return `*Errors`; other errors are operational and must not
be shown verbatim. Parent authorization failure is `gorm.ErrRecordNotFound`.

## Atomic persistence

Inline locks the authorized parent `FOR UPDATE`, even for empty collections.
Existing submitted child identities are reloaded and locked in key order under
the parent scope before any writes. Item limits are calculated from the stored
collection, not a client-provided initial count. Explicit deletes run first,
then creates/updates run in submission order. This permits replacing a deleted
unique value. Swapping two surviving unique values is not implicitly staged;
PostgreSQL constraints decide whether it is valid.

Every save/delete, GORM hook, model-form check/hook, and formset hook uses the
same outer transaction. Any failure rolls back the entire batch. Results are
returned only after commit: Saved contains persisted rows in submission order;
Deleted contains removed IDs. GORM soft-delete behavior and authored database
cascade rules apply; this package does not invent cascades.

`BeforeDelete` and `AfterDelete` accept `(context.Context, *gorm.DB, *T)`.
Changing deletion identity is rejected. `Validate(context.Context, *gorm.DB)`
is a final cross-row validation hook: query the transaction and return `*Errors`
for safe collection messages. It should be read-only. Model hooks cannot move
saved rows outside the collection; persisted ownership fields are checked.
Limits are also rechecked after hooks. Use the supplied transaction for audit
or join-table writes; defer external side effects until commit or use an outbox.

For other collection structures, supply a `Collection[T]` with a trusted Lock,
Scope, Seed and Protected field names. Lock must serialize all membership changes
(including insertions into an empty collection); Scope filters rows on the supplied
transaction; Seed supplies trusted initial values. All writers—including code
outside this package—must honor the same collection lock for count guarantees.
Normal database deadlock/serialization errors remain operational errors; callers
may retry the complete operation. Repeated submissions are separate operations,
not implicit idempotent requests. Do not construct sets on an existing transaction;
the public Save result assumes ownership of the outer commit.

The core's `Form.InTransaction(tx)` is the general composition seam used here.
Individual model-form results inside that transaction remain provisional until
the outer commit. It accepts PostgreSQL transaction handles only and retains the
original model/naming configuration.

## Verification and boundaries

Tests cover malformed management data, bounded allocation, identity tampering,
scoped parent/child ownership, mixed add/edit/delete, omitted-row preservation,
zero values, replacement under uniqueness, limits, concurrent additions, and
rollback including deletion/audit hooks. A generated independent project
registers the app and exercises the API through HTTP form submissions. Lifecycle
checks verify removal does not perform schema/data cleanup. Tests create isolated
SQL fixtures, not AutoMigrate-managed schemas.

This completes FORM-03 for the documented integer-key collection contract.
Nested inline collections, automatic relation/widget inference, client-side row
editors, string/composite identities
are excluded. FORM-01 widgets/validators are complete; see [forms completion](https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md).
See [TESTING.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/contrib/formsets/TESTING.md) for reproducible checks.

`Model.VersionField` enables per-row `_version` validation for edits and deletes.
`IgnoreEmptyNew` optionally discards wholly empty new rows. `AdminInline[P,T]`
provides a typed inline editor and transactional adapter for `admin.Config[P]`.
Its parent authorization, ownership and child validation are covered by
`admin_test.go`. See the complete forms guide for configuration.


---

Source: `contrib/migrations/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/ref/migrations/index.md

# Model-driven migrations (experimental installable)

This independent Go module implements Cicadel's standard automated
migration battery. It uses GORM model metadata, compares it with recorded model
history, and writes **Goose SQL migration files**. Generation never opens a
database. Applying migrations remains an explicit, separate command.

For the default project workflow, use [the migration guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md). The lower-level APIs and standalone tools below operate on the same engine and support existing hosts and history maintenance.

## Try the complete workflow

From this repository:

```sh
cd contrib/migrations/example
go run . migrations:makemigrations notes --dry-run
go run . migrations:makemigrations notes --name initial
DATABASE_URL='postgres://user:password@localhost/app?sslmode=disable' go run . migrate
```

Edit `models/note.go`, adding `Published bool` with the tag
`` `gorm:"not null;default:false"` ``, then:

```sh
go run . migrations:makemigrations notes --name published
go run . migrations:makemigrations notes --check
go run . migrate
```

Keep `DATABASE_URL` in the environment when applying. `--check` exits unsuccessfully
if an unrecorded model change exists; it does not check which files the database
has applied. `--dry-run` prints the candidate file. Both modes leave files and
directories untouched. An unchanged model set writes nothing.

## Install and register

The source module lives at `github.com/fauzaanu/cicadel/contrib/migrations` and has
its own `go.mod`, tests and dependencies. Framework management imports this module as its canonical migration implementation.
There is no published package release yet. For local development, add a project
`replace` for this module to the checkout's `contrib/migrations` directory and
require it at `v0.0.0`; likewise replace the framework with this checkout. Before
publication, pin a released framework version and remove the development replace.
The manifest's `v0.1.0` is the experimental contract version, not an existing tag.

```go
import migrations "github.com/fauzaanu/cicadel/contrib/migrations"

// In your installed-app factory:
generator, err := migrations.New(migrations.Config{
    Apps: []migrations.Definition{{
        Name: "blog",
        Directory: "apps/blog/migrations",
        Models: []any{&blog.Author{}, &blog.Post{}},
    }},
})
// Check err, then register your blog app and generator with cicadel.New.
// Give the blog app Migrations: os.DirFS("apps/blog/migrations") for development,
// or embed the committed migrations in the production executable.
```

Run `migrations:makemigrations blog` through `management.Manager`. The app registers
this as a `BuildCommands` contribution. **Your project builder must inspect
`app.IsBuildCommand(args[0])` before opening the database or acquiring resources.**
The manager bypasses runtime hooks, provider checks and global runtime checks for
these commands. Constructors must also remain free of database work. See the
[runnable host](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/contrib/migrations/example/manage.go) for the full wiring; ordinary existing project
builders are not automatically rewritten by installing this module.

`models.go` and `models/*.go` both work: these are ordinary imported Go structs.
Explicitly register every managed model in `Definition.Models`. Alternatively, generate this registry using the build-time discovery command below. Use the same GORM naming
strategy in `Definition.NamingStrategy` and your runtime GORM configuration.
Each directory belongs to exactly one app. Cross-app relationships require
explicit pinned historical references, described below.

## File format and review

`00001_initial.sql` contains a model-state JSON comment followed by `-- +goose Up`
and `-- +goose Down` SQL. Later files record a hash of the preceding file. The
snapshot and SQL are published together as one file, with an exclusive generation
lock and an atomic no-overwrite publish. Every generation revalidates the history
and regenerates its expected SQL to detect accidental edits. Commit these files.
SQL from old files runs independently of current model definitions.

Review both directions before applying. Down statements can drop tables, columns
and data; their existence is not a promise of lossless rollback. Use the
checksum-aware `Runner` for PostgreSQL transactions, execution history,
locking and schema verification. Rollback uses an explicit target with
`cicadel-migrate -target APP=VERSION -allow-data-loss apply`, as shown below.

Handwritten histories require reviewed per-version snapshots and the explicit
import/adoption protocol below. Legacy generated formats require contiguous
versions; format 3 supports explicit branches and merges. Do not mix unrecorded
SQL into a managed directory. Use recorded data/schema declarations instead.
Generation validates immutable history offline; the runner additionally detects
applied-history changes and managed-schema drift against the live database.
Generation does not prove constraints will fit existing data.

## Supported slice

- PostgreSQL only; single or composite primary keys, optional integer identity.
- Built-in boolean, integer, float, string, byte and time fields; nullable columns,
  string lengths, and scalar defaults. Unsigned 64-bit values are limited to the
  PostgreSQL signed BIGINT range; choose signed types for predictable portability.
- Creating tables; adding ordinary nullable columns or non-null columns with an
  explicit scalar default; adding ordinary/unique indexes.
- Single/composite foreign keys to registered primary or unique keys in the same
  app, including belongs-to/has-one/has-many declarations and reference actions.
  Explicit join models represent relationship tables. All tables and indexes
  are created before foreign keys. Named check constraints are supported.
- Deterministic output, no-op detection, SQL preview, CI checks and reverse SQL.

Undeclared removals, renames and alterations are rejected. Explicit declarations
are described below. Remaining unsupported features include implicit many-to-many join tables,
native user-defined SQL types, unregistered custom storage mappings,
expression/default SQL and advanced indexes. Versioned built-in storage mappings
for custom fields and serializers are supported as described below.
Explicit `gorm:"-"`/migration-ignore fields remain unmanaged. Unsupported GORM
features may still be used with the existing handwritten migration workflow.
Other databases are excluded. Dependency graphs, compatible merges, replacement
bundles, verified baselines and managed-schema drift checks are supported with
the explicit boundaries documented below.

## GORM and GEN

GORM is already the runtime ORM. Normal Go models and GORM queries work today;
`AutoMigrate` is not called. This package generates schema migration files, and
The recorded-history runner applies them. [GORM GEN](https://gorm.io/gen/index.html) can additionally
generate type-safe query APIs from existing structs (`ApplyBasic`), or generate
structs from live tables. It does not replace historical schema diffing. GEN is
not a dependency of this package; the separate [querygen installable](https://cicadel.fauzaanu.com/en/0.2.7/ref/querygen/index.md)
generates queries from authored models and tests GORM version compatibility.

## Verification

```sh
go test -race ./...
go vet ./...
CICADEL_TEST_DATABASE_URL='postgres://.../disposable_test_database' go test -race ./...
```

The PostgreSQL integration test creates and drops its `ym_*` fixture tables and
`cicadel_modeltest_versions`. Use a disposable database. CI runs this nested module
explicitly: root `go test ./...` does not traverse nested modules.

## Build-time model discovery

Opt models in with `//cicadel:model` immediately above their exported struct
declarations. Helpers without that marker are excluded even in `models.go`.
Select the installed app packages explicitly; no runtime directory scanning occurs.
From the consumer module (after installing this module):

```sh
go run github.com/fauzaanu/cicadel/contrib/migrations/cmd/cicadel-models --out modelregistry/models.gen.go ./apps/blog ./apps/blog/models
go run github.com/fauzaanu/cicadel/contrib/migrations/cmd/cicadel-models --check --out modelregistry/models.gen.go ./apps/blog ./apps/blog/models
```

Use `modelregistry.Models()` in `Definition.Models`. The output package must be
separate from model packages to avoid import cycles. Go package/type analysis
respects imports, GOOS, GOARCH and `--tags`; excludes test files; rejects aliases,
generic and unexported model types. Run `--check` for every supported build
configuration before compilation. A configuration with a different model set
requires a separate registry/build configuration, not silently shared history.
`--check` detects a stale or missing registry without writing anything.

The runnable example uses generated discovery; its `models.Models()` function
also demonstrates the explicit-registration escape hatch. Regenerate it from
this module using:

```sh
go run ./cmd/cicadel-models --out example/modelregistry/models.gen.go ./example/models
```

## Declared PostgreSQL changes (format 2)

Explicit declarations were introduced in format 2; new files use format 3.
Format-1 and format-2 files remain readable and byte-for-byte immutable;
the next file links their existing hash. No conversion or rewrite is necessary.

Pass `Options.Changes` in Go or `--changes changes.json` to `makemigrations`.
Declarations run in order before inferred additions. For example, after renaming
`Body` to `Text` in the model (keeping its table name):

```json
[{"kind":"rename_column","table":"demo_notes","name":"body","to":"text"}]
```

```sh
go run . migrations:makemigrations notes --name rename_body --changes changes.json
```

Declarations are one migration's intent, not permanent model settings. Omit them
on subsequent no-op/check runs. Reusing a stale declaration fails validation.

Supported declarations:

- `rename_table` (`table`, `to`) and `rename_column` (`table`, `name`, `to`)
  preserve data and update recorded references. Implicit PK/identity names are
  renamed with their owning objects.
- `drop_table` and `drop_column` require a nonempty `reason` acknowledging data
  loss. Drop dependent indexes/FKs explicitly first; no implicit CASCADE.
- `drop_index`, `drop_check` and `drop_foreign_key` explicitly remove constraints. A changed
  model declaration then adds its replacement through the ordinary diff.
- `alter_column` supplies the complete target `column`. Type/size changes require
  an authored `using` expression and `reason`; `reverse_using` is optional and
  is an author's explicit claim that the reverse conversion is appropriate.
  Making a column non-null requires `backfill`, an SQL expression for NULL rows.
  Defaults may be changed or removed. Primary/identity alterations still fail.
- `data` supplies `up` and optional `down` SQL against historical table/column
  names, independently of current Go types. It must not change schema. SQL is
  trusted developer input; never interpolate request input into declarations.

A removal, backfill, conversion without `reverse_using`, or data operation without
`down` makes the migration irreversible: its Down raises an error. Restore a
backup or write a reviewed forward repair. Even an explicit inverse conversion
may lose information; review it against real data. A reversible schema change
is not a data backup. New constraints may fail against existing rows; PostgreSQL
rolls back the transactional migration, permitting correction and retry.

Preview/check validate all declarations and historical files before writing.
Embedded Goose directives in authored expressions/SQL are rejected. PostgreSQL
checks SQL syntax and data-dependent constraints when applying; offline generation
does not claim to prove arbitrary SQL expressions safe or valid.

## PostgreSQL catalog, execution and recovery

`Load(definitions...)` reads historical files without current models. Its catalog
orders migrations by version-level dependencies plus each app's previous version.
Set `Options.Dependencies` to refs such as `Ref{App: "accounts", Version: 2}` when
creating a dependent migration. Missing dependencies, cycles and inconsistent
applied prefixes fail planning. A target cannot orphan another app's dependency.
Format-3 histories support explicit branches, merges and replacement bundles as
described below; duplicate IDs and missing parent versions are rejected.

A standalone command avoids starting application runtime hooks:

```sh
# From contrib/migrations, after generating example migrations:
go run ./cmd/cicadel-migrate -app notes=example/migrations show
go run ./cmd/cicadel-migrate -app notes=example/migrations -offline sql
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations plan
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations apply
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations verify
# Roll back to a target after reviewing its Down SQL and taking a backup:
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations -target notes=1 -allow-data-loss apply
```

Repeat `-app APP=DIRECTORY` for **every managed app**, including dependencies.
`show` inspects artifacts offline; `status` reports applied/pending state from the
database. `migrate`, `showmigrations` and `sqlmigrate` alias `apply`, `status` and
`sql`, respectively. `plan` and `sql` compare against applied history.
`-offline` explicitly assumes a fresh database. `-timeout` bounds connection,
lock and execution time. Plans are rechecked under the shared Goose advisory lock.

The new `Runner` maintains `cicadel_migration_checksums` alongside existing
`cicadel_APP_versions` Goose history. Every migration's SQL, checksum and Goose
record commit atomically. A failure rolls back that migration; previously
committed migrations remain applied. Correct the data prerequisite and retry the
same immutable SQL. Do not edit an applied migration or rewrite its checksum.
Missing applied files, modified checksums, inconsistent dependencies and drift
fail explicitly. A commit error is reported as uncertain: inspect before retrying.

For an existing **generated** Goose history, use `adopt` once. Adoption verifies
the actual managed schema against the snapshot of the applied prefix before
recording checksums. It never marks pending migrations applied or overwrites
checksums. Unrecorded handwritten histories are not automatically adopted. Existing schemas
without history use the explicit initial-baseline workflow below.

Schema verification renders expected tables in a randomly named scratch schema
inside a transaction that is always rolled back. It requires database CREATE
privilege. Managed columns, defaults, identities, keys, constraints, indexes,
user-trigger presence and row-level-security enablement are compared; unrelated
tables are ignored. This is schema verification, not verification of row contents,
permissions, sequence counters, every PostgreSQL extension feature or external
processes that change schema without taking the migration lock.

Management commands and the standalone tooling use this same checksum-aware runner. The former core Goose executor has been removed. Existing Goose records require verified adoption before further migrations; applied SQL is never silently replayed.

### Authored schema SQL and initial baselines

`Record(definition, historicalState, options)` is the model-independent recording
API. `RecordData(definition, up, down, options)` uses the latest recorded state
without loading models. Both use the same atomic file publication and hash chain.

For handwritten schema SQL, a `Change{Kind: "schema", After: &state, Up: sql,
Down: reverseSQL, Reason: "..."}` records the complete resulting historical
state. Missing Down makes it irreversible. The transactional runner verifies
that SQL actually produced the declared state **before committing**; it also
checks tables declared removed are gone. Only schema features represented by
`State` can be verified. Transaction-control statements and concurrent DDL are
rejected. Explicit handwritten SQL is trusted developer code.

To adopt an existing database with no migration history, generate schema-only
initial files from its intended models, review them, then run:

```sh
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations -reason 'Adopt existing release after schema review and backup' baseline
```

Baseline requires exact managed-schema verification and no existing Goose history
for those apps or checksum-managed history in the database. Include all initial
apps in the same operation. Only generated initial schema files are eligible;
authored data SQL and later versions cannot be skipped this way. Initial SQL is
**not executed**. `cicadel_migration_baselines` permanently records the checksums,
reason and time of adoption, separately from execution history. Existing rows
remain intact. Later migrations execute normally. Existing Goose histories use
`adopt` instead; neither workflow can rewrite an existing checksum.

### Branches and replacements (format 3)

New files now use format 3, recording explicit parent IDs and hashes. Formats 1
and 2 remain readable without rewriting. Version IDs are unique positive integers;
format-3 IDs may have gaps so independently developed branches can allocate
separate IDs. Legacy formats retain their original contiguous-history contract.

Use `--parent VERSION --version NEW_ID` to generate a deliberate branch. On
combining branches, ordinary generation/application rejects multiple heads.
Create an explicit merge using `makemigrations --merge` with the combined models,
or, independently of models:

```sh
go run ./cmd/cicadel-migrate -app notes=example/migrations -name merge_branches merge
```

Compatible disjoint schema changes merge deterministically. Concurrent changes
to the same schema object, including duplicate additions, fail rather than
inventing a destructive resolution. Resolve unapplied conflicting work explicitly;
never edit a migration already applied to any deployment. Authored data SQL still
requires human review for semantic conflicts; schema snapshots cannot prove data
operations commute. Target versions select their ancestor closure, not every
smaller numeric ID. Rollback follows reverse dependency order.

Record a cross-app dependency with `--depends accounts:2` (repeat as needed), or
`Options.Dependencies`. All dependency apps must be supplied when loading/applying.
Data SQL can be recorded offline with `-up-file` and optional `-down-file` followed
by the `data` command; it reads historical state without importing current models.

Consolidate an app's ancestor history into a replacement:

```sh
go run ./cmd/cicadel-migrate -app notes=example/migrations -target notes=3 -name initial_history squash
```

The `.squash.json` bundle is canonical, checksummed and verified against every
original source. Fresh installations execute an eligible consecutive bundle in
one transaction and audit it in `cicadel_migration_replacements`. Partially applied
histories execute remaining originals, preserving data SQL order. Cross-app
ordering that interleaves bundle members also falls back to originals. Rollback
uses original reverse operations. SQL is consolidated, not optimized away.
**Retain the originals and the bundle**: deletion of either executed history is
an error, and originals remain necessary for older deployments. This workflow
supports replacement without assuming all users have already upgraded.

### PostgreSQL capabilities and nontransactional recovery

`Renderer("postgres")` exposes the versioned `SchemaRenderer` contract and its
capabilities. Other databases are rejected. `Render` is offline and accepts
historical before/after states and explicit declarations. PostgreSQL 18.4 is the
locally tested version; CI runs PostgreSQL 18. Ordinary schema operations run
transactionally. No support for unrelated database providers is implied.

One explicitly supported nontransactional operation is a single concurrent index
addition, selected with `Options.ConcurrentIndex` or
`makemigrations --concurrent-index INDEX_NAME`. Its reverse drops that index
concurrently. Mixing it with other schema changes is rejected before publication;
arbitrary nontransactional SQL and transactional replacement of concurrent-index
migrations are unsupported.

Before concurrent DDL, the runner commits a dirty marker. Failure or interruption
blocks ordinary apply/plan until recovery is deliberate. For a failed unique
index, inspect PostgreSQL's invalid index and duplicate rows, repair the data and
remove the known failed index explicitly. Then:

```sh
# Certify that the pre-migration schema is restored; this does not rerun SQL:
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations -target notes=3 -recovery retry recover
# Retry the immutable migration:
DATABASE_URL='postgres://.../app' go run ./cmd/cicadel-migrate -app notes=example/migrations apply
```

If DDL completed but the process stopped before recording completion, use
`-recovery complete` instead. It records completion only after verifying the
post-migration schema. Both actions are audited in `cicadel_migration_recoveries`.
Neither action blindly executes SQL, discards a dirty marker, drops an index, or
claims transactional rollback of nontransactional work.

### Cross-app model relationships

Pin the referenced app's recorded schema in the dependent definition:

```go
migrations.Definition{
    Name: "notes", Directory: "apps/notes/migrations",
    Models: []any{&notes.Note{}},
    References: []migrations.ReferenceSource{{
        App: "accounts", Version: 1, Directory: "apps/accounts/migrations",
    }},
}
```

The referenced model may appear in a GORM relationship field, but do not register
its table as owned by both apps. Generation resolves the pinned historical state,
records it in the dependent snapshot, and automatically adds the version-level
dependency. Catalog loading checks that the recorded referenced snapshot matches
the referenced migration. Every dependency app must be supplied to the runner.

Cross-app destructive changes require deliberate ordering: for example, first
record removal of a dependent FK, then rename the referenced table with a dependency
on that removal, then add the FK against the new pinned snapshot. The planner
will not guess how to coordinate a destructive change across apps. Explicit join
models with composite keys can refer to multiple app snapshots.

## Project initialization and runnable lifecycle

The [project workflow guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md) installs the commands with
Go tool directives and initializes an offline entrypoint. Run
`go tool cicadel-migrations-init -app blog=./apps/blog` after marking authored
models. Existing files are never overwritten. The separate-consumer test exercises
actual local module installation, discovery across `models.go` and `models/`,
regeneration checks, offline migration generation and PostgreSQL application.

From this module, run the complete disposable lifecycle:

```sh
DATABASE_URL='postgres://.../disposable_database' go run ./example/workflow
```

It preserves generated artifacts for review and removes its own uniquely named
schema. The walkthrough covers initial generation/application, a cross-app FK,
rename/rollback/reapply, conversion/backfill, historical data SQL, transactional
failure/retry and concurrent-index repair/recovery. Its integration test runs in CI.

### Importing an existing handwritten history

`ImportGoose(definition, []LegacySnapshot{...})` requires a reviewed schema state
and reason for **every** handwritten SQL version. It preserves all SQL bytes and
writes `.cicadel-legacy.json`, binding file hashes, historical states and declared
dependencies. `Reversible` defaults to false; a legacy Down is not evidence that
lost rows can be recovered. Later generated files link the imported fingerprints.

The CLI accepts the corresponding JSON array:

```sh
go tool cicadel-migrate -app blog=apps/blog/migrations -states-json reviewed_states.json import
DATABASE_URL='postgres://.../existing_app' go tool cicadel-migrate -app blog=apps/blog/migrations adopt
```

Existing applied prefixes are verified against their actual recorded schema
before adoption. Fresh installations execute the original SQL and generated
upgrades. Tests cover fresh, initial-prefix and fully-applied legacy histories.
Editing either imported SQL or its metadata changes the migration fingerprint.

Supported import directives are transactional Up/Down and
StatementBegin/StatementEnd. NO TRANSACTION, environment substitution, unknown
directives, transaction control and CRLF source files fail before publication;
convert unsupported histories deliberately rather than silently changing their
execution semantics. Snapshots must use supported PostgreSQL state metadata.
Adoption verifies schema, not historical row contents: reviewing old data SQL and
its provenance remains the operator's responsibility.

### Package-owned embedded histories

Runtime catalogs can use `Definition{Name: "packageapp", Source: migrationFS}`
with an `fs.FS` rooted at that app's migrations. This supports independently
installed packages and executables without source-tree access. Use
`//go:embed all:migrations` and `fs.Sub` when importing histories: the `all:` prefix
includes `.cicadel-legacy.json`. Generation/import/squash require a writable source
checkout and reject an embedded source. They never write into a dependency cache.
The separate-consumer integration test applies an embedded package history.

### Custom fields and serializers

Register explicit storage metadata in `Definition.CustomTypes`, keyed by the
explicit GORM `type` tag when present, otherwise its field data type. For example:

```go
CustomTypes: map[string]migrations.CustomType{
    "uuid": {Version: 1, SQL: "uuid"},
    "jsonb": {Version: 1, SQL: "jsonb"},
    "numeric": {Name: "money", Version: 1, SQL: "numeric(12,2)"},
},
```

`SnapshotWithOptions` accepts the same registry through `SnapshotOptions`.
Mappings use supported built-in PostgreSQL storage types and record their version
in historical state. Storage changes require explicit alteration declarations;
old SQL replays without the current custom Go field implementation. Native enum
and domain lifecycle management and arbitrary custom SQL types are unsupported.

## Handwritten schema metadata

Reviewed import snapshots can represent serial primary keys, named UNIQUE
constraints and the `now()` timestamp default. These are explicit historical
metadata, not inferred from the live database during generation. Verification
compares their PostgreSQL catalog signatures, including constraints and sequence
properties. Other SQL default expressions remain unsupported. Original SQL bytes
and applied versions are preserved during verified adoption.


---

Source: `contrib/migrations/example/migrations/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/contrib/migrations/example/migrations/README.md

Generated SQL belongs here. Run commands from the example directory.
Commit generated files; review their Up and Down sections before applying.


---

Source: `contrib/querygen/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/ref/querygen/index.md

# Typed query generation

This separately installable module generates GORM query APIs from authored Go
structs. PostgreSQL is the only supported database. It does not generate models,
read database schemas or generate/apply schema migrations.

Tested compatibility: GORM **v1.31.2**, GEN **v0.3.29**, dbresolver **v1.6.2**.
GEN's default dbresolver v1.5.3 fails to compile against this GORM version
(`undefined: gorm.Stmt`); keep the explicit v1.6.2 requirement. GEN transitively
depends on other vendor drivers through upstream datatypes; these are not
Cicadel database integrations and do not change the PostgreSQL-only contract.

From this module:

```sh
go run ./example/generate
go test -race ./...
CICADEL_TEST_DATABASE_URL='postgres://.../disposable_database' go test -race ./...
```

Regeneration tests compare every generated query file byte-for-byte with the
committed example and run twice. PostgreSQL tests compile and execute typed
create, filter and update queries. A separate temporary consumer module resolves
this module through a local replacement, generates its own query package from the
runtime catalog, then compiles and executes that exact output against PostgreSQL.
It verifies create/filter/delete, nested transaction rollback and canceled contexts
on a pinned connection with a transaction-local temporary table. This is local
installation verification, not evidence of a published release.

For local installation, require `github.com/fauzaanu/cicadel/contrib/querygen` at
`v0.0.0`, replacing it with this directory and replacing the framework with the
checkout. Run `go mod tidy`. No package release has been published yet.

Standard projects run `go run manage.go generatequeries` offline from registered `ModelOf` declarations. The generated `query/` directory is reviewed and committed. Existing custom hosts can register `querygen.New(querygen.Config{Models: registry.Models(),
OutputDirectory: "query"})` as an installed app. Run `querygen:generate` through
the host's management entrypoint, which must dispatch build commands before
opening a database. Explicit models work equally well without discovery.
The command writes generated queries to a dedicated output directory. Review
and commit generated files; remove obsolete generated files deliberately when
removing models. Do not store authored code in that directory.

Use `query.Use(db)` for instance-local query objects. The example deliberately
avoids GEN's package-global default database. Runtime models remain authoritative.
See the upstream [struct-based DAO configuration](https://gorm.io/gen/dao.html).

Catalog integration: pass `Config{Apps: installedApps, OutputDirectory: "query"}`
to consume app-owned `ModelOf[T]` declarations directly. `Apps` and `Models` are
mutually exclusive. Ownership and declared tables are validated before output;
tables must match GORM's default naming strategy, including `TableName` methods.
The factory snapshots declaration slices. Generation remains offline, does not
start apps, and never changes historical migration snapshots. Query model Go
names must be unique across selected apps and exported/importable.


---

Source: `docs/ai.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/intro/ai/index.md

# Build with an AI agent

Give your coding agent a task and the documentation index for your application's
version. Use this page to pick the right index and copy a starting prompt.

## Choose the documentation version

Pick a version with **Documentation version** on this page. The links and prompts
below change to match it.

| Version | Content |
| --- | --- |
| `dev` | Follows ongoing development |
| Released versions | Frozen; match that release exactly |

- [Application documentation index](https://cicadel.fauzaanu.com/en/0.2.7/llms.txt)
  links to focused Markdown guides.
- [Complete application documentation](https://cicadel.fauzaanu.com/en/0.2.7/llms-full.txt)
  bundles every guide, for when the agent needs broader context.

> [!TIP]
> The root `/llms.txt` currently points to `dev`. Put the version-specific URL in
> saved project instructions.

## Start an application

```text
Use https://cicadel.fauzaanu.com/en/0.2.7/llms.txt as your Cicadel documentation index.
Create a new application in ./myapp with module example.com/myapp.
The application should: [describe the users, screens, data and permissions].
Read the relevant guides before choosing APIs. Show concrete Go and .templ code.
Configure PostgreSQL for the standard accounts and recorded-migration workflow.
Register apps explicitly, rebuild generated UI, and run checks and tests.
Verify the resulting HTTP behavior and report the local URL and any remaining setup.
```

## Add a feature to an existing application

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/llms.txt.
First inspect this project's go.mod, registered apps, routes and existing UI.
Add [feature] using the project's conventions and matching Cicadel version.
Implement its handlers, components, validation and permissions.
If the schema changes, generate and review a recorded PostgreSQL migration.
Run the affected tests and the project's normal checks. Summarize the result.
```

## Fix a bug

```text
Use https://cicadel.fauzaanu.com/en/0.2.7/llms.txt and the relevant API guide.
Reproduce this problem: [steps, expected result, actual result].
Find the failing request or data flow, add a regression test, and fix it.
Preserve existing authorization, CSRF checks and migration history.
Run the test against the real affected behavior and report what passed.
```

## Give the agent useful context

Tell the agent:

- the application module path;
- the screen or route to change;
- the expected behavior;
- who may access the data.

> [!WARNING]
> Supply secrets through your agent's secure mechanism. Never paste them into a prompt.

For specialized work, point the agent at a skill. Skills are optional instructions
for building applications and reusable packages.

- [Component-authoring skill](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/SKILL.md)
- [Installable-app skill](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/SKILL.md)

## Framework design is separate

Application work does not need the framework roadmap or implementation history.
Those documents have a [separate framework index](https://cicadel.fauzaanu.com/en/0.2.7/framework/llms.txt).
Read [the philosophy](https://cicadel.fauzaanu.com/en/0.2.7/internals/philosophy/index.md) only for the reasoning behind Cicadel's design.


---

Source: `docs/api.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/ref/api/index.md

# API index

The source packages include Go documentation; inspect them with `go doc github.com/fauzaanu/cicadel/PACKAGE`.

| Package | Main entry points |
| --- | --- |
| `cicadel` | `App`, `Manifest`, `Requirement`, `New`, `Start`/`Close`, `InstalledApps`, `Resources`, `Check`, `SystemChecks`, `SystemCheck`, `CheckMessage`, `Run`/`Serve`, `Health`, `App.Settings`, `Application.PackageSettings`, `AppSettings`, `App.Events`, `App.Subscriptions`, `Application.Context`, `Application.Events` |
| `events` | `New[T]`, `Event[T].Emit`/`Handle`/`Name`/`Owner`, `Handler[T]`, `Declaration`, `Subscription`, `NewDispatcher`, `App`, `Dispatcher.Subscribers`, `WithDispatcher`, `FromContext`, `HandlerError`, `MaxDepth`, `ErrDepth`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md) |
| `settings` | `Defaults`, `Load`, `LoadWith`, `Settings.Validate`, `Settings.Env`; package settings `NewPackage[T]`, `Package.Resolve`/`Value`, `LoadPackage[T]`, `PackageSettings`, `Field`, `PackagePrefix`, `CoreKeys`, `Redacted`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/package-settings/index.md) |
| `urls` | `Path`, `Include`, `New`, `Router.Reverse` |
| `response` | `HTML`, `JSON`, `Redirect`, `Error`, `LocalPath` |
| `errorpages` | `Middleware`, `Options`, `Error`, `New`, `Default`, `Reason`, `ReasonCSRF`, `Event`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md) |
| `bodylimit` | `Apply`, `Set`, `Limit`, `ErrBodyRead`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/request-limits/index.md) |
| `htmx` | `Script`, `Handler`, `HTML`, `IsRequest`, `IsPartial`, `Trigger`, `TriggerDetail`, `Redirect`, `Location`, `Refresh`, `Retarget`, `Reswap`, `Reselect`, `PushURL`, `ReplaceURL`, `CSRFHeaders`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md) |
| `ui` | `Definition[P,S]`, `Content`, `Text`, `Fragment`, `Group`, `Renderer`, `Merge`, `URL`, `Resolve`, `Diagnostic`, `Committed` |
| `ui/layout`, `ui/form` | Minimal document (`layout.Props`: `Title`, `Stylesheet`, `Lang`, `Dir`, `CSRFToken`) and accessible field/CSRF components |
| `uic` | `Compile`, `Generate`, `GoDiagnostics`; `cicadel ui generate/build/check`, `ui css install/build/check` |
| `templates` | Deprecated experimental compatibility: `New`, `Engine.Render`, `Engine.HTML` |
| `database` | `Open`, `Migrator`, `Migrate`, `Atomic`, `OnCommit`, `ErrNoTransaction`; [transactions](https://cicadel.fauzaanu.com/en/0.2.7/howto/transactions/index.md) |
| `apptest` | `Check`: per-instance lifecycle smoke checks for app authors |
| `management` | `Manager.Run`, `Manager.CommandNames`, `UsageError`, `ExitCode`, custom `Command` |
| `forms` | `Parse`, legacy `Form.Required`/`Valid`; typed `New`, `Typed[T]`, built-in fields/validators, `Definition.Bind`, `Value[T]` |
| `forms/upload` | `Parse`, `Middleware`, `FromRequest`, `Batch.Save`/`Close`, `CleanupError` |
| `forms/model` | `New[T]`, `Config[T]`, `Field`, `Bind`, `Bound.Create`/`Update`, `Related[R]`, `InTransaction`, `Errors`; [model-form contract](https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md) |
| `security` | `NewSessions`, `Login`, `Logout`, `CSRF`, `CSRFFailureMessage`, `RequireLogin`, password helpers |
| `signing` | `Keys`, `NewKeyring`, `Keyring.Signer`, `For`, `Signer.Sign`/`Verify`/`VerifyNoExpiry`/`Issued`/`WithClock`, `SignJSON`, `VerifyJSON[T]`, `GenerateKey`, `ErrInvalid`, `ErrExpired`, `ErrNoKey`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/signing/index.md) |
| `admin` | `Routes[T]`, explicit `Config[T]`, `Field`, permission `Action` |
| `api` | `Decode`, `Pagination`, `Fail`, generic `List[T]` |
| `static` | `URL`, `NewManifest`, `Manifest.URL`/`Handler`/`Collect`, `ParseURL`, `Handler` (single directory); [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md) |
| `paginate` | `Parse`, `Options`, `Request`, `Query[T]`, `Slice[T]`, `Page[T]` (`URL`, `Links`), `Nav`, `Navigation`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md) |
| `flash` | `New`, `Messages.Add`/`Success`/`Info`/`Warning`/`Error`/`Pop`/`Peek`, `List`, `ErrNoSession`; [guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md) |
| `observability` | `NewLogger`, `NewLogging`, `Logger`, `Middleware`, `RequestID`, `Event`, `OpenRotatingFile`, `NewEmailHandler`, `NewQueryLogger` |
| `jobs` | `Migrate`, `NewProducer`, `InsertTx`, `NewWorker` |
| `mail` | `Message.Bytes`, `Sender.Send`/`SendMany`, `SMTP`, `Transport`, `RenderComponent`, `Render`, `Capture`, `Console`, `File`, `Discard` |
| `storage` | `Store`, `NewLocal`, `HTTP`, `ValidateKey` |
| `cache` | `NewMemory`, `Get`, `Set`, `Delete` |

The CLI is `go run ./cmd/cicadel startproject DIRECTORY MODULE`, `startapp NAME [DIRECTORY]`, or `startpackage DIRECTORY MODULE NAME`. See [installable apps](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md). The full workflow is in [the tutorial](https://cicadel.fauzaanu.com/en/0.2.7/intro/tutorial/index.md); integration boundaries and limitations are in [extensions](https://cicadel.fauzaanu.com/en/0.2.7/topics/extensions/index.md).

Native i18n/l10n APIs are intentionally absent. See [the battery support policy](https://cicadel.fauzaanu.com/en/0.2.7/sources/batteries.md) for package-extension plans and current capability gaps.

The approved UI architecture is [composable components](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md). The compiler/runtime and typed library contracts are implemented; legacy template calls remain a separate compatibility API.

Tailwind is the first-party default; see [CSS tooling](https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md) and the
[tested component authoring guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md).

The first-party [formsets module](https://cicadel.fauzaanu.com/en/0.2.7/ref/formsets/index.md) adds `New[T]`,
`Inline[P,T]`, `Collection[T]`, `Bound.Save` and `App` for atomic collections.

See [complete forms](https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md) for widgets, revision tokens, uploads
and atomic administration inlines.

The first-party [accounts module](https://cicadel.fauzaanu.com/en/0.2.7/ref/accounts/index.md) exports `Service.Browser`, `Browser.HTMLApp`, `Browser.Middleware`, `Browser.Login`/`Logout`, `Browser.LoginRequired`, `Browser.RequireLogin`, and typed `accountui.Page`. See [authentication](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md), [email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md) and [logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md) for complete integration contracts.

The [foundation guide](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md) documents `cicadel dev`, command help and
structured deployment checks, configuration precedence and lifecycle contracts.


---

Source: `docs/authentication.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md

# Browser authentication and the accounts starter

The accounts app signs users in with server-side sessions and CSRF checks.
Every generated project includes it.

## How it fits together

Cicadel has one core accounts service and two HTTP adapters:

- **Browser adapter.** Server-rendered HTML, server-side SCS sessions and CSRF checks.
- **JSON bearer adapter.** For API clients that send `Authorization: Bearer …`.

Both adapters read the same PostgreSQL users, account sessions, recovery tokens,
groups and permissions. Disabling an account, resetting its password or revoking
its sessions affects both. A browser never receives the account bearer token in
HTML or JSON.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md.
Add browser sign-in to my application using the accounts starter or adapter.
Use PostgreSQL sessions, CSRF protection and verified recovery addresses.
Show the registration and route protection code. Test sign-in, sign-out,
and rejection of revoked sessions; keep secrets outside source code.
```

## Create the starter

From the framework checkout:

```sh
go build -o bin/cicadel ./cmd/cicadel
./bin/cicadel startproject /tmp/myapp example.com/myapp
cd /tmp/myapp
go mod edit -replace=github.com/fauzaanu/cicadel=/absolute/path/to/Cicadel
go mod edit -replace=github.com/fauzaanu/cicadel/contrib/accounts=/absolute/path/to/Cicadel/contrib/accounts
go mod edit -replace=github.com/fauzaanu/cicadel/contrib/formsets=/absolute/path/to/Cicadel/contrib/formsets
go mod edit -replace=github.com/fauzaanu/cicadel/contrib/migrations=/absolute/path/to/Cicadel/contrib/migrations
go mod edit -replace=github.com/fauzaanu/cicadel/contrib/querygen=/absolute/path/to/Cicadel/contrib/querygen
go mod tidy
export DATABASE_URL='postgres://USER:PASSWORD@localhost/myapp?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run manage.go migrate
CICADEL_USER_PASSWORD='a local account password' go run manage.go createuser owner@example.com
go run manage.go runserver
```

`startproject` always includes accounts, formsets and the standard migration
workflow. Runtime commands need PostgreSQL.

The accounts module ships with the framework at the same version. Keep all core
modules on one version, and commit your resolved Go dependencies.

### Who can have an account

- The stored username is the account's verified recovery address. Create accounts
  only for email addresses whose ownership you have verified.
- Requests cannot supply a separate delivery address.
- There is no public registration endpoint and no administrator panel.
- Use the service's `Create` API for your own provisioning and invitation workflows.

## Screens and actions

The default prefix is `/accounts`. Change it with `accounts.Pages.Prefix`.

| Route | GET | POST |
| --- | --- | --- |
| `/accounts` | Signed-in account and session actions | — |
| `/accounts/login` | Login form | Rotate session and sign in |
| `/accounts/recover` | Recovery form | Deliver a reset link to the verified destination |
| `/accounts/reset` | Reset form with token | Consume the token once and replace the password |
| `/accounts/change-password` | Current/new password form | Replace password and revoke all sessions |
| `/accounts/logout` | — | Revoke current account session and destroy its cookie session |
| `/accounts/revoke` | — | Revoke all account sessions and sign out |
| `/static/accounts/app.<hash>.css` | Embedded compiled stylesheet, published through `App.Static` | — |

To customize the screens, compose your own pages with `contrib/accounts/accountui`.

## Integrate an existing application

Create the service and the browser adapter in your project setup. Then register
the returned app:

```go
service, err := accounts.New(accounts.Options{
    DB: db,
    DeliverRecovery: DeliverRecovery,
})
if err != nil {
    return err
}
browser, err := service.Browser(security.NewSessions(store, true))
if err != nil {
    return err
}
authApp, err := browser.HTMLApp(accounts.Pages{
    Brand: "My application",
    Logger: logger,
})
if err != nil {
    return err
}
installed = append(installed, authApp)
```

This fragment uses your PostgreSQL `db`, shared session `store`, logger, recovery
callback and existing `[]cicadel.App`. Pass `installed` to the project's
`cicadel.New` call.

1. Register the adapter once.
2. Run `migrate` before serving.

The generated starter has the full setup in `project/application.go`.

## Protect a view

Send anonymous visitors to the sign-in page, like Django's `login_required`.
Install `browser.Middleware` and `browser.LoginRequired` on the app that owns the
views:

```go
notes := cicadel.App{
    Name: "notes",
    Middleware: []cicadel.Middleware{
        browser.Middleware,
        browser.LoginRequired("/accounts/login"),
    },
    Routes: []urls.Route{
        urls.Path("GET", "/notes/{id}", "notes:detail", detail),
    },
}
```

An anonymous `GET /notes/42` is redirected to
`/accounts/login?next=%2Fnotes%2F42`. The sign-in page carries `next` in its form
and returns there after a successful sign-in.

- Unsafe requests (POST, DELETE …) are redirected without `next`, so signing in
  never repeats an action.
- htmx requests get `HX-Redirect`, so the whole page navigates. `next` is the
  page the request came from (`HX-Current-URL`) when it is on the same host.
- `next` is only ever a local path. The sign-in page ignores `//evil.test`,
  `https://…`, backslashes and control characters, and returns to the account
  page instead.
- `LoginRequired` panics at startup when its login URL is not a local path.

For JSON routes, use `browser.RequireLogin` instead. It answers 401.

- Apply `browser.Middleware` first. It loads the session, checks CSRF and resolves
  the user.
- Read the user with `accounts.UserFromContext` inside handlers.
- Both guards check a freshly resolved account, not only a stored SCS user ID.

> [!WARNING]
> Login is not authorization. Object permissions still need explicit application
> policy and scoped database queries. Check them inside the handler.

`HTMLApp` already applies LoadAndSave → CSRF → account resolution to its own routes.
Do not wrap those routes with the same middleware again.

## Sessions

- The starter stores sessions in the PostgreSQL table `accounts_browser_sessions`,
  using SCS's configurable table name. You can supply a custom store instead.
- Migration 002 adds that table without rewriting existing accounts history.
- Sessions are HttpOnly, SameSite=Lax and secure by default.
- Sessions rotate on login and clear at logout.
- Account expiry and revocation are checked on every browser request.
- SCS expiry can end a session before its account token expires.
  `accounts:cleanup` removes expired tokens.
- Every unsafe method requires CSRF.
- Bodies under `browser.Middleware` keep the application's limit,
  `settings.MaxBodyBytes`, or a route's own limit (see
  [Limit request bodies](https://cicadel.fauzaanu.com/en/0.2.7/howto/request-limits/index.md)). The account pages bound their own
  forms to 8 KiB.
- htmx requests send the CSRF token as a header when the page sets
  `layout.Props.CSRFToken` (see [htmx](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md#csrf-for-htmx-requests)).

## API clients

For API-only clients, use `service.HTTPApp(prefix)` and `service.Middleware` with
an explicit `Authorization: Bearer …` header.

Register either adapter once, under the `accounts` app name. If a host needs both,
combine their routes into that one app. Scope the cookie middleware to the HTML
routes.

> [!WARNING]
> Never apply cookie CSRF middleware to a bearer-only API by accident.

## React to account changes

The accounts service emits typed events such as `accounts.UserCreated`,
`accounts.LoggedIn` and `accounts.PasswordChanged`. See
[accounts events](https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md#accounts-events).

## Recovery delivery

`project.DeliverRecovery` is the application-owned callback that sends reset links.
It:

- sends to the stored verified address;
- builds a local reset route from the configured origin;
- passes the token only to the mail transport.

Recovery reveals nothing about which usernames exist:

- Known and unknown users get the same recovery response.
- Missing delivery configuration is handled without revealing whether a username exists.
- Delivery errors are logged without tokens, addresses or server response text.

Passwords must be 12–72 bytes. Applications may add their own password policy.

Configure these starter environment variables:

| Variable | Purpose |
| --- | --- |
| `CICADEL_PUBLIC_URL` | HTTPS origin used to construct reset links |
| `CICADEL_MAIL_FROM` | Sender mailbox |
| `CICADEL_SMTP_ADDRESS` | SMTP `host:port` with STARTTLS |
| `CICADEL_SMTP_USERNAME`, `CICADEL_SMTP_PASSWORD` | Optional SMTP credentials |
| `CICADEL_LOG_FORMAT`, `CICADEL_LOG_LEVEL` | JSON/text format and log threshold |

## Deploy

1. Use HTTPS and secure cookies.
2. Configure allowed hosts.
3. Apply gateway rate limits to the login and recovery endpoints.
4. Schedule `manage.go accounts:cleanup`.
5. Do not log query strings on reset routes at the proxy.

Reset pages send `no-referrer`, `no-store` and a restrictive content security
policy. See [email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md), [logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md) and
[operations](https://cicadel.fauzaanu.com/en/0.2.7/howto/operations/index.md) for configuration details.


---

Source: `docs/cache.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/cache/index.md

# Cache application data

The `cache` package stores expensive results as bytes for a limited time. Like
Django's `CACHES`, you name each cache and pick a backend for it.

`cache.Backend` is the context-aware interface that backends implement. You can
replace the backend without changing the code that uses it.

## Cache a value

```go
backend, err := cache.NewMemoryBackend(1000, 64*1024)
if err != nil { return err }
registry, err := cache.NewRegistry(map[string]cache.Alias{
    "articles": {Backend: backend, Namespace: "production:blog", Version: "v1"},
})
if err != nil { return err }
articles, err := registry.Lookup("articles")
if err != nil { return err }
err = articles.Set(ctx, "public:42", []byte("cached payload"), time.Minute)
```

Build the registry at startup. Then inject the clients into your apps.

## Misses and errors

| Result | Meaning |
| --- | --- |
| `(nil, false, nil)` | A miss. |
| An error | An outage. Check it with `errors.Is`. |

On an error, you choose whether to fall back to the authoritative data source.
Cicadel never decides that for you.

> [!WARNING]
> Never use cache contents for session revocation, authorization decisions or
> distributed locking.

## The memory backend

`NewMemoryBackend(capacity, maxValueBytes)` is a bounded, concurrent backend that
lives in one process.

- It copies values in and out.
- Entries expire at the TTL boundary.
- When full, it evicts the oldest written entry.
- The existing `Memory` and `Store` APIs remain compatible.

Each instance is local to one application process. It does not coordinate with
other processes. Use a suitable shared backend when several instances must share entries.

## Keys

The registry copies the alias map. Each alias hashes its name, namespace and
version together with your key into a length-framed SHA-256 key.

- Raw keys never reach the backend.
- Keys must be 1–1024 bytes.
- TTLs must be positive.
- Hashing does not encrypt values.

Put every variation into the logical key: tenant, locale, permission and
representation, where they apply.

## Invalidate entries

- `Delete` removes one logical key. Deleting a missing key succeeds.
- Changing `Version` selects a fresh key space. Old entries expire on their own.
  Every process must adopt the new version to agree on the active generation.
- There is deliberately no global flush.

Readers and writers in flight can race with a delete. Invalidation is not
transactional.

## Write a backend

A backend must:

- be safe for concurrent use;
- preserve byte ownership;
- implement positive TTLs;
- report operational errors.

Cancellation can race with a completed write. An error does not prove the change
was rolled back. The built-in backend checks cancellation before its short
in-memory operation. Network backends should pass the context to their transport.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/cache/index.md.
Cache [expensive read] in this application. Include tenant and permission
variation in the key, set a TTL, define invalidation after writes, and keep
the database authoritative. Test hits, misses and backend failures.
```

## Coalescing expensive loads

Create one `cache.NewLoader(client)` and reuse it. Then call
`loader.Get(ctx, key, ttl, load)`. The `load` function takes a context and returns
`([]byte, error)`.

- Hits skip the function.
- Concurrent misses for the same key share the first caller's function and TTL.
  Different keys load independently.
- The loader rechecks the cache before loading, which closes the miss/join race.
- Successful loads fill the cache. Load and backend failures propagate, and callers can retry.
- Every caller gets its own copy of the result.

### Cancellation

Cancelling a caller stops only that caller's wait. The load keeps the first
caller's context values. It ends when every waiter cancels or the work finishes.

### Rules for load functions

- Honor cancellation.
- Never call back into the same loader and key.
- Use keys that include every authorization and tenant variation.
- Keep one load policy per loader.

Coordination is local to one loader instance, not across processes. Deletes and
concurrent writes keep the best-effort consistency described above.

## Bounded load execution

For request-serving apps, cap concurrent loads and give each one a deadline:

```go
loader := cache.NewBoundedLoader(client, 32, 5*time.Second)
```

Both limits must be positive.

- Hits still work at capacity.
- Callers that join an existing load share its slot.
- New misses at capacity get `cache.ErrLoaderBusy` immediately. Check it with
  `errors.Is` and choose your own retry or fallback.

The deadline covers the backend recheck, the load and the write. Functions and
backends must cooperate with cancellation.

An abandoned load keeps its slot until it actually returns. This stops repeated
cancelled requests from starting unlimited replacement goroutines.

> [!WARNING]
> A load function that ignores cancellation can use up every slot. Go cannot force
> it to stop.

`NewLoader` stays compatible and unbounded. Neither constructor provides
distributed admission control or transactional invalidation.

Race-tested evidence:

- `TestBoundedLoaderAdmissionAndAbandonedExecution` checks capacity rejection,
  abandoned-write prevention and slot reuse.
- `TestBoundedLoaderDeadline` checks deadline propagation and limit validation.


---

Source: `docs/component-authoring.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md

# Build a page with components

Components are Cicadel's replacement for Django templates. This walkthrough builds
a card component and a list page, then wires up the view, URL and tests.

Every snippet below is real code. `TestComponentAuthoringGuide` copies each file
into a generated project, then compiles and renders it.

See also:

- [Component UI](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md): the full API contract.
- [Tailwind CSS](https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md): styling.
- [`$cicadel-components`](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/SKILL.md): the reusable agent skill.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md.
Add [screen] to my application using typed Cicadel components.
Inspect the current app structure, compose the page from explicit props and slots,
and connect its handler and route. Build the UI and test its rendered output.
```

## Translate what you know

Think "props down, markup composed, HTML returned." Cicadel borrows React's
composition model, not its JavaScript runtime.

| React habit | Cicadel equivalent |
| --- | --- |
| Function component with typed props | Private `.templ` function; public `ui.Definition[Props, Slots]` contract |
| `<Card title="Hello">…</Card>` | `@Card.Call(CardProps{Title: "Hello"}, CardSlots{Children: ...})` |
| `children` / a ReactNode prop | `ui.Content` fields named `Children`, `Footer`, etc. |
| Fragment `<>…</>` | Private markup helper via `ui.Fragment(helper(...))`, or `ui.Group(...)` |
| `{title}` | `{ p.Title }` (text escapes automatically) |
| `{items.map(...)}` | A multiline Go `for` block |
| Conditional JSX | A multiline Go `if` or `switch` block |
| Default/destructured props | Go zero values plus a pure `Defaults` function |
| `className`, `htmlFor` | HTML `class`, `for` |
| Boolean HTML prop | `disabled?={ p.Disabled }` |
| Utility classes | Tailwind v4, complete class strings in source |
| Context provider / hook state | Explicit typed inputs; handlers load data and process POSTs |
| `onClick` / hydration | Not part of this server engine; use links/forms for server interactions |
| `key` | No reconciliation runtime, so no key prop; keep DOM IDs unique for labels |

Do not add JSX, hooks, npm or a browser CDN script to write components. Tailwind
runs from a pinned standalone build tool.

## Set up the project

1. Generate a project with the module path `example.com/componentguide`.
2. Run `go mod tidy`.
3. Install the CSS compiler once with `go tool cicadel ui css install`.

You add the files below to an ordinary local Go app. You do not need a new module.

## 1. Define the contract

The contract declares the props, slots, defaults and validation.

### apps/dashboard/card.go

<!-- file: apps/dashboard/card.go -->
```go
package dashboard

import (
    "fmt"
    "github.com/fauzaanu/cicadel/ui"
)

type CardProps struct {
    Title string
    Tone string
}
type CardSlots struct { Children, Footer ui.Content }

var Card = ui.Definition[CardProps, CardSlots]{
    Name: "dashboard:card",
    Source: "apps/dashboard/card.templ",
    Defaults: func(p CardProps) CardProps {
        if p.Tone == "" { p.Tone = "neutral" }
        return p
    },
    Validate: func(p CardProps, s CardSlots) error {
        if err := ui.Required("Title", p.Title); err != nil { return err }
        if s.Children.Empty() { return fmt.Errorf("Children slot is required") }
        if p.Tone != "neutral" && p.Tone != "success" {
            return fmt.Errorf("unknown Tone %q", p.Tone)
        }
        return nil
    },
    Body: card,
}

func cardClasses(tone string) string {
    if tone == "success" { return "rounded-xl border border-emerald-300 bg-emerald-50 p-6" }
    return "rounded-xl border border-slate-200 bg-white p-6"
}
```

The rules this contract sets:

- An empty `Tone` defaults to `neutral`.
- An empty `Title` or a missing `Children` slot is an error.
- `Footer` is optional.

Zero and `false` are not always "missing". Use pointer props only when an omitted
value must differ from a supplied zero or `false`.

> [!WARNING]
> `Defaults` must not mutate objects referenced by caller-owned maps, slices or pointers.

## 2. Write the markup

### apps/dashboard/card.templ

<!-- file: apps/dashboard/card.templ -->
```templ
package dashboard

templ card(p CardProps, s CardSlots) {
    <section class={ cardClasses(p.Tone) }>
        <h2 class="text-xl font-semibold text-slate-900">{ p.Title }</h2>
        <div class="mt-3 text-slate-700">@s.Children</div>
        if !s.Footer.Empty() {
            <footer class="mt-4 text-sm text-slate-500">@s.Footer</footer>
        }
    </section>
}
```

Two kinds of insertion, on purpose:

| Syntax | Inserts |
| --- | --- |
| `{ p.Title }` | Escaped text. |
| `@s.Children` | A typed HTML fragment. |

Write complete utility class names in Go variants, as `cardClasses` does. Tailwind
cannot evaluate `"bg-" + color + "-50"`.

## 3. Compose the page

### apps/dashboard/page.templ

<!-- file: apps/dashboard/page.templ -->
```templ
package dashboard

import "github.com/fauzaanu/cicadel/ui"
import "github.com/fauzaanu/cicadel/ui/layout"

templ itemFooter() {
    <a class="underline hover:text-indigo-600" href="/">Back to home</a>
}

templ dashboardBody(rows []Item) {
    <div class="mx-auto max-w-3xl space-y-6 px-6 py-12">
        <h1 class="text-3xl font-bold">Dashboard</h1>
        if len(rows) == 0 {
            <p>No items yet.</p>
        }
        for _, row := range rows {
            @Card.Call(CardProps{Title: row.Title, Tone: row.Tone}, CardSlots{
                Children: ui.Text(row.Description),
                Footer: ui.Fragment(itemFooter()),
            })
        }
    </div>
}

templ dashboardPage(rows []Item, stylesheet string) {
    @layout.Page.Call(layout.Props{Title: "Dashboard", Stylesheet: stylesheet},
        layout.Slots{Children: ui.Fragment(dashboardBody(rows))})
}
```

- Private helpers such as `itemFooter` need no public definition. Add one only for
  a reusable, validated contract.
- `ui.Text` wraps request text and escapes it.
- `ui.Fragment` adapts compiled markup. Never pass it strings.
- `ui.Group` combines fragments that are already typed.

## 4. Add the view and URL

### apps/dashboard/app.go

<!-- file: apps/dashboard/app.go -->
```go
package dashboard

import (
    "context"
    "log/slog"
    "net/http"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/static"
    "github.com/fauzaanu/cicadel/ui"
    "github.com/fauzaanu/cicadel/urls"
)

type Item struct { Title, Description, Tone string }
type LoadItems func(context.Context) ([]Item, error)

func New(load LoadItems) cicadel.App {
    return cicadel.App{
        Name: "dashboard",
        Components: []ui.Export{Card.Export(1)},
        Routes: []urls.Route{urls.Path("GET", "/dashboard", "dashboard:index",
            func(w http.ResponseWriter, r *http.Request) {
                rows, err := load(r.Context())
                if err != nil { response.Error(w, 500); return }
                stylesheet, err := static.URL(r.Context(), "project", "app.css")
                if err != nil { response.Error(w, 500); return }
                err = (ui.Renderer{}).HTML(r.Context(), w, 200, ui.Fragment(dashboardPage(rows, stylesheet)))
                if err != nil {
                    slog.ErrorContext(r.Context(), "render dashboard", "error", err)
                    if !ui.Committed(err) { response.Error(w, 500) }
                }
            }),
        },
    }
}
```

- The loader is explicit. It can query through your application's database.
- The component never discovers a request-wide map.
- `static.URL` resolves the project's compiled stylesheet to its content-hashed URL.
  The handler passes it in as a prop. See [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md).
- Keep permissions in the handler and its query scope.

### Register the app: project/apps.go

For the runnable demo, replace the starter's empty app list with this loader:

<!-- file: project/apps.go -->
```go
package project

import (
    "context"
    "example.com/componentguide/apps/dashboard"
    "github.com/fauzaanu/cicadel"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{dashboard.New(func(ctx context.Context) ([]dashboard.Item, error) {
        return []dashboard.Item{{Title: "Ready", Description: "Typed props and slots work.", Tone: "success"}}, ctx.Err()
    })}, nil
}
```

In your own project, use your module's import path.

A direct call to `Card` uses that definition. For an overridable library, resolve it
through `ComponentRegistry` and inject the result into the page factory. See
[the override recipe](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/references/patterns.md#libraries-and-project-overrides).

## 5. Test the behavior

### apps/dashboard/app_test.go

<!-- file: apps/dashboard/app_test.go -->
```go
package dashboard

import (
    "context"
    "strings"
    "testing"
    "testing/fstest"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/apptest"
    "github.com/fauzaanu/cicadel/ui"
)

func TestDashboard(t *testing.T) {
    attack := `<script>alert("x")</script>`
    project := cicadel.App{Name: "project", Static: fstest.MapFS{"app.css": {Data: []byte("body{}")}}}
    app := apptest.New(t, apptest.Settings(), []cicadel.App{project,
        New(func(context.Context) ([]Item, error) {
            return []Item{{Title: attack, Description: attack}}, nil
        }),
    })
    stylesheet, err := app.Static().URL("project", "app.css")
    if err != nil { t.Fatal(err) }
    res := apptest.NewClient(app).Get(t, "/dashboard").Status(t, 200)
    res.Contains(t, `rel="stylesheet"`).Contains(t, `href="`+stylesheet+`"`)
    res.Contains(t, "Back to home").Contains(t, "border-slate-200")
    if strings.Contains(string(res.Body), "<script>") { t.Fatal("unescaped input") }
}

func TestCardContractAndEmptyList(t *testing.T) {
    renderer := ui.Renderer{}
    if _, err := renderer.Render(t.Context(), Card.Call(CardProps{Title: "x"}, CardSlots{})); err == nil {
        t.Fatal("missing children accepted")
    }
    if _, err := renderer.Render(t.Context(), Card.Call(CardProps{Title: "x", Tone: "invalid"}, CardSlots{Children: ui.Text("x")})); err == nil {
        t.Fatal("invalid tone accepted")
    }
    out, err := renderer.Render(t.Context(), ui.Fragment(dashboardPage(nil, "")))
    if err != nil || !strings.Contains(string(out), "No items yet.") { t.Fatalf("%s: %v", out, err) }
}
```

These tests check behavior, not a full HTML snapshot. Add assertions for your own
fields, labels, error relationships, links and authorization rules.

## The edit loop

```sh
go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go run manage.go check
```

Then restart `go run manage.go runserver` to load the rebuilt embedded markup and CSS.

- `ui check` reports missing or stale artifacts. `ui build` fixes them.
- Commit `.templ` files, ordinary Go, CSS input and config, generated Go and generated CSS together.
- Do not hand-edit generated output.
- The starter's CSS is already compiled. The first run does not download a compiler or need Node.
  After UI changes, install the tool once and rebuild.
- Class sources from installed libraries go in the `packages` list of `ui.css.json`.

## Common mistakes

- Write multiline `if` and `for` blocks, not JavaScript ternaries or inline JSX blocks.
- Use `class`, not `className`. Use complete utility names, not dynamic name fragments.
- `ui.Merge` merges tokens, not Tailwind conflict groups. With `p-2 p-6`, the last
  one is not promised to win. Pick a single spacing variant instead.
- Pass slot values explicitly. `{ children... }` is intentionally unsupported.
- Keep CSS out of markup. Inline styles, scripts, event attributes and active SVG
  are not in the initial component contract. Do not work around that with raw HTML.
- Keep CSRF and accessible errors by using `ui/form` with explicit session tokens.
- Fix failures in the authored source. JSON diagnostics point to source components
  and keep generated Go positions. Never fix a type error in `*_templ.go`.

For targeted fixes to forms, defaults and forwarding, see the
[skill's pattern reference](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/references/patterns.md).

## Give the skill to your coding agent

The portable skill lives at `skills/cicadel-components/`, with its patterns and
debugging reference. The repository's `AGENTS.md` points agents to it for UI tasks.

With Codex:

1. Copy the directory into `${CODEX_HOME:-$HOME/.codex}/skills/`, or use your skill installer.
2. Keep the reference directory next to `SKILL.md`.
3. Invoke `$cicadel-components`.

The skill needs no browser tools or runtime plugin. Other coding agents can read the
same Markdown directly. If an agent loaded its skill catalog before you installed
the skill, refresh or reopen the session.


---

Source: `docs/component-ui.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md

# Component UI

Components are how Cicadel renders HTML. You write markup in `.templ` files with typed
Go props and explicit slots, generate Go with the Cicadel CLI, and render from handlers.
They take the place of template files, and the compiler checks every call.

This page is the API contract. To build your first component, start with
[the component walkthrough](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md).

![A typed component call: props, children and named slots go into a Definition, which validates and calls its compiled templ body to produce escaped HTML. Apps export definitions in their namespace; the project app may override a body while the original contract stays authoritative.](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/docs/diagrams/component-composition.svg)

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md.
Build a reusable component for [purpose] with typed props and explicit slots.
Show the .go contract, .templ markup and handler call. Use escaped text,
rebuild the generated UI, and test valid and invalid props.
```

## Define a component

A component has three parts: a Go contract, a `.templ` body and a call site.
Keep `props.go` and `card.templ` together in one Go package, often in an app's
`templates/cards/` directory.

The contract declares props, slots, validation and the body:

```go
package cards

import "github.com/fauzaanu/cicadel/ui"

type Props struct {
    Title string
    Compact bool
}
type Slots struct {
    Children ui.Content
    Footer ui.Content
}
var Card = ui.Definition[Props, Slots]{
    Name: "cards:card",
    Source: "templates/cards/card.templ",
    Validate: func(p Props, s Slots) error {
        if err := ui.Required("Title", p.Title); err != nil { return err }
        if s.Children.Empty() { return ui.Required("Children slot", "") }
        return nil
    },
    Body: card,
}
```

The body is ordinary templ markup:

```templ
package cards

templ card(p Props, s Slots) {
    <section>
        <h2>{ p.Title }</h2>
        @s.Children
        if !s.Footer.Empty() {
            <footer>@s.Footer</footer>
        }
    </section>
}
```

A handler calls the definition and renders it:

```go
content := cards.Card.Call(
    cards.Props{Title: "Welcome"},
    cards.Slots{Children: ui.Text("Hello"), Footer: ui.Text("Thanks")},
)
err := (ui.Renderer{}).HTML(r.Context(), w, 200, content)
if err != nil && !ui.Committed(err) { response.Error(w, 500) }
// Log errors privately; do not send diagnostic details to public clients.
```

In markup, insert a component with `@Definition.Call(props, slots)` or `@someContent`.

Private bodies and reusable page composition can also live next to the handlers
that own them, as in the articles example.

### Names and imports

- Imports are ordinary Go module imports and aliases.
- There is no filesystem-based name lookup and no global registry.
- Exported contracts have `appname:component` names, such as `cards:card`.

## Slots and content

A slot is a `ui.Content` field. `ui.Content` is an opaque **HTML fragment**. It is
never a string or an attribute value.

| API | What it does |
| --- | --- |
| `ui.Text(s)` | Escapes a string into content. |
| `ui.Group(a, b, ...)` | Combines fragments into one. |
| `ui.Fragment(c)` | Adapts a trusted compiled component. |
| `ui.Content{}` | Empty content. |
| `c.Empty()` | Reports whether content was supplied. |
| `ui.NoSlots` | Declares a component with no slots. |

`Empty()` reports presence, not rendered length. `ui.Text("")` is a supplied empty
value, so it is not empty.

Name the default child content `Children`. Every other field is a named slot.

There is one model: explicit fields. templ's implicit `{ children... }` context
transport is rejected by the compiler.

## Props, defaults and validation

Go checks field names, types, function arguments, imports and slot compatibility.
Omitted struct fields get Go zero values.

| Hook | When it runs | Use it for |
| --- | --- | --- |
| `Defaults` | First, on a local copy of the props. | Filling in values. |
| `Validate` | Before the component's body and before the HTTP response is committed. | Required values and slot presence. |

- **Required is your rule.** Not every zero value is invalid. You define what is required.
- **Zero versus omitted.** Use pointer or option fields when "omitted" and an explicit
  zero or `false` must differ. Do not treat every zero value as missing.
- **Pure hooks.** Both hooks must be pure. They must not change data the caller references.
- **Overrides keep hooks.** An override body keeps the original `Defaults` and `Validate`.
- **Definitions are configuration.** Treat exported definition variables as immutable.
  Copy one before customizing it.

## Inputs and scope

Cicadel has no context processors and no implicit request map. Pass everything in.

- Dependencies and request data are explicit typed props, function parameters or
  factory arguments.
- A nested body sees only its Go lexical scope and its declared inputs.
- The request `context.Context` carries cancellation and private render bookkeeping.
  Pass business services as explicit typed inputs.
- Use ordinary Go `if`, `switch`, `for` and helpers for variants and collections.
- Every generated markup function receives render frames. This includes private
  bodies and recursive calls.

## Safety and rendering boundary

### Escaping

- templ escapes text expressions and string attributes, across nested components.
- Fragment slots are HTML-body values.
- `title` and `textarea` accept only text and text expressions, not component insertion.
- Mismatched closing tags and unsupported context composition are compile errors.

### URLs

Dynamic URL attributes use templ's contextual URL sanitization. Unsafe values become
`about:invalid#TemplFailedSanitizationURL`.

Use `ui.URL` when you want an error instead:

- **Allows** relative URLs and the `http`, `https`, `mailto` and `tel` schemes.
- **Rejects** control characters, backslashes, surrounding whitespace,
  protocol-relative URLs and every other scheme.

`ui.URL` is not an origin allowlist.

### Forwarding attributes

`ui.Merge` is the forwarding boundary. Pass it ordered `ui.Attributes` groups.

- Names must be lowercase.
- Later values win. Classes are the exception: they merge unique tokens in
  first-seen order.
- Known boolean attributes need `bool` values. `false` omits them.
- Text, `aria-*` and `data-*` values need strings. Use `"false"` for ARIA false.
- URL-like attributes must also pass `ui.URL`.
- Output attribute order is deterministic.
- Merge before spreading. Do not repeat merged keys as literal attributes.

Forwarding is allowlisted. `ui.Merge` rejects:

- event handlers and inline `style`
- `srcdoc` and `srcset`
- namespaced attributes
- arbitrary custom behavior attributes, such as `hx-get`
- unknown standard attributes

Explicit attributes you write in trusted markup are a separate authoring decision.
Contextual URL escaping still applies to them. An application can extend a typed
component's declared API instead of forwarding everything blindly.

### What the source contract rejects

The initial source contract rejects:

- inline script and CSS templates
- `script` and `style` elements
- event-handler attributes and dynamic attribute names
- active foreign or embedded content: `svg`, `math`, `iframe`, `object`, `embed`
  and obsolete raw-text elements

Link static stylesheets explicitly. Client enhancement adapters and active content
are future capabilities. Composition does not imply them.

### Trusted code

> [!WARNING]
> Cicadel has no conversion from strings to trusted HTML, URLs or JavaScript.
> Do not call upstream `templ.Raw` or `SafeURL`, and do not write untrusted strings directly.

`ui.Fragment` is a narrow adapter for **trusted Go implementations**. They must
preserve HTML safety.

Components and packages run trusted Go code. They are not a sandbox and can bypass
any framework contract on purpose. Review them like any other dependency.

## Render a response

`ui.Renderer` renders into a buffer first, then writes.

| Method | Behavior |
| --- | --- |
| `Renderer.Render` | Returns bytes only after a successful render. |
| `Renderer.HTML` | Renders, then sets the content type and status, then writes. |

- A render error leaves the HTTP writer untouched.
- A write failure after commitment is a `*ui.CommitError`. Check it with
  `ui.Committed(err)`. Log it and never try a second response.
- Pass a response writer that has not been committed yet.
- `Renderer` has no streaming or flush API.
- Direct low-level component `Render` calls do not give HTTP atomicity.
- Go panics stay panics. The host's recovery middleware handles them. They do not
  become validation failures.

### Limits

| Limit | Default | Override |
| --- | --- | --- |
| Render depth | 64 frames | `Renderer{MaxDepth: ...}` |
| Output size | 4 MiB | `Renderer{MaxBytes: ...}` |

- Frames include contract calls and markup bodies.
- Cancellation is checked at component boundaries and on buffered writes.
- Go helpers must cooperate with the context. The engine cannot stop an infinite Go computation.
- The output bound excludes caller-owned props and intermediate Go expressions.

### Concurrency and buffers

- No shared compile or render cache holds request values, children, context or output.
- Generated literal writes ignore upstream development-mode environment variables
  and never read source files.
- Generated code and literals are immutable.
- Cicadel uses request-owned buffers. It bypasses templ's global buffer pool on
  purpose, because that pool retains an underlying writer.
- Definitions and registries can be shared. Do not mutate props, slices, maps or
  closures while a render uses them.

## Installable libraries and overrides

Apps register components explicitly. Importing a package or embedding source
activates nothing on its own.

```go
cicadel.App{
    Name: "cards",
    Components: []ui.Export{Card.Export(1)},
}
```

### Exports and namespaces

- `App.Components []ui.Export` registers each `Definition.Export(version)`.
- The app owns its namespace. Duplicate names, invalid exports and nil bodies fail construction.
- Component contract versions are positive integers. They are independent of module versions.
- `Manifest` and `Requires` check app APIs and dependency versions. Go modules select the actual code.

### Assets

- `App.ComponentAssets` lists required files in `App.Static`. Construction checks
  that they exist and are files.
- Static files are served under `/static/<app>/` with content-hashed URLs. See
  [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md).
- Compiled Go embeds the markup. `go:embed` packages static resources and can
  package sources for inspection.
- At runtime nothing reads `.templ` files or the working directory.

### Project overrides

Only the **local `project` app** can set `ComponentOverrides`. Build each one with
`Definition.Override(version)`. No package or manifest app can override another
package implicitly.

| Rule | Why |
| --- | --- |
| One override wins over the original. Duplicate overrides fail. | No ambiguity about which body renders. |
| It keeps the exact named Go props and slots types and the contract version. | Callers stay type-compatible. |
| It supplies only the body and source. The original defaults and validation stay authoritative. | A replacement cannot silently weaken required props or slots. |

Semantic HTML behavior still needs application tests.

### Resolve and inject

1. Build a registry with `cicadel.ComponentRegistry(apps)`.
2. Resolve a definition with `ui.Resolve(registry, cards.Card)`.
3. Pass the resolved value into your page or route factories.

`cicadel.New` also validates the registry and exposes it as `Application.Components`.

Calling an imported definition directly uses that definition. No hidden lookup
changes its meaning. Explicit injection keeps project overrides reviewable and
keeps separate hosts independent.

### Example library

The [independent cards module](https://github.com/fauzaanu/cicadel/tree/2678611d308376ca8045c8741ee9d4d7814a3fec/examples/component-library) includes:

- a compiled body with a required child slot and an optional footer
- forwarded attributes
- embedded source and CSS
- an app manifest and HTTP tests

It has no mandatory design-system dependency.

The [generated consumer test](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/components_test.go) verifies
real installation. It publishes a unique test version through a local Go proxy,
runs `go get`, installs it into a fresh starter and overrides it explicitly. It
checks escaping and concurrency, then runs compiled HTTP tests and a production
executable outside the source tree.

> [!NOTE]
> This verifies module installation. It does not claim the example is publicly
> published. The local module's framework `replace` is for development only.

## Exact authoring and verification loop

Generated projects pin the CLI through a Go `tool` directive. After `go mod tidy`:

```sh
go doc example.com/your-library.Props
# Edit the props/slots types and .templ body.
go tool cicadel ui css install  # once, when using Tailwind
go tool cicadel ui build
go tool cicadel ui check --json
go test -run '^TestMyPage$' ./apps/myapp
go test -race ./...
go run manage.go check
go build -trimpath -o bin/server .
```

- In the framework checkout, use `go run ./cmd/cicadel ui build` and `go run ./cmd/cicadel ui check`.
- In an existing project, add the matching CLI with
  `go get -tool github.com/fauzaanu/cicadel/cmd/cicadel@VERSION`.
- The tool's compiler and runtime must come from the same framework dependency graph.

### What each command does

| Command | Does | Does not |
| --- | --- | --- |
| `ui generate` | Parses all module sources before writing. Writes deterministic `*_templ.go` files atomically per file, with a source hash and compiler version. | Build CSS. It is markup only. |
| `ui build` | Generates markup and builds configured Tailwind CSS. | — |
| `ui check` | Detects missing, stale and orphan outputs. Checks configured CSS freshness. Compiles all Go packages and tests (`go test -c -o /dev/null ./...`, using the platform null device). | Change generated files, run tests, start a web server or evaluate app factories. |
| `manage.go check` | Constructs and validates the installed registry and resources. | Replace host-specific database setup, which follows the host's construction rules. |

- Commit the generated `*_templ.go` files.
- Production `cicadel.New` validates registered libraries, assets and overrides before serving.
- Run both source checks and host validation in CI.

> [!WARNING]
> A plain `go build` cannot detect that an ignored `.templ` source changed. The
> stale check is a required build step.

### Development and restarts

- `go tool cicadel dev` compiles and restarts the executable automatically. See
  [the foundation workflow](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md).
- In-process hot replacement is not supported.
- Manual build, check and restart of `go run manage.go runserver` still work.
- A syntax failure during generation leaves existing outputs intact.
- A failed development build keeps the working server running.
- Concurrent generators in one checkout are unsupported.
- Nested Go modules need their own invocation.
- `.git` and hidden directories, `vendor` and `testdata` are not compiled as application sources.
- Remove orphan generated files explicitly. They are never adopted silently.

### Diagnostics

Commands exit 0 on success and 1 on failure, including invalid arguments.

`--json` prints a JSON array of diagnostics to stdout. It is empty on success. The
CLI also prints a human-readable error to stderr.

| Field | Meaning |
| --- | --- |
| `code` | Stable diagnostic ID. |
| `message` | What went wrong. |
| `file`, `line`, `column` | Source position. One-based. |
| `stack` | Component stack. |

Stable IDs, by when they happen:

| Stage | Code | Meaning |
| --- | --- | --- |
| Compile | `UI_PARSE` | The `.templ` file could not be parsed. |
| Compile | `UI_SYNTAX` | A syntax error at a reported line and column. |
| Compile | `UI_GENERATE` | Go generation from the template failed. |
| Compile | `UI_TYPE` | The generated Go does not type-check. |
| Compile | `UI_BUILD` | The package containing components does not build. |
| Check | `UI_STALE` | Generated output is missing or out of date. Run `cicadel ui generate`. |
| Check | `UI_ORPHAN` | A generated file has no `.templ` source. Remove it. |
| Registry | `UI_NAMESPACE` | An exported component name is invalid in its namespace. |
| Registry | `UI_COLLISION` | Two components or overrides share a name. |
| Registry | `UI_UNKNOWN` | An override targets a component that does not exist. |
| Registry | `UI_CONTRACT` | An override or resolve does not match the original contract. |
| Render | `UI_ATTRIBUTE` | An attribute name is invalid or not lowercase. |
| Render | `UI_URL` | A URL is unsafe or contains control characters. |
| Render | `UI_LIMIT` | Output exceeded the render byte limit. |
| Render | `UI_RENDER` | A component failed while rendering. |
| Render | `UI_WRITE` | Writing the response failed after output started. |

Tailwind has its own `UI_CSS_*` codes; see [the Tailwind guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md).

- Runtime diagnostics implement `error` and `Unwrap`, and can be JSON-encoded.
- Nested errors keep their deepest component stack.
- Source parse and render expression locations are precise.
- Go type errors map to the owning `.templ` declaration. They also keep the exact
  generated Go position and message.
- Plain Go errors keep their Go source position.

> [!WARNING]
> Error messages can contain input values. Keep them in development tooling and private logs.

## Forms and layouts

| Component | Provides |
| --- | --- |
| `ui/layout.Page` | A minimal document shell with explicit header, children, footer and scripts slots, plus an optional explicit stylesheet URL. `Lang` and `Dir` set `<html lang dir>` (for example `Lang: "dv", Dir: "rtl"` for Thaana pages; defaults `en` and `ltr`, validated). `CSRFToken` makes htmx requests send `X-CSRF-Token`. |
| `ui/form.Field` | Associated labels, bound values, `required` and `maxlength`, password/text/textarea variants, and error-only `aria-invalid` and `aria-describedby`. |
| `ui/form.CSRF` | A hidden CSRF field. It requires an explicit token from the session middleware. |

Components do not create tokens, validate requests or bypass CSRF. Binding and
validation stay in `forms` and your application.

The starter, the articles list/detail/login/edit pages and the catalog/admin pages
use these compiled components. Their authorization, ownership filtering, CSRF and
persistence paths are unchanged. Real PostgreSQL HTTP regression tests verify them.

FORM-01 is still Partial. Richer typed binding, validators, widgets and ModelForms
are separate work. The broader administration battery is not completed here either.

Application UI uses compiled `.templ` components. Template strings, global
definitions and `template.HTML` are not component content. Follow the
[component authoring guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md).

## htmx and REST

Use the bundled [htmx 4 integration](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md) for component HTML requests. Keep
REST/JSON handlers for API clients.

To load the embedded runtime, pass `htmx.Script()` to the standard page layout's
`Scripts` slot and mount `htmx.Handler()`. No CDN, npm or deployment-time asset
collection is required.

## Acceptance checklist

These checks cover the initial server component contract on this page, not upstream
templ features Cicadel excludes. Commands and evidence are recorded in
[component verification](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/component-verification.md).

- [x] Syntax, layout, Go compiler and runtime API, props, explicit slots and scope.
- [x] Deterministic generated artifacts and source diagnostics. Unknown components,
  invalid nesting or context, and incompatible props or slots are rejected.
- [x] Typed props, required validation, defaults, explicit dependencies, children,
  named slots, nesting, conditionals, collections and reusable layouts.
- [x] Safe forwarding and merging, and contextual escaping, including malicious inputs.
- [x] Accessible reusable form components and explicit CSRF integration.
- [x] Package namespaces, collision checks, exact compatible overrides, required
  embedded assets, app dependency versions and component contract versions.
- [x] Development regeneration and restart, nested render stacks, stale checks and
  production registry validation without JavaScript tooling.
- [x] Buffered HTTP failures, committed write errors, concurrency, cancellation,
  recursion bounds, output limits and request-owned buffers.
- [x] Starter, articles and catalog/admin pages built from reusable components.
- [x] An independent library installed into a generated app with typed props,
  children, named slots, an explicit override, security and isolation tests, and
  production checks.


---

Source: `docs/email.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md

# Email

Send email with `mail.Sender` and an explicit `mail.Transport`, such as SMTP.
Delivery is synchronous and context-aware, and creating a sender makes no network
calls.

```go
sender := mail.Sender{Transport: mail.SMTP{
    Address: "smtp.example.com:587",
    Username: smtpUsername,
    Password: smtpPassword,
}}
err := sender.Send(ctx, mail.Message{
    From: "App <app@example.com>",
    To: []string{"recipient@example.com"},
    Subject: "Account invitation",
    Text: "Your account is ready.",
    HTML: "<p>Your account is ready.</p>",
})
```

- `mail.Message` holds the envelope and the text and HTML content.
- `mail.Sender` validates each message before handing it to the transport.
- Credentials and recipients come from application configuration or trusted data.

The accounts starter wires recovery email in `project/accounts.go`. The
[authentication guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md) lists its environment settings.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md.
Add email delivery for [event] using Cicadel mail.Sender.
Read SMTP credentials from secret configuration, send after successful persistence,
and test recipients and message content with an in-memory transport.
```

## Build a message

Messages support `To`, `Cc`, `Bcc`, `ReplyTo`, plain text, HTML alternatives,
attachments and extension headers:

```go
message.Attachments = []mail.Attachment{{
    Filename: "report.csv",
    ContentType: "text/csv",
    Data: csvBytes,
}}
message.Headers = map[string]string{"X-Application": "reports"}
```

### Attachments

- Attachment names cannot include path separators.
- You supply the bytes. The API does not read arbitrary filesystem paths.
- You own attachment size limits.

### Headers

- Extra headers accept `X-*` headers, `Message-ID`, `In-Reply-To` and `References`.
- They cannot override envelope, MIME or Bcc fields.
- Duplicate header names, compared case-insensitively, are rejected.
- CR, LF and NUL header injection is rejected.

> [!NOTE]
> Bcc addresses are used only for the SMTP envelope. They never appear in the
> serialized MIME.

Do not change a message while it is being sent.

## Render the body

Use `mail.RenderComponent(ctx, message, content)` to render a compiled typed
component into the HTML body. Set `message.Text` yourself for the text
alternative.

`mail.Render` remains a compatibility helper. It uses separate Go text and
escaped HTML templates.

- Neither helper turns arbitrary user HTML into trusted markup.
- Email clients support less CSS than browsers. Tailor email components to the
  clients you target.

## MIME output

`Message.Bytes()` validates and serializes the message. The output has:

- Date and Message-ID headers, and UTF-8 headers;
- quoted-printable bodies;
- multipart alternatives and base64 attachments;
- CRLF line endings and standard line wrapping.

The sender and recipient mailboxes are parsed and validated.

## SMTP

`SMTP.Encryption` controls the connection:

| Mode | Behavior |
| :--- | :--- |
| `starttls` (default) | Requires STARTTLS and certificate verification. |
| `tls` | Implicit TLS, commonly on port 465. |
| `plain` | Only to an actual loopback address, and refuses credentials. For local mail capture tools. |

- A cloned `TLSConfig` can supply a private certificate pool.
- Disabling verification is rejected. The minimum TLS version is 1.2.
- Credentials are sent only after TLS.

## Send in batches

`Sender.SendMany` validates the whole input before delivering anything. It reuses
one SMTP connection when the server supports it, and returns the number of
messages accepted before an error.

- The default timeout is 30 seconds for the whole batch.
- Context cancellation closes the connection, even while waiting for an SMTP
  response.
- A failed QUIT after every DATA command was accepted does not mark those
  messages as failed.
- A connection failure during DATA acknowledgement can leave delivery uncertain.

> [!WARNING]
> The framework never silently retries or swallows delivery errors. You own the
> retry and idempotency policy.

## Development backends

| Backend | Behavior |
| --- | --- |
| `mail.Capture` | Thread-safe in-memory outbox with deep copies on write and read |
| `&mail.Console{Writer: writer}` | Serialized MIME to an explicit writer, with synchronized writes |
| `mail.File{Directory: path}` | One mode-0600 `.eml` file per message in a private directory |
| `mail.Discard{}` | Explicitly validate without delivery |
| Custom `mail.Transport` | Implement `Send(context.Context, mail.Message) error` |

Console and file messages include private bodies and reset links. Select them
explicitly for development. The accounts starter uses SMTP. Writers,
filesystems, credentials and provider accounts stay application-owned.

## Testing

Tests send no real email. The SMTP tests use isolated loopback servers with
locally created certificates, and account tests inject a capture callback.

`mail/delivery_test.go` covers MIME parsing, attachment decoding, Bcc privacy,
header rejection, outbox isolation, file permissions, STARTTLS and implicit TLS,
connection reuse, partial delivery, failed upgrades and cancellation. Run the
package under the race detector alongside the framework CI suite.


---

Source: `docs/error-pages.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md

# Show error pages

Browsers get a styled HTML page for 404s, 500s and other errors, and a handler
panic becomes a 500 page instead of a dropped connection. Handlers keep
reporting errors with `http.Error` or `response.Error`.

## Generated projects

`startproject` wires this already. `project/errors.go` installs the middleware
and `project/errors.templ` holds the page:

```go
func GlobalMiddleware(logs *slog.Logger) []cicadel.Middleware {
    return []cicadel.Middleware{
        observability.Middleware(logs, nil),
        errorpages.Middleware(errorpages.Options{Page: ErrorPage, Logger: logs}),
    }
}

func ErrorPage(r *http.Request, e errorpages.Error) ui.Content {
    stylesheet, err := static.URL(r.Context(), "project", "app.css")
    if err != nil {
        stylesheet = ""
    }
    return ui.Fragment(errorPage(stylesheet, e))
}
```

Edit `project/errors.templ` to change the design. Run `go tool cicadel ui build`
afterwards, as for any component.

## Add it to an existing project

Pass the middleware to `cicadel.New`, after `observability.Middleware` so pages
and logs carry the request ID:

```go
app, err := cicadel.New(s, apps,
    observability.Middleware(logs, nil),
    errorpages.Middleware(errorpages.Options{Page: ErrorPage, Logger: logs}),
)
```

Without `Page`, the middleware uses `errorpages.Default`: the minimal
`ui/layout` document with the status, a title, a description and a link home.

## What gets a page

The middleware replaces a response when all of these hold:

- the status is 400 or higher;
- its `Content-Type` is `text/plain`, which is what `http.Error` writes;
- the client explicitly accepts `text/html`, as browser navigations and htmx
  requests do.

That covers the router's own 404 and 405 responses, `http.Error` in your
handlers, CSRF failures and `MaxBytesError` handling. Other headers, such as
`Allow` on a 405, are kept.

These pass through unchanged:

- responses you render yourself, in HTML, JSON or any other type;
- API clients: no `Accept` header, `*/*` (curl, `fetch()`) or other types such
  as `application/json`;
- successful and redirect responses.

> [!NOTE]
> Pages show fixed copy for the status. The text a handler passed to
> `http.Error` is never displayed, so a database error message cannot leak
> into a page.

## The page data

`Page` receives an `errorpages.Error`:

| Field | Meaning |
| --- | --- |
| `Status` | The HTTP status. `Code()` returns it as text for templates. |
| `Title`, `Description` | Fixed copy, such as "Page not found". |
| `Reason` | `errorpages.ReasonCSRF` for a failed CSRF check, otherwise empty. |
| `RequestID` | The `observability` request ID, when that middleware runs outside. |

`errorpages.New(status, reason)` builds the same value, for tests or for pages
you render yourself. A CSRF failure has the title "Form expired" and tells the
user to reload the page.

## Panics

A panic in a handler or inner middleware:

1. is logged with its stack and the request ID;
2. is passed to `Options.Report`, if set, for an error tracker;
3. becomes a 500 page, with any headers the handler set for its own
   representation (`Content-Type`, `Content-Disposition`) removed.

If the handler had already sent part of its response, the page cannot replace
it. The middleware then aborts the connection with `http.ErrAbortHandler`, so
the client never mistakes a truncated response for a complete one.

```go
errorpages.Options{
    Page:   ErrorPage,
    Logger: logs,
    Report: func(r *http.Request, recovered any, stack []byte) {
        sentry.CurrentHub().Recover(recovered) // any tracker
    },
}
```

## htmx requests

An htmx partial request never receives a full page, because htmx would swap it
into the target element. Instead the response keeps its status and carries:

- `HX-Reswap: none`, so the page stays as it is;
- `HX-Trigger: {"cicadel:error":{"status":403,"title":"Access denied"}}`.

Listen for the event in a static script to show a message. Inline handlers such
as `hx-on` need `unsafe-eval`, which the default content security policy blocks.

```js
document.addEventListener("cicadel:error", (event) => {
  showToast(event.detail.title); // your own notification code
});
```

Full-page htmx navigations, such as boosted links and history restores, get the
page.

## Test it

```go
app := apptest.New(t, s, apps, GlobalMiddleware(slog.New(slog.DiscardHandler))...)
apptest.NewClient(app).
    Request(t, "GET", "/missing", nil, http.Header{"Accept": {"text/html"}}).
    Status(t, 404).
    Contains(t, "Page not found")
```

## Limits

- Requests rejected before your middleware runs keep plain text: a host not in
  `AllowedHosts` (400) and the framework's last-resort panic recovery.
- A page-specific `Content-Security-Policy` set by the failing handler still
  applies to the error page.
- A panic recovered here is not seen by `observability.Middleware`, so its
  `Event.Panicked` is false. The request is still logged with status 500, and the
  panic is logged here with its stack.


---

Source: `docs/events.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md

# Events

Events let one app announce what happened and other installed apps react.
Payloads are typed, registration is explicit, and the application checks every
subscription before it starts. If you know Django, they fill the role of signals.

## How events differ from signals

- **Explicit.** An app lists the events it emits in `App.Events` and its handlers
  in `App.Subscriptions`.
- **Checked at startup.** `cicadel.New` validates both before the application starts.
- **No magic.** Nothing connects at import time, and there is no global registry.

The standard project subscribes in `project/events.go`. The accounts app emits
`user_created`, `logged_in`, `login_failed`, `logged_out` and `password_changed`.
A package made with `startpackage` declares and emits `greeted` as a template.

## Declare and emit an event

1. Declare each event once, as a package-level variable of the app that owns it.
   Use that app's label and a lowercase name.
2. Choose the payload type. Handlers receive it.
3. List the declaration in the app's `Events`.
4. Call `Emit` with the request, command or hook context.

<!-- example: installable/apps/orders/app.go -->
```go
package orders

import (
    "context"
    "errors"
    "net/http"

    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/database"
    "github.com/fauzaanu/cicadel/events"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/urls"
    "gorm.io/gorm"
)

// Placed is emitted inside the transaction that stores a new order.
var Placed = events.New[Placement]("orders", "placed")

// Placement is the Placed payload. Handlers write through Tx so their work
// commits or rolls back with the order.
type Placement struct {
    OrderID int64
    Tx      *gorm.DB
}

// App stores orders in an orders table created by its recorded migration.
// confirm runs after commit, so a rolled-back order is never confirmed.
func App(db *gorm.DB, confirm func(context.Context, int64) error) cicadel.App {
    return cicadel.App{
        Name:   "orders",
        Events: []events.Declaration{Placed},
        Subscriptions: []events.Subscription{
            Placed.Handle(func(ctx context.Context, e Placement) error {
                id := e.OrderID
                return database.OnCommit(e.Tx, func(ctx context.Context) error { return confirm(ctx, id) })
            }),
        },
        Routes: []urls.Route{urls.Path("POST", "/orders", "orders:place", func(w http.ResponseWriter, r *http.Request) {
            err := database.Atomic(r.Context(), db, func(tx *gorm.DB) error {
                var id int64
                if err := tx.Raw("INSERT INTO orders DEFAULT VALUES RETURNING id").Scan(&id).Error; err != nil {
                    return err
                }
                return Placed.Emit(r.Context(), Placement{OrderID: id, Tx: tx})
            })
            var refused *events.HandlerError
            switch {
            case errors.As(err, &refused):
                response.Error(w, http.StatusConflict) // a handler rejected the order; nothing was stored
            case err != nil:
                response.Error(w, http.StatusInternalServerError)
            default:
                w.WriteHeader(http.StatusCreated)
            }
        })},
    }
}
```

`events.New` panics on an invalid label, like `regexp.MustCompile`, because it
runs when the package is initialized.

## Subscribe

`Event.Handle(fn)` returns a subscription. List it in any installed app's
`Subscriptions`, including the declaring app's own. The project subscribes in
`project/events.go`:

```go
func Subscriptions() []events.Subscription {
    return []events.Subscription{
        orders.Placed.Handle(func(ctx context.Context, e orders.Placement) error {
            return e.Tx.Exec("INSERT INTO order_audit(order_id) VALUES (?)", e.OrderID).Error
        }),
    }
}
```

`go run manage.go apps` lists each app's emitted (`emits`) and handled
(`handles`) events.

## What the application checks

`cicadel.New` fails, naming the app, when:

- an app declares an event whose owner label is a different app;
- the same declaration is listed twice, or two declarations share a name;
- a subscription refers to an event that no installed app declares, for example
  after its owning app was removed (the error asks whether that app is installed);
- a subscription has a nil handler or was not created with `Handle`.

Subscriptions refer to the declared Go value, not its name. A handler always
receives the payload type the emitter sends.

## Delivery

| Rule | Behavior |
| :--- | :--- |
| Synchronous and ordered | `Emit` runs handlers on the calling goroutine. Apps run in dependency order (the order `manage.go apps` prints), then handlers in the order each app lists them. |
| No queue | There is no queue and no retry. Enqueue a job from a handler for slow or retried work. |
| Errors stop delivery | The first handler error stops the remaining handlers. `Emit` returns a `*events.HandlerError` naming the event and the subscribing app. `errors.Is` and `errors.As` reach the handler's own error. The emitter decides what the error means. |
| Panics | Handler panics propagate, as they would from an HTTP handler. |
| Cancellation | `Emit` checks the context before each handler and returns `ctx.Err()` once it is done. Handlers should honour the context too. |
| Nesting | A handler may emit other events. Nesting deeper than `events.MaxDepth` (16) levels fails with `events.ErrDepth` instead of recursing forever. |
| Concurrency | `cicadel.New` builds the dispatcher once and it never changes, so concurrent requests can emit freely. Handlers that share state must synchronize it. |

## Transactions

Emit inside the transaction that made the change, with `database.Atomic`. Pass the
transaction in the payload as `Tx` when handlers may need to write.

- A handler that writes through `Tx` commits or rolls back with the change.
- A handler error rolls the change back.
- Use `database.OnCommit(e.Tx, fn)` for email, cache invalidation and other
  effects that must happen only after commit. See [transactions](https://cicadel.fauzaanu.com/en/0.2.7/howto/transactions/index.md).
- Handlers must not keep `Tx` after they return.

Emit events that do not describe a database change, such as a rejected request,
outside any transaction.

## Where events are delivered

`Emit` finds the application's dispatcher in the context. Cicadel attaches it for:

- every request served by the application;
- app `Start` and cleanup hooks;
- app commands, and every command run by `manage.go`, including project commands.

For other work the application owns, such as a River worker or a goroutine
started in `Start`, attach it with `Application.Context`. This also attaches the
signing keys and static-file manifest:

```go
ctx = app.Context(ctx)
```

> [!WARNING]
> With no dispatcher in the context, `Emit` has no subscribers and returns nil.
> This keeps services usable on their own, but events emitted from a bare
> `context.Background()` are not delivered.

## Test a package's events

In package tests, build a dispatcher directly:

```go
d, err := events.NewDispatcher(
    events.App{Name: "greet", Events: []events.Declaration{greet.Greeted}},
    events.App{Name: "listener", Subscriptions: []events.Subscription{greet.Greeted.Handle(record)}},
)
ctx := events.WithDispatcher(t.Context(), d)
```

Or install a listener app beside the package with `apptest.New`.

## Accounts events

| Event | Payload | Emitted |
| :--- | :--- | :--- |
| `accounts.UserCreated` | `UserCreation{User, Tx}` | by `Service.Create` (and `createuser`) after inserting the user |
| `accounts.LoggedIn` | `Login{User, Tx}` | by `Service.Login`, browser and JSON sign-in, after inserting the session |
| `accounts.LoginFailed` | `LoginFailure{Username}` | when sign-in is rejected with `ErrCredentials`; never for database or backend errors, and never with the password |
| `accounts.LoggedOut` | `Logout{UserID, Tx}` | by `Service.Logout`, browser and JSON sign-out, and when a browser signs in again over an older session |
| `accounts.PasswordChanged` | `PasswordChange{UserID, Reset, Tx}` | by `ChangePassword` and `ResetPassword` after replacing the hash and ending sessions |

Payloads with `Tx` are emitted inside the account transaction. A refused
`UserCreated` leaves no user, and a refused `LoggedIn` leaves no session. For
example, create a profile with every user from `project/events.go`:

```go
accounts.UserCreated.Handle(func(ctx context.Context, e accounts.UserCreation) error {
    return e.Tx.Exec("INSERT INTO profiles(user_id) VALUES (?)", e.User.ID).Error
})
```

`LoginFailure.Username` is the submitted, untrusted value. Escape it when you
display it and bound it when you store it. A `LoginFailed` handler error is
joined to `ErrCredentials`, so callers still see a rejected sign-in.

## Not covered

- **Model save and delete events** are not emitted automatically. Use GORM hooks
  or emit from the code that saves.
- **Request start and finish** are middleware concerns.
- **Cross-process delivery.** Events are in-process. They do not cross processes
  or survive a restart. Use the River integration in `jobs` for durable work.


---

Source: `docs/extensions.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/extensions/index.md

# Framework integrations

Each integration has a small, deliberate contract. Pass dependencies explicitly in
app constructors. Imports never register models, routes, jobs or templates.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/extensions/index.md.
Integrate [admin, storage or background-job feature] into this application.
Read the relevant integration API before writing code. Pass explicit dependencies,
keep authorization in the application, and test the real success and failure paths.
```

## Admin

`admin.Routes[T]` creates list, create, edit and delete HTML routes for a GORM
model with one integer primary key. You supply:

- an explicit field allowlist;
- a request-specific query scope;
- an authorization callback;
- a CSRF-token provider.

Permissions are required. They are checked both before and after applying
submitted fields. Unlisted fields cannot be assigned. Wrap the routes in session
and CSRF middleware.

> [!WARNING]
> Do not expose credential fields. The list is capped at 100 records in this
> initial version; it is not a general reporting interface.

### Run the catalog example

The catalog example shows related products and categories, with different editor
and manager permissions. It accepts Basic authentication over HTTPS using a bcrypt
hash from the environment. It is an integration example, not an
account-management product.

```sh
export CICADEL_CATALOG_PASSWORD_HASH="$(CICADEL_USER_PASSWORD='your local test passphrase' go run ./examples/catalog hashpassword)"
export DATABASE_URL='postgres://USER:PASSWORD@localhost/cicadel_catalog?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run ./examples/catalog migrate
go run ./examples/catalog runserver
```

- Sign in as `editor` or `manager` with the supplied password. Both can edit; only
  the manager can delete.
- The two roles share a demonstration password. Real projects should use their
  user directory and independently managed credentials.
- Send credentials from your HTTP client. Denied access returns 403, not a browser
  authentication prompt.
- `/admin/categories/` and `/admin/products/` host the admin. `/` is a paginated
  public product API.

## JSON APIs

| Helper | What it does |
| :--- | :--- |
| `api.Decode` | Requires JSON, rejects unknown fields and trailing values, and relies on the application's request-body limit. Validate required fields after decoding. |
| `api.Pagination` | Bounds limit and offset. |
| `api.Fail` | Returns consistent code, message and field errors. |

Use explicit output structs so model fields are never disclosed by accident.
Schema generation is not included. An optional schema layer can be added without
changing handlers.

## Mail

`mail.Sender` validates envelope and header inputs before calling a `Transport`.

- `mail.Render` uses separate text and escaped HTML engines.
- `mail.Capture` is concurrency-safe development storage.
- Built-in SMTP supports verified STARTTLS and implicit TLS, connection reuse for
  batches, MIME alternatives, attachments, and CC and BCC.
- Console, file, capture and discard backends support development and tests.

Configure the provider and verified destinations explicitly. See [email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md).

## File storage

`storage.Local` stores flat, application-generated keys in a rooted directory.
Writes are bounded. An object is replaced atomically only after the whole upload
succeeds.

`storage.HTTP` supports object storage through a signed-URL function you provide.

- It requires HTTPS, refuses redirects and bounds uploads.
- The trusted signer owns credentials, buckets and signature policy.
- It is a generic signed-URL adapter, not a bundled S3 credential or signing
  implementation.
- Test your provider's signing and required headers before deployment, and
  configure a client timeout.

Serve stored media with the right content types and authorization. Validate
filenames and content at the upload boundary.

## Cache

`cache.Memory` has a fixed entry capacity, a per-value byte limit, a key-length
limit, a TTL, copied values and explicit deletion. It is process-local. When full,
it evicts the oldest inserted entry.

- Use it only for results you can recompute.
- Invalidate keys after committed writes.
- Version key formats when output changes.
- Never treat cache presence as authorization.

Shared, multi-instance invalidation needs a different, application-provided cache
implementation.

## Jobs

Cicadel uses [River's PostgreSQL queue](https://riverqueue.com/docs) and exposes
River's own client and worker types.

| Function | Role |
| :--- | :--- |
| `jobs.Migrate` | Runs River's schema upgrades as an explicit deployment step. |
| `jobs.NewProducer` | Uses the application's SQL pool. |
| `jobs.InsertTx` | Requires an active GORM transaction and enqueues atomically with its writes. Call it inside `db.Transaction`, passing `tx`, not the outer `db`. |
| `jobs.NewWorker` | Uses a separate pgx pool, with explicit worker registrations and concurrency. |

Run a worker in three steps:

1. Start the worker once.
2. Call `Stop` with a shutdown deadline.
3. Close its pool.

River owns persistence, retry scheduling, job timeout configuration and queue
coordination. Set per-job attempt and timeout policies with River's options.

> [!WARNING]
> Workers must be idempotent. External side effects can happen again if
> completion acknowledgement fails. Transactional enqueueing does not make
> network calls atomic.

Prepared-statement transaction wrappers are not supported by the initial GORM
enqueue helper. The integration test proves that rolled-back jobs disappear and
committed jobs run. It does not claim exactly-once external delivery.

## Localization

Cicadel has no native internationalization or localization engine. The
experimental `locale` package was removed before release.

- Use third-party Go libraries through explicit middleware and template helpers.
- There is no bundled catalog, translation command, locale negotiation or
  humanization API.
- Browser translation does not remove server-side localization requirements.
- Accessible labels, validation errors and time-zone-correct timestamps remain
  application and framework concerns.

## Observability

`observability.Middleware` generates request IDs. It logs method, status, bytes
and duration, without bodies or query strings. It exposes a synchronous callback
for metrics or tracing adapters.

- Keep callbacks fast, concurrency-safe and non-panicking.
- Full distributed trace propagation is an application integration.
- Health handlers support optional, bounded readiness checks.

## Extension contracts

Public extension points are ordinary Go interfaces and functions:

- HTTP handlers and middleware;
- explicit app constructors and dependencies;
- `template.FuncMap` and filesystem sources;
- native GORM, SCS stores and River workers;
- mail transports, storage stores and observer callbacks.

Extensions share the core's version compatibility policy. There is no dynamic
plugin loading and no stable binary ABI.

### Installable apps

The [installable-app foundation](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md) supplies manifests,
compatibility and dependency checks, namespaced commands, checks and resources,
PostgreSQL migrations, and startup and cleanup. Typed component contributions are
implemented.

Broader model and settings contracts and more module extraction remain open in
[the package acceptance checklist](https://cicadel.fauzaanu.com/en/0.2.7/sources/batteries.md#package-system-acceptance-checklist).
Accounts, formsets, migrations and query generation already have independent
modules. Other integrations remain in the main module.

### Component packages

UI packages export typed `ui.Definition` contracts through `App.Components`, with
explicit children and named slots. See [the component UI design](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md).

- `template.FuncMap` and legacy template filesystems are compatibility-only.
- The starter and both application examples use compiled components.
- A completed component package must not depend on Django template syntax or
  hidden request context.

## Accounts and logging

The [accounts starter](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md) uses compiled HTML and PostgreSQL cookie
sessions. The JSON bearer adapter remains available for API clients. Both use one
account service, shared revocation and explicit object authorization.
Administration remains a separate, limited integration.

[Logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md) provides:

- named configuration, propagation and filters;
- JSON and text handlers, and file rotation;
- optional captured or SMTP error alerts;
- credential redaction, request IDs and panic stacks;
- private GORM query timing.

Application configuration owns outputs and closes resources after requests drain.


---

Source: `docs/forms-completion.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md

# Forms and validation

Forms declare the fields you accept, bind a submission and validate it. Use one
for any browser form, like a Django `Form`.

Act on the data only after validation succeeds. Keep session and CSRF middleware
around the handler.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md.
Add a form for [fields and validation rules] to my application.
Show field errors beside the controls and preserve non-sensitive submitted values.
Use the existing sessions and CSRF middleware. Test valid input, invalid input,
missing CSRF tokens and unexpected fields before connecting any side effects.
```

## Define fields

Create the definition once, during application setup. Handle configuration errors
before you serve requests.

<!-- example: forms/apps/contact/form.go -->
```go
package contact

import "github.com/fauzaanu/cicadel/forms"

func Definition() (*forms.Definition, error) {
    return forms.New([]forms.Field{
        forms.Text(forms.Options{
            Name: "email", Label: "Email", Widget: "email", Required: true,
        }, forms.Email),
        forms.Boolean(forms.Options{
            Name: "accepted", Label: "I agree to the terms",
        }, forms.Accepted),
    })
}
```

Only declared fields are bound. For other common inputs, use `forms.Integer`,
`forms.Number`, `forms.Date`, `forms.Select` and `forms.Multiple`.

## Bind a submission

In your POST handler, after authentication and CSRF checks:

```go
r.Body = http.MaxBytesReader(w, r.Body, 8<<10)
posted, err := forms.Parse(r)
if err != nil {
    response.Error(w, http.StatusBadRequest)
    return
}
bound := definition.Bind(posted.Values)
if !bound.Valid() {
    // Render your form page with bound and status 422.
    renderForm(w, r, http.StatusUnprocessableEntity, bound)
    return
}
email, ok := forms.Value[string](bound, "email")
if !ok {
    response.Error(w, http.StatusInternalServerError)
    return
}
// Use email for the application's next step only after validation succeeds.
```

- `definition` is the result of `Definition()`.
- `renderForm` is your page-rendering helper.
- For a GET, render `definition.Initial()` instead.

> [!WARNING]
> Do not log submitted values or redisplay passwords.

## Render labels and errors

This component renders the bound fields. Pass a CSRF token from your existing
session middleware.

<!-- example: forms/apps/contact/form.templ -->
```templ
package contact

import "github.com/fauzaanu/cicadel/forms"
import "github.com/fauzaanu/cicadel/ui"
import "github.com/fauzaanu/cicadel/ui/form"

templ fields(bound *forms.Bound, csrfToken string) {
    <form method="post" action="/contact">
        @form.CSRF.Call(form.CSRFProps{Token: csrfToken}, ui.NoSlots{})
        for _, field := range bound.Fields() {
            @form.Field.Call(form.Bound(field, "contact-" + field.Name), ui.NoSlots{})
        }
        <button type="submit">Submit</button>
    </form>
}
```

The field component connects labels, help text and errors to the control. Show
form-wide errors separately with `bound.Errors()[""]`.

The [component guide](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md) shows a complete handler and
page-rendering flow.

## Save a model

Use [model forms](https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md) when accepted values create or update a GORM
model. Define an allowlist of editable fields. Scope every update to records the
current user may change.

## Stale edits

Reject an edit when someone else changed the record first:

1. Add a `Revision int64` column with a recorded migration.
2. Set `model.Config[T].VersionField` to `"Revision"`.
3. Render `form.Version(ctx, &record)` in a hidden `_version` field.
4. When a save returns `model.ErrConflict`, show a conflict message. Ask the user to
   reload before trying again.

## File fields and persistence

Use `forms/upload` for bounded multipart uploads.

- Close each parsed batch.
- Choose trusted storage keys.
- Connect storage writes to your persistence operation.

The [upload reference](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/reference/forms.md#file-fields-and-persistence) covers
limits, validation, cleanup and middleware order.

## Admin integration

- Use `admin.Config[T].Model` to supply model-form fields and validation.
- Use the first-party [formsets module](https://cicadel.fauzaanu.com/en/0.2.7/ref/formsets/index.md) for multiple
  rows and inline editing.

See the [forms reference](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/reference/forms.md) for field types, custom validators
and transaction behavior.


---

Source: `docs/htmx.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md

# Add interactive behavior

Use htmx to update part of a page with server-rendered HTML. This guide builds a
search form that works with htmx and with ordinary navigation.

Cicadel bundles htmx 4. Your Go application serves the script, so you need no CDN.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md.
Add a GET search form to my application using Cicadel's bundled htmx.
Register the script route, include the script once, and render a full page for
ordinary requests and a results fragment for partial requests.
Keep authorization in the handler and test both responses, including escaped input.
```

## 1. Register the script and search routes

Add `apps/search/app.go`:

<!-- example: htmx/apps/search/app.go -->
```go
package search

import (
    "log/slog"
    "net/http"
    "strings"

    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/htmx"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/ui"
    "github.com/fauzaanu/cicadel/urls"
)

func New() cicadel.App {
    return cicadel.App{
        Name: "search",
        Routes: []urls.Route{
            urls.Path("GET", htmx.ScriptPath, "search:script", htmx.Handler().ServeHTTP),
            urls.Path("GET", "/search", "search:index", Search),
        },
    }
}

func Search(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query().Get("q")
    items := []string{}
    for _, title := range []string{"Go notes", "PostgreSQL notes", "UI notes"} {
        if strings.Contains(strings.ToLower(title), strings.ToLower(query)) {
            items = append(items, title)
        }
    }
    err := htmx.HTML(w, r, http.StatusOK,
        ui.Fragment(page(query, items)),
        ui.Fragment(results(items)),
    )
    if err != nil {
        slog.ErrorContext(r.Context(), "render search", "error", err)
        if !ui.Committed(err) {
            response.Error(w, http.StatusInternalServerError)
        }
    }
}
```

- `htmx.Handler()` serves the bundled script at `htmx.ScriptPath`.
- `htmx.HTML` takes two renderings: the full `page` and the `results` fragment.
  It sends the fragment for htmx partial requests and the full page otherwise.

For database-backed search, replace the sample list with a query scoped to the
current user's permitted rows. Use the same permissions for full and partial requests.

## 2. Include the script and render results

Add `apps/search/page.templ`:

<!-- example: htmx/apps/search/page.templ -->
```templ
package search

import "github.com/fauzaanu/cicadel/htmx"
import "github.com/fauzaanu/cicadel/ui"
import "github.com/fauzaanu/cicadel/ui/layout"

templ page(query string, items []string) {
    @layout.Page.Call(layout.Props{Title: "Search"}, layout.Slots{
        Scripts: htmx.Script(),
        Children: ui.Fragment(searchForm(query, items)),
    })
}

templ searchForm(query string, items []string) {
    <h1>Search notes</h1>
    <form action="/search" method="get" hx-get="/search" hx-target="#results">
        <label for="query">Search</label>
        <input id="query" name="q" type="search" value={ query }/>
        <button type="submit">Search</button>
    </form>
    <section id="results" aria-live="polite">
        @results(items)
    </section>
}

templ results(items []string) {
    if len(items) == 0 {
        <p>No results.</p>
    }
    <ul>
        for _, item := range items {
            <li>{ item }</li>
        }
    </ul>
}
```

- `Scripts: htmx.Script()` includes htmx once, in the full document.
- The partial response contains only the results markup.
- Text inside `{ ... }` is escaped.

## 3. Register the app

In `project/apps.go`, import `example.com/myapp/apps/search` and add `search.New()`
to the existing list:

```go
func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        notes.New(),
        search.New(),
    }, nil
}
```

Keep your other app registrations. Use your own module path in the import.

## 4. Build and run

```sh
go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go run manage.go runserver
```

Open `http://127.0.0.1:8000/search`. You can also check both response forms:

```sh
curl 'http://127.0.0.1:8000/search?q=Go'
curl -H 'HX-Request: true' -H 'HX-Request-Type: partial' \
  'http://127.0.0.1:8000/search?q=Go'
```

| Request | Response |
| --- | --- |
| Ordinary | A full HTML document. |
| htmx partial | The `<ul>` results, with no document wrapper. |

`htmx.HTML` also sets the required `Vary` headers. It returns a full page for
history restoration.

## POST and DELETE requests

The example uses a read-only GET. For writes, keep your app's authentication and
CSRF middleware, and send its CSRF token.

### CSRF for htmx requests

Pass the session's token to the page layout. Every htmx request from the page then
sends it as the `X-CSRF-Token` header, which `security.Sessions.CSRF` accepts:

```templ
@layout.Page.Call(layout.Props{Title: "Notes", CSRFToken: token}, layout.Slots{
    Scripts:  htmx.Script(),
    Children: ui.Fragment(notes(items)),
})
```

- `token` comes from your session, for example `browser.CSRFToken(r.Context())`.
- The layout renders `<body hx-headers:inherited='{"X-CSRF-Token":"…"}'>`.
  `htmx.CSRFHeaders(token)` returns the same value for your own layouts.
- Pages that set the token must not be stored by shared caches. The CSRF
  middleware already sends `Cache-Control: no-store`.

Ordinary forms that must also work without JavaScript still need the hidden field:

```templ
<form action="/notes/delete" method="post">
    @form.CSRF.Call(form.CSRFProps{Token: token}, ui.NoSlots{})
    <button hx-delete="/notes/42" hx-target="#notes">Delete note</button>
</form>
```

`form` is `github.com/fauzaanu/cicadel/ui/form`.

> [!WARNING]
> htmx headers are not authorization. Check object permissions before deleting.

## Respond with htmx headers

The `htmx` package sets the response headers htmx 4 reads:

| Function | Header | Effect |
| --- | --- | --- |
| `Trigger(w, "saved")` | `HX-Trigger` | Dispatch events on the requesting element. |
| `TriggerDetail(w, "notify", detail)` | `HX-Trigger` | An event with a JSON detail. Calls accumulate. |
| `Redirect(w, "/notes/")` | `HX-Redirect` | Full-page navigation. Writes status 200. |
| `Location(w, "/notes/")` | `HX-Location` | htmx navigation without a full reload. Writes 200. |
| `Refresh(w)` | `HX-Refresh` | Reload the page. |
| `Retarget(w, "#errors")` | `HX-Retarget` | Swap into another element. |
| `Reswap(w, "outerHTML")` | `HX-Reswap` | Change the swap style. |
| `Reselect(w, "#list")` | `HX-Reselect` | Swap only part of the response. |
| `PushURL(w, "/notes/?page=2")` | `HX-Push-Url` | Push a history entry. |
| `ReplaceURL(w, "/notes/")` | `HX-Replace-Url` | Replace the current history entry. |

`Redirect`, `Location`, `PushURL` and `ReplaceURL` accept only local paths and
return an error otherwise, so a `?next=` value cannot redirect off-site. Use
`Redirect` instead of `http.Redirect` for htmx requests: the browser follows a
3xx itself, and htmx would swap the target page into the fragment.

```go
func create(w http.ResponseWriter, r *http.Request) {
    // ... validate and save ...
    if htmx.IsRequest(r) {
        _ = htmx.TriggerDetail(w, "notify", map[string]string{"message": "Saved"})
        _ = htmx.Redirect(w, "/notes/")
        return
    }
    http.Redirect(w, r, "/notes/", http.StatusSeeOther)
}
```

### Out-of-band swaps

Update other parts of the page in the same response. Group the main fragment with
elements that carry `hx-swap-oob` and a matching `id`:

```templ
templ counter(n int) {
    <span id="note-count" hx-swap-oob="true">{ strconv.Itoa(n) }</span>
}
```

```go
err := htmx.HTML(w, r, http.StatusOK, page, ui.Group(ui.Fragment(row(note)), ui.Fragment(counter(total))))
```

### Errors

With [error pages](https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md) installed, a failed htmx partial request keeps
its status, swaps nothing (`HX-Reswap: none`) and triggers `cicadel:error` with
the status and title.

## htmx 4 attributes

| Need | Use |
| --- | --- |
| Inherit an attribute | Explicit inheritance, such as `hx-target:inherited="#results"` |
| Queue requests | `hx-sync="this:queue all"` |
| Keep content on a server error | `hx-status:5xx="swap:none"` |

Return useful field errors with status 422.


---

Source: `docs/installable-apps.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md

# Installable applications

An installable app is a Go package that returns a `cicadel.App`. It brings
routes, commands, components and, optionally, database migrations. You register
it in `project/apps.go`.

First-party packages are core defaults. They use the same public contracts as
your own packages. The standard scaffolding registers accounts and formsets and
supplies the migration and query-generation commands.

> [!NOTE]
> Running `go get` on a third-party module does not activate it. An app is active
> only after you register it in `InstalledApps`.

## How apps are composed

![cicadel.New validates each installed App's contributions, orders the apps by dependency and builds one Application](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/docs/diagrams/app-composition.svg)

`cicadel.New` takes the list of apps and builds one `Application`:

1. It validates each app: name, commands, checks, routes, middleware and manifest.
2. It checks declared dependencies and orders apps so dependencies come first.
3. It resolves each app's typed settings.
4. It builds the event dispatcher, component registry, static manifest and routes.

Any error stops startup.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md.
Add [package and version] to my existing Cicadel application.
Inspect its constructor and required configuration, then register it in
project/apps.go without replacing existing apps. Check its dependencies and routes.
Review any database migrations before applying them. Run app checks and tests.
```

## Install a published package

Use the module path and version the package author gives you:

```sh
go get example.com/your-org/greetings@v0.1.0
```

`example.com/your-org/greetings` is a placeholder, not a published Cicadel
package. The next section shows how to create a local package with this API.

Import the package in `project/apps.go` and add its constructor to your app list:

```go
package project

import (
    "os"
    greetings "example.com/your-org/greetings"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/contrib/formsets"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        formsets.App(),
        greetings.New(greetings.Options{
            Greeting: "Welcome",
            Output: os.Stdout,
        }),
    }, nil
}
```

- Keep the standard `formsets.App()` entry and your other apps.
- You do not list accounts here. The project builder composes it.
- Database-backed factories can use the supplied `*gorm.DB`. Follow the package's
  constructor signature.

## Create a local package

From an existing Cicadel project, scaffold a separate module beside it:

```sh
go tool cicadel startpackage ../greetings example.com/your-org/greetings greetings
cd ../greetings
go get github.com/fauzaanu/cicadel@main
go mod tidy
go test -race ./...
cd ../myapp
go mod edit -replace=example.com/your-org/greetings=../greetings
go get example.com/your-org/greetings@v0.1.0
```

Register it as shown above, then run:

```sh
go run manage.go apps
go run manage.go check
go run manage.go greetings:hello
# Welcome
go run manage.go runserver
```

`GET /greetings/` returns `{"greeting":"Welcome"}`. The scaffold includes this
route, a command, typed options and tests.

> [!TIP]
> Need an app inside one project only? Use `startapp notes` instead.

## What a package returns

This small app exports one named route:

<!-- example: installable/apps/hello/app.go -->
```go
package hello

import (
    "net/http"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/urls"
)

func New() cicadel.App {
    return cicadel.App{
        Name: "hello",
        Manifest: &cicadel.Manifest{
            Module: "example.com/hello",
            Version: "v0.1.0",
            API: cicadel.AppAPIVersion,
        },
        Routes: []urls.Route{
            urls.Path("GET", "/hello/", "hello:index",
                func(w http.ResponseWriter, r *http.Request) {
                    if err := response.JSON(w, http.StatusOK, map[string]string{"message": "Hello"}); err != nil {
                        response.Error(w, http.StatusInternalServerError)
                    }
                }),
        },
    }
}
```

- `Name` owns the route and command namespace. Keep it stable across upgrades,
  especially when the app owns migration history.
- Go selects the module version. `Manifest.Version` is the package's
  compatibility metadata.

## Declare settings

1. Give the package a typed `Options` struct.
2. Tag the fields a deployment may override with `setting:"NAME"` or
   `setting:"NAME,secret"`.
3. Return `Settings: settings.NewPackage(options)` on the app.

The project passes values in Go. `CICADEL_<APP>_<NAME>` overrides them.
`manage.go apps` lists them with secrets redacted, and `manage.go check` reports
invalid keys. The `startpackage` scaffold does this for its greeting. See
[package settings](https://cicadel.fauzaanu.com/en/0.2.7/howto/package-settings/index.md).

## Emit and handle events

Events let apps react to each other without direct calls.

- Declare each event with `events.New[Payload]("<app name>", "name")`.
- List it in `App.Events` and call `Event.Emit(ctx, payload)`.
- Subscribe to other apps' events with `Event.Handle(fn)` in `App.Subscriptions`.

`cicadel.New` rejects subscriptions to events no installed app declares.
Handlers run synchronously in dependency order. The `startpackage` scaffold emits
a `greeted` event. See [events](https://cicadel.fauzaanu.com/en/0.2.7/howto/events/index.md).

## Publish static files

Put public CSS, images and scripts in an embedded directory and return it as
`App.Static`.

- The host serves each file at `/static/<app name>/<path>` with a content-hashed URL.
- `go run manage.go collectstatic DIR` collects them.
- Resolve URLs in handlers with `static.URL(r.Context(), "greetings", "site.css")`.

Do not add your own asset routes. `App.Resources` stays private. The
`startpackage` scaffold publishes `assets/static/`. See
[static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md).

## Add migrations

For a package with PostgreSQL tables, embed recorded SQL migrations:

```go
//go:embed migrations/*.sql
var migrations embed.FS

func migrationFiles() (fs.FS, error) {
    return fs.Sub(migrations, "migrations")
}
```

1. Import `embed` and `io/fs`.
2. Use the returned filesystem as `App.Migrations`. Handle its error in your factory.
3. Set `Manifest.Providers` to `[]string{"postgres"}`.
4. Run the host's `go run manage.go migrate` before serving requests.

Follow [the migration guide](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md) for generated model migrations.

## Depend on another app

If your package needs another installed app, declare it in `Manifest.Requires`:

```go
Requires: []cicadel.Requirement{
    {Name: "accounts", Version: cicadel.VersionRange{
        Min: "v1.0.0", Before: "v2.0.0",
    }},
},
```

These bounds are an example. They do not claim an accounts v1 release exists.
The host must register the dependency too. Missing or incompatible dependencies
fail startup checks.

## Remove or disable an app

To remove an app:

1. Delete its constructor from `InstalledApps`.
2. Remove unused imports.
3. Run `go mod tidy`.

To disable an app, omit its registration but keep its Go module available.

Either way, its routes, commands, static files and owned resources disappear
from the application. Existing PostgreSQL data and recorded migration history
remain. Deleting data is a separate, deliberate operation.

> [!WARNING]
> Restore the registration before running migrations. The migration runner
> rejects an incomplete catalog that contains previously applied package
> migrations.

Re-enabling the package restores its surfaces and lets its recorded history be
checked again. `TestInstallUpgradeRemoveExternalPackage` exercises this sequence
after a version upgrade, before removing the module entirely.

## External translation helpers

Localization is a third-party responsibility. An installable can:

- supply request middleware through `App.Middleware`;
- store its language selection under an unexported context key;
- expose a plain-text helper that accepts `context.Context`.

Render the result with normal `.templ` text expressions or `ui.Text`. Translated
strings must not become trusted HTML because they came from a catalog. Keep the
language selection in the request context, not in package globals, so concurrent
requests cannot change each other's output.

App middleware wraps only that app's routes. It does not translate host routes or
other installed apps. Hosts that want translated components on their own routes
must compose the extension's middleware there. The extension decides fallback
languages, missing-key handling and catalog ownership. Cicadel does not prescribe
translation catalogs or language negotiation.

`internal/scaffold/translation_test.go` checks this boundary. It installs a
separately versioned module through a local Go proxy into a generated consumer.
It covers Unicode, fallback text, escaped untrusted keys, concurrent requests,
isolation from host routes, unregistration, and `go mod tidy` removal followed by
a rebuild. Its tiny two-language lookup is test data, not a production
translation implementation.

## Related

- Component exports: [component libraries](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md#installable-libraries-and-overrides).
- Package lifecycle and compatibility: the
  [package authoring reference](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/SKILL.md).


---

Source: `docs/logging.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md

# Logging

Cicadel logs with Go's `log/slog`. You get named loggers, handlers, filters, levels
and output formats, all configured in Go.

The generated project owns its logging setup in `project/logging.go`. The default
is JSON to stderr.

## Configure with environment variables

| Variable | Values |
| --- | --- |
| `CICADEL_LOG_FORMAT` | `json` (default) or `text` for local development |
| `CICADEL_LOG_LEVEL` | `DEBUG`, `INFO`, `WARN` or `ERROR` |

Invalid values fail startup. The error does not print them.

For local development:

```sh
export CICADEL_LOG_FORMAT=text
export CICADEL_LOG_LEVEL=DEBUG
go run manage.go runserver
```

## Create a standalone logger

Import `os` and `github.com/fauzaanu/cicadel/observability`:

```go
logger, err := observability.NewLogger(observability.Logging{
    Output: os.Stderr,
    Format: "json",
})
if err != nil {
    return err
}
logger.InfoContext(ctx, "note created", "note_id", noteID)
```

`NewLogger` returns a standard `slog.Logger`. You can also:

- pass a `slog.LevelVar` to change the level at runtime;
- set `AddSource` to record caller locations;
- set a `ReplaceAttr` hook to rewrite attributes.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md.
Configure application logging for [events]. Use structured fields and the
existing project logger. Include request correlation, exclude secrets and
personal payloads, and verify the expected output in a focused test.
```

## Named loggers

Use a `System` when apps need their own levels, filters, several destinations or
propagation rules:

```go
level := new(slog.LevelVar)
level.Set(slog.LevelInfo)
logs, err := observability.NewLogging(observability.Config{
    Handlers: map[string]observability.HandlerConfig{
        "console": {Output: os.Stderr, Format: "json", Level: level},
        "errors": {Output: errorFile, Format: "text", Level: slog.LevelError},
    },
    Root: observability.LoggerConfig{
        Level: level, Handlers: []string{"console"},
    },
    Loggers: map[string]observability.LoggerConfig{
        "application": {Handlers: []string{"errors"}},
        "application.audit": {
            Handlers: []string{"errors"}, StopPropagation: true,
        },
    },
})
// Handle err before using logs.
logger := logs.Logger("application.accounts")
logger.InfoContext(ctx, "account enabled", "account_id", userID)
```

### How names resolve

- A name inherits from its closest configured dot-separated ancestor, then from `Root`.
- The nearest configured level applies. Each destination also checks its own level.
- Handlers on ancestors receive propagated events unless `StopPropagation` is set.
- A shared handler runs once per event, even when several levels reference it.

### Filters and custom handlers

- Logger filters come from the nearest configuration. Handler filters apply per destination.
- Filters receive redacted records. They return true to keep an event and must be
  safe for concurrent use.
- Custom formatters and exporters implement `slog.Handler`. Supply them through
  `HandlerConfig.Handler`.

### Validation and ownership

The configuration checks names, formats, nil filters and handler references before
use. It copies configuration containers. You still own the level variables, writers,
handlers and filter closures you reference.

Drain requests before you close outputs.

`Config.OnError` observes handler write and delivery errors. Its callback must not
log through the same failing logging system. Slog's convenience methods do not
return output errors themselves.

## Sensitive data

Cicadel redacts credential attributes before filtering and output. This covers
nested groups, `With` attributes and resolved `LogValuer` values.

- Redacted keys include password, password_hash, token, csrf_token, authorization,
  cookies, secret, API keys, SMTP password and database URL.
- Matching ignores case, hyphens, dots and underscores.
- A `credentials` group is redacted as a whole.
- `NewLogger`'s `ReplaceAttr` hook runs between redaction passes. So renamed
  sensitive keys are still protected.

> [!WARNING]
> Redaction works on structured fields only. It cannot make free-form messages,
> error strings, custom string payloads or arbitrary objects safe. Never put
> credentials into log messages. Never dump request, settings or model objects.

Error logs should name the operation and safe metadata. Leave out raw provider
responses and database query arguments.

## Requests

`observability.Middleware(logger, observe)` logs every request:

- It generates a fresh request ID and sets the `X-Request-ID` header.
- It logs method, status, bytes and duration.
- It ignores incoming IDs, paths, query strings, headers and bodies.
- It keeps standard response interfaces through httpsnoop.

| Response status | Level |
| --- | --- |
| Below 400 | INFO |
| 4xx | WARN |
| 5xx | ERROR |

`observability.Logger(ctx, logger)` attaches the same request ID to your own
application events. Pass the same logger to the middleware.

### Panics

- Panics are logged with Go call stacks. The panic value and local variables are never logged.
- Uncommitted responses get a generic 500. Committed responses are not rewritten.
- `http.ErrAbortHandler` keeps standard HTTP abort semantics.

Observer callbacks receive status, timing, bytes and a `Panicked` flag. They run
synchronously, so they must be fast, safe for concurrent use and must not panic.

Distributed trace propagation needs an explicit exporter or middleware integration.

## Database queries

```go
db.Logger = observability.NewQueryLogger(logger, 200*time.Millisecond)
```

This logs GORM query timings without SQL text or query arguments.

| Query | Level |
| --- | --- |
| Normal | DEBUG |
| Slower than the threshold | WARN |
| Failed | ERROR |

`ErrRecordNotFound` counts as a normal outcome. GORM's `LogMode` is honored. The
accounts starter turns this adapter on. Other applications opt in explicitly.

## Log files

`observability.OpenRotatingFile(path, maxBytes, backups)` returns a synchronized
writer. It keeps numbered backups, creates files with mode 0600 and needs an
explicit `Close`.

- Rotation happens between complete writes. One large record can exceed the size limit.
- Use one writer per path in one process.
- No background goroutine is started for rotation.

> [!TIP]
> With several replicas, log to stdout and use your platform's log collector.

## Error email

`observability.NewEmailHandler(sender, from, recipients, interval)` creates a
handler for ERROR and above, like Django's `AdminEmailHandler`.

- It sends a redacted JSON record through the configured mail transport.
- Each send has a five-second timeout.
- A shared suppression interval prevents alert storms.
- It attaches no request dumps or local variables.
- Delivery is synchronous. Use a custom queue handler to keep network latency out
  of requests.

Set `OnError` to observe failed alerts without recursive logging. The framework
never chooses alert recipients and sends nothing when you construct the handler.

## What is tested

`observability/logging_test.go` covers routing, propagation, filters, live levels,
grouped attributes, credential privacy, correlated panic events, query privacy,
file rotation, concurrent writes and captured email alerts.

This is a practical logging foundation. It does not claim full compatibility with
Python's logging API or automatic integration with third-party exporters.


---

Source: `docs/migrations.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md

# PostgreSQL model migrations

Migrations record every schema change as reviewable SQL. Use them whenever you add
or change a model: run `makemigrations`, review the SQL, then run `migrate`.

GORM runs your queries at runtime. It never replaces recorded history with
`AutoMigrate`.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md.
Add [model or schema change] through the application's registered Models and
recorded PostgreSQL history. Generate and review SQL, test against a disposable
database, and report the plan before touching an existing production database.
Do not use AutoMigrate or rewrite applied migration files.
```

## How it works

![Models flow through makemigrations into a reviewable SQL file, then migrate applies it to PostgreSQL and records the history](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/docs/diagrams/migrations-flow.svg)

1. You register models in your app's `Models()`.
2. `makemigrations` compares them with the recorded history and writes a new SQL file.
3. You review the SQL, commit it and rebuild the application.
4. `migrate` applies pending files to PostgreSQL and records what it applied.

The first-party `contrib/migrations` module does the work: generation, historical
state, version dependencies, execution, verification and recovery. The standard
management commands use it.

## Add a model

`startproject` already includes accounts, formsets, the migration commands and
typed query generation. `startapp blog` creates an app with:

- a `Models()` function,
- a `MigrationDirectory`,
- an embedded migration filesystem.

Register `blog.New()` in `project/apps.go`. Keep the existing first-party
registrations.

Then add and register a model in `apps/blog/models.go`:

<!-- example: migrations/apps/blog/models.go -->
```go
package blog

import "github.com/fauzaanu/cicadel"

type Note struct {
    ID int64 `gorm:"primaryKey"`
    Title string `gorm:"not null"`
}

func (Note) TableName() string { return "blog_notes" }

func Models() []cicadel.Model {
    return []cicadel.Model{cicadel.ModelOf[Note]("note", "blog_notes")}
}
```

## Generate and apply

From the project root:

```sh
go run manage.go makemigrations blog --name initial
go run manage.go makemigrations blog --check
go run manage.go generatequeries
DATABASE_URL='postgres://.../app' go run manage.go migrate plan
DATABASE_URL='postgres://.../app' go run manage.go migrate
DATABASE_URL='postgres://.../app' go run manage.go migrate verify
DATABASE_URL='postgres://.../app' go run manage.go showmigrations
```

| Command | What it does | Needs PostgreSQL |
| --- | --- | --- |
| `makemigrations APP --name NAME` | Writes the next SQL file into the app's migration directory. | No |
| `makemigrations APP --check` | Fails when model changes need a migration. Writes no files. | No |
| `generatequeries` | Generates typed query files. | No |
| `migrate plan` | Lists the steps `migrate` would run. | Yes |
| `migrate` | Applies pending migrations. | Yes |
| `migrate verify` | Checks that the database schema matches the applied history. | Yes |
| `showmigrations` | Lists each migration as applied or pending. | Yes |

Generation compares registered models with the recorded historical state. It never
reads a developer's database. It runs offline, even when `DATABASE_URL` points to
an unavailable server. So app factories used by `InstalledApps(nil)` must not do
database work.

After generating:

1. Review the generated SQL and query files.
2. Commit them.
3. Build the application again, so its embedded history is current.

## Model registration

Migrations and typed queries share one public `ModelOf` registry. It holds model
names, types and table ownership. Each declared table must match GORM's table name.

Configure these in `project/migrations.go` through
`management.ModelMigrationOptions`:

- pinned cross-app historical references,
- naming strategies,
- custom type mappings.

Renames, removals, conversions and backfills must be declared explicitly. Use
`makemigrations APP --changes changes.json`. See the
[operation contract](https://cicadel.fauzaanu.com/en/0.2.7/ref/migrations/index.md).

## Core module composition

The migration engine is a core default shipped as an installable Go module.
Standard projects already include its management commands.

- Register models and migration sources through the app contract.
- Generate package-owned migrations in the package's source checkout.
- Application builds load recorded history from the embedded filesystem.

Use the same framework version for the CLI and the application. Recorded
migrations and history from any release keep working with later releases. See the
[data guarantee](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee).

## Recovery

Management commands load every registered migration source into one dependency
catalog. They use the runner's shared PostgreSQL lock. Register every app whose
applied history you manage.

| Task | Command |
| --- | --- |
| Review a target version | `migrate plan --target APP=VERSION` |
| Roll back deliberately, after review | `migrate apply --target APP=VERSION --allow-data-loss` |
| Verify an eligible pre-existing initial schema | `migrate baseline --reason TEXT` |
| Recover a nontransactional index migration | `migrate recover --migration APP:VERSION --recovery retry\|complete` |

> [!WARNING]
> Migration history is not a data backup.

Unsupported changes fail explicitly. See
[the supported PostgreSQL operations](https://cicadel.fauzaanu.com/en/0.2.7/ref/migrations/index.md) and the
[acceptance evidence](https://cicadel.fauzaanu.com/en/0.2.7/sources/contrib/migrations/ACCEPTANCE.md).


---

Source: `docs/model-forms.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md

# Model forms

`forms/model` validates submitted fields and saves GORM models in PostgreSQL. Use it
for create and edit forms backed by a model.

It does not create tables or change migrations. Declare constraints in
[recorded migrations](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md) before you use a form. Its exported API is
part of the [stable surface](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee).

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md.
Implement create and edit forms for [model].
Allow only the intended editable fields, set owner values on the server,
and scope updates to authorized records. Handle validation, conflicts and
database errors. Test that another user cannot edit the record.
```

## Define, bind and save

```go
import (
    "github.com/fauzaanu/cicadel/forms"
    modelform "github.com/fauzaanu/cicadel/forms/model"
    "gorm.io/gorm"
)

// Define once with an ordinary, unscoped PostgreSQL *gorm.DB.
articleForm, err := modelform.New[Article](db, modelform.Config[Article]{
    Fields: []modelform.Field{
        {Name: "Title", Required: true, MaxRunes: 200},
        {Name: "Published"},
        {Name: "CategoryID", Required: true,
            Check: modelform.Related[Category]("category_id", func(tx *gorm.DB) *gorm.DB {
                return tx.Where("tenant_id = ?", tenantID)
            })},
    },
})
// Handle err during application setup (or request setup for tenant-specific forms).

// In a handler, after authentication, body limiting and CSRF middleware:
posted, err := forms.Parse(r)
// Handle parse failure before accessing posted.
bound := articleForm.Bind(posted.Values)
if errors := bound.Errors(); len(errors) != 0 {
    // Redisplay fields with these errors and bound.Values().
    return
}

// New records receive trusted server values separately from submitted input.
created, err := bound.Create(r.Context(), Article{TenantID: tenantID, OwnerID: userID})

// Editing loads and locks the authorized record. ID is parsed from the route.
updated, err := bound.Update(r.Context(), articleID, func(tx *gorm.DB) *gorm.DB {
    return tx.Where("tenant_id = ? AND owner_id = ?", tenantID, userID)
})
```

`Create` and `Update` are alternative handler paths. Check every returned error.

## Handle errors

| Error | Meaning |
| --- | --- |
| `modelform.Errors` | Safe display messages, keyed by field. The empty key `""` is a form-wide error. |
| `gorm.ErrRecordNotFound` | The target is missing or outside the authorized scope. |
| Any other error | An operational failure. Handle it on the server, not in response bodies. |

Get display messages with `var validation modelform.Errors` and
`errors.As(err, &validation)`.

A save returns a model only on success. Database work follows the request context.

## Allowed fields

You list every editable field. There is no "all model fields" mode.

- `Name` is the Go model field name.
- `Input` defaults to GORM's column name. It respects column tags and the
  configured naming strategy.
- Unknown submitted keys are ignored. CSRF fields and submit buttons pass through
  without allowing mass assignment.
- Duplicate values for an editable field are rejected. The form never picks one
  arbitrarily.
- The binder copies submitted input. `Values()` returns a copy.

You can share a definition between requests. Parser, check and hook closures must
be safe for concurrent use. Do not share tenant-specific closures across tenants.

## Supported conversion

| Go type | Accepted input |
| --- | --- |
| Strings | Whitespace and Unicode are kept. `Required` tests trimmed emptiness. `MaxRunes` counts Unicode code points. Invalid UTF-8 is rejected. |
| Signed and unsigned integers, including named types | Decimal, within the destination type's overflow limits. Negative input for an unsigned type fails. |
| Floating point | NaN, infinity and overflow are rejected. |
| Booleans | `true`, `1`, `on`, `false`, `0` and empty. A missing checkbox is false. |
| `time.Time` | RFC3339 timestamps with an explicit offset, normalized to UTC. Locale-specific dates and naive timestamps are not inferred. |
| A single pointer to a supported type | Empty input becomes nil. |
| Anything else | Set `Field.Parse`. |

Empty input for a non-pointer numeric or bool field becomes zero. Empty input for
a non-pointer timestamp is invalid.

> [!WARNING]
> Floats do not give decimal precision. For exact money, use a custom parser and a
> decimal model type.

`Required` means a nonempty submission, not "must be true". Use a check for
consent requirements.

`Field.Parse` handles custom column types and normalization:

- Return exactly the field's Go type, including its pointer or named type.
- Parser failures show a generic conversion error. Parser internals never become UI copy.
- Parsing may run more than once, so parsers must be pure.

## Binding rules

- Binding is a full form submission, not PATCH. Missing editable fields become
  zero or nil, or fail `Required`.
- Binding errors stop the save before any transaction or hook runs.
- `Errors()` checks conversion only. Database checks run at save time.
- Primary keys, associations, read-only columns and automatic timestamps cannot be
  input fields.
- Models need a single primary key.
- Unsupported column types need an explicit parser.

Cicadel does not generate widgets or derive validation from the schema. Set
`Required` and `MaxRunes`, and write business checks, yourself.

## Relationships

`Related[R](inputName, scope)` is a `Field.Check` for a scalar foreign key or a
nullable scalar key.

- The required scope lists the choices the caller may make.
- It takes a PostgreSQL share lock on the matching related record until the
  transaction ends. The record cannot be deleted or changed while the form saves.
- An unavailable choice and an unauthorized choice give the same field error.
- A nullable key accepts empty input unless `Required` is set.

Keep foreign-key constraints in the database even when you use this helper.

Automatic association saving is off. Cicadel infers no relationships or
relationship policy from GORM tags. For multiple rows and inline editing, use the
first-party [formsets module](https://cicadel.fauzaanu.com/en/0.2.7/ref/formsets/index.md). For explicit
join-table changes, use `AfterSave`. That hook then owns authorization and
validation for those changes.

## Checks and hooks

| Hook | Signature | Use it for |
| --- | --- | --- |
| `Field.Check` | `(context.Context, *gorm.DB, any) error` | Validating one field. |
| `Config.BeforeSave` | `(context.Context, *gorm.DB, *T) error` | Cross-field validation. Setting trusted server-owned fields. |
| `Config.AfterSave` | `(context.Context, *gorm.DB, *T) error` | Audit records and explicit join-table changes, in the same transaction. |

- Return `modelform.Errors` for safe messages. Return any other error to abort.
- Checks run in definition order and stop at the first error.
- `BeforeSave` cannot change the primary key.
- Framework hooks and normal GORM model hooks both take part in rollback.
- In hooks, use only the supplied transaction for dependent writes.
- Do not mutate caller-owned reference values in create seeds.

> [!WARNING]
> Database rollback cannot undo sent mail. Do not perform external side effects in
> hooks. Register them with `database.OnCommit(tx, ...)`, which runs them only after
> the outermost transaction commits, or use a transactional outbox. See
> [transactions](https://cicadel.fauzaanu.com/en/0.2.7/howto/transactions/index.md).

## Constraints

PostgreSQL constraints are the final authority for uniqueness, including
simultaneous submissions.

- A duplicate key becomes a safe form-wide error.
- Foreign-key, check and not-null violations get generic messages.

This avoids leaking constraint names or values. It also supports composite
uniqueness without a misleading preflight query. You can add friendlier field
messages in checks, but they must not replace database constraints.

## Transactions and authorization

`Update` runs `SELECT ... FOR UPDATE` on the scoped target. It reloads the current
state before binding.

- Concurrent saves on the same row run one after another.
- A stale caller copy cannot overwrite server-owned fields.
- Every mutable scalar column on the freshly loaded model is saved, including
  trusted hook changes and zero values.
- Updates never fall back to inserts.
- GORM's normal soft-delete and field-permission behavior applies.

`Create` uses GORM's normal model and database default semantics. The create seed
must have a zero primary key. To assign custom primary keys, use a trusted GORM
create hook.

Define the form with a plain database handle, not an existing transaction. Scope
functions are trusted query filters. Keep them on the supplied transaction and
model. Do not change the table, selection, connection or context.

A failure in binding, validation, persistence, hooks or commit returns no saved
model.

Your application still owns authorization, CSRF, request size limits, rendering,
retries and idempotency.

- A `Bound` is not a one-use token. Repeated `Create` calls are separate attempts.
- Deadlocks, serialization failures, connection failures and cancellation are
  operational errors for the caller.
- Check relationships in the same order across forms to reduce lock conflicts.

## Multiple saves in one transaction

`Form.InTransaction(tx)` returns a definition that uses an existing PostgreSQL
transaction. Its save results stay provisional until the outer transaction commits.

- Use the same database and naming configuration.
- You own the outer commit or rollback.
- Start the outer transaction with `database.Atomic`. Then `database.OnCommit`
  hooks registered by the saves run after the outer commit.
- A failed save discards its own hooks.

## Stale edits

Set `Config.VersionField` to an application-owned `int64` revision column. The form
then rejects stale edits.

1. Render `Form.Version` in a hidden `_version` field.
2. On save, a stale revision returns `ErrConflict` and writes nothing.

See [forms and validation](https://cicadel.fauzaanu.com/en/0.2.7/topics/forms-completion/index.md) for the full form flow and admin
integration.


---

Source: `docs/operations.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/operations/index.md

# Deploy your application

Build one executable, configure it with environment variables, run migrations as
a separate step and start the server. This page covers settings, migration safety
and the security work your application owns.

> [!NOTE]
> Released APIs follow the [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee).
> Security behavior is covered by automated tests; your application still owns
> the deployment checks on this page.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/operations/index.md.
Prepare this application for [deployment target]. Build its executable and
embedded assets, validate production configuration, and plan migrations and backups.
Keep secrets out of source. Run checks and verify readiness before reporting success.
```

## Build and run

From your application directory:

```sh
export CICADEL_DEBUG=false
export CICADEL_SECURE_COOKIES=true
export CICADEL_ALLOWED_HOSTS=app.example.com
go tool cicadel ui build
go build -trimpath -o bin/server .
bin/server check --deploy --json
# When this application has database migrations:
bin/server migrate
bin/server runserver
```

- Templates, migrations and static files are embedded in the executable.
- Run migrations as a separate deployment step.
- `check --deploy --json` prints structured deployment diagnostics, like Django's
  `check --deploy`.
- The example Dockerfile builds a non-root executable image.

See [the foundation guide](https://cicadel.fauzaanu.com/en/0.2.7/internals/foundation/index.md) for custom checks, command flags and
statuses, and the development rebuild/restart workflow.

## Settings

Settings apply in this order, later ones winning:

1. Typed defaults.
2. Project assignments.
3. Environment overrides.

Production requires debug off, allowed hosts and secure cookies. Debug mode does
not show exception details to clients.

Invalid values fail validation without printing their contents.
`settings.LoadWith` supports isolated test overrides and copies the allowed-host slice.

### Environment variables

| Variable | Value |
| --- | --- |
| `DATABASE_URL` | PostgreSQL connection URL. Supply it as a secret. |
| `CICADEL_SECRET_KEY` | Signing key. Generate it with `cicadel secretkey` and supply it as a secret. |
| `CICADEL_SECRET_KEY_FALLBACKS` | Old keys during rotation. See [signed tokens](https://cicadel.fauzaanu.com/en/0.2.7/howto/signing/index.md). |
| `CICADEL_ADDRESS` | Listen address. |
| `CICADEL_DEBUG` | Debug mode. |
| `CICADEL_ALLOWED_HOSTS` | Comma-separated exact hosts, without ports. |
| `CICADEL_SECURE_COOKIES` | Secure cookie flag. |
| `CICADEL_STATIC_URL` | A local path such as `/static/` or an `https` CDN prefix. See [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md). |
| `CICADEL_TRUSTED_PROXIES` | Addresses of your reverse proxy. See [behind a proxy](#behind-a-proxy). |
| `CICADEL_HSTS_SECONDS`, `CICADEL_SECURE_REDIRECT`, `CICADEL_CONTENT_SECURITY_POLICY` | HTTPS policy. See [security headers](https://cicadel.fauzaanu.com/en/0.2.7/howto/security-headers/index.md). |
| `CICADEL_MAX_BODY_BYTES` | Request body limit, as a decimal integer. |
| `CICADEL_MAX_OPEN_CONNS`, `CICADEL_MAX_IDLE_CONNS` | Database pool sizes, as decimal integers. |
| `CICADEL_READ_TIMEOUT`, `CICADEL_WRITE_TIMEOUT`, `CICADEL_IDLE_TIMEOUT`, `CICADEL_SHUTDOWN_TIMEOUT`, `CICADEL_CONN_MAX_LIFETIME` | Go durations such as `15s` or `30m`. |

### Default limits

| Limit | Default |
| --- | --- |
| Request body | 1 MiB |
| Header/read timeout | 15 seconds |
| Write timeout | 30 seconds |
| Idle timeout | 60 seconds |
| Shutdown deadline | 10 seconds |
| Open database connections | 10 |
| Idle database connections | 5 |
| Connection lifetime | 30 minutes |

Tune these for your workload and database capacity.

Handlers must honor request cancellation. The shutdown deadline closes any
remaining HTTP connections. The application owner closes its database after
serving stops.

## Static files

The executable serves static files at content-hashed `/static/<app>/` URLs.

To use a CDN instead:

1. Run `go run manage.go collectstatic DIR`.
2. Upload the output.
3. Set `CICADEL_STATIC_URL=https://…/` and switch traffic.

See [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md).

## Behind a proxy

Terminate TLS at a reverse proxy. Set `CICADEL_TRUSTED_PROXIES` to the proxy's
addresses.

- Cicadel then honors `X-Forwarded-For` and `X-Forwarded-Proto` from those peers.
- It ignores them from any other peer.
- It never trusts `Forwarded` or `X-Forwarded-Host`.

Keep the original allowed `Host`. HSTS, the HTTPS redirect and the content security
policy are covered in [security headers](https://cicadel.fauzaanu.com/en/0.2.7/howto/security-headers/index.md).

## Sessions

| Starter | Session table |
| --- | --- |
| Articles example | `sessions` |
| Accounts starter | `accounts_browser_sessions`, owned by the package, from migration 002 |

Sessions:

- are shared across instances;
- rotate at login;
- expire after 12 hours, or after 30 minutes idle;
- are invalidated at logout.

The accounts browser bridge checks revocation and account availability on every
request. Custom user stores must implement their own revocation policy. A session
ID alone is not an object permission policy.

## Migration safety

Each app keeps its version history table. Checksums live in the shared migration
ledger. Recorded version dependencies decide the order. The canonical runner takes
a shared PostgreSQL advisory lock.

> [!WARNING]
> Run migration commands over a direct or session-pooled database connection. Do
> not use transaction-mode PgBouncer.

What happens on failure:

- A failed transactional migration rolls back its schema and data changes. It is
  not marked as applied.
- A nontransactional migration can leave partial changes. Inspect them and write
  an explicit repair. Never blindly rerun destructive statements.

### Before destructive changes

1. Take a database backup and test it.
2. Prefer expand, backfill, contract changes that work with both the old and new
   app versions.
3. Remember that Goose down migrations may be destructive.

Management commands use the checksum-aware runner. They roll back to an explicit
target only with reviewed history and a data-loss acknowledgement. When needed,
restore a tested backup or apply a reviewed forward repair.

Migration history is not a backup. The shared lock serializes migrations, but
separate migrations do not make a whole deployment atomic.

## Your security responsibilities

### Queries and responses

- Pass user values as GORM parameters. SQL fragments, ordering, table names and raw
  queries are not safe when you pass arbitrary user strings into them.
- Select columns explicitly for JSON responses. Never serialize password hashes or
  whole user models.

### Sessions and CSRF

Apply middleware in this order:

1. Session `LoadAndSave`.
2. CSRF.
3. Application authorization.

- Unsafe session-based requests need a `csrf_token` form field or an
  `X-CSRF-Token` header. This includes JSON writes.
- Session pages are sent with `Cache-Control: no-store`.
- Authentication rotates the session and the CSRF token.
- Secure cookies require HTTPS, except in explicit local development.
- Add gateway or application rate limits to login and other expensive endpoints
  before you expose them publicly.

### Permissions

Every object change needs a current permission check. The articles example
restricts changes by author ID, both before rendering and in the SQL `UPDATE`
condition.

- `security.RequireLogin` is low level. It only checks that a session exists.
- Accounts-backed routes use `browser.RequireLogin` with `browser.Middleware`.
  It resolves current account availability and revocation.
- The accounts package supplies password reset, password change and revocation.
  Verified recovery destinations, invitation policy and MFA integration stay
  application choices.

### Input and output

- The body limit also applies to forms.
- Multipart handlers must parse bounded input explicitly, remove temporary files,
  validate content and use the storage API instead of user-supplied paths.
- HTML templates escape ordinary strings. Trusted template types skip escaping.
  Use them only around developer-controlled content.
- Redirect helpers accept local absolute paths only.

## Check before deploying

```sh
go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go run manage.go check --deploy --json
go build -trimpath -o bin/server .
```

Run database integration tests against a disposable PostgreSQL database. Keep
secrets in your deployment configuration.

## Logging

`observability.NewLogger(observability.Logging{Output: os.Stderr, Format: "json"})`
builds a standard `slog.Logger`.

- Choose `text` for local development.
- Pass a `slog.LevelVar` to change the level at runtime.
- Set `AddSource` for caller locations.
- Use `observability.Logger(ctx, logger)` for request correlation. Pass the same
  logger to the request middleware.

Credential attributes are redacted by key before the optional `ReplaceAttr` hook
runs. Key redaction cannot clean free-form text, so never put credentials in
messages or errors. See [logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md).

## SMTP delivery

```go
mail.Sender{Transport: mail.SMTP{Address: "smtp.example.com:587"}}
```

This sends email over SMTP with:

- mandatory STARTTLS and certificate verification;
- context cancellation and a default 30-second deadline;
- plain text and HTML bodies encoded as MIME alternatives when both are present.

Supply credentials through secret configuration. Building a sender does not
contact the SMTP server.

Delivery errors go back to the caller. Retries must allow for uncertain delivery
after an SMTP connection failure. The application owns verified recovery destinations.

## Related guides

- [Logging](https://cicadel.fauzaanu.com/en/0.2.7/topics/logging/index.md): named handlers, error alerts and generated-starter configuration.
- [Email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md): attachments, envelopes and batch counts.
- [Authentication](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md): accounts, sessions and recovery.


---

Source: `docs/package-settings.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/package-settings/index.md

# Package settings

An installable app declares its configuration as one typed Go struct. A deployment
can override tagged fields with `CICADEL_<APP>_<NAME>` environment variables.

## How it works

- The project passes the values in Go.
- A deployment may override tagged fields under the app's own prefix.
- The application resolves and validates the settings before `Start`.
- `manage.go check` reports an invalid key without printing its value.
- Secret fields are never displayed.

> [!NOTE]
> Unlike Django, there is no global `settings` object for apps. Each app reads its
> own resolved struct directly.

## Declare settings

1. Tag each field a deployment may change with `setting:"NAME"`.
2. Add `,secret` for credentials.
3. Leave handles and callbacks untagged. They are set only in Go.

Supported types are `string`, `bool`, integers, unsigned integers, floats,
`time.Duration` and `[]string` (comma separated).

<!-- example: installable/apps/newsletter/app.go -->
```go
package newsletter

import (
    "context"
    "errors"
    "net/http"
    "strings"
    "time"

    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/response"
    "github.com/fauzaanu/cicadel/settings"
    "github.com/fauzaanu/cicadel/urls"
)

// Options is configured by the project. A deployment may override tagged
// fields with CICADEL_NEWSLETTER_FROM, CICADEL_NEWSLETTER_BATCH,
// CICADEL_NEWSLETTER_INTERVAL and CICADEL_NEWSLETTER_API_KEY.
type Options struct {
    From     string        `setting:"FROM"`
    Batch    int           `setting:"BATCH"`
    Interval time.Duration `setting:"INTERVAL"`
    APIKey   string        `setting:"API_KEY,secret"`
}

// Validate runs after environment overrides. Name the field, never the value.
func (o Options) Validate() error {
    if !strings.Contains(o.From, "@") {
        return errors.New("From must be an email address")
    }
    if o.Batch < 1 || o.Batch > 1000 {
        return errors.New("Batch must be 1–1000")
    }
    return nil
}

func New(options Options) cicadel.App {
    if options.Batch == 0 {
        options.Batch = 100
    }
    config := settings.NewPackage(options)
    return cicadel.App{
        Name:     "newsletter",
        Settings: config,
        Start: func(context.Context) (cicadel.Cleanup, error) {
            _ = config.Value().Interval // resolved and valid here
            return nil, nil
        },
        Routes: []urls.Route{
            urls.Path("GET", "/newsletter/", "newsletter:index",
                func(w http.ResponseWriter, r *http.Request) {
                    if err := response.JSON(w, http.StatusOK, map[string]int{"batch": config.Value().Batch}); err != nil {
                        response.Error(w, http.StatusInternalServerError)
                    }
                }),
        },
    }
}
```

`settings.NewPackage` records the project's values without reading the
environment. Construct a fresh one inside the app constructor, as above, so each
application gets its own.

If `Options` has a `Validate() error` method, it runs after overrides.

## Configure them in the project

Install the app in `project/apps.go` with explicit Go values:

```go
newsletter.New(newsletter.Options{From: "news@example.com", Interval: time.Hour})
```

`cicadel.New` resolves every app's settings in dependency order. It reads the
environment that `settings.Load` read (`Settings.Env`).

Override one value per deployment:

```sh
CICADEL_NEWSLETTER_BATCH=500 go run manage.go runserver
```

### In tests

Settings from `settings.Defaults()` or `apptest.Settings()` read no environment.
Tests see only the Go values. Inject overrides with
`settings.LoadWith(apptest.Settings(), lookup)`.

## Inspect and check

`go run manage.go apps` lists each key, its current value and where it came from.
Secret values print as `[redacted]`:

```text
newsletter (local)
  CICADEL_NEWSLETTER_FROM="news@example.com" (default)
  CICADEL_NEWSLETTER_BATCH="500" (environment)
  CICADEL_NEWSLETTER_INTERVAL="1h0m0s" (default)
  CICADEL_NEWSLETTER_API_KEY="[redacted]" (default)
```

An invalid value does not stop construction. Instead:

- `go run manage.go check` (and `check --json`) reports it as
  `<app>:settings:invalid`. It names the key but not the value.
- `Start` refuses to run.

```text
error newsletter:settings:invalid: CICADEL_NEWSLETTER_BATCH must be an integer in range
```

Validation errors read `app newsletter settings: Batch must be 1–1000`.
`Application.PackageSettings` returns the same redacted description for tools.

## Rules

- Keys are always `CICADEL_<APP>_<NAME>`, with `NAME` in upper snake case.
- `cicadel.New` rejects:
  - a key that collides with a project setting (`settings.CoreKeys`);
  - a key that collides with another app's key;
  - a duplicate name;
  - an unsupported field type.
- A system check named `settings` is reserved on apps that declare settings.
- Settings resolve once. Sharing one `settings.Package` between two apps is an error.
- A package that needs its values during construction resolves them itself with
  `Package.Resolve(app, s.Env())`. It still sets `App.Settings` to the same value,
  so `apps` and `check` see it.
- `settings.LoadPackage` resolves without keeping the result.

## Accounts settings

The standard accounts app uses this contract. Generated projects set
`AccountOptions` in `project/accounts.go`. A deployment may override:

- `CICADEL_ACCOUNTS_SESSION_LIFETIME`
- `CICADEL_ACCOUNTS_RECOVERY_LIFETIME`
- `CICADEL_ACCOUNTS_IDLE_TIMEOUT`
- `CICADEL_ACCOUNTS_BCRYPT_COST` (10–16)

With an invalid value, the project builds without account services. `check`
reports the key and `runserver` refuses to start.


---

Source: `docs/pagination-and-messages.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md

# Pagination and flash messages

`paginate` splits ordered query results into numbered pages and renders page
navigation. `flash` stores one-time messages, such as "Note created", in the
user's session and shows them on the next page.

They fill the roles of Django's `Paginator` and messages framework.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/pagination-and-messages/index.md.
Paginate [list route] with paginate.Parse and paginate.Query using a
deterministic Order, answer 400 for ErrInvalidPage and 404 for ErrPageNotFound,
and render paginate.Nav. After [form] succeeds, add a flash.Success message and
redirect; render flash.List on the next page. Add tests for both.
```

## Paginate a list

```go
func List(db *gorm.DB) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        req, err := paginate.Parse(r, paginate.Options{PerPage: 20})
        if err != nil {
            response.Error(w, http.StatusBadRequest)
            return
        }
        page, err := paginate.Query[Note](r.Context(), db.Where("owner_id = ?", ownerID(r)).Order("created_at DESC, id DESC"), req)
        if errors.Is(err, paginate.ErrPageNotFound) {
            response.Error(w, http.StatusNotFound)
            return
        }
        if err != nil {
            response.Error(w, http.StatusInternalServerError)
            return
        }
        content := ui.Group(notesList(page.Items), paginate.Nav.Call(paginate.Navigation(page), ui.NoSlots{}))
        if err := (ui.Renderer{}).HTML(r.Context(), w, http.StatusOK, content); err != nil && !ui.Committed(err) {
            response.Error(w, http.StatusInternalServerError)
        }
    }
}
```

### Parse the page number

`Parse` reads `?page=`. The default is 1.

- Zero, negative, malformed, repeated or larger-than-`MaxPageNumber` values return
  `ErrInvalidPage`. Answer 400.
- The page size is `PerPage` (default 20).
- To let clients choose the size, set `SizeParam`, for example `"per_page"`.
  Clients can then pick up to `MaxPerPage` (default 100).

### Query the page

`Query` requires an `Order` clause. Without one it returns `ErrUnordered`, because
unordered pages can repeat or skip rows.

> [!TIP]
> Make a unique column such as `id` the last sort key.

- It counts and loads in one read-only `REPEATABLE READ` transaction, so the total
  and the items agree.
- Inside your own transaction, it uses that transaction instead.
- A page past the last returns `ErrPageNotFound`. Answer 404.
- Page 1 of an empty result is a normal empty page.
- `Slice` paginates an in-memory slice the same way.

> [!WARNING]
> Pagination applies no authorization. Scope the query to rows the user may see.

### The page value

| Field or method | Contents |
| --- | --- |
| `Items` | The rows on this page |
| `Number` | The page number |
| `Size` | The page size |
| `Total` | The total item count |
| `Pages` | The page count |
| `HasPrevious()`, `HasNext()` | Whether neighbor pages exist |
| `Start()`, `End()` | 1-based item positions, for "Showing 21–40 of 95" |

## Page navigation

`paginate.Navigation(page)` builds props for `paginate.Nav`. It is a semantic,
unstyled component that renders:

- a `<nav aria-label="Pagination">` landmark;
- Previous and Next links with `rel="prev"` and `rel="next"`;
- page numbers, with `aria-current="page"` on the current page;
- long ranges shortened with `…`, like Django's `Paginator.get_elided_page_range`.

For other widths, call `page.Links(onEachSide, onEnds)`.

Links are query-only relative URLs such as `?page=3&q=go`. They keep every other
query parameter and never contain a host or path. Page 1 omits `page=`.

Style it with your own CSS, for example `nav[aria-label=Pagination] a[aria-current]`.

## Flash messages

### Create the store

Create the store from the same `security.Sessions` your browser sessions use.
In the standard project, that is the session manager passed to `service.Browser`
in `project/application.go`:

```go
sessions := security.NewSessions(store, s.SecureCookies)
browser, err := service.Browser(sessions)
// ...
messages := flash.New(sessions)
```

Pass `messages` to your app constructors, the same way you pass the database.

Routes must run inside session middleware. Accounts pages and `browser.Middleware`
already do. For other routes, add `sessions.LoadAndSave` to `App.Middleware`.

### Add a message

Add a message, then redirect:

```go
func Create(messages *flash.Messages) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // ... save the note ...
        if err := messages.Success(r.Context(), "Note created"); err != nil {
            response.Error(w, http.StatusInternalServerError)
            return
        }
        http.Redirect(w, r, "/notes/", http.StatusSeeOther)
    }
}
```

### Show messages

On the next page, `Pop` returns and removes pending messages. So each one appears once:

```go
pending, err := messages.Pop(r.Context())
if err != nil {
    response.Error(w, http.StatusInternalServerError)
    return
}
content := ui.Group(flash.List.Call(flash.ListProps{Messages: pending}, ui.NoSlots{}), page)
```

`flash.List` renders:

- errors and warnings with `role="alert"`;
- info and success messages with `role="status"`;
- a `data-level` attribute for styling;
- nothing when there are no messages.

### Message rules

- Levels are `flash.Info`, `Success`, `Warning` and `Error`.
- Text is plain text and is always escaped.
- Each message is 1–1000 bytes of UTF-8.
- At most 20 messages can be pending per session.
- `Peek` reads messages without removing them.
- Without session middleware, every call returns `flash.ErrNoSession`.

## Limits

- Pagination uses `OFFSET`, which slows down on very deep pages of large tables.
  Keyset ("load more after id X") pagination is not included.
- The standard project does not yet create the flash store for you. Wire it as
  shown above.


---

Source: `docs/performance.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/performance/index.md

# Measure application performance

Measure a real route or query before you change it. Include authentication,
database access and rendering when they are part of the path.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/performance/index.md.
Investigate [slow route or operation] in this application.
Create a representative benchmark, record latency and allocations, and profile it.
Fix the measured bottleneck while preserving behavior and permissions.
Compare repeated runs and report the workload and any remaining uncertainty.
```

## Benchmark a handler

Add a benchmark next to the handler you want to measure. This template uses a
generated notes app. Replace it with your real handler and its dependencies.

<!-- example: quickstart/apps/notes/benchmark_test.go -->
```go
package notes

import (
    "net/http/httptest"
    "testing"
)

func BenchmarkIndex(b *testing.B) {
    request := httptest.NewRequest("GET", "/notes/", nil)
    b.ReportAllocs()
    for b.Loop() {
        recorder := httptest.NewRecorder()
        Index(recorder, request)
        if recorder.Code != 200 {
            b.Fatalf("status = %d", recorder.Code)
        }
    }
}
```

Run it five times:

```sh
go test ./apps/notes -run '^$' -bench BenchmarkIndex -benchmem -count=5
```

This measures the handler directly. It leaves out network, middleware and database
costs unless your setup includes them.

## Profile the operation

```sh
go test ./apps/notes -run '^$' -bench BenchmarkIndex -benchtime=5s \
  -cpuprofile=cpu.out -memprofile=mem.out
go tool pprof -top cpu.out
go tool pprof -top -alloc_space mem.out
```

For database work, load representative rows into a disposable PostgreSQL database.

- Check query counts with
  [the application testing helpers](https://cicadel.fauzaanu.com/en/0.2.7/topics/testing/index.md#postgresql-isolation-and-query-budgets).
- Inspect slow SQL with PostgreSQL's query planner.

## Compare a change

1. Keep the same inputs, dataset and concurrency before and after the change.
2. Record errors as well as latency.
3. Repeat the runs. One short run is not enough to claim a speedup.

Do not use a development server's latency as your production capacity estimate.

## Compared with Django

The documentation home page compares the standard Cicadel project with a vanilla
Django 6.1 project on the same machine, both on PostgreSQL with auth, sessions
and CSRF.

| Measure | Cicadel | Django |
| --- | --- | --- |
| Container image | 35 MB | 320 MB |
| Memory at idle | 24 MB | 86 MB (1 gunicorn worker) |
| Requests per second | ~23,000 | ~10,300 (10 gunicorn workers, 581 MB) |
| Median response | 1 ms | 2 ms (10 workers) |

The method, versions, raw results and a harness to reproduce them are in
[the comparison notes](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/benchmarks/django-comparison/README.md). Re-run it on
your own hardware before relying on a number.


---

Source: `docs/reference/forms.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/reference/forms.md

# Forms reference

Detailed field, upload and transaction behavior for application authors.

## Standalone forms

```go
definition, err := forms.New([]forms.Field{
    forms.Text(forms.Options{Name: "email", Label: "Email", Widget: "email", Required: true}, forms.Email),
    forms.Integer(forms.Options{Name: "age", Label: "Age", Required: true}, forms.Range[int64](18, 120)),
    forms.Boolean(forms.Options{Name: "accepted", Label: "Accept terms"}, forms.Accepted),
    forms.Multiple(forms.Options{Name: "topics", Label: "Topics", Choices: []forms.Choice{
        {Value: "go", Label: "Go"}, {Value: "sql", Label: "SQL"},
    }}),
})
// Check configuration errors before serving requests.
posted, err := forms.Parse(r)
// Handle parse errors and apply request body limits.
bound := definition.Bind(posted.Values)
if bound.Valid() {
    age, ok := forms.Value[int64](bound, "age")
    // Use age after checking ok; values have already passed validators.
}
```

`Initial()` supplies initial values without claiming the form was submitted or
valid. `Bind` snapshots input and ignores undeclared names. Single-value fields
reject repeated values. Multiple-choice fields reject duplicate or unavailable
choices. Invalid UTF-8, numeric overflow, non-finite numbers, invalid dates and
malformed timestamps are rejected. Strings preserve whitespace; Required checks
trimmed emptiness. Optional numeric/boolean fields become zero/false; optional
dates/timestamps become zero time. `Date` accepts YYYY-MM-DD; `Timestamp` requires
an RFC3339 offset and returns UTC. There is no implicit locale conversion.

Built-ins are `Text`, `Integer` (int64), `Number` (float64), `Boolean`, `Date`,
`Timestamp`, `Select`, and `Multiple`. `Typed[T]` supports explicit custom parsers
and `Validator[T]` functions. Built-in validators cover rune length, ordered
ranges, email, HTTP(S) URLs, patterns and required acceptance. Exact decimals and
application-specific identifiers should use explicit types/parsers rather than
binary floating point. Parser error details are never exposed as display text.

Pass cross-field checks to `New`; they run after every field converts successfully
and return `forms.Errors`, using an empty key for form-wide messages. `Errors`,
`Values` and `Fields` return independent snapshots; `Value[[]string]` also copies
choice lists. Custom pointer/map values and callbacks remain application-owned;
use immutable values and pure, concurrency-safe parsers/validators. Check `Valid`
before acting on cleaned fields. Password/file values are excluded from `Fields`
redisplay; raw `Values` intentionally retains the submission and must not be logged.
The original `forms.Parse`/`Required` API remains compatible.

## Accessible components

Render each `bound.Fields()` entry through `ui/form.Bound(field, uniqueID)` and
`ui/form.Field.Call(props, ui.NoSlots{})` in an authored `.templ` component.
The shared widget supports text/textarea, password, email, URL, number, select,
multiselect, checkbox, radio, date, datetime-local, time, file and hidden controls.
Use a custom parser for local datetime/time inputs; the timestamp field deliberately
requires an explicit offset. Set `Multiple` for directly authored multiselect props;
the bound adapter supplies it automatically.

Labels target controls; radio groups use fieldsets/legends; help/error IDs are
connected with `aria-describedby`, errors use `aria-invalid` and `role=alert`.
Submitted choices and checkboxes preserve state. Text, labels, help, errors and
option values are escaped. Password/file widgets never render a submitted value.
Applications display form-wide errors from `Errors()[""]` in their page layout.

## Stale edits

Add an application-owned `Revision int64` column through a recorded migration,
initializing existing rows to 1. Set `model.Config[T].VersionField = "Revision"`;
do not make Revision editable. New model-form records start at 1. Render
`form.Version(ctx, &record)` as hidden `_version`. Updates compare it while holding
the row lock and increment the revision in the same transaction. A missing or
malformed revision is a validation error; an old revision returns
`model.ErrConflict` and writes nothing. Hooks cannot modify the revision.

Formsets use each row's `<prefix>-<index>-_version` for updates and deletions and
roll back the complete collection on a stale row. Admin renders revision fields
and returns HTTP 409 for conflicts, preserving submitted input. Reload and
explicitly reconcile edits; never silently retry using a fresh token. Every writer
to versioned data must advance the same revision. Existing unversioned models keep
their old behavior until explicitly opted in. Row/collection locking still protects
transactional writes; revisions additionally protect against an old browser form.

## File fields and persistence

`forms/upload.Parse(w, r, Config)` streams multipart bodies into private temporary
files under a mandatory total limit and explicit per-field limits. It bounds text
fields and part counts, rejects duplicate/unknown file fields, sanitizes display
filenames, checks optional extension and sniffed media-type allowlists, and
validates required/clear semantics. The client filename is never a storage key.
Use `ValidateContent` for application-specific inspection (image decoding, document
parsing or a scanning service) before storing. Content-type sniffing is not malware
scanning. Serve untrusted files as attachments with appropriate content headers.

Each `upload.Field` defines Name, MaxBytes, Required, AllowClear, MediaTypes,
Extensions and a trusted ExistingKey loaded by the authorized handler. An empty
file input preserves the existing file. `<name>_clear=on` explicitly removes it;
required files cannot be cleared, and replacement plus clear is rejected. File
inputs cannot be prefilled after errors; users must select the file again.

Always `defer batch.Close()`. `batch.Values` supplies ordinary fields for typed or
model binding. `batch.Save(ctx, store, persist)` generates random storage keys,
stores incoming files, and calls `persist(map[string]upload.Stored)` with keys and
metadata. The callback owns and commits the database transaction (for example,
sets the model's file-key field in BeforeSave and uses a revision-checked update).
Return an error only when the database save did not commit. On failure, new objects
are removed and old ones retained; after success, replaced/cleared old objects are
removed. Objects still referenced by another unchanged field are preserved.

Storage and PostgreSQL are separate systems: this is compensating cleanup, not a
distributed transaction. `*upload.CleanupError` exposes retry keys and whether the
database operation committed. Record and retry failed deletions; do not repeat a
committed database save. For process crashes or an uncertain database commit,
applications need durable outbox/reconciliation appropriate to their store. These
operational realities are explicit, not a claim of cross-system atomic commit.
Batch Save is one-use. Cleanup uses a bounded context independent of request
cancellation. Temporary files are removed by Close or failed-parse cleanup.

For browser multipart POSTs with session CSRF, use the middleware order:

```text
authentication -> upload.Middleware(config) -> sessions.CSRF -> handler
```

Keep the session LoadAndSave wrapper outside that chain. The upload middleware
parses once, makes text values available to CSRF, and closes the batch after the
handler chain. Use `upload.FromRequest(r)` in the handler. Alternatively a direct
Parse handler can sit behind CSRF when the client supplies `X-CSRF-Token`.

## Admin integration

`admin.Config[T].Model` supplies model-form fields, validators/checks, hooks and
VersionField. Display field order must match the explicit model field order when
both are supplied. Otherwise fields are derived from the existing admin allowlist.
`admin.Field.Widget`/Choices choose the shared widgets; listed choices are checked
server-side. `Seed` supplies trusted defaults. Permissions are checked on the
current locked record and the proposed model. Existing routes retain deny-by-default
permissions, scoped lookup and the external authentication/CSRF middleware contract.

The first-party `formsets.AdminInline[P,T](../AdminConfig[P,T])` adapter goes in
`admin.Config[P].Inlines`. Configure child Set, ForeignKey (Go field name), Label,
Extra, ParentScope and optional field Widgets. Extra rows render ordinary controls;
entirely empty new rows are ignored, and partially filled rows validate normally.
The parent key is derived from the authorized parent model, never POST. Scope,
identity, version, min/max, deletion and protected-field rules remain those of the
formset API. Child errors redisplay beside their row controls.

Parent creation/update and all inline saves share one outer transaction. Any
child error rolls back the parent, its revision and every child mutation. The
adapter uses only public admin/model-form integration contracts; core does not
import the first-party module. Parent deletion follows authored foreign-key/cascade
policies. No implicit related-record cascade is added by the framework.


---

Source: `docs/releases.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md

# Releases and stability

The current release is **v0.2.7**. This page covers what a release contains, what
stays stable, how versions are chosen and how to install, upgrade and cut a release.

The **dev** documentation describes the latest code on `main`, which may include
unreleased changes. Versioned documentation matches each release exactly.

## Is Cicadel ready to use?

**Yes, for building applications.** v0.2.7 contains the core of a web framework.
Each part below is documented and tested against real PostgreSQL in freshly
generated projects:

- projects, apps, typed settings, management commands, system checks and a
  rebuilding development server;
- routing with named URLs and reversal, request/response helpers and middleware;
- HTML error pages and panic recovery, per-route request body limits and
  login redirects that return users to the page they asked for;
- GORM models with recorded, reviewable PostgreSQL migrations and typed queries;
- typed `.templ` components, Tailwind CSS and htmx;
- forms, model forms, formsets and bounded file uploads;
- accounts: login, logout, password change and reset, groups and permissions,
  sessions and CSRF protection;
- pagination and flash messages;
- security headers, HSTS, HTTPS redirect and trusted-proxy handling;
- signed, expiring tokens with secret-key rotation;
- transactions with post-commit hooks;
- static files with hashed URLs, email, logging and application test helpers;
- installable packages for your own and third-party apps, with typed per-package
  settings and typed events.

Every item in the [readiness checklist](https://cicadel.fauzaanu.com/en/0.2.7/sources/README.md#readiness-checklist) is
released as of v0.2.4. Next is the v0.3 milestone: package-system completion,
module extraction and a wider PostgreSQL migration subset.

**Not in the core,** and not needed to build an application: an administration
interface, cache and task backends beyond the included ones, sitemaps and managed
redirects. They are planned as packages after the core.

> [!NOTE]
> Cicadel has not had an outside security audit. The owners decided not to make one
> a release requirement. Automated tests cover the security features. If you deploy
> publicly, review your own application's threat model.

## Stability guarantee

From v0.1.0, releases follow [semantic versioning](https://semver.org/).

The root module and the four core modules release together with the same version:
`contrib/accounts`, `contrib/formsets`, `contrib/migrations` and `contrib/querygen`.
Use the same version for all of them.

| Release | What it may contain |
| --- | --- |
| **Patch** (`v0.2.1`, `v0.2.2` …) | Fixes and backward-compatible additions. Never breaks the stable surface. Upgrade with `go get github.com/fauzaanu/cicadel@v0.2.x` and the matching core module versions. |
| **Minor** (`v0.3.0` …) | A completed milestone (see the [versioning standard](#versioning-standard)). Before v1.0, it may also change the stable surface when necessary. |
| **v1.0 and later** | No breaking changes within a major version. |

When a minor release changes the stable surface:

- the [changelog](https://cicadel.fauzaanu.com/en/0.2.7/releases/changelog/index.md) lists the change under **Breaking changes**, with
  exact upgrade steps;
- where practical, the old API keeps working for one more minor release, marked
  `// Deprecated:` with its replacement.

### The stable surface

- exported Go APIs of the packages listed in the [API index](https://cicadel.fauzaanu.com/en/0.2.7/ref/api/index.md);
- the layout generated by `startproject`, `startapp` and `startpackage`;
- `manage.go` and `cicadel` command names, flags and exit codes;
- `settings.Settings` fields and `CICADEL_*` / `DATABASE_URL` environment variables;
- the installable-app contract (`cicadel.App`, `Manifest`, `AppAPIVersion`).

### Your data is always protected

- Recorded migrations and migration history written by any release keep working
  with every later release.
- Cicadel never requires you to edit an applied migration.
- Framework-owned tables (accounts and sessions) change only through new recorded
  migrations. Never through automatic or destructive schema changes.

### Not covered

- anything under `internal/`;
- unexported behavior;
- the exact HTML and CSS of starter and account pages;
- error message wording;
- performance characteristics.

Security fixes may change behavior that was itself insecure. The changelog calls
out such changes.

## Versioning standard

Version numbers track milestones, not individual features. v1.0 arrives only when
Cicadel is a complete framework.

### Choosing the next version

| Change | Release |
| --- | --- |
| Bug or security fix | next patch |
| New package, API, setting or command that existing code does not notice | next patch |
| New secure default that existing projects must opt into (generated projects get it) | next patch |
| Changed default behavior, removed or changed API, changed generated layout | waits for the next minor |
| Last item of the current milestone | next minor |

Rules:

- Bump the minor version only when the current milestone is complete. Never bump
  it for a single feature. Never release more than one minor per milestone.
- Work that would break existing applications waits for the milestone's minor
  release. Until then, ship it behind a setting or as a new API, and deprecate
  the old one.
- Release patches as often as finished work allows. Documentation-only or
  test-only changes do not need a patch.

### Milestones

| Version | Milestone | Scope |
| --- | --- | --- |
| v0.1 | Core framework | Released. |
| v0.2 | Core completeness | Released (v0.2.0–v0.2.4): pagination and flash messages, security headers and HTTPS policy, signed tokens, post-commit hooks and per-package settings. |
| v0.3 | Packages and migrations | Package-system completion, module extraction and the wider migration operation subset. In progress as v0.2.x patches: typed events (v0.2.5) and accounts events (v0.2.6). v0.2.7 adds browser request handling: error pages, login redirects, per-route body limits and htmx response helpers. |
| v0.4 … v0.x | Django-parity batteries | One milestone each, in order: administration; cache and task backends; internationalization and time zones; sitemaps, syndication and managed redirects; anything else needed to match Django's included batteries. |
| v1.0 | Complete and stable | See the criteria below. |

### v1.0 criteria

All of these must hold:

1. Every milestone above is released, giving Cicadel the capabilities of Django's
   included batteries for PostgreSQL applications, or more.
2. Every exported API in the [API index](https://cicadel.fauzaanu.com/en/0.2.7/ref/api/index.md) is documented and tested, and
   every capability has a tutorial or guide.
3. The owners have built and run real applications on the framework.
4. One full minor release cycle has passed with no breaking changes.

## Install a release

```sh
go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.7 startproject myapp example.com/myapp
```

> [!NOTE]
> The repository is private. Set `GOPRIVATE=github.com/fauzaanu/cicadel` and
> configure Git credentials with access first.

The generated `go.mod` pins the framework and core modules at the CLI's release.

### Upgrade an application

Move all five modules to the new version together:

```sh
v=v0.2.7
go get github.com/fauzaanu/cicadel@$v \
  github.com/fauzaanu/cicadel/contrib/accounts@$v \
  github.com/fauzaanu/cicadel/contrib/formsets@$v \
  github.com/fauzaanu/cicadel/contrib/migrations@$v \
  github.com/fauzaanu/cicadel/contrib/querygen@$v
go mod tidy
go run manage.go migrate plan
```

1. Read the changelog entry first.
2. Apply any listed upgrade steps.
3. Run `go run manage.go migrate` and your tests.

## Release procedure

Maintainers and agents release completed work this way:

1. Pick the version with the [versioning standard](#versioning-standard).
   Move the changelog's **Unreleased** entries under `## vX.Y.Z — YYYY-MM-DD`,
   with a **Breaking changes** list when the stable surface changed.
2. Set `defaultModuleVersion` in `internal/scaffold/scaffold.go` to `vX.Y.Z`, and
   update the current release named on this page.
3. Run every local CI check, push, and wait for the GitHub workflows to pass.
4. Tag the pushed commit for every module and push the tags:
   `vX.Y.Z`, `contrib/accounts/vX.Y.Z`, `contrib/formsets/vX.Y.Z`,
   `contrib/migrations/vX.Y.Z` and `contrib/querygen/vX.Y.Z`.
5. Run the **Draft release** workflow with the tag. It re-runs every verification
   workflow, builds CLI archives with checksums and creates a draft. Publish it with
   `gh release edit vX.Y.Z --draft=false`.
6. Verify a fresh project from the tag with `GOWORK=off` and no `replace`
   directives: `startproject`, `go mod tidy`, `go test ./...` and
   `go run manage.go check`.
7. Freeze the documentation for the release with
   `python3 website/scripts/add-version.py vX.Y.Z`. In the same commit, move the
   core modules' requirements on each other to `vX.Y.Z` (`GOWORK=off go get` in
   each module, then `go mod tidy`), so every module builds on its own with
   `GOWORK=off`. Commit and push.

> [!WARNING]
> If step 6 fails, fix it and release the next patch version. Never move a
> published tag.

### Core and contrib release order

A contrib module can only import core APIs that exist in the core version its
`go.mod` requires. The accounts and formsets checks type-check against that pin.

When a module needs a new core package or API:

1. Release the core change first.
2. Adopt it in the module after the freeze commit has moved the pin.
3. Release that as the next patch.

For example, v0.2.5 added `events` and v0.2.6 made accounts emit them.

## Requirements

- Go 1.26.11 or later in the 1.26 series.
- PostgreSQL 18.
- The CLI and application on the same framework revision. Commit `go.mod` and
  `go.sum`.

Check the framework version your application uses:

```sh
go list -m github.com/fauzaanu/cicadel
```

Start with [the application tutorial](https://cicadel.fauzaanu.com/en/0.2.7/intro/tutorial/index.md). Then use the topic guides for
the current model, component, form and account workflows.

## Core module composition

The root Go workspace includes the first-party modules for checkout development.

- The distributable framework pins the migration and query-generation module
  versions. New projects pin accounts and formsets as well.
- Before updating those pins, run integration checks in every module. Then verify
  a generated project with `GOWORK=off` and no local replacements.
- The repository is currently private. Authorized consumers need Git credentials
  and `GOPRIVATE=github.com/fauzaanu/cicadel`. CI uses its repository-scoped token
  through the Git credential helper.

## Release workflow details

The **Draft release** workflow runs only when invoked manually.

- Before it builds CLI archives, these suites must pass: root CI, accounts,
  formsets, migration/query-generation installables and documentation
  verification. A failure in any suite prevents artifact creation.
- Documentation verification in this workflow does not publish the website.
- Select the workflow revision that matches the existing semantic-version tag. The
  build job checks that the tag resolves to the same commit the reusable workflows
  checked. Only then does it compile Linux/macOS amd64/arm64 binaries and checksums.
- A tag pointing elsewhere fails closed. Rerun against the correct revision.
- A draft is not a publication. Publish the draft as described in the
  [release procedure](#release-procedure).


---

Source: `docs/request-limits.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/request-limits/index.md

# Limit request bodies

Every request body is capped at `settings.MaxBodyBytes` (1 MiB by default,
`CICADEL_MAX_BODY_BYTES`). Raise the cap for one route, such as an upload, and
keep the small default everywhere else.

## Upload routes raise their own limit

`forms/upload` uses the upload's `Config.MaxBytes` as the request's limit. No
other change is needed:

```go
upload.Middleware(func(*http.Request) (upload.Config, error) {
    return upload.Config{
        MaxBytes: 12 << 20, // a 10 MB file plus the form around it
        Fields:   []upload.Field{{Name: "slip", MaxBytes: 10 << 20}},
    }, nil
})
```

Each field keeps its own `Field.MaxBytes`.

## Other routes: `bodylimit.Limit`

Wrap a route handler, or add the middleware to `App.Middleware` for every route
of an app:

```go
urls.Route{
    Method:  "POST",
    Path:    "/imports",
    Name:    "imports:create",
    Handler: bodylimit.Limit(50 << 20)(http.HandlerFunc(createImport)),
}
```

`Limit` can raise or lower the default. Inside a handler, call
`bodylimit.Set(w, r, n)` instead.

## Rules

- A limit can change only before the body is first read. After that, `Set`
  returns `bodylimit.ErrBodyRead` and `Limit` answers 500, because the route's
  limit could not be applied.
- Reading past the limit fails with `*http.MaxBytesError`, and the server closes
  the connection after the response. Answer with 413 or a form error.
- CSRF middleware parses URL-encoded forms, so its reads count against the
  route's limit. Multipart bodies are not read by CSRF.
- `contrib/accounts` no longer caps every route under `Browser.Middleware` at
  8 KiB. The account pages keep their own 8 KiB bound.
- Handlers served outside a `cicadel.Application` have no adjustable limit.
  `Set` then wraps the body with `http.MaxBytesReader`, which can only lower an
  existing limit. Call `bodylimit.Apply` to install one.

Keep `MaxBodyBytes` small. Every form and JSON endpoint accepts that much
without asking.


---

Source: `docs/security-headers.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/security-headers/index.md

# Secure headers and HTTPS

Cicadel adds security headers to every response and enforces an HTTPS policy you
control from settings. If you know Django, this is the job of its
`SecurityMiddleware`.

Generated projects start with secure values. `go run manage.go check --deploy`
warns about anything left off.

## Ask your agent

> Configure HSTS, the HTTPS redirect, trusted proxies and the content security
> policy for my Cicadel project, then make `check --deploy` pass without warnings.

## What every response gets

| Header | Value | Controlled by |
| --- | --- | --- |
| `X-Content-Type-Options` | `nosniff` | always |
| `Referrer-Policy` | `same-origin` | always |
| `X-Frame-Options` | `DENY` | always |
| `Content-Security-Policy` | your policy | `ContentSecurityPolicy` |
| `Strict-Transport-Security` | `max-age=N` on HTTPS responses | `HSTSSeconds`, never in debug |

A handler can set its own `Content-Security-Policy`. It replaces the default for
that response. The account pages do this with a stricter policy.

## Settings

Generated projects set these in `project/settings/settings.go`:

```go
s := settings.Defaults()
s.HSTSSeconds = settings.HSTSYear
s.ContentSecurityPolicy = settings.DefaultContentSecurityPolicy
return settings.Load(s)
```

| Field | Environment variable | Default | Purpose |
| --- | --- | --- | --- |
| `HSTSSeconds` | `CICADEL_HSTS_SECONDS` | 0 (generated: one year) | Tell browsers to use HTTPS only. Sent only on HTTPS responses with debug off. |
| `SecureRedirect` | `CICADEL_SECURE_REDIRECT` | false | Redirect plain-HTTP requests to HTTPS with `308`, after the host check, debug off only. |
| `TrustedProxies` | `CICADEL_TRUSTED_PROXIES` | none | Comma-separated IPs or CIDR prefixes of your reverse proxies. |
| `ContentSecurityPolicy` | `CICADEL_CONTENT_SECURITY_POLICY` | empty (generated: default policy) | Policy for responses that set none. Empty sends no header. |

> [!WARNING]
> HSTS is hard to undo. Browsers remember it for `max-age` seconds. If you are not
> sure your whole domain serves HTTPS, start with a short value such as 300.
> Cicadel never adds `includeSubDomains` or `preload`.

## Content security policy

`settings.DefaultContentSecurityPolicy` is:

```text
default-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'
```

- It allows scripts, styles, images, fonts and requests from your own origin only.
- That fits the starter pages, Tailwind output and self-hosted htmx.
- Inline `<script>` and `style="…"` attributes are blocked.

If your static files come from a CDN (`CICADEL_STATIC_URL=https://cdn.example.net/…`),
add its origin, for example `default-src 'self' https://cdn.example.net; …`.
`check --deploy` warns when it is missing.

## Behind a reverse proxy

Most deployments terminate TLS at a proxy or load balancer. Cicadel learns that a
request used HTTPS, and the real client address, only from proxies listed in
`TrustedProxies`:

```sh
CICADEL_TRUSTED_PROXIES=10.0.0.0/8
```

For a request whose direct peer is trusted:

- `X-Forwarded-Proto: https` (last value) marks it as HTTPS. HSTS is sent and
  `SecureRedirect` does not redirect it.
- `r.RemoteAddr` becomes the rightmost `X-Forwarded-For` entry that is not itself
  a trusted proxy. Clients cannot spoof it by prepending values.

Requests from any other peer keep their real address, and their forwarded headers
are ignored.

> [!NOTE]
> `Forwarded` and `X-Forwarded-Host` are never used. The host check always applies
> to the request's own `Host`.

Check the scheme in handlers with `security.IsHTTPS(r)`.

## Existing projects

Projects generated before v0.2.1 keep their behavior. To upgrade:

1. Add the two settings lines above to `project/settings/settings.go`.
2. Set `CICADEL_TRUSTED_PROXIES`.
3. In production, set `CICADEL_SECURE_REDIRECT=true`, unless your proxy already
   redirects HTTP.
4. Run `go run manage.go check --deploy`.


---

Source: `docs/signing.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/signing/index.md

# Signed tokens

The `signing` package issues tokens that cannot be forged or altered. They expire
after an age you choose and survive secret-key rotation.

Use them when you need to know that your application created a value, and when:

- links in emails: confirm an address, accept an invitation, unsubscribe;
- values you hand to the browser and read back.

> [!WARNING]
> Tokens are **signed, not encrypted**. Anyone holding a token can decode its
> payload. Put identifiers in tokens, never passwords or other secrets.

## Ask your agent

> Add an email-confirmation link to my Cicadel project using the `signing`
> package: a purpose-specific signer, a typed JSON payload and a 48-hour expiry.
> Configure `CICADEL_SECRET_KEY` and make `check --deploy` pass.

## Configure the secret key

Generate a key and supply it through your deployment's secret configuration:

```sh
go tool cicadel secretkey       # prints a new 43-character random key
export CICADEL_SECRET_KEY=...   # never commit it
```

| Field | Environment variable | Purpose |
| --- | --- | --- |
| `SecretKey` | `CICADEL_SECRET_KEY` | Signs new tokens. At least 32 bytes. Empty disables signing. |
| `SecretKeyFallbacks` | `CICADEL_SECRET_KEY_FALLBACKS` | Comma-separated previous keys that still verify tokens. At most 8. |

- Settings validation rejects short keys, fallbacks without a current key and
  repeated keys. It never prints them.
- `go run manage.go check --deploy` warns (`settings:secret_key`) when no key is set.
- `apptest.Settings()` uses the fixed `apptest.TestSecretKey`, so tests can sign
  tokens without configuration.

## Sign and verify in a handler

Each kind of token has a **purpose**: a stable printable name such as
`"accounts.confirm-email"`. A token signed for one purpose never verifies for
another, even under the same secret key.

```go
type confirmation struct {
	UserID int64  `json:"user_id"`
	Email  string `json:"email"`
}

func sendConfirmation(w http.ResponseWriter, r *http.Request) {
	s, err := signing.For(r.Context(), "accounts.confirm-email")
	if err != nil {
		response.Error(w, 500) // signing.ErrNoKey: CICADEL_SECRET_KEY is missing
		return
	}
	token, err := signing.SignJSON(s, confirmation{UserID: user.ID, Email: user.Email})
	if err != nil {
		response.Error(w, 500)
		return
	}
	link := "https://example.com/confirm?token=" + token // URL-safe; no escaping needed
	// email the link
}

func confirm(w http.ResponseWriter, r *http.Request) {
	s, err := signing.For(r.Context(), "accounts.confirm-email")
	if err != nil {
		response.Error(w, 500)
		return
	}
	c, err := signing.VerifyJSON[confirmation](s, r.URL.Query().Get("token"), 48*time.Hour)
	switch {
	case errors.Is(err, signing.ErrExpired):
		// genuine but too old: offer to send a new link
	case err != nil:
		response.Error(w, 400) // forged, altered, wrong purpose or retired key
		return
	}
	// c.UserID and c.Email are exactly what you signed
}
```

The application puts its keyring on every request's context, so `signing.For`
works in any handler. Outside a request, such as a management command or a
background job, use `app.Signer(purpose)`. Both use the same keys, so a token
issued in a job verifies in a handler.

## API

| API | Use |
| --- | --- |
| `s.Sign(payload []byte)` / `s.Verify(token, maxAge)` | Raw bytes, at most `signing.MaxPayload` (8 KiB). |
| `signing.SignJSON(s, v)` / `signing.VerifyJSON[T](s, token, maxAge)` | Typed payloads. Unknown fields are rejected, so changing `T` invalidates older tokens. |
| `s.VerifyNoExpiry(token)` / `signing.VerifyJSONNoExpiry[T]` | Tokens that deliberately never expire, such as unsubscribe links. |
| `s.Issued(token)` | When a genuine token was signed. |
| `s.WithClock(now)` | A copy reading time from `now`, for tests. |

Verification rules:

- `Verify` requires a positive `maxAge`. Zero is a programming error, not "no expiry".
- `errors.Is(err, signing.ErrInvalid)` is true for every rejected token, including
  expired ones. Test `signing.ErrExpired` first to treat expiry differently.
- A token whose issue time is more than `signing.ClockSkew` (one minute) in the
  future is rejected.

### Single-use tokens

A signature proves who issued a token. It does not prove the token is unused.

To make a token single-use, include state that the action changes. Compare it on
verification. Good choices are a hash of the current email address or of the
password hash.

For example, a password-reset token that carries a hash of the stored password
hash stops working once the password changes. Never put the raw secret in the token.

## Rotate the secret key

1. Generate a new key. Deploy it as `CICADEL_SECRET_KEY` and move the old key to
   `CICADEL_SECRET_KEY_FALLBACKS`. New tokens use the new key. Existing tokens
   still verify.
2. Wait for the longest `maxAge` your application uses.
3. Remove the old key from `CICADEL_SECRET_KEY_FALLBACKS`. Tokens signed with it
   now fail with `signing.ErrInvalid`.

> [!WARNING]
> If a key leaks, skip the wait. Deploy a new key without the leaked one as a
> fallback. Every token signed with it, including `VerifyNoExpiry` tokens,
> becomes invalid immediately.

## How it works

The token format is `base64url(payload) "." base36(unix seconds) "." base64url(MAC)`.

- The MAC is HMAC-SHA256 over the first two parts.
- It uses a per-purpose key derived as HMAC-SHA256(secret key,
  `"cicadel-signing-v1\x00" + purpose`).
- Verification compares MACs in constant time against the current key and each
  fallback.
- Only the URL-safe base64 alphabet is accepted, so every token has exactly one
  encoding.
- The payload is decoded only after the MAC matches.
- Input longer than a maximum-size token is rejected before any work.

Tests that cover this:

- `signing/signing_test.go`: tampering at every position, purpose and key
  separation, expiry boundaries, clock skew, rotation, key validation, JSON
  strictness, concurrency and the `FuzzVerify` fuzz target.
- `signing_test.go`: request-context signing, rotation across deployments and
  settings validation through a running application.
- `internal/scaffold/signing_test.go`: a generated project loading keys from the
  environment.


---

Source: `docs/static-files.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md

# Static files

Every app publishes its public CSS, images, fonts and scripts through
`App.Static`. Cicadel serves each file under the app's namespace with a
cache-busting URL, and can collect the files for a CDN or reverse proxy.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md.
Publish [files] from [app] through App.Static. Resolve each URL in the handler
with static.URL and pass it to the component as a typed prop. Do not add a
route for static files. Run the app tests and go run manage.go collectstatic.
```

## Publish an app's files

Embed a directory and pass it as `App.Static`:

```go
//go:embed all:static
var public embed.FS

func New() cicadel.App {
    files, err := fs.Sub(public, "static")
    if err != nil {
        panic(err)
    }
    return cicadel.App{Name: "notes", Routes: URLs(), Static: files}
}
```

Generated code already does this:

- `startapp` generates this layout with an empty `static/` directory.
- The starter project publishes `project/static/` as the `project` app.
- The accounts package publishes its stylesheet as the `accounts` app.

## How files are served

A file `static/css/notes.css` in the `notes` app is available at two URLs:

| URL | Caching |
| :--- | :--- |
| `/static/notes/css/notes.3f1c9a2b7d4e.css` | `public, max-age=31536000, immutable` |
| `/static/notes/css/notes.css` | `no-cache` with a strong content `ETag` |

- **Hashed name.** The 12 characters are the start of the file's SHA-256 digest.
  The URL changes whenever the content changes.
- **App prefix.** Two apps can never publish the same path. A project cannot
  silently replace a package's file.

### What is not published

- Files and directories starting with `.` are never published.
- `App.Resources` stays private. Nothing in it is served.
- Symbolic links, duplicate app names, and an authored file whose name equals
  another file's hashed name are construction errors.

## Link to a file

Resolve URLs in the handler and pass them to components as typed props:

```go
func Index(w http.ResponseWriter, r *http.Request) {
    stylesheet, err := static.URL(r.Context(), "notes", "css/notes.css")
    if err != nil {
        response.Error(w, http.StatusInternalServerError)
        return
    }
    page := layout.Page.Call(layout.Props{Title: "Notes", Stylesheet: stylesheet},
        layout.Slots{Children: ui.Text("Notes")})
    if err := (ui.Renderer{}).HTML(r.Context(), w, http.StatusOK, page); err != nil && !ui.Committed(err) {
        response.Error(w, http.StatusInternalServerError)
    }
}
```

`static.URL` fails for an unpublished file instead of producing a broken link.

The application puts its manifest in every request context. Outside a request, use
`app.Static().URL("notes", "css/notes.css")`. Tests use the same method to find
the URL to fetch.

## Configure the URL

`settings.StaticURL` (environment: `CICADEL_STATIC_URL`) defaults to `/static/`.
It must end in `/` and must not contain a query or fragment.

| Value | Behavior |
| :--- | :--- |
| Local path, such as `/static/` or `/assets/v2/` | The application serves the files. Requests under the prefix are answered after host validation and the standard security headers, but before global middleware. |
| Absolute URL, such as `https://cdn.example.com/static/` | URLs point at that origin, and the application does not serve them. Upload `collectstatic` output there. Production requires `https`; `http` is accepted only with debug on. |

> [!WARNING]
> With a local path, registering a route under the prefix is a startup error
> while any app publishes files.

## Collect files for a CDN or proxy

```sh
go run manage.go collectstatic public
```

`collectstatic` runs offline. It does not open PostgreSQL or start app services.

- It writes each authored and hashed file under `public/<app>/`.
- It writes `public/manifest.json`, mapping `app/path` to the hashed path.
- It writes files atomically.
- It keeps earlier hashed files, so pages from the previous release keep working
  during a rolling deployment. Delete old ones yourself when no deployed release
  references them.
- If a hashed path already exists with different bytes, it stops with an error.

Serve the hashed files with a long immutable cache lifetime and the authored
names with revalidation, matching the table above.

## Limits

- Source filesystems must not change while the application runs. Embedded files
  are the supported source. The development server restarts after rebuilding CSS,
  which recomputes hashes.
- References inside a file are not rewritten. A stylesheet's relative
  `url(font.woff2)` resolves to the authored name. That name is served with
  revalidation, not an immutable lifetime.
- Precompressed variants, `findstatic` and source maps are not generated.
- The bundled htmx runtime is still served from its own versioned path. See
  [interactive behavior](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md).


---

Source: `docs/tailwind.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md

# Tailwind CSS

Tailwind CSS is Cicadel's default way to style components. New projects come with
Tailwind v4 input, compiled CSS and a static route that serves it.

The server runs no Tailwind or Node process and needs no CDN. You can still use
another CSS system: see [Use another stylesheet system](#use-another-stylesheet-system).

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/howto/tailwind/index.md.
Style [component] using this application's existing Tailwind setup.
Use complete utility classes, keep labels and focus states accessible,
and run the matching Cicadel ui build and ui check commands.
```

## The authoring loop

In a generated project, after `go mod tidy`:

```sh
# Once per development/CI machine; explicit network download.
go tool cicadel ui css install

# After editing .templ, Go class variants, or CSS input.
go tool cicadel ui build
go tool cicadel ui check --json
go test -race ./...
go build -trimpath -o bin/server .
```

In the framework checkout, use `go run ./cmd/cicadel` in place of `go tool cicadel`.

The starter ships with real compiler-generated CSS. Its first run works without
downloading any CSS tool. Tests that compile CSS need the installed compiler,
including the framework's scaffold and docs tests. CI installs it first.

## Which toolchain

The toolchain pins Tailwind **v4.3.3**. Cicadel uses the upstream
[standalone CLI](https://tailwindcss.com/docs/installation/tailwind-cli).

It does not use npm, PostCSS, a custom CSS compiler or a browser-time Tailwind script.

## Commands

| Command | What it does |
| --- | --- |
| `ui css install` | Downloads the pinned executable, verifies its SHA256 and installs it in the OS user cache. A valid installation is not downloaded again. |
| `ui build` | Generates `.templ` Go, then builds CSS if `ui.css.json` exists. |
| `ui generate` | Generates markup only. Use it for component-only libraries. |
| `ui css build` | Builds and minifies CSS only. Replaces the output atomically after success. |
| `ui check --json` | Checks markup and configured CSS freshness, then compiles Go and tests without running them. |
| `ui css check` | Recompiles CSS and compares it, without changing the committed output. |

What the commands never do:

- `build` and `check` never download the Tailwind executable or add a Go dependency.
- Package resolution uses read-only `go list`.
- `check` uses temporary files and caches. It leaves generated source and CSS unchanged.

Go and CSS toolchains still need their normal local caches. Install Go dependencies
with Go tooling before an offline build.

### Errors

| Problem | Diagnostic |
| --- | --- |
| Compiler not installed | `UI_CSS_TOOL` |
| Output is stale | `UI_CSS_STALE` |

Every failed command exits nonzero. Use the top-level `ui check --json` for machine
diagnostics. The `ui css ...` commands print human-readable errors.

## Configuration: ui.css.json

A generated project has this `ui.css.json`:

```json
{
  "version": "v4.3.3",
  "input": "project/styles/input.css",
  "output": "project/static/app.css",
  "packages": []
}
```

- Paths are relative to the project or module directory where you run the command.
- `input` and `output` must be different local `.css` paths.
- Unknown fields, unsupported versions and invalid paths fail with an error.
- Commands do not search parent directories.
- The framework's pinned version and the config version must match. Upgrading
  Tailwind is a reviewed framework and toolchain upgrade, never an implicit `latest` fetch.

## The input file

`project/styles/input.css` imports Tailwind with automatic detection turned off. It
lists the project's `.templ` and ordinary Go source patterns explicitly.

- Generated `*_templ.go` files and tests are excluded. Stale generated classes and
  test payloads cannot leak into your CSS.
- Source paths are relative to the input file, not your current directory.

See upstream [source detection](https://tailwindcss.com/docs/detecting-classes-in-source-files).

### Customize the theme

Tailwind v4 is configured in CSS. Add theme values to the input file:

```css
@theme {
  --color-brand-600: #4f46e5;
}
```

Then write `class="bg-brand-600 text-white"` in `.templ`.

- Keep the existing `@import` and `@source` declarations.
- Local CSS imports resolve relative to the input file.
- Do not use v3 `@tailwind base` directives. A `tailwind.config.js` is not loaded automatically.
- The standalone build does not promise to bundle arbitrary npm plugins. Those need
  their own explicitly maintained build integration.
- CSS is trusted authored source, never request input.

## Classes and variants

Write complete utilities with responsive and state variants:

```templ
<button class="rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700 focus-visible:outline-2 sm:px-6">
    Save
</button>
```

Tailwind scans text. It does not run Go. So for dynamic variants, choose between
complete literal strings in Go. Never build utility names from values such as
`"bg-" + color + "-600"`.

For a finite set of classes that cannot appear literally in scanned source, add an
explicit CSS `@source inline(...)` declaration. Never safelist an unbounded set
derived from user input.

> [!NOTE]
> `ui.Merge` combines distinct class tokens. It is not tailwind-merge and does not
> decide which conflicting utility wins. The generated CSS cascade does. Prefer a
> typed variant that picks one spacing or color utility per state.

## Classes from installed packages

You register an app through Go imports and manifests as usual. Its classes are a
separate step: add the **exact Go import path** of each package that contains
Tailwind classes to `packages`.

```json
{
  "version": "v4.3.3",
  "input": "project/styles/input.css",
  "output": "project/static/app.css",
  "packages": ["example.com/your-library/cards"]
}
```

That path is an example. For each entry, Cicadel:

1. Resolves the path through the host's selected Go module graph.
2. Adds that directory as an explicit Tailwind source for the build.

- This works with installed module-cache sources and local replacements.
- No path into one user's module cache is committed.
- Scans include subdirectories, so point at the narrow component package.
- `packages` does not install modules, activate apps or grant permissions.
- A missing package fails with `UI_CSS_PACKAGE`. Install it with normal Go tooling first.

Library releases must include their class-bearing source or literal candidates.
Tailwind cannot find utilities hidden in runtime-only data. Library authors are
responsible for sensible source directory contents and dependency declarations.

## Serve the CSS

The starter publishes `project/static/` as the `project` app's `App.Static` files.

1. The home handler resolves `app.css` to its content-hashed URL with
   `static.URL(r.Context(), "project", "app.css")`.
2. It passes the URL to `layout.Page` through the optional `Props.Stylesheet`.
3. `layout.Page` emits a contextually escaped `<link rel="stylesheet">`.

See [static files](https://cicadel.fauzaanu.com/en/0.2.7/howto/static-files/index.md) for caching and CDN collection.

The renderer and layout never insert CSS into other applications on their own.
Existing pages keep their current stylesheet.

## Production

- Commit CSS input, config and generated CSS together with the generated component Go.
- Run `ui check` before the production build.
- After UI changes, run `ui build`, then restart or rebuild the Go server to refresh embedded assets.
- There is no HMR or watch server, and no CSS compilation at runtime in production.
- To serve the CSS from a CDN, set `CICADEL_STATIC_URL` and upload the output of
  `go run manage.go collectstatic DIR`.

Tailwind v4 targets modern browsers. Use the upstream
[compatibility guidance](https://tailwindcss.com/docs/compatibility) to choose browser
support. This integration verifies generated CSS and its HTTP delivery, not
pixel-identical rendering across browser engines.

## Use another stylesheet system

1. Remove `ui.css.json`.
2. Replace `project/static/app.css` with your own stylesheet or build output.
3. Keep or change the explicit stylesheet link.

`ui build` and `ui check` then handle markup only. Do not leave a Tailwind config
pointing at output that a different compiler maintains.

## Add Tailwind to an existing project

1. Add `ui.css.json`.
2. Add an input file that imports Tailwind with explicit source directories.
3. Choose an output location owned by your static pipeline.
4. Add the stylesheet link.
5. Install the tool, then run `ui build` and `ui check`.
6. Verify that the asset route serves the CSS.

Upgrading Cicadel does not restyle existing apps.


---

Source: `docs/testing.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/topics/testing/index.md

# Testing applications and installable apps

Cicadel tests are ordinary Go tests in `*_test.go` files. The `apptest` package
removes setup repetition without bypassing your application's security or lifecycle.

There is no second test language and no hidden registry. Dependencies are explicit.
The same tests work with `go test`, editors, race detection, coverage, fuzzing and
AI coding agents. The PostgreSQL fixture lives in
`github.com/fauzaanu/cicadel/apptest/postgres`.

## Ask your agent

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/topics/testing/index.md.
Add application tests for [feature] using the matching Cicadel apptest API.
Exercise real routes, validation, permissions and CSRF. Use an isolated
PostgreSQL fixture for database behavior. Run the tests and report any skips.
```

## Write your first test

```go
func TestIndex(t *testing.T) {
    t.Parallel()
    app := apptest.New(t, apptest.Settings(), []cicadel.App{notes.New()})
    client := apptest.NewClient(app)
    client.Get(t, "/notes/").Status(t, 200).JSON(t, `{"app":"notes"}`)
}
```

- `apptest.Settings()` returns fresh settings that ignore the environment. The
  allowed host is `testserver` and secure cookies are on. Change the returned
  value before you build the app to test other configurations.
- `apptest.New` registers cleanup before startup. It runs the real application
  startup and checks, and uses the test's context for its lifetime. It closes the
  app with a separate, bounded context.
- Build fresh app factories and dependencies in every test.
- `apptest.Check` is the two-instance lifecycle smoke test for installable app authors.

## Run, discover and diagnose

Run these from a project directory with the matching `cicadel` CLI installed:

```sh
go test -list . ./...
cicadel test --report test-results.json -- -race -coverprofile=coverage.out ./...
cicadel test --strict --require-integration --report test-results.json -- -race ./...
cicadel test -- -json ./... > test-events.jsonl
go test -count=1 -run '^TestArticle$/^other_author$' ./apps/articles
go tool cover -func=coverage.out
```

Install the project's matching CLI with
`go install github.com/fauzaanu/cicadel/cmd/cicadel@VERSION`. Inside the framework
repository, use `go run ./cmd/cicadel test ...` instead.

How `cicadel test` behaves:

- Framework flags go before `--`. Go flags go after it.
- It defaults to `-count=1 -timeout=2m` and `./...`. Your own Go flags can
  override the count and timeout.
- It streams output and exits with a failure status on build or test failures.
- It atomically replaces the JSON report, even when tests fail. The report
  directory must already exist.

### The JSON report

| Field | Contents |
| --- | --- |
| `version` | `1`, the report schema version |
| `tests` | Outcomes of named tests and subtests |
| `packages` | Package outcomes |
| `skipped` | Count of named skips |

Parent tests and subtests each get a record. So the count is not a count of
independent scenarios. Keep the JSON events too when you need detailed failure logs.

> [!WARNING]
> Test output can contain the payloads you supply. Use synthetic data and treat
> reports and logs accordingly.

### Strict mode and integration

- `--strict` fails if any named test skips or if no named tests run. Use it for
  verification, not for `-list` or benchmark-only runs.
- `--require-integration` sets `CICADEL_TEST_REQUIRE_INTEGRATION=1`. Helpers that
  use `apptest.RequireEnv` then fail instead of skipping when a prerequisite is missing.
- Strict mode also catches ordinary `t.Skip` calls in application tests.

A missing database must never count as verified integration coverage.

### Nested modules and fuzzing

Like `go test`, `./...` covers only the current module. Run the command separately
in each nested module, including `contrib/migrations`. Go fuzzing usually targets
one package and one fuzz target. Use the standard Go flags for that.

## HTTP clients

Each `apptest.NewClient` has its own cookie jar. Requests run in process through
your handler at `https://testserver`. There is no listener and no network access.

```go
alice, bob := apptest.NewClient(app), apptest.NewClient(app)
alice.PostForm(t, "/login", url.Values{
    "username": {"alice"}, "password": {"test password"},
    "csrf_token": {tokenObtainedFromLoginPage},
}).Redirect(t, http.StatusSeeOther, "/")
bob.Get(t, "/private/").Status(t, http.StatusUnauthorized)
alice.JSON(t, "POST", "/api/notes", map[string]string{"title":"hello"}).Status(t, 201)
```

- Nothing is disabled. Authentication, CSRF, request limits, host checks and
  middleware all run.
- Redirects stay responses, so you can assert the status and location.
- Cookies respect path, domain, expiry and the secure flag.
- You can set an explicit request host to test host validation. Other URL
  origins are rejected.

### Requests and assertions

| API | What it does |
| --- | --- |
| `Request(t, method, path, body, headers)` | Any method, headers or multipart form. Buffers at most 4 MiB and closes the body. |
| `Response.HTTP` | The headers and status. |
| `Response.Body` | The body as reusable bytes. |
| `Status`, `Header`, `Contains`, `Redirect`, `JSON` | Assertions that report failures at the caller. |
| `DecodeJSON` | Decodes into a typed value and rejects trailing values. |

JSON assertions ignore whitespace and object key order. Array order and number
spelling still matter: `1` differs from `1.0`. Numbers lose no float64 precision.

### Lower-level requests

`Client.Do` takes a standard `*http.Request`. Use it for cancellation, an explicit
host or large bodies. You must close the response body.

The in-process client does not emulate a browser, TLS negotiation, streaming,
network timeouts or wire-level behavior such as HEAD body suppression. Browser
cookie policies such as SameSite are also out of scope. Use Go's
`httptest.NewServer` or `NewTLSServer` for those transport tests.

## PostgreSQL isolation and query budgets

Set `CICADEL_TEST_DATABASE_URL` to a **dedicated test PostgreSQL server**. Its role
needs `CREATEDB`.

> [!WARNING]
> This is an administrator connection, not an application database for the fixture
> to truncate. The fixture creates a random database from `template0` and drops
> only that database at cleanup.

The fixture needs PostgreSQL 13+ for forced cleanup. It never falls back to
`DATABASE_URL`. It never syncs a schema or runs migrations for you.

```go
func TestCreateArticle(t *testing.T) {
    t.Parallel()
    fixture := postgres.New(t)
    // Apply the application's real migrations explicitly using fixture.SQL/URL.
    // Seed typed fixtures after migration, checking every returned error.
    db, queries := postgres.Capture(fixture.DB)
    s := apptest.Settings()
    s.DatabaseURL = fixture.URL
    app := apptest.New(t, s, []cicadel.App{articles.New(db)})
    client := apptest.NewClient(app)
    queries.Reset() // exclude startup/setup from the request budget
    client.Get(t, "/articles/").Status(t, 200)
    queries.AssertMax(t, 3)
}
```

### Order and cleanup

1. Create the database fixture first.
2. Then create the app, client and server resources.
3. Give every extra connection `fixture.URL`: session stores, workers and migrations.

Go runs cleanup in reverse registration order. So workers and application pools
close before the fixture drops the database.

- Do not share database fixtures between parallel tests.
- Cleanup failures fail the test.
- Killing the process can prevent cleanup. Disposable CI servers are still a good fit.

### Transactions

`postgres.Transaction(t, db)` starts a transaction and rolls it back at cleanup.
Inject that transaction into every code path under test. Do not commit it.

Connections opened elsewhere cannot see uncommitted fixtures. Use a fresh database
for tests that involve commits, concurrent connections, constraints or workers.

### Query budgets

`postgres.Capture(db)` returns a private GORM session and a concurrency-safe query
recorder. It does not change the original session's logger. Inject the returned session.

- `Snapshot`, `Reset`, `AssertCount` and `AssertMax` support exact counts and budgets.
- Failed statements count.
- SQL text and arguments are not kept.
- Wait for background work before you assert or reset.

The recorder is a GORM query budget, not a global SQL audit. It does not see raw
`database/sql` calls, other sessions or transaction control statements.

## Fixtures and side effects

Keep domain fixture functions in `_test.go` files. Give them typed inputs and
explicit defaults, and return the objects they create. Use fresh dependencies per
test and `t.Cleanup`. Avoid global settings, global registries and environment
changes in parallel tests.

Framework components already expose side effects you can assert:

| Side effect | How to test it |
| --- | --- |
| Email | Inject `mail.Capture` as the mail transport and assert `Messages()`. |
| File storage | Inject `storage.NewLocal(t.TempDir(), limit)` and register its `Close` with cleanup. |
| Cache | Create a fresh `cache.NewMemory` per test. Its contents are not shared. |
| Management commands | Give `management.Manager.Output` a `bytes.Buffer`, run `Manager.Run(t.Context(), args)`, then assert errors, output and saved state. |
| River workers | Test worker logic with explicit dependencies. Use a fresh PostgreSQL fixture for transactional enqueue, rollback and real worker integration. |

There is no implicit privileged login and no automatic CSRF bypass. Test
unauthorized, forbidden, invalid-input and cross-user cases next to the successful
ones. Check what was actually saved and sent, not only the HTTP status.

## Workflow for AI agents

Generated projects, apps and installable packages include starter tests that run.
Projects and packages also include `TESTING.md`. An agent should:

1. Find existing tests and public APIs. Identify the behavior and the failure mode.
2. Add a minimal regression test. Run it against the broken behavior to prove it fails.
3. Make the change. Rerun the targeted test, then the package tests.
4. Run the full suite with race detection, real integration prerequisites and strict
   reporting. Inspect failed **and skipped** outcomes. Run each nested module separately.
5. Check coverage for missed behavior. Add boundary, authorization, rollback and
   failure-path cases. A coverage percentage alone does not prove correctness.
6. Report the exact commands and limits. Never weaken assertions, disable security,
   auto-accept snapshots or use mocks in place of a claimed database integration check.

Use deterministic values and synchronization instead of sleeps. Fuzz parsers,
normalizers, routing and validation with standard Go fuzz targets. Keep failing
inputs in Go's corpus.

These tools help agents write reliable tests. They do not guarantee that generated
tests are complete or correct.

## Components

With the default CSS workflow, install the pinned Tailwind CLI once with
`go tool cicadel ui css install`. Then, in generated projects:

```sh
go tool cicadel ui build
go tool cicadel ui check --json
```

- The source check runs offline. It compiles tests without running them.
- `manage.go check` separately validates the registered libraries and assets.
- Test component behavior with `apptest` HTTP assertions and ordinary Go tests.
- For focused checks, render with `(ui.Renderer{}).Render(t.Context(), content)`.

You need no separate component test language or snapshot tool. See
[the component authoring loop](https://cicadel.fauzaanu.com/en/0.2.7/topics/component-ui/index.md#exact-authoring-and-verification-loop)
and [recorded verification](https://cicadel.fauzaanu.com/en/0.2.7/sources/docs/component-verification.md).

### In the framework repository

- Run the independent `examples/component-library` module separately. Its
  generated-consumer test installs real versioned modules outside the checkout and
  checks explicit overrides and compiled operation, without browser automation.
- The Tailwind and scaffold documentation tests need the installed Tailwind tool.
  Run `go run ./cmd/cicadel ui css install` before the root suite. Tests never
  download it for you.
- `TestComponentAuthoringGuide` extracts the guide's file-marked code blocks into a
  fresh starter. It generates markup and CSS, type-checks, and runs the HTTP,
  escaping and contract tests under the race detector.
- `TestStarterTailwind` checks that the shipped stylesheet is real, up-to-date
  compiler output.

## Accounts, mail and logging

Run `contrib/accounts` as its own module:

1. `ui build` and `ui check --json`.
2. `go test -race ./...` with `CICADEL_TEST_DATABASE_URL` set to the disposable
   PostgreSQL server.
3. `sh verify-host.sh`.
4. Vet, build and vulnerability scanning.

The exact commands are in `.github/workflows/accounts.yml`.

The root scaffold suite tests `startproject` in a separate module. It needs the
same integration prerequisites.

No test delivers external email. SMTP tests use isolated loopback servers and test
certificates. Logging alerts use an in-memory outbox.


---

Source: `docs/transactions.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/howto/transactions/index.md

# Transactions and post-commit hooks

`database.Atomic` runs related writes in one PostgreSQL transaction, like Django's
`transaction.atomic`. `database.OnCommit` schedules work that must happen only after
those writes commit, like Django's `transaction.on_commit`.

Use `OnCommit` for sending an email, enqueueing a job on another system or
invalidating a cache. A rolled-back transaction never sends the email.

## Ask your agent

```text
In my Cicadel project, send a welcome email after a new member is saved. Use
the model form's `AfterSave` hook to register a `database.OnCommit` callback,
so the email goes out only after the transaction commits. Add a PostgreSQL
test showing that a rejected save sends nothing.
```

## Run writes atomically

```go
err := database.Atomic(r.Context(), db, func(tx *gorm.DB) error {
	if err := tx.Create(&order).Error; err != nil {
		return err
	}
	return tx.Model(&stock).Where("id = ?", order.ItemID).
		Update("count", gorm.Expr("count - 1")).Error
})
```

`database.Atomic(ctx, db, fn)` begins a transaction and passes it to `fn`.

- When `fn` returns nil, it commits.
- When `fn` returns an error or panics, everything rolls back. The error or panic
  propagates unchanged.
- Use the supplied `tx` for every query.

It wraps GORM's `db.Transaction`. It accepts the same optional `*sql.TxOptions`,
for example `&sql.TxOptions{Isolation: sql.LevelSerializable}`.

### Nested calls are savepoints

Pass a `tx` from an enclosing `Atomic`, and `Atomic` creates a savepoint instead of
a new transaction. If the inner function fails, only its writes roll back. The
outer function decides what to do with the error:

```go
err := database.Atomic(ctx, db, func(tx *gorm.DB) error {
	tx.Create(&invoice)
	if err := database.Atomic(ctx, tx, func(tx *gorm.DB) error {
		return tx.Create(&optionalDiscount).Error
	}); err != nil {
		log.Printf("discount skipped: %v", err) // invoice still commits
	}
	return nil
})
```

## Run code after commit

Register a hook inside the transaction:

```go
err := database.Atomic(ctx, db, func(tx *gorm.DB) error {
	if err := tx.Create(&member).Error; err != nil {
		return err
	}
	return database.OnCommit(tx, func(ctx context.Context) error {
		return sender.Send(ctx, welcomeMessage(member.Email))
	})
})
```

### Hooks in model forms

These saves already run through `database.Atomic`:

- model form saves (`Bound.Create` and `Update`),
- administration saves,
- formset saves (from v0.2.4),
- account service operations in `contrib/accounts`.

So a model-form hook can register directly:

```go
form, err := model.New[Member](db, model.Config[Member]{
	Fields: []model.Field{{Name: "Email", Required: true}},
	AfterSave: func(ctx context.Context, tx *gorm.DB, m *Member) error {
		to := m.Email
		return database.OnCommit(tx, func(ctx context.Context) error {
			return sender.Send(ctx, welcomeMessage(to))
		})
	},
})
```

Copy the values a hook needs, as above. Do not capture models that later code may
change.

In a formset `Save`, hooks run after the whole formset commits. They are dropped
if any row fails.

## Semantics

| Situation | Behavior |
| --- | --- |
| Outermost transaction commits | Hooks run in registration order, after commit and before `Atomic` returns. |
| `fn` returns an error, panics, or the commit fails | No hook runs; every hook registered in the transaction is discarded. |
| A savepoint (nested `Atomic`) fails | Hooks registered in it, and in savepoints inside it, are discarded. Hooks registered before or after it in the enclosing transaction survive. |
| A savepoint succeeds | Its hooks join the enclosing transaction and run only when the outermost transaction commits. |
| `OnCommit` outside an `Atomic` transaction | Returns `database.ErrNoTransaction`; the hook is never run. This includes transactions from `db.Begin`, a raw `db.Transaction` and `apptest/postgres.Transaction`, whose commit Cicadel cannot observe. |
| A hook returns an error or panics | The commit stands. The failure (with the panic's stack) is logged with `slog.Default()` at error level, later hooks still run and `Atomic` returns nil. |
| `ctx` is cancelled before commit | PostgreSQL rolls the transaction back; `Atomic` returns the error and no hook runs. |
| `ctx` is cancelled after commit | Hooks still run. They receive `context.WithoutCancel(ctx)`: request values (such as the request ID) remain, cancellation and deadline do not. Set your own timeout in a hook that needs one. |
| Concurrent transactions | Each transaction has its own hooks; they never mix. |

Hooks run after the connection returns to the pool, so they must not use `tx`. A
hook that needs to write starts a new `database.Atomic`. Registering on a finished
transaction returns `ErrNoTransaction`.

> [!WARNING]
> A crash between commit and hook leaves the hook's work undone. When the effect
> must not be lost, use a transactional outbox instead: insert a job in the same
> transaction with `jobs.InsertTx`.

### Transactions started elsewhere

`Atomic` tracks the transactions it begins. Inside a transaction that GORM or your
code began directly:

- `Atomic` still creates savepoints,
- `OnCommit` returns `ErrNoTransaction`.

So start the outermost transaction with `database.Atomic` wherever hooks may be
registered. This includes before `model.Form.InTransaction(tx)`.

If GORM's `DisableNestedTransaction` is set, nested calls create no savepoint.
Their writes and hooks stand or fall with the enclosing transaction.

## Test hooks

Hooks run on commit. Test them with a committed transaction in a disposable
database from `apptest/postgres.New`. Do not use `postgres.Transaction`, which
always rolls back.

```go
func TestWelcomeEmail(t *testing.T) {
	db := postgres.New(t).DB
	outbox := &mail.Capture{}
	// ... apply migrations, build the form with mail.Sender{Transport: outbox}
	if _, err := form.Bind(url.Values{"email": {"ada@example.com"}}).Create(ctx, Member{}); err != nil {
		t.Fatal(err)
	}
	if len(outbox.Messages()) != 1 {
		t.Fatal("welcome email not sent after commit")
	}
}
```

See [model forms](https://cicadel.fauzaanu.com/en/0.2.7/topics/model-forms/index.md), [email](https://cicadel.fauzaanu.com/en/0.2.7/topics/email/index.md) and [testing](https://cicadel.fauzaanu.com/en/0.2.7/topics/testing/index.md).


---

Source: `docs/tutorial.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/intro/tutorial/index.md

# Your first application

Create a project, add an app and serve its first route. Start here if you are new
to Cicadel.

You need Go 1.26.11 or later and PostgreSQL 18. The standard project includes
accounts, so runtime commands need a database.

> [!NOTE]
> This tutorial uses the current release, v0.2.7. Released APIs follow the
> [stability guarantee](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#stability-guarantee). See
> [what is included](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#is-cicadel-ready-to-use).

## Ask your agent

Copy this prompt into your coding agent. Change `myapp` and the module path for your project.

```text
Read https://cicadel.fauzaanu.com/en/0.2.7/llms.txt and its quick-start guide.
Create a Cicadel application in ./myapp with module example.com/myapp.
Use the Cicadel version this documentation describes and record the resolved Go dependency versions.
Add a local notes app, register it in project/apps.go, and serve GET /notes/.
Configure PostgreSQL for the standard account and migration workflow. Do not overwrite an existing project.
Run the application checks and tests, start it locally, and verify /notes/ over HTTP.
Tell me the URL, files changed, and checks that passed.
```

For another version, use the [agent setup page](https://cicadel.fauzaanu.com/en/0.2.7/intro/ai/index.md). Its links and prompts follow
the documentation version selector.

## Create the project

Run these commands from the directory that will contain `myapp`:

```sh
export GOPRIVATE=github.com/fauzaanu/cicadel
go run github.com/fauzaanu/cicadel/cmd/cicadel@v0.2.7 startproject myapp example.com/myapp
cd myapp
go mod tidy
export DATABASE_URL='postgres://USER:PASSWORD@localhost/myapp?sslmode=disable'
export CICADEL_DEBUG=true
export CICADEL_SECURE_COOKIES=false
go run manage.go migrate
go run manage.go check
go run manage.go runserver
```

Open `http://127.0.0.1:8000`. Stop the server with Ctrl-C before you continue.

- **Access.** The repository is private. Configure Git credentials with access, and
  set `GOPRIVATE` as shown.
- **Versions.** The generated `go.mod` pins the framework and core modules at the
  CLI's release. Commit `go.mod` and `go.sum` to keep it.
- **Project CLI.** Inside the project, `go tool cicadel` runs that project's CLI.

> [!TIP]
> To follow the development branch instead, use `@main` in place of `@v0.2.7` and
> read the **dev** documentation. See [install a release](https://cicadel.fauzaanu.com/en/0.2.7/releases/releases/index.md#install-a-release).

## Add and register an app

From `myapp`, create a notes app:

```sh
go tool cicadel startapp notes
```

Add the app to `project/apps.go`. Keep the core registrations:

<!-- example: quickstart/project/apps.go -->
```go
package project

import (
    "example.com/myapp/apps/notes"
    "github.com/fauzaanu/cicadel"
    "github.com/fauzaanu/cicadel/contrib/formsets"
    "gorm.io/gorm"
)

func InstalledApps(_ *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        formsets.App(),
        notes.New(),
    }, nil
}
```

Change `example.com/myapp` if you chose a different module path.

Unlike Django's `INSTALLED_APPS` strings, this is a Go list of app values. Creating a
folder or importing a package does not register an app. This list does.

## Check the route

The generated `apps/notes/urls.go` connects `/notes/` to `Index`:

```go
func URLs() []urls.Route {
    return urls.Include("/notes", "notes",
        urls.Path("GET", "/", "index", Index),
    )
}
```

List the apps, run the checks and tests, then start the server:

```sh
go run manage.go apps
go run manage.go check
go test -race ./...
go run manage.go runserver
```

Fetch the route from a second terminal:

```sh
curl http://127.0.0.1:8000/notes/
# {"app":"notes"}
```

## Make changes

| File | What to change |
| --- | --- |
| `project/apps.go` | Register local and installed apps |
| `project/settings/settings.go` | Set project defaults |
| `apps/notes/urls.go` | Add routes |
| `apps/notes/views.go` | Handle requests |
| `apps/notes/models.go` | Define database models when needed |
| `project/home.templ` | Edit the homepage |
| `project/errors.templ` | Edit the 404, 500 and other [error pages](https://cicadel.fauzaanu.com/en/0.2.7/howto/error-pages/index.md) |

For UI changes, install the CSS tool once. Then rebuild and check:

```sh
go tool cicadel ui css install
go tool cicadel ui build
go tool cicadel ui check --json
```

Restart the server after you rebuild. For automatic rebuilds and restarts, run
`go tool cicadel dev` instead of `runserver`.

## Choose your next step

- [Render a component](https://cicadel.fauzaanu.com/en/0.2.7/howto/component-authoring/index.md).
- [Add htmx interactions](https://cicadel.fauzaanu.com/en/0.2.7/howto/htmx/index.md).
- [Install a reusable app](https://cicadel.fauzaanu.com/en/0.2.7/topics/installable-apps/index.md).
- [Add PostgreSQL migrations](https://cicadel.fauzaanu.com/en/0.2.7/topics/migrations/index.md).
- [Start with sign-in screens](https://cicadel.fauzaanu.com/en/0.2.7/topics/authentication/index.md).

## Deploy

Build the server with `go build -o bin/server .`. Then follow
[deployment configuration](https://cicadel.fauzaanu.com/en/0.2.7/howto/operations/index.md).

> [!WARNING]
> `CICADEL_DEBUG=true` and `CICADEL_SECURE_COOKIES=false` are for local development
> only. Do not use them in production.


---

Source: `examples/component-library/README.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/examples/component-library/README.md

# Independent cards component library

This is an illustrative separate Go module, not a published release or mandatory
visual system. `cards.New()` exports `cards.Card`, embedded source and CSS through
the normal app contract. `Props` requires a title; `Slots` requires `Children` and
accepts an optional `Footer`. No database is needed.

For local development, its `go.mod` replaces the framework with this checkout:

```sh
go mod tidy
go run -mod=mod github.com/fauzaanu/cicadel/cmd/cicadel ui check
go test -race ./...
go vet ./...
```

After source edits run the same CLI with `ui generate`. Publish a real module
version and remove machine-local replacements before distributing your own library.
A host explicitly adds `cards.New()` to InstalledApps, resolves `cards.Card` through
`cicadel.ComponentRegistry`, and injects the definition into its page factory.
Only the project app can supply a compatible override. Styles are optional; the
example publishes `static/card.css` through `App.Static` and declares it as a
required component asset. Hosts serve it at a content-hashed URL under
`/static/cards/`; resolve it with `static.URL(ctx, "cards", "card.css")`.

The executable end-to-end consumer is
[`TestExternalComponentLibrary`](https://github.com/fauzaanu/cicadel/blob/2678611d308376ca8045c8741ee9d4d7814a3fec/internal/scaffold/components_test.go).
It generates a starter, installs a unique library version using a local Go proxy,
adds an override, exercises HTTP/security/isolation, and verifies compiled operation
outside the source tree. It does not depend on a public example.com release.


---

Source: `skills/cicadel-components/SKILL.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/SKILL.md

---
name: cicadel-components
description: Build, edit, debug, and test Cicadel server-rendered .templ components, pages, layouts, accessible forms, and Tailwind CSS. Use for Cicadel UI work; React composition is the mental model, not a React or JSX runtime.
---

# Cicadel components

Deliver working typed components and their verification, not just markup suggestions.
Use terminal/compiler/HTTP tests; never browser or desktop automation.

## Find the actual contract

Read repository instructions and inspect `go.mod`, existing `.templ` files and their
props/slots definitions. Locate the selected framework with
`go list -m -f '{{.Dir}}' github.com/fauzaanu/cicadel` when working in an app. Its
`docs/component-ui.md` is the precise contract; `docs/component-authoring.md` is the
runnable React-style walkthrough; `docs/tailwind.md` covers CSS setup and packages.
Use those versioned docs when available rather than inventing APIs from React or
upstream templ. For focused composition/defaults/attributes/forms/override patterns,
read [references/patterns.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/references/patterns.md). This skill can be copied out
of the repository; its reference is self-contained.

## Use the familiar composition model

- A reusable public component is `ui.Definition[Props, Slots]`; its private body is
  a `.templ` function with those same two parameter types. Exported `Props` and
  `Slots` structs are the discoverable API. `Body: card` refers to generated Go.
- Call it with `@Card.Call(Props{...}, Slots{...})`. A slot is `ui.Content`:
  `ui.Text(value)` for text, `ui.Fragment(privateBody(...))` for compiled markup,
  `ui.Group(...)` for a fragment list. Name the ordinary child slot `Children`;
  other struct fields are named slots. `ui.NoSlots{}` means no slots.
- Props flow down; handlers fetch/bind data and pass it explicitly. Pass services
  or resolved component definitions as typed dependencies. Do not add ambient
  maps, providers, hooks, client state, effects, or hidden registry lookups.
- Go field/type checking replaces TypeScript props checking. Omitted fields use
  Go zero values. `Defaults` runs before `Validate`; use pointers when absent and
  false/zero differ. Neither hook may mutate caller-owned maps/slices/pointers.
  Required slots need an explicit `Empty()` check in `Validate`.
- Use `{ expression }` for text, `@content` for a component, Go `if`/`for`/`switch`
  for control flow, `class`/`for` HTML attributes, and `required?={ bool }` for
  booleans. Put control-flow bodies on separate lines. Do not write JSX, `.map`,
  React `key`, `{ children... }`, `className`, `onClick`, or `dangerouslySetInnerHTML`.

## Style with first-party Tailwind

Tailwind v4 is the default for generated projects, not a mandatory renderer.
Inspect `ui.css.json` and `project/styles/input.css`. Preserve an existing explicit
choice of another CSS system. The standalone compiler is pinned by the framework:
`go tool cicadel ui css install` installs it once; builds/checks never download it.
No npm, CDN script, `tailwind.config.js`, or v3 `@tailwind` directives are needed.

Write **complete literal utility names** in `.templ` or Go variant branches:
`"bg-indigo-600 text-white"`, not `"bg-" + color + "-600"`. Tailwind scans text;
it cannot evaluate Go strings. Class merging deduplicates identical tokens but
is not tailwind-merge: select one padding/color/etc. variant instead of assuming
last class wins. Keep CSS in the input stylesheet with v4 `@theme`/`@utility`.
Inline style/script and active SVG are outside the component contract.

For installed component libraries, add exact Go import paths to the config's
`packages` array so their classes are scanned; Go registration alone does not add
CSS sources. Explicitly register app exports/dependencies and required resources.
Use the installable-app workflow when distribution is part of the request.

## Render, diagnose, verify

Use `(ui.Renderer{}).HTML(r.Context(), w, status, content)` on an uncommitted writer.
On error log privately; send a generic error only if `!ui.Committed(err)`. Never
turn request strings into trusted HTML, URL, JS, or CSS; forwarding goes through
`ui.Merge`, and optional strict URL validation uses `ui.URL`.

From a generated app after `go mod tidy`:

```sh
go tool cicadel ui build
go tool cicadel ui check --json
go test -run '^TestYourComponent$' ./apps/yourapp
go test -race ./...
go run manage.go check
go build -trimpath -o bin/server .
```

In the framework checkout use `go run ./cmd/cicadel` instead of `go tool cicadel`.
`ui build` generates markup and configured CSS. `ui generate` is markup-only.
`ui check` catches stale markup/CSS and compiles Go without executing initializers.
Host `check` validates actual registrations/resources; it may need the host's DB.
Restart the Go server after rebuilding embedded assets; no automatic HMR is implied.

Read the diagnostic code and source position; fix authored `.go`/`.templ`/CSS,
then rebuild. Never edit `*_templ.go`, hand-edit compiled CSS, auto-accept snapshots,
or weaken escaping to make a test pass. Test actual output, empty/invalid inputs,
slots, escaping, links/labels and handler status. Use `apptest` for routes and
`Renderer.Render` for fragments; no separate test language is needed. Commit
source and generated artifacts together. Preserve unrelated checkout edits.


---

Source: `skills/cicadel-components/references/patterns.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-components/references/patterns.md

# Focused component patterns

Read the selected framework's public types first. These patterns describe the
initial `ui.Definition` / explicit-slot API and first-party Tailwind v4 workflow.

## Ownership and optional inputs

Put pure display logic in components and request/database/auth logic in handlers.
Private markup helpers may take ordinary Go parameters. Use a public definition
when a component needs validation/defaults or is an exported/overridable contract.
A string prop cannot be supplied as HTML; a slot cannot be used as an attribute.

For a boolean defaulting to true, make the prop `Expanded *bool`. In `Defaults`,
only when `p.Expanded == nil`, assign a new local true value's address. Do not write
through the supplied pointer. The body uses `*p.Expanded` after defaulting. Prefer
ordinary `bool` when false is the intended default. For enums, use a named Go
string type with constants, default the empty value, and reject unknown values in
`Validate`. Go accepts arbitrary conversions to named string types, so constants
alone do not validate input.

`ui.Content{}` means not supplied; `ui.Text("")` means supplied empty text. Required
child/slot validation should check presence, not render it twice to inspect length.

## Attribute forwarding

Declare `Attributes ui.Attributes` only when forwarding is part of the component
contract. `ui.Merge(base, forwarded)` returns `(templ.Attributes, error)`. Propagate
that error; do not spread an unchecked arbitrary map or discard the error. A body
can prepare merged attributes in its Go factory and return a `templ.ComponentFunc`
that returns the validation error, otherwise call its private markup body. A
simpler component should declare the few specific props it needs instead.

Class strings merge distinct tokens; conflicting Tailwind utility groups do not
resolve by argument order. Prefer a typed variant that selects one complete set:

```go
func buttonClasses(danger bool) string {
    if danger { return "rounded-lg bg-red-600 px-4 py-2 text-white hover:bg-red-700" }
    return "rounded-lg bg-indigo-600 px-4 py-2 text-white hover:bg-indigo-700"
}
```

Render it as `class={ buttonClasses(p.Danger) }`. All candidate names exist literally
in source. `aria-*` values are strings (including `"false"`); HTML booleans are bools.
A label uses `for={ p.ID }`, not JSX `htmlFor`.

## Forms

Reuse `ui/form.Field` with `FieldProps{ID, Name, Label, Value, Error, Required,
MaxLength, Type, Autocomplete, Multiline}`; omitted `Type` defaults to text.
`Multiline: true` renders a textarea. IDs must be unique per page; when repeating
fields, derive a stable ID from the row identity. `Field` adds error relationships
when `Error` is nonempty. Validation/binding remains in `forms` or the handler.

A normal `<form method="post">` contains
`@form.CSRF.Call(form.CSRFProps{Token: token}, ui.NoSlots{})` and fields. The handler
obtains `token` from the existing session middleware and passes it explicitly.
Do not invent a token, suppress CSRF middleware, or retain password inputs after
failed login. Authorization remains in handlers and database query scopes.
The articles `.templ` pages are an executable reference.

## Libraries and project overrides

A library exports `Card.Export(1)` in its owning `App.Components` and declares
normal manifest dependencies. Publish CSS and images through `App.Static`;
`ComponentAssets` lists required paths in it. Resolve hashed URLs in handlers with
`static.URL(ctx, "app", "file.css")` and pass them as props. Do not add asset routes.

For an override, copy the original definition, set `Body` to the custom compiled
function with the **original named Props and Slots types**, and put
`replacement.Override(1)` in the local `project` app's `ComponentOverrides`.
Do not redefine lookalike structs. The registry preserves original defaults and
validation, and rejects type/version mismatches or multiple overrides.

Build `cicadel.ComponentRegistry(apps)`, call `ui.Resolve(registry, library.Card)`,
check the error, then pass the resolved definition into page/handler factories.
A direct `library.Card.Call(...)` deliberately bypasses project overrides.
Add the library's Go import path to `ui.css.json` `packages` when using its Tailwind
classes. This is build-time source discovery, not app installation or registration.

## Repair loop

| Symptom/code | Repair |
| --- | --- |
| `UI_PARSE`, unterminated `if`/`for` | Use Go expressions and multiline templ control-flow blocks; check matching tags/braces. |
| `UI_TYPE`, undefined private body | Generate before type checking; check package/import names and body signature. |
| Unknown prop/slot field | Inspect the exported Go struct; use its exact name/type. |
| `UI_STALE` or `UI_CSS_STALE` | Run `ui build`, inspect source/output changes, rerun check. |
| `UI_CSS_TOOL` | Run the explicit `ui css install` once, then retry offline build. |
| `UI_CSS_PACKAGE` | Install the module with Go tooling; list an exact existing package import path. |
| Classes render but CSS is absent | Use full literal names; inspect input `@source` and config `packages`; rebuild CSS. |
| `UI_RENDER` required value/slot | Fix caller props or explicitly revise the contract; do not erase validation. |
| `UI_CONTRACT` override mismatch | Reuse original public types and contract version. |
| `UI_ATTRIBUTE`, `UI_URL`, `UI_SYNTAX` | Use permitted attributes/contexts; do not cast values to unsafe types. |
| `UI_WRITE` / committed error | Log transport failure; do not write a second response. |

`--json` diagnostics carry stable codes; type-error source locations point to the
owning `.templ` declaration and retain the exact generated Go position. Runtime
errors include nested component stacks. Keep supplied values out of public errors.


---

Source: `skills/cicadel-installables/SKILL.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/SKILL.md

---
name: cicadel-installables
description: Build, integrate, test, and evolve independently installable Cicadel applications and batteries using Go modules, app manifests, explicit registration, and lifecycle contracts. Use for third-party Cicadel apps or first-party contrib packages, not generic Go packages or unrelated frameworks.
---

# Cicadel installable applications

Develop the requested battery through Cicadel's public installable-app boundary. First-party capabilities are core defaults composed through that boundary; module packaging does not make them opt-in alternatives. Preserve the user's requested feature scope; this skill does not authorize publishing modules, sending messages, changing repository visibility, or deploying an application.

## Establish the actual contract

Locate the host/project and framework revision. In a framework checkout, read `docs/installable-apps.md`, `apps.go`, `application.go`, `lifecycle.go` and the relevant part of `management/management.go`. In an external app, inspect `go.mod`, `go list -m` and the APIs of the selected Cicadel version. Do not assume an API from this skill is present in an older module pin.

Read `batteries.md` and the relevant design if available. Current boundaries:

- Cicadel releases follow `docs/releases.md#stability-guarantee`. Released APIs, including the app API (`AppAPIVersion`), change only under that policy; unreleased work may change directly without shims. Go modules select code; the manifest declares the app contract and compatibility. Neither is a replacement for the other.
- Core has no native localization/internationalization or GIS. External apps may provide them without making them mandatory dependencies.
- UI uses compiled `.templ` bodies and typed `ui.Definition` props/slots, exported through `App.Components`. For component authoring use `skills/cicadel-components/SKILL.md` and read `docs/component-ui.md` for explicit overrides and required assets. Tailwind is the default; installed library class sources must be explicitly listed in the host CSS configuration. Use this component contract for application UI.
- GORM model/query integration is available. The standard migration and typed query commands use registered model metadata; inspect the documented PostgreSQL operation subset before relying on it. Do not equate `AutoMigrate` with recorded, reviewable migrations.

For a new package or host integration, read [package-authoring.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/package-authoring.md). For startup, commands, settings or lifecycle changes, read [runtime-contracts.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/runtime-contracts.md). For persistence, upgrades, verification or first-party promotion, read [data-and-verification.md](https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/data-and-verification.md). Load only the references relevant to the task.

## Choose the smallest real implementation

Use `cicadel startpackage DIRECTORY MODULE NAME` for an independent module, or inspect an existing package rather than regenerating it. Keep app-owned models, views, routes, assets and migrations with the app. A nested module inside a larger repository still needs its own test/build workflow; `go test ./...` in the parent skips it.

Use `go get MODULE@VERSION` in a consumer and an explicit factory in `project/apps.go`. No import side effects, automatic downloads at startup, global registration registry or custom dependency resolver. Use local `replace` directives for development only when appropriate; distinguish them from verified remote/versioned installation.

Expose typed options and explicit dependencies in the factory. Reserve core changes for a missing general-purpose integration contract that the requested battery actually needs. Implement that seam with tests and document its scope; do not put the whole battery in core for convenience.

Register routes, namespaced commands/checks, resource filesystems, migrations and lifecycle through the actual exported `App` fields. Preserve ownership boundaries. Do not claim model/component contributions are registered merely because their files are in `Resources`.

## Completion and handoff

Verify behavior in a separate host, not just package-unit tests. Choose the appropriate checks in the verification reference; do not introduce database or browser requirements for a package that does not need them. Use HTTP tests and terminal/API tools; do not use desktop/browser automation.

Report what can be installed and invoked, the selected module/app API versions, tests actually run, provider coverage and remaining limitations. Update the applicable battery/plan only for implemented, verified work. A scaffold, callback wrapper or passing smoke test does not complete a larger battery. Keep skill guidance aligned with changes to the public contracts when the task changes those contracts.


---

Source: `skills/cicadel-installables/references/data-and-verification.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/data-and-verification.md

# Models, migrations, upgrades and verification

## GORM and source layout

Applications can define normal GORM structs in `models.go`, multiple `.go` files in one package, or an imported `models/` package. Go compiles the package as a unit. Use `ModelOf` declarations in the app's `Models` registry; do not claim that unregistered structs are automatically discovered from filenames.

Use the host's `*gorm.DB`, pass request contexts with `WithContext`, and wrap related writes in explicit transactions. Defining a struct does not itself create a table. Distinguish GORM's query/model capabilities from the narrower subset supported by an experimental migration generator.

## Schema changes

Inspect the migration package/version before choosing commands. Record the supported providers and operations. Management commands use the first-party `contrib/migrations` module for recorded model state, declared alterations, version dependencies, checksum-aware execution and recovery. Never widen a provider claim just because GORM has a driver.

For recorded automatic migrations, compare model declarations with immutable recorded state, generate reviewable artifacts, and apply separately. Re-running unchanged models should produce no new migration. A generator should fail explicitly for unsupported renames, destructive changes, unknown types/default expressions, history mismatches and ambiguous data backfills instead of guessing.

Do not convert an existing handwritten SQL history into a model snapshot by inventing historical state. Require a documented baseline/adoption procedure and preserve all original SQL bytes. Installed packages own their migrations; a host must not write generated changes into a dependency cache during ordinary builds. Generate package migrations in the package's source checkout, review and version them, then consume the released artifacts.

New migration output is not automatically permission to execute it on a live or production database. Use disposable test databases for verification within the task's authorization. A generation command never mutates a database; a separate apply command has the normal deployment/data-change scope.

## Upgrade and removal

Pin the package revision in the consumer. Verify installation and recorded schema changes with representative data, constraints and failures. Released Cicadel versions follow the stability guarantee; do not invent compatibility obligations for unreleased designs. Apply append-only migration history; retain old artifacts after changing today's model types. Data migration operations must not depend on future runtime model definitions.

Removing registration/imports plus `go mod tidy` disables a package; it must not silently drop tables, reverse migrations or delete stored data. First-party promotion preserves app labels, command/resource namespaces and history identity. Change unreleased module paths directly; released paths follow the stability guarantee. First-party capabilities are core defaults composed through these contracts.

## Test selection and evidence

- Run package tests and applicable race checks in every module changed. Parent `go test ./...` excludes nested modules.
- Build a separate consumer and install the package through Go module/version selection. A temporary file-backed Go proxy is suitable for isolated install/upgrade tests; distinguish it from a real public release. Local replacements are useful but prove a different path.
- Exercise routes over real HTTP or `httptest`, commands, resource lookup and actual feature outcomes. No GUI/browser automation is needed.
- For persistence, run clean install, no-op repeat, upgrade, rollback/failure and removal/data-retention tests on each claimed provider. Clearly report skipped tests when no test database is configured.
- For a generator, also check deterministic output, recorded history verification, no database access during generation, no-op/check/dry-run behavior, and refusal of unsupported changes without writing artifacts.
- Run appropriate vet/build/vulnerability checks after implementation; do not repeatedly broaden testing once relevant checks pass without a new reason.

Link source, tests and commands in the package's documentation. Mark only verified acceptance items complete. First-party batteries are core defaults through the same public contracts; don't declare the whole framework or multi-provider migration system complete from one package's passing tests.

## Recorded migration installable

Standard projects use `manage.go makemigrations APP`, `generatequeries`, `migrate`,
`migrate verify` and `showmigrations`; see `docs/migrations.md`. Standalone tools
remain lower-level access to the same engine for import and history maintenance. Package-owned embedded histories use `Definition.Source`
with an `fs.FS`; include hidden import manifests using `//go:embed all:migrations`.
Generation writes only to an explicit source checkout. Custom fields require
versioned built-in storage mappings. Existing handwritten histories require
reviewed per-version snapshots before import and verified adoption. Keep original
files when creating replacement bundles. No published installable release has
been verified; local replacement tests establish source compatibility only.


---

Source: `skills/cicadel-installables/references/package-authoring.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/package-authoring.md

# Package and host authoring

## Choose identity before writing persistence

Use a stable lowercase `App.Name` (maximum 40 characters). It owns route/command/resource namespaces and migration history. The Go module path identifies distribution, not database identity. A repository move or first-party promotion is not a reason to rename the app label.

A distributable app declares `Manifest.Module`, its release `Version`, the supported `API`, versioned `Requires`, and database `Providers` if needed. App dependency bounds use the explicit half-open interval `[Min, Before)`. All required apps must be registered; the framework does not fetch or activate them. Project-local legacy apps can omit a manifest but cannot satisfy a versioned requirement.

Inspect `AppAPIVersion` in the selected source. Do not hard-code an assumed future API version or claim that a manifest version verifies the downloaded code. Go module pins/checksums and manifests serve different purposes.

## Create the package

Typical workflow from a framework checkout:

```sh
go run ./cmd/cicadel startpackage /tmp/notices example.com/team/notices notices
cd /tmp/notices
go mod edit -replace=github.com/fauzaanu/cicadel=/absolute/framework/checkout
go mod tidy
go test ./...
```

The module path is an example, not an existing published dependency. Use the user's repository/module identity when known. A publishable package should pin a real framework version, remove machine-specific replacements from release configuration, document supported app API versions, and carry its own tests. Don't publish a tag/release merely to satisfy an example command unless authorized.

Within a monorepo, keep an installable battery in its own Go module, for example `contrib/<battery>`. Supply reproducible local workspace/replacement configuration and explicit CI commands for that module. Compose first-party capabilities into standard scaffolding and commands. Core composition can import these modules; preserve acyclic package imports and pin resolvable dependency versions.

## Register in a host

A generated project owns `project/apps.go` with `InstalledApps(db *gorm.DB) ([]cicadel.App, error)`. Its factory list is passed to `cicadel.New`. Existing handwritten hosts can register descriptors directly. Factories may receive a database, storage adapter, renderer or other service explicitly; there is no requirement to create a global dependency container.

```go
func InstalledApps(db *gorm.DB) ([]cicadel.App, error) {
    return []cicadel.App{
        notices.New(notices.Options{Output: os.Stdout}),
    }, nil
}
```

Install with a versioned `go get`, register, run checks, apply migrations when needed, then serve. Use `manage.go apps` to inspect manifest declarations and `go list -m all` to inspect selected code. For private modules use Go's normal repository credentials/GOPRIVATE configuration; do not put tokens in source, logs or documentation.

## Contribution boundaries

- Manifest app routes use `appname:route` names. The factory owns/configures URL paths; registration does not silently prefix them. Check collisions with another app and with project routes.
- Command maps use local names; callers invoke `appname:command`. Builtins and existing app commands cannot be silently replaced.
- Checks use local IDs, prefixed in diagnostics. Keep checks read-only and independent of schema existence before `migrate`.
- Resources use an app-owned `fs.FS`. Embedding files does not automatically expose them on HTTP or override another app's files. Explicitly choose which assets are served.
- App middleware is route-scoped. Host-wide middleware must be an explicit host choice, with ordering documented.
- Public CSS, images and scripts use `App.Static` (served at `/static/<app>/` with hashed URLs; resolve with `static.URL`). Never add asset routes or serve `App.Resources`.
- Components use `App.Components`, required `ComponentAssets` (paths within `App.Static`), and local-project `ComponentOverrides`. Resolve definitions through `ComponentRegistry` and inject them explicitly. Run `cicadel ui generate/check`, component tests and independent consumer checks. Arbitrary files under `Resources` are not typed registration. Historical model APIs remain separately versioned.

Constructors should return descriptors and capture instance-local configuration. They must not start goroutines, open pools or execute migrations merely on import/construction. Use startup hooks for resources with a runtime lifetime.


---

Source: `skills/cicadel-installables/references/runtime-contracts.md`
Markdown: https://cicadel.fauzaanu.com/en/0.2.7/sources/skills/cicadel-installables/references/runtime-contracts.md

# Runtime and command contracts

## Per-host lifecycle

`New` validates registration and compatibility. `Start` performs configuration checks and initializes dependencies first. Each startup returns a cleanup callback; if it acquired resources before failing, return both cleanup and the error. A failed start unwinds the failing app and prior dependencies in reverse order using a fresh bounded cleanup context.

`Run`/`Serve` manage startup and shutdown, including request draining. Library/test callers using their own server must explicitly start the host and drain requests before closing it. Apps with manifests/checks/hooks are not ready before startup. Repeated successful start/close calls do not repeat work. Construct fresh factories/hosts after a closed or failed runtime instance.

Keep hooks cancellation-aware; return errors instead of panicking. Hooks/checks must not recursively call `Start` or `Close`. A context deadline cannot forcibly stop a goroutine that ignores cancellation. Do not mutate exported application configuration after startup.

Copied descriptors protect registry containers, not closure state or filesystem implementations. Factory-owned state must remain safe under concurrent requests and separate host instances. Avoid package-global singleton resources.

## Commands and offline tooling

Runtime commands run with declared provider checks and app startup/cleanup. Do not run lifecycle-owning commands on an instance simultaneously serving HTTP. Builtin check/list/migration inspection paths do not start runtime services; migrations may need to create those services' tables first.

When writing build-time tooling such as migration generation, inspect the selected core for an explicit offline/build-command contract. Such a command must not require a database connection or start every installed service. If that contract is missing, add a small, tested core seam or provide a standalone generation entrypoint; do not smuggle offline behavior into a runtime hook.

A host builder can still accidentally connect to a database before dispatching an offline command. Keep host construction side-effect-free until command mode is known, or provide an explicit offline construction path. Document how typed model/config dependencies are supplied without live connections. The generator itself must not inspect the live database as its canonical history or call `AutoMigrate`.

## Failure behavior to prove

Choose tests relevant to the package, including:

- An invalid configuration fails before a resource is acquired.
- Missing/incompatible dependencies and namespace collisions are diagnosed.
- Partial startup failure closes acquired resources once, in reverse order, without discarding the original error.
- Graceful shutdown drains active work before cleanup; failed socket binding releases already-started resources.
- Two independently constructed hosts do not share mutable state.
- Middleware affects only its declared routes; secrets do not appear in client-facing errors.
- Runtime/offline command classification is respected, including by host construction.

Use `apptest.Check` as a lifecycle smoke check when available; add feature tests for actual behavior rather than treating it as complete certification.

## Offline build tools

Use `App.BuildCommands` for namespaced generators that must work without a runtime
or database. The manager skips runtime checks, provider validation and lifecycle
hooks; the command must validate its own inputs. Runtime and build command names
cannot collide. Hosts must inspect `Application.IsBuildCommand` before opening
connections; constructor work happens before manager dispatch. Never put database
mutations in build commands. This is a contract, not isolation from plugin code.
The `contrib/migrations/example` host demonstrates this separation and tests with
an unreachable database URL.