# AGENTS.md — notes for AI coding sessions

**Keep this file up to date.** When you change conventions, routes, the data
model, the dev workflow or anything else described here, update this file in
the same commit. It is the first thing a future session reads.

## What this is

Blogspace: a multi-tenant blog host. One Go binary + Postgres. The base domain
serves the superadmin's own blog plus the management site (`/webadmin`,
`/dashboard`, `/b/<sub>/…`, `/admin/`); every other blog is served at
`<sub>.BASE_DOMAIN`. See `README.md` for the user-facing description, config
table and deployment notes.

## Hard constraints (from the product owner)

- **Keep JavaScript light.** Pages must work on old PCs/browsers and on
  phones, so don't rely on JS for core functionality: server-rendered
  forms do the work, and JS is for small conveniences (auto-submit a
  filter, select-on-click, etc.). Plain inline scripts are fine; no
  frameworks, no build step, no heavy libraries. If a feature genuinely
  needs JS, keep it small and give it a sensible fallback where cheap
  (e.g. the `<noscript>` button in `posts.html`).
- Server-rendered `html/template`; no SPA, no frontend toolchain.
- Postgres holds **everything**, including uploaded files (`files.data bytea`,
  `STORAGE EXTERNAL`, served in `substring()` slices so a download never
  loads the whole blob).
  **Each blog is its own database** (`blog_<sub>`, see Key mechanics) so a
  blog is backed up and restored with plain `pg_dump`/`psql`; the control
  database (`DATABASE_URL`) holds only `users` and the `blogs` registry.
- Posts, page intros and announcements are Markdown (goldmark → bluemonday)
  **or raw HTML**: each has a `format` column (`markdown` | `html`), the
  editor's Format radios. HTML is stored and output **unsanitised** — the
  owner's decision, same as the custom HTML module below, same blast radius.
  No WYSIWYG. The editor's toolbar, preview and "Insert file" are scripted
  conveniences over a plain textarea (`partials/editor.html`); the no-JS
  fallback (bare textarea, format radios, file appended on save) must keep
  working.
- Changes are live immediately — there is no draft/preview system. The UX
  is "save, then refresh your blog tab"; keep the "View blog ↗" links.
- Theme customisation is a structured form only; **no custom CSS input**.
  The one escape hatch is the **custom HTML module** (Design tab), which the
  owner chose to store and output **unsanitised**. The blast radius is the
  blogger's own origin: the session cookie is host-only on the base domain
  and `HttpOnly`, management POSTs need the HMAC `_csrf` token, and the
  base-domain blog is only editable by the superadmin.
- App runs plain HTTP behind a reverse proxy; auth is a JWT cookie.
  `HTTPS=true` tells it the proxy has TLS (https links, `Secure` cookie,
  HSTS); `TRUST_PROXY=true` that `X-Forwarded-For`'s last entry is the client.
- Stdlib `net/http` ServeMux with method+pattern routes. No router library.

## Layout

```
cmd/blogspace/        main.go (serve|seed|migrate, superadmin + root blog bootstrap,
                      migrates every blog database at start), seed.go
internal/config/      env → Config; RootSubdomain = "www"
internal/db/          Cluster (control pool + lazy per-blog pools, CREATE/DROP DATABASE),
                      goose providers; migrations/control/*.sql, migrations/blog/*.sql
internal/store/       Store = control DB (users, blog registry, create/delete blog);
                      BlogStore = one blog's DB (settings, pages, posts, files, sections, modules, menu)
internal/auth/        bcrypt, JWT issue/parse, cookie, HMAC CSRF
internal/markdown/    Render(md) → sanitized HTML
internal/i18n/        languages, T/Tf (English keys → catalog), FormatDate/Month, Accept-Language Match;
                      el.go is the Greek catalog, el_months.go the month tables
internal/slug/        Make/Valid/WithSuffix (Greek transliteration included)
internal/web/         server.go (host router, middleware, render helpers)
                      routes.go (all routes), handlers_*.go (sections = announcements, design = the one
                      look-and-layout form, files = the upload library), design_form.go (parsing the
                      design form's module and menu rows), filetype.go (what an upload is, how it may be served)
                      theme.go (colours/fonts/layout switches), layout.go (module kinds, archive grouping),
                      summary.go (what a listing shows of a post)
                      templates/ (embedded; layouts/, partials/, auth/, dashboard/, admin/, blog/)
                      static/ (dashboard.css — lean look; custom properties, flexbox and grid
                               are fine there. blog.css — floats except the three-column `.cols`
                               and the `.notices` row, which are flexbox; it must keep working on old browsers)
```

## Key mechanics

- **One database per blog**: the registry row (`blogs`: id, owner, subdomain,
  `db_name`) lives in the control DB; everything else — a one-row `settings`
  table (title, tagline, language, theme) plus pages, posts, files, sections, modules,
  menu_items — lives in `blog_<sub>` (`db.DBName`: dashes → underscores, so
  subdomains are capped at 58 chars). No table in a blog DB carries a
  blog id; the database is the scope. `store.Store` (control) hands out a
  `store.BlogStore` per blog via `Store.Open`, which also fills `Blog.Title/
  Tagline/ThemeJSON` from `settings`. `db.Cluster` caches one small pool per
  blog (4 conns, idle closed after 2 min). `Store.Open` resets the pool and
  retries once so a `dropdb --force` + restore under a running app is seamless.
  Creating a blog: registry insert in a control tx → `CreateBlogDB` (CREATE
  DATABASE + blog migrations, outside the tx) → settings/home page/defaults →
  commit; any failure rolls back and drops the DB. A leftover database with
  the blog's name is `db.ErrDatabaseExists` (409 in `/admin/users/new`).
  Deleting a user drops their blog database. Start-up (`migrateBlogs`)
  migrates every registered blog DB; a missing one is logged and skipped.
- **Host routing** (`web/server.go` `ServeHTTP`): base domain or `www.` →
  root mux with `ctxHostSub = "www"`; `<sub>.base` → subdomain mux; anything
  else 404. Public blog handlers get the blog via the `hostBlog` wrapper;
  management handlers get it via `withBlog` (`/b/{sub}/…`, owner or
  superadmin). Both call `resolveBlog`, which puts the blog in `ctxBlog`
  (templates see it as `.Blog`) and its `BlogStore` in `ctxBlogStore`
  (`blogStore(r)` in handlers).
- **Root blog** is a normal `blogs` row with subdomain `www`, owned by the
  first superadmin, created by `ensureRootBlog` on startup. Managed at
  `/b/www/`. `Config.BlogURL("www")` returns the root URL.
- **Route precedence**: on the root mux the blog's `GET /{page}` and
  `GET /{page}/{post}` coexist with literal management routes. Any new
  top-level management path must be added to `reservedPageSlugs`
  (`handlers_pages.go`) and to `TestRootRoutePrecedence`. `/static/{file}`
  is a single segment on purpose (a `/static/` prefix pattern conflicts
  with `/{page}/{post}`); static files must stay flat. The public
  `GET /tag/{tag}` is a literal first segment, so it beats `/{page}/{post}`
  on every host (`tag` is reserved too), and so is `GET /search` (`search`
  reserved). A `{page}` wildcard never matches
  a trailing slash, so listings put `?p=N` straight after `base` (`/`,
  `/news`, `/tag/go`) — `/news/?p=2` would be a 404.
- **Auth**: login lives only at `/webadmin` on the root domain (deliberately
  not `/login`, and not linked from public pages); `/webadmin` on a blog host
  redirects there with `next=/b/<sub>/`. After login (or when already logged
  in) `landing` sends a blogger whose `next` is another blog's `/b/<sub>/…`
  to `/dashboard` (their own blog) instead of the 403; superadmins go where
  they asked. HS256 JWT in `session` cookie (`HttpOnly`, `SameSite=Lax`,
  7 days). Claims carry `uid` + `ver` (= `users.token_version`); the
  session middleware re-loads the user every request and drops the session
  if disabled or version mismatch. Password change / reset / disable bump
  `token_version`. Every management POST must include
  `<input type="hidden" name="_csrf" value="{{.CSRF}}">`; the check runs in
  `guardPOST`, which first refuses a POST whose `Sec-Fetch-Site` is
  `cross-site` or `same-site` (`crossSiteForm`: a blog subdomain is
  same-site, only the dashboard origin may post; the login form checks it
  too against login-CSRF), then caps the body at the limit it is given +
  1 MB and parses the form. `requireLogin` only redirects anonymous users;
  `requireAuth` = login + `guardPOST(0)` (dashboard, password, admin: no
  uploads); `withBlog` = login → `resolveBlog` → owner-or-superadmin →
  `guardPOST(blog.UploadLimit(cfg))`, and `withBlogFiles(n, …)` allows n
  limits for the Files page's multi-upload (`maxUploadFiles` = 10). Errors
  from `guardPOST` go through `s.fail`, which answers JSON when the request
  has `Accept: application/json` (the upload scripts). `POST /logout` runs
  `guardPOST` too when a user is logged in (blogs are same-site with the
  root domain, so `SameSite=Lax` alone would let a blog page log a
  superadmin out).
- **Hardening** (`web/ratelimit.go`): a per-key token bucket throttles the
  anonymous endpoints worth abusing — `loginLimit` on `POST /webadmin`, keyed
  by client address *and* by lowercased username (10 at once, then 10 a
  minute each), `searchLimit` on `GET /search` per address — answered with 429 by `s.throttle` and a log line; failed
  logins are logged with the username and address, and the login body is
  capped at `maxLoginBody` (64 KB) since it is the one POST outside
  `guardPOST`. `s.clientIP` is the peer address, or the last
  `X-Forwarded-For` hop with `TRUST_PROXY` (earlier entries are forgeable).
  `secureHeaders` (`ServeHTTP`) puts `nosniff`, a `Referrer-Policy` and,
  with `HTTPS`, HSTS on every response; the management paths on the root
  host (`managementPaths` — add a new top-level management prefix there
  as well as to `reservedPageSlugs`) also get `X-Frame-Options: DENY` and
  a CSP of `frame-ancestors`/`base-uri`/`form-action`/`object-src` only —
  no `script-src`, the dashboard's inline scripts are a product
  constraint. Public blog pages carry no framing rule (owner content).
  Audited and left as is (2026-09): SQL is all parameterised (`likeEscape`
  for ILIKE, `pgx.Identifier` for database names); templates are
  `html/template` and the only `{{html}}` sinks are owner-authored content;
  `/media` never renders a type a browser would script (`filetype.go`). Flood
  control for everything else stays at the reverse proxy (`limit_req`).
- **Templates**: each page file is parsed together with its layout
  (`layouts/dashboard.html` or `layouts/blog.html` for `blog/*`) and all
  `partials/*.html`. Page files define `content` (and optionally `title`).
  Handlers call `s.render(w, r, "dir/file.html", map[string]any{...})`;
  page data is under `.Data.<key>`, common fields (`.User`, `.Blog`,
  `.CSRF`, `.Flash`, `.Error`, `.BlogURL`, `.RootURL`) are top level.
  Flash messages travel as `?ok=` query param via `redirectOK` (a `#anchor`
  in the target is kept after the query). Add new
  templates to `TestAllTemplatesParse`.
- **Design tab** (`handlers_design.go`, `dashboard/design.html`,
  `GET|POST /b/{sub}/design`): the whole look and layout of a blog is **one
  form with one Save** — theme values, the area switches and column widths,
  the modules of every area (with their settings inline, folded in a
  `<details>`) and the menu — stored atomically by `BlogStore.SaveDesign`
  (theme + full module list + full menu in one transaction: rows with an id
  are updated, without one inserted, missing ones deleted). Because a missing
  row means delete, `handleDesign` reads *everything* — modules, menu, then
  the uploads — before reporting the first problem, and the rejected form is
  rendered from all of it; never bail out half-way. Sections are cards
  with ids (`designSections`) a sticky side index jumps to; the hidden `at`
  field says which one was in view so the flash returns there. Module rows are
  `mod.<i>.{id,area,kind,title,body,count,pos,del}` and menu rows
  `menu.<i>.{id,page,label,url,pos,del}` (`design_form.go`: `parseModules`,
  `parseMenu`); `i` only tells rows apart, `pos` orders them. The inline
  script reorders rows in the DOM (renumbering `pos` on submit), clones the
  `<template id="tpl-<area>-<kind>">` rows to add modules, fills the colour
  inputs from a scheme button, tracks unsaved changes (badge, `beforeunload`,
  confirm on "Discard changes") — all of it optional: without it `pos` is a
  number box, Remove a checkbox, `add.<area>` / `menu_add_page` /
  `menu_add_label`+`url` / the `preset` select are applied on save. A
  validation error re-renders the form **with what was sent** (the parsers
  return every row along with the error; a bad link stays as a row to fix).
  `POST /b/{sub}/design/reset` stores `DefaultTheme()` and calls
  `ResetModules`. `GET /b/{sub}/layout` (the old tab) redirects to
  `/design#columns`. **Header preview** (`POST /b/{sub}/design/preview`,
  `handleDesignPreview`, `blog/preview.html`): the Menu card's frame. The
  handler reads the form exactly as a save would (theme, modules, menu —
  errors ignored, what was sent is shown), drops the banner, and executes the
  `preview` template alone (a whole small page: blog.css, the theme CSS, the
  `siteheader` template) — never the layout. Because the dashboard is on the
  root host, where `/media` is the root blog's files, the page's images and
  fonts are linked through `view.Media` (`/media` from `renderStatus`,
  `/b/<sub>/media` here; the theme CSS through `Theme.CSSAt`). The script
  POSTs the form (file inputs dropped) 300 ms after any change — `touch()`
  schedules it, so module order counts too — into
  `<iframe sandbox="allow-same-origin" srcdoc>`: same origin, unlike the
  editor's HTML preview, because the session cookie is `SameSite=Lax` and an
  opaque origin would not send it for those images; safe only while no header
  module kind is owner HTML (all four are template-escaped) and there is no
  `allow-scripts`. The dashboard's script sizes the frame to the header
  (`fitFrame`, on load and on the Wide/Phone toggle — the frame at 380px, so
  blog.css's phone rules apply).
- **Theme** (`web/theme.go`): struct stored as jsonb on `settings.theme`.
  `ParseTheme` merges over `DefaultTheme()` and `normalize()` clamps every
  value to an allowlist (hex colours, enum strings, uuid image ids, column
  percentages) — this is what makes inlining the generated CSS safe. Add
  new options in the struct, `normalize`, `ThemeFromForm`, the CSS template
  and `dashboard/design.html`; defaults must reproduce the look blogs had
  before the option existed. Non-CSS options (`ShowDates`, `DateFormat` via
  `FormatDate`, `PostsPerPage`, `Favicon`, `Logo`) are read by the blog
  templates and handlers, and so are `ListStyle` (`full` | `summary`, see
  Summaries) and `PostImage` (where the post page shows the featured image:
  `top` | `bottom` | `list` = listings only). `TitleSize` is emitted inside
  the wide-screen media query so blog.css's phone rule keeps winning.
  `HeaderRule` (`none` | `line` | `dots` | `stripes`) is a decoration beside
  the title and logo modules in the header, filling the rest of the row (both
  sides when `HeaderAlign` is `center`): `Theme.RuleClass` turns it into the
  `ruled rule-<kind>` classes on the block, the `rule` template adds the
  `.header-rule` cells and blog.css draws them — table cells (so the rule is
  as tall as the brand and old browsers agree) in `currentColor`, i.e. the
  header text colour. On phones the row is a flexbox instead (a table would
  wrap a long title one word per line): the brand wraps only when it must and
  the rules take what is left, nothing when the title needs the whole width. The menu
  links' look is switches that combine — `NavBold`, `NavUpper`, `NavUnderline`
  (`hover` | `never` | `always`), `NavSize`, `NavGap`, `NavActive` (how the
  current page's link is marked: `underline` | `bold` | `box` | `none`) and
  `NavAlign` (`left` | `center` | `right` | `spread`) — turned into body
  classes by `Theme.NavClass` (`nav-<align> nav-ul-<kind> nav-size-<s>
  nav-gap-<g> nav-active-<a>`, plus `nav-bold`/`nav-upper`) that blog.css
  draws; the theme CSS only colours the links. `spread` is justified text
  with a full-width `::after` line, header only; `center`/`right` stay
  unscoped (a column menu's block links centre their text, as before). They replaced a `nav_style` select
  (`normal` | `uppercase` | `plain`), which `ParseTheme` still decodes and maps
  onto the switches — `uppercase` was also the small size — (`omitempty`, so
  the next save drops it). `TitleRule` (`none` | `line` | `dots` | `dots2` | `stripes`) is the header
  rule's kinds, plus a double dotted row (`dots2`: the border and an
  absolutely positioned `::after` with a second one 2px above), under page and post titles (`.page-title`, `.post-title`): a body
  class from `Theme.TitleRuleClass` (`titles-<kind>`) that blog.css draws
  (border width/style only — never the shorthand, or it would reset the
  colour; stripes are an `::after` gradient in `currentColor`), coloured
  by the theme CSS in the link colour; `overflow:hidden` ends it at a floated
  thumbnail. `TagHash` lists tags as `#name` wherever they appear: the
  `posttags` partial (takes `dict "tags" … "hash" …`), the two tag modules
  and the tag page title (`tagname` template func).
  `Font`/`HeadingFont` `fira` is Fira Code, the one built-in choice that is a
  web font: `static/FiraCode-VF.woff2` (the variable face, OFL — licence in
  `static/FiraCode-LICENSE.txt`), declared as `@font-face` when `UsesFira`.
  **Custom fonts** (`CustomFont`, `CustomHeadingFont`: font file ids or ""):
  a chosen file is declared as `@font-face` (`"BlogFont"` / `"BlogHeadingFont"`,
  `src:url(/media/<id>)`, same-origin so no CORS) and put first in the stack,
  the built-in `Font`/`HeadingFont` choice behind it as the fallback — so
  there is no "custom" enum value and no invalid state. `HeadingFontFamily`
  builds on the text's stack when `HeadingFont` is `same`, and the `h1…h6`
  rule is emitted whenever `HeadingFontSet` (a heading choice or a heading
  file). Picked with the `fontpick` partial: a plain `<select>` of the newest
  `recentImages` library fonts (`kind = font`) plus the chosen older one, and
  an upload input — no library panel, no script.
  Optional colours (`LinkHover`, `NavHover`) are `""` = inherit and come
  from a colour input paired with a `<name>_custom` checkbox, shown/hidden
  with CSS only (`.hoverpick > input:not(:checked) ~ …`). Image fields use the
  `imagepick` partial: a `<select>` of the `recentImages` newest library
  images (`kind = image`) plus the chosen one (`imageNames` looks up an older
  one's filename, fonts included), so the page never grows with the library; `none` clears, a
  uuid selects, no value keeps (`pickFile`); an upload in `<name>_file` wins.
  The `imagelib` partial (one per form; the design page and the post form
  both include it) is the panel behind "Choose from library…", with its own
  script: it marks every `.imagepick` with `.js` (hiding the select, showing
  the buttons — `.ip-nojs`/`.ip-jsonly`, independent of the form's own `js`
  class), fetches `GET /b/{sub}/files?kind=image&q=&p=` with
  `Accept: application/json` (`{files:[{id,filename}], page, last}`, 50 a
  page, thumbnails `loading=lazy`), writes the choice into the select and
  fires `change` on it, which is how the design form learns it is dirty.
  `Presets()`/`WithPreset` are the colour schemes (colours only; `Preset.Colors`
  is the JSON the scheme buttons carry). The layout switches
  (`HeaderOn/LeftOn/RightOn/FooterOn`, `LeftWidth`, `RightWidth`,
  `KeepColumns`) live in the theme and are read by `ThemeFromForm` like
  everything else (checkboxes: unticked = off).
- **Layout** (`modules` table, `store/modules.go`, `web/layout.go`,
  `design_form.go`): a blog page is six areas —
  `header`, `left`, `above`, `below` (the two custom-HTML slots inside the
  main column, one module at most), `right`, `footer` — each an ordered
  list of modules (`kind`: title, logo, menu, search, archive, recent, tags,
  tagcloud, html, rss, text, sitemap — the list is also a CHECK constraint
  on `modules.kind`, so a new kind needs a migration; `moduleKinds` says
  which kinds an area accepts; `moduleHasSettings` takes the module because a header search box
  has nothing to edit). Modules have an optional `title` (heading), `body` (raw HTML or
  footer text) and `count` (recent posts; tags to list, 0 = all). `blogView`
  builds a `Layout` (`buildLayout`, areas that are switched off are dropped)
  and only fetches the archive index / recent posts / tag counts when a
  visible module needs them (`NeedsArchive/MaxRecent/NeedsTags`). A side column is
  laid out only when it has modules, or always with `theme.keep_columns`
  (`HasLeft/HasRight` → `body.has-*`
  classes; column widths in the theme CSS under `@media (min-width: 701px)`).
  The page is the screen's width unless `page_width` (pixels, 0 = screen,
  clamped 400–3000) caps `.wrap.body-wrap` with `max-width`, centred or at
  the left per `page_align` (`Theme.PageMargin`); the column percentages
  divide the page either way and `keep_columns` is how a blogger gets a
  narrower main column. `align_to_main` insets the header's and footer's
  `.wrap`s to the main column's edges (`Theme.Inset`: the wrap's 1em plus
  the column's share of the wrap's content box, `calc((1-2w/100)em + w%)`;
  with a page width those wraps get the same `max-width`/margin and the
  share is `min(w%, w% of the page width)`, the px value alone first for
  browsers without `min()` — wide screens only, backgrounds untouched);
  below 700px `.cols` becomes block flow so the order is main → left →
  right → footer. Everything is rendered by the `module` template in
  `layouts/blog.html`. New blogs get `insertDefaultModules` (title + menu
  in the header, RSS in the footer) — keep it in step with the layout
  migration's defaults.
- **Menu** (`menu_items` table, `store/menu.go`): the single ordered list
  the Menu module shows — page entries (`page_id`, unique per page, cascade
  on delete) and custom links (`label` + `url`, validated by
  `validLinkURL`: http(s), mailto or a `/path`). `Page.ShowInNav` is
  derived (`EXISTS` on `menu_items`); `CreatePage`/`UpdatePage` add or
  remove the entry so the page form's checkbox and the Design tab agree.
- **Favicon**: `static/favicon.svg` + `favicon.png` are the defaults, linked
  from both layouts. A blog can set `theme.favicon` (an image id) which the
  blog layout links instead. `GET /favicon.ico` on every host
  (`handleFavicon`) serves the png or redirects to the blog's image, so
  icon-probing browsers never hit the 404 page; `favicon.ico` is reserved.
- **Files** (`files` table, `store/files.go`, `handlers_files.go`,
  `filetype.go`, `/b/{sub}/files…`): the upload library, any type. A row is
  `id, filename, content_type, kind, size, data`; `kind` (image, document,
  audio, video, font, archive, other) is decided at upload by `fileType`, which
  trusts `http.DetectContentType` first and lets the extension refine only a
  generic sniff (text/plain, octet-stream) to a type on the allowlists in
  `filetype.go`; anything unknown is stored as `application/octet-stream`.
  Fonts (`fontTypes`: WOFF2, WOFF, TTF, OTF) are known by their bytes alone,
  like images; TTC and EOT stay `other`.
  `/media/{uuid}` is served on every host with immutable cache headers, from
  the host's blog database only (the root domain serves the root blog's
  files); dashboard previews for another blog on the root host use
  `GET /b/{sub}/media/{id}` (`withBlog`). **The root domain carries the
  session cookie, so `servedAs` renders inline only images, fonts (a browser
  parses one only inside `@font-face`), PDF, plain text,
  audio and video; everything else (HTML, SVG, XML, JS, archives, binaries)
  goes out as `application/octet-stream` + `Content-Disposition: attachment`.**
  `?download` forces attachment. SVG is therefore never an image (download
  only, and refused by the design page's `readUpload(…, imagesOnly)`); ICO
  is. The bytes are streamed by `BlogStore.FileReader` (a `chunkReader` over
  `substring()`, 512 KiB per query, Range requests included), which is why
  the per-blog limit is capped at 1024 MB (`maxUploadMB`: int4 offsets).
  Only a single range is honoured (`singleRangeOnly` drops multi-range
  headers): ServeContent's multipart answer would cost a query per range.
  Ids are immutable, so a renamed file keeps its old download name in
  browsers that cached it. Markdown keeps the relative `/media/…` form
  because post bodies render on the blog host; `fileMarkdown` writes
  `![name](…)` for images and `[name](…)` for the rest. Deleting a file
  clears theme references to it. `POST /b/{sub}/files/upload` takes several
  `file` parts (the no-JS `<input multiple>`), or answers JSON
  (`{id, filename, kind, size, markdown, html}` / `{error}`) for one file when the
  request has `Accept: application/json` — what the editor and the Files
  page scripts call. `dashboard/files.html` lists by `?kind=&q=&p=`
  (`ListFiles`, 50 per page, `pageBounds` clamps), shows `FileUsage` and the
  blog's limit; rename/delete return to the `back` field. The per-blog limit
  is `blogs.max_upload_bytes` in the control DB (NULL = `MAX_UPLOAD_MB`, now
  10), set at `POST /admin/blogs/{id}/upload-limit` from `admin/index.html`;
  `Blog.UploadLimit(cfg)` resolves it.
- **Editor** (`partials/editor.html`, args via `dict`: name, value, format,
  rows, tall, upload, preview, csrf, and `formatof` for a second editor in
  the same form — the page's outro passes `"intro"` — which then renders no
  Format row and watches the named editor's radios): a Format row (radios
  `format` = `markdown`|`html`) and a textarea with a Markdown toolbar
  (bold, italic, strike, heading cycle, quote, code, lists, rule, link box,
  Insert file), Ctrl+B/I/K, list continuation on Enter, and a Write/Preview
  toggle that POSTs the text to `/b/{sub}/preview` (`handlePreview`:
  `markdown.Render` → `{html}`, nothing stored). Every edit goes through one
  `replace()` built on `execCommand("insertText")` so browser undo works. The
  toolbar is `hidden` until the script runs; without JS it is a bare textarea
  + "Insert file" + cheat-sheet, and paste/drop take any file. Forms using it
  must be `multipart/form-data` and their save handler must set `Format` with
  `pick(r.FormValue("format"), store.FormatMarkdown, store.FormatHTML)`, call
  `s.readUpload(r, "<name>_file", false)` (`body_file`, `intro_file`,
  `outro_file`) + `appendFile(body, f, format)`
  (the no-JS path: `fileMarkdown` or `fileHTML`, i.e. `<img>`/`<a>`), and
  store `renderBody(format, src)` (`markdown.Render`, or the source untouched
  for HTML) in the `*_html` column (`readUpload`'s last argument is the kind
  the field must be — `"image"`, `"font"` — or `""` for anything) — the public templates only ever print
  that column.
  **HTML mode** (`.editor.html`, toggled by the radios): the Markdown toolbar
  groups (`.ed-md`), link box, shortcuts, list continuation and cheat-sheet
  are off, the textarea is monospace, Insert file inserts the upload JSON's
  `html` field. Preview does not touch the server: the text goes into
  `<iframe sandbox srcdoc>` (`.ed-preview-frame`) — an opaque origin with no
  scripts — because the text may not be the viewer's own (a superadmin edits
  other people's blogs) and must never run on the dashboard origin, where the
  session lives. Markdown preview keeps using `.ed-preview` in the page.
- **Page intro and outro** (`pages.intro_md/intro_html`, `outro_md/outro_html`,
  one `format` for both): text before and after the page's posts, the
  blog-wide `above`/`below` HTML modules' per-page counterpart (a home page
  with a site map or a widget after its posts). `blog/page.html` prints the
  outro after the `postlist` and treats a page with only an outro as not empty.
- **Summaries** (`web/summary.go`, `theme.list_style`): with `summary` a
  listing (page or tag) shows `Post.Excerpt` + a "Read more" link when
  `Post.HasMore` — both filled by `fillExcerpts` in the listing handlers, never
  stored. `postSummary` cuts the *source* at `<!--more-->` and renders that
  part (bluemonday drops the comment from the full body; in HTML mode it
  stays, harmless); without the marker a Markdown post is cut at the first
  blank-line block boundary past `summaryWords` (70) words, never inside a
  code fence, and an HTML post is shown whole (cutting hand-written markup
  blind would leave tags open). `full` puts the whole body in `Excerpt`.
- **Featured image** (`posts.image uuid REFERENCES files ON DELETE SET
  NULL`, `Post.Image` as a string id or ""): picked on the post form with the
  `imagepick` partial (`image`, upload `image_file` wins; `postFormData`
  loads the recent images like the design page and clears an id whose file
  is gone). Listings float it right as `.post-thumb` (`has-thumb` clears the
  float); the post page shows it as `.post-image` above or below the body per
  `theme.post_image`, or not at all (`list`). No resizing: the thumbnail is
  the file scaled by CSS.
- **Announcements** (`sections` table, `store/sections.go`,
  `handlers_sections.go`, `/b/{sub}/announcements…`): per-blog notices with
  `placement` (`<column>-<position>`: left|main|right × top|bottom, split by
  `Section.Column()/Position()`), `style` (plain|note|warning|gizmo — a CHECK
  constraint, so a new style needs a migration), `enabled`
  and `sort_order`. `blogView` loads the enabled ones and `placeNotices`
  groups them by placement, moving ones for a side column that is not laid
  out into the main column. Two switches hide them: `pages.show_notices`
  (`Page.ShowNotices`, the page form's "Show announcements on this page",
  default on) covers the page and its posts, and `theme.post_notices`
  (`PostNotices`, Design → Content, default on) covers every post page —
  `renderPage`/`handleBlogPost` put `noNotices` (a typed empty map, so the
  layout's `index` lookups still work) in `notices` instead. Tag, search
  and 404 pages always show them.
  Rendered by the `notices` template in `layouts/blog.html` inside a
  `.notices` wrapper; CSS classes `notice notice-<style>` use translucent
  colours so they fit any theme, except `gizmo`: a box framed in the theme's
  link colour (`.notice-gizmo { border-color }` comes from the theme CSS).
  On wide screens `.notices` is a flex row (the second flexbox in blog.css,
  stacking on old browsers like `.cols`). `placeNotices` returns `Notice`
  (the section + `Width`): in the main column, consecutive headed gizmo
  boxes (`.headed`) are paired two to a row by `pairNotices`, and
  `shareRow` gives the pair the `rowShares` split (25/75, 33/67, 50/50,
  67/33, 75/25) nearest the ratio of their text lengths (`noticeLen`: title
  + body with tags stripped) as `.w-<percent>` classes whose flex-bases sum
  to 90% (the leftover grows into both, so a third never fits). Every other
  box, and every box in a side column, takes the whole row.
- **Dashboard nav**: `dashnav.html` marks the current tab with `hasPrefix
  .Path`; a new management section needs a tab there.
- **Languages** (`internal/i18n`, `settings.language`): every blog has a
  language (`en` by default, `el` = Greek) chosen on the Settings tab. Public
  pages use the blog's language; management pages use the **logged-in user's
  own blog's** language (a user has one blog, so a superadmin editing someone
  else's blog keeps theirs); anonymous pages (`/webadmin`) match
  `Accept-Language`. `server.go`: `hostBlog`/`withBlog` put it in `ctxLang`,
  `s.lang(r)` resolves it (lazily looking the user's blog up otherwise), the
  `view` carries it as `.Lang` (also the `<html lang>`).
  Keys are the English strings: templates write `{{t "Save"}}` /
  `{{tf "Page %d of %d" .N .Last}}`, handlers `s.tr(r, "Post deleted.")` /
  `s.trf(r, "Uploaded %s.", name)`; an unknown key renders as English.
  Templates are compiled once **per language** (`templates.get(lang, name)`)
  with `funcsFor(lang)`, whose `t`, `tf`, `date` (dashboard, long style),
  `postdate` (`style, time` for the theme's `DateFormat`), `month`
  (archive headings) and `modsummary` are closed over the language — so
  templates need no data plumbing. A sentence with a link in the middle is
  split into fragments around the `<a>`. `moduleNames`/`areaNames`/preset
  names stay English maps and are translated where used (`{{t (index …)}}`,
  `s.tr(r, moduleNames[k])`). Content the blogger typed is never translated;
  default module headings are created in the blog's language.
  `TestGreekCatalogComplete` scans the templates and handlers for keys and
  fails when the Greek catalog misses one or keeps a stale one — reword an
  English string and the catalog entry must follow. Keys reached through a
  variable (`{{t .Role}}`) are listed in that test by hand.
  Adding a language: an entry in `i18n.languages`, a catalog file, a month
  table in `monthTables` (nominative, in-date and short forms), and the test
  gets a copy per language if its rules differ.
- **Post date** is `posts.created_at` — there is no separate "published
  at": the blogger sets it on the post form (`posted_at`, a
  `datetime-local` input that degrades to a text box; `parsePostDate`
  accepts `YYYY-MM-DD[THH:MM]`), for new and existing posts alike, and it
  drives ordering, the archive, the feed and the displayed dates. Blank keeps
  the current value; a new post starts at now. Times are in the server's
  zone, which is also the one dates are rendered in. `posts.hide_date`
  (`Post.HideDate`, the form's "Hide the date on this post") is a per-post
  override of the theme's `ShowDates`: the listing, post page and search
  templates check `and ShowDates (not .HideDate)`; the feed keeps its `pubDate`.
- **Tags** (`tags` + `post_tags` tables, `store/tags.go`, `web/tags.go`):
  a tag is `name` + unique `slug` (`slug.Make(name)`), so the slug is both
  the URL (`/tag/<slug>`, `handleBlogTag`, published posts of every page,
  paginated) and the dedupe key — "Go" and "go" are one tag, the first
  spelling wins. `Post.Tags` rides along in `postCols` as two arrays.
  The post form is one comma-separated `tags` box (prefilled by
  `tagsText`); the blog's existing tags sit folded under it as chips that
  a small inline script toggles in the box (a plain list without JS).
  `parseTags` normalises the box (20 per post, 40 runes each; nothing
  slug-worthy → dropped) and `SetPostTags` stores it after the post is
  saved. Tags no post carries
  are deleted (`deleteOrphanTags`, also after post/page deletion), so the
  form only lists tags in use. `TagCounts` counts published posts only:
  a tag on hidden posts alone shows nowhere public and its page is a 404.
  Tags render under the post date (`posttags` in `partials/postlist.html`,
  which also holds the article loop + pager shared by `blog/page.html`
  and `blog/tag.html`); the two modules are `tags` (by use, `count`) and
  `tagcloud` (alphabetical, `cloudSizes` → `tc-1…tc-5`).
- **Search** (`web/search.go`, `handleBlogSearch`, `GET /search?q=&p=`,
  `blog/search.html`): the `search` module is a plain GET form of one input
  (`searchform` in `layouts/blog.html`; Enter submits, the placeholder is the
  label, so "Search" is not repeated all over the page). In the header it is
  rendered inside the menu module's row, floated right (`Layout.HeaderMenu/
  HeaderSearch`), and gets its own thin bar only when the header has no menu;
  in a column it is a box with an optional heading. The results page shows a
  box of its own only when no module does (`Layout.HasSearch`). `searchPattern` turns the query into the regex both Postgres and Go
  run: words `regexp.QuoteMeta`'d and joined with `.*`, so the reader's words
  are literal, case does not matter (`~*` / `(?is)`) and spaces mean
  "anything in between", in order. `SearchPublishedPosts` matches it against
  `title || '\n' || body_md` of published posts from every page, 20 per page
  (`searchPerPage`); queries are cut at 100 runes and 8 words
  (`maxSearchWords`). The scan is unindexed, so the handler is throttled
  per client address (`searchLimit`, 30 then 30 a minute) and the query
  runs under `searchDeadline` (5 s): a timeout is logged and shown as no
  results, not a 500. Results are title, date
  and `searchSnippet` (the Markdown around the first match, escaped, the
  match in `<mark>`; the body's start when only the title matched). A blank
  or unmatched query is a normal 200, not a 404; the pager is the page's
  own (`&p=N` after `?q=`), not the `postlist` one.
- **Slugs**: auto-generated from the title; on collision generated slugs
  get `-2`, `-3`…, user-typed slugs return a 409 with a message.
  `slug.Clean` is `Make` without the "untitled" fallback, for inputs that
  should be rejected instead (tags).
- **Errors**: `store.ErrNotFound` / `store.ErrConflict` are the sentinels
  (`store.wrap`). Handlers use `s.serverError` (logs, 500) and
  `s.plainError(status, msg)` (small standalone HTML page).

## Dev workflow

```sh
make dev        # postgres in docker + app (DEV=1: templates/static reloaded from disk)
make seed       # admin/admin (superadmin, owns root blog), alice/alicealice
make test       # unit tests; no DB needed
make db-reset   # wipe dev data (control and all blog databases: the whole volume)
```
Port 8080 may be taken on the owner's machine: `make dev ADDR=:8090 PUBLIC_PORT=8090`.
Browsers resolve `*.blogspace.localhost` to loopback; with curl use
`-H 'Host: alice.blogspace.localhost' localhost:8090/…`.

`DEV=1` also allows a missing `JWT_SECRET` and defaults the bootstrap
superadmin password to `admin`. Production refuses both.

## Conventions

- Run `gofmt -w .`, `go vet ./...`, `go test ./...` before committing.
- Migrations: `internal/db/migrations/blog/NNNNN_name.sql` for blog content
  (runs in every blog database — it must not reference `users`/`blogs`) and
  `internal/db/migrations/control/` for users and the registry; goose
  `-- +goose Up/Down` sections; they run automatically at startup. Never
  edit an applied migration. Blog chain so far: `00001_init`, `00002_language`,
  `00003_files`, `00004_tags`, `00005_search`, `00006_format`, `00007_post_image`,
  `00008_page_outro`, `00009_gizmo_style`, `00010_font_kind`, `00011_post_hide_date`, `00012_page_show_notices`, `00013_page_kind`, `00014_drop_page_kind` (13 added special pages, 14 dropped them again — both stay, applied databases need the pair); control: `00001_init`, `00002_upload_limit`. Both chains were re-baselined at 00001 after
  the move to per-blog databases; deployments from before it have
  `goose_db_version` rows 2–7 in the control DB that must be deleted once
  (README "Upgrading from a single database") or the next control migration
  is refused as "missing".
- Blog content goes through `BlogStore` methods, which take `ctx` first and
  are bound to one blog's database, so a blogger can never touch another
  blog's rows; users and the registry go through `Store`.
- Keep handlers thin: validate → call store → `redirectOK`. Re-render the
  form with `"error"` in the data map on validation failure (4xx status).
- Match the existing comment density; comments explain *why*, not *what*.
- Commit messages: short imperative subject, body explains the reason.

## Things deliberately not built (ask before adding)

Drafts/preview, custom CSS, comments, multiple blogs per user, email,
user self-registration, custom domains per blog, image resizing,
sanitising the custom HTML module (owner's decision, see above).