novaconium/AGENTS.md

# AGENTS.md

Context for any coding agent working in this repo — Claude, DeepSeek, or
otherwise; this file (and the maintenance rule below) applies regardless of
which model or CLI is driving. Full narrative docs live at `/admin/docs`
when the app is running (also the *only* place Twig upgrade instructions
live now — see `/admin/docs/upgrading-twig`; there's no separate
MAINTENANCE.md, keeping one copy in the docs page avoids drift). `README.md`
is the GitHub-facing pitch, `novaconium/ISSUES.md` is the roadmap/backlog,
and this file is the short, agent-facing version. The original design
rationale used to live in a standalone `plan.md`; it's now folded into
`/admin/docs/design-notes` (everything in it shipped) and the file was
deleted. There used to also be a
`GUIDE.md` mirroring `/admin/docs` for offline reading — it was removed to
cut a doc copy that had to be kept in sync; `/admin/docs` is the only
narrative reference now.

## Documentation is duplicated on purpose — keep all copies in sync

Every topic (routing, sidecars, libraries, layouts, caching, SEO, Matomo,
admin authentication, styling, project layout, third-party) exists in
**two** places: a page under `novaconium/pages/admin/docs/<topic>/index.twig`
(the canonical reference), and (for anything a README-reading human needs
up front) a mention in `README.md`. This is intentional — `/admin/docs` is
for reading against a running instance with no internet needed, and
`README.md` is the GitHub-facing pitch — but it means **any agent that
changes framework behavior or adds a feature must update both copies in
the same change**, not just the one that was open. Concretely, after
touching routing/rendering/caching/SEO behavior or adding a new top-level
docs topic:

1. Update (or add) the matching page under
   `novaconium/pages/admin/docs/<topic>/index.twig`, and if it's a new
   topic, link it from both `admin/docs/index.twig` and the nav in
   `admin/docs/_layout/layout.twig`.
2. Update `README.md` if the change affects the feature list, getting
   started steps, or the docs index there.
3. Update this file if the change affects a convention an agent needs to
   know before editing code (not just narrative docs).

A doc change that only touches one of these copies is incomplete —
verify the other copy before considering the task done.

## What this is

A dependency-light PHP + Twig micro-framework: directories under `pages/`
map directly to URLs (Hugo-style page bundles), optional `index.php`
sidecars supply data or short-circuit to a `Response`, and sidecar-less
pages get pre-rendered to static HTML on first request and served straight
from Apache after that. No Composer, no build step to install — Twig is
vendored as plain source files.

## The two-root split — read this before editing anything under `pages/` or `lib/`

Everything lives in one of two places:

- **`App/`** — the actual project: `App/pages/` (routes/content) and
  `App/lib/` (project's own `Lib\` classes). This is the only directory a
  site author is expected to touch.
- **`novaconium/`** — the framework itself: router/renderer core
  (`novaconium/src/`), default pages (`novaconium/pages/` — root layout,
  404, the `/admin` tools), default `Lib\` classes (`novaconium/lib/`),
  vendored Twig, autoloader, config, bootstrap.

Routing and rendering resolve against **both roots, in order** —
`App/pages/` first, `novaconium/pages/` as fallback — via
`novaconium/src/Overlay.php`. Same mechanism for `Lib\` classes:
`App/lib/` is checked before `novaconium/lib/` in `novaconium/autoload.php`.
Concretely: dropping a file at the same relative path in `App/` overrides
the `novaconium/` default; nothing needs to be duplicated for the site to
work, since `novaconium/pages/` already supplies a working layout and 404.

Twig's `FilesystemLoader` is constructed with both paths as an array, so
`{% extends %}` / `{% include %}` get this override-then-fallback
resolution for free — no custom logic needed there.

The same override-by-presence pattern applies to `novaconium/config.php`:
if `App/config.php` exists, `novaconium/bootstrap.php` and
`novaconium/bin/clear-cache.php` shallow-merge it over the framework defaults
with `array_merge()`. A project only needs to list the keys it's changing
— never edit `novaconium/config.php` directly.

`config['matomo_url']` / `config['matomo_site_id']` (both default `''`)
gate the Matomo tracking script emitted by the root layout — set both via
`App/config.php` to enable it, since either being empty disables tracking
entirely. `bootstrap.php` normalizes a missing trailing slash on
`matomo_url` before passing it to `Renderer`, which exposes `matomo_url`,
`matomo_site_id`, and `is_404` as Twig globals (`is_404` is overridden to
`true` in the 404 template's local render context by
`Renderer::renderNotFound()`, per Twig's local-context-over-global
precedence). Any new Twig global added to `Renderer`'s constructor should
follow this same pattern: default value, `addGlobal()` call, documented
here and in `/admin/docs`.

`config['site_name']` (default `'My Site'`) is the same pattern — passed to
`Renderer` and exposed as the `site_name` Twig global, used by
`novaconium/pages/_layout/layout.twig` for the default `title` block,
`og:site_name`, and the footer copyright line. Any other hardcoded
site-identity string that shows up in a shared template (as opposed to a
per-page override) should become a `config.php` key the same way, not stay
hardcoded in the template.

`config['admin_username']` / `config['admin_password_hash']` (username
defaults to `'admin'`, password hash defaults to `''`) gate every
`/admin/*` route behind HTTP Basic Auth — this replaced the old
`docs_enabled` flag entirely (removed); a single gate over all of
`/admin/*` (docs included) made a docs-only toggle redundant. Unlike the
Twig-global pattern above, the gate itself is enforced in `bootstrap.php`,
before rendering: `AdminAuth::requireLogin(...)`
(`novaconium/src/AdminAuth.php`) is called once for any resolved route
whose path is `admin` or starts with `admin/`. **Any new admin page
dropped under `App/pages/admin/` or `novaconium/pages/admin/` is
automatically protected — no per-page wiring needed.** `bootstrap.php`
also special-cases the literal path `/admin/logout` *before* router
resolution — no page exists there — to call `AdminAuth::logout()`, which
always issues a fresh 401 so the browser drops its cached credentials
(there's no server-side session to invalidate). `Renderer` separately
exposes an `admin_auth_enabled` Twig global (true when a password hash is
set) so `admin/index.twig` can conditionally show the "Logout" link — this
is a derived display flag, not the enforcement mechanism itself, which
never depends on Twig. `novaconium/pages/admin/password-hash/` is a
built-in `password_hash()` form (no CLI needed) for generating
`admin_password_hash` — a normal admin page, so it's covered by the same
gate: reachable while no password is set yet (to generate the first
one), then protected like everything else under `/admin/*` afterward. It
computes and displays the hash per-request only; nothing is persisted or
logged. This is a single-user HTTP Basic Auth stopgap, not
the full multi-user system tracked in `novaconium/ISSUES.md` ("Admin login & user
management"); don't extend this class toward multi-user/session-based
auth — that's a separate, larger feature that
will replace it.

`Lib\Db` (`novaconium/lib/Db.php`) is the SQLite/MySQL groundwork tracked
in `novaconium/ISSUES.md` — a thin, no-ORM PDO wrapper, `Lib\` (not `App\`)
so a project can override it via `App/lib/Db.php` like any other `Lib\`
class. It supports multiple, independently-configured, **simultaneously
open** named connections (`config['db_connections']`, keyed by name) rather
than one global connection — because sidecars are plain PHP with full
access to any `Lib\` class, a single request can legitimately need more
than one database at once (e.g. this site's own SQLite data alongside a
MySQL connection to a legacy database). `Db::query(string $sql, array
$params = [], string $connection = 'default')` (prepare+execute) is the
only query-running helper — never add a string-interpolation shortcut; see
`Lib\Input`'s doc-comment, which already commits this project to
parameterized queries as the sole SQL-injection defense. Each connection is
lazy and independent (opened on first `Db::query()`/`Db::connection()` call
naming it, same shape as `Lib\Csrf`'s lazy session start), and migrates
automatically at that point: plain `.sql` files under that connection's own
`migrations_dir` — a single path, or (since the content index shipped) an
**ordered list of roots**, each root's own files filename-ordered and
roots processed fully in the order given, not interleaved by filename
across roots (so a framework root always finishes before a project root on
the same connection). Tracked by path **relative to the repo root** (e.g.
`novaconium/migrations/0001_x.sql`), not bare filename — two roots can
each contain a same-named file, and tracking by bare filename would make
the second one seen look "already applied" and silently skip it; a
repo-relative path is also portable across environments, unlike a full
absolute path, which would make every migration look new again after a
clone/deploy to a different directory. `realpath()` normalizes any `..` a
`migrations_dir` like `__DIR__ . '/../App/migrations'` would otherwise
leave in the tracked name. Each connection's own auto-created
`schema_migrations` table tracks its migrations independently of any other
connection's; each is only ever run once. `novaconium/bin/migrate.php`
loops every configured connection and runs the same migration step
explicitly (e.g. from a deploy script) without serving a request first.
Only `'sqlite'` and `'mysql'` drivers are implemented; a connection's
`migrations_dir` is optional — omit it to never run migrations against
that connection (e.g. a legacy database this project shouldn't manage
schema for).

**`db_connections` is the one config key in the project that isn't plain
shallow-merge** — `bootstrap.php`/`bin/*.php`'s usual `array_merge($config,
$appConfig)` would let a project's `App/config.php` silently delete the
framework's `default` connection just by adding a second named connection
(a shallow merge replaces the whole key, it doesn't merge inside it). So
`Lib\Db::config()` (and the copy of this logic duplicated in
`bin/migrate.php`, same duplication precedent as the two-step config load
already duplicated across `bootstrap.php`/`bin/clear-cache.php`) merges
`db_connections` one level deeper, by connection name, **after** capturing
the framework defaults — capture the defaults *before* the top-level
`array_merge()` overwrites `$config['db_connections']`, not after, or the
deeper merge silently operates on the already-overwritten value and the
`default` connection vanishes anyway. (This exact bug was hit once while
building this feature — verified by testing a real `App/config.php`
override end-to-end, not just reading the code — so it's worth re-checking
by hand if this logic is ever touched again.) See
`/admin/docs/database` for the worked example.

**`config['db_connections']['default']['path']` must stay outside both
`public/` (would be web-accessible) and `novaconium/`** — unlike
`cache_dir`/`contact-log.txt`, which are disposable, a SQLite file is data a
project can't afford to lose, and `novaconium/` gets wholesale-replaced by
the "Updating the framework" workflow (`/admin/docs/getting-started`: `rm
-rf novaconium && cp -r <new-novaconium>`). The default
(`data/novaconium.sqlite`) lives in a new top-level `data/` directory
instead — project-owned like `App/`, gitignored per-file
(`*.sqlite`/`-journal`/`-wal`/`-shm`, with a tracked `.gitkeep` so the
directory exists in a fresh clone) rather than wholesale like
`public/cache/`, since a project might reasonably want other non-DB files
there later. The default connection's `migrations_dir` scans
`novaconium/migrations/` (framework-shipped schema, e.g. the content
index below) before `App/migrations/` (project schema) — see the
`migrations_dir` array-form paragraph above. Any *other* connection a
project adds still defaults to no `migrations_dir` at all unless it sets
one; the two-root default is specific to `default`.

`Lib\Session` (`novaconium/lib/Session.php`) is a thin wrapper around
native PHP sessions (`session_start()`/`$_SESSION`, not a custom store),
all-static and lazy-start like `Lib\Csrf` — nothing calls `session_start()`
until the first real call to a `Session` method. Its `ensureSession()` is a
**deliberate duplicate** of `Csrf::ensureSession()` (same cookie params,
same `session_status()` guard) rather than a shared helper — keeps `Csrf`
standalone with zero new dependencies on a class that didn't exist when it
shipped, same tolerance for small duplication already established by the
config-load block duplicated across `bootstrap.php`/`bin/clear-cache.php`/
`Lib\Db::config()`. Both classes touching the same native session in the
same request is safe either way, since `session_start()` silently no-ops
if a session is already active — there's no ordering requirement between
`Csrf::token()`/`::verify()` and any `Session` method.

Flash data (`Session::flash()`/`::getFlash()`) is one swap, not a
sweep/expiry pass: the first `Session` method call in a request snapshots
whatever was flashed on the *previous* request into an in-memory static
(`self::$currentFlash`) for that request's `getFlash()` reads, then
immediately empties the stored flash bucket so `flash()` calls made
*during* the current request start filling a fresh bucket for the request
after this one. This relies on static properties not persisting across
requests (true under `php -S`, mod_php, and PHP-FPM alike — each request
gets fresh PHP state regardless of worker-process reuse) — don't add any
caching/memoization to `Session` that assumes static state survives
between requests, since none of it does. See `/admin/docs/session` for a
worked flash example.

**Standing rule: any mechanism that conditionally hides page content from
the public must also be threaded into `Renderer::render()`'s
`$excludeFromCache` decision, not just a pre-render auth gate.** This
bit twice already — once as a designed-around gotcha (draft pages), once
as a real pre-existing bug found while testing that feature (`/admin/*`
itself). The reason: `Renderer::render()` writes a sidecar-less page's
output to the static HTML cache (`novaconium/src/Cache.php`), and
`.htaccess` serves a cached file *before PHP, and therefore any auth
check, ever runs again* (see `/admin/docs/caching`). A route can be
gated by `AdminAuth::requireLogin()`/`::isAuthenticated()` and still leak
completely to the public the moment it's viewed once by someone
authorized, if the page has no sidecar and nothing tells `Renderer` to
skip the cache write for that route. `draft_routes` (see
`/admin/docs/drafts`, `novaconium/config.php`) and every `/admin/*` route
both pass `true` for `Renderer::render()`'s `$excludeFromCache` param
from `novaconium/bootstrap.php` for exactly this reason — most pages
under `novaconium/pages/admin/` (e.g. `admin/index.twig`) have no
sidecar, so before this was wired up, visiting `/admin` once as an
authenticated admin would cache the admin panel and serve it to every
subsequent visitor, unauthenticated, straight from `public/cache/admin/`.
Any future feature that gates a route by anything other than a sidecar
check (paywall content is the next one on the roadmap likely to hit this)
needs to make the same check here, not just at the point where the
request is first authorized.

`AdminAuth::isAuthenticated(string $username, string $passwordHash): bool`
(`novaconium/src/AdminAuth.php`) is the credential check on its own, with
no response side effects, extracted out of `requireLogin()` (which still
does the same check, then issues the `401` challenge on failure) so a
different caller can react to failure differently. The draft-page gate in
`bootstrap.php` is the first such caller: on failure it renders a plain
404 via the same path an unmatched route takes, not a login prompt —
prompting for credentials at a draft URL would itself reveal that
something is gated there, which defeats the point of hiding it. Returns
`true` (open access) when `$passwordHash` is empty, mirroring
`requireLogin()`'s existing no-op-when-unset posture, so a draft behaves
consistently with the rest of `/admin/*`: wide open until a password is
configured, gated once one is.

`App\ContentIndexer` (`novaconium/src/ContentIndexer.php`) is the shared
crawler behind `/sitemap.xml`, `/search`, and blog tag browsing (see
`/admin/docs/content-index`) — `App\`, not `Lib\`, since it's rendering
infrastructure akin to `Renderer`/`Router`, not project-overridable
content. Content stays in files; only metadata is indexed. Per-page
metadata is four Twig blocks declared in the root layout next to the SEO
blocks (`keywords`, `tags`, `changefreq`, `priority` — the last three
never rendered into the page, only harvested) and pulled via
`Renderer::renderForIndex()`, which calls Twig's own
`TemplateWrapper::renderBlock()` per block rather than parsing `.twig`
source — this is deliberate: it gets App-over-novaconium override and
layout-inheritance resolution for free, the same way a real render does.
**`config['content_index_enabled']` defaults to `false`** — same posture
as `matomo_url`/`admin_password_hash`, since this is a real SQLite
dependency plenty of sites won't want. Every consumer route checks the
flag *before* touching `Lib\Db` and 404s if it's off, so the feature has
zero filesystem footprint (no `data/novaconium.sqlite`) when disabled —
verified end-to-end, not assumed, since "off" silently still creating a
database file would defeat the point.

**Reentrancy hazard, already hit once:** `ContentIndexer::reindex()`
renders every routable page as part of the crawl — including `/search`
itself, which is also a real page and also calls
`ContentIndexer::ensureFresh()` from its own sidecar. Without a guard,
crawling `/search` would trigger a nested `reindex()` call mid-transaction
and fatal on a second `PDO::beginTransaction()`. `ContentIndexer` guards
this with a `private static bool $indexing` flag, checked at the top of
both `ensureFresh()` and `reindex()` — either no-ops while a reindex is
already running on the call stack. Any future consumer route added under
this mechanism inherits the same hazard for free (it'll also get crawled,
and if its sidecar also calls `ensureFresh()`, the guard already covers
it) — don't remove the flag thinking it's unnecessary.

`reindex()` also forces `$_SERVER['REQUEST_METHOD']` to `'GET'` for the
duration of the crawl (restoring whatever it was before, in a `finally`)
— sidecars are expected to be side-effect-free for non-POST requests
anyway (ordinary HTTP-safe-method hygiene), but this guarantees a lazy
reindex triggered from within a POST request can never leak that POST
into an unrelated page's sidecar purely because the crawler happened to
render it. A crawl is a full truncate-and-rebuild inside one transaction,
not incremental — simple and correct at this site's scale; don't add
incremental/diffing logic without a real need for it.

## Running it

```
php -S 127.0.0.1:8000 -t public public/router.php
```

`public/router.php` is dev-only, mimics `public/.htaccess`. There is no
test suite — verification is manual route-by-route (see
`/admin/docs/design-notes`'s Verification section for the checklist used
after any framework change).
After testing, clear stray cache with `php novaconium/bin/clear-cache.php` or
POST `/admin/clear-cache`, and remove anything written to `App/lib/` or
`App/pages/` that was only for testing an override — nothing here is
gitignored except `public/cache/*` and `novaconium/contact-log.txt`, so
test debris left in `App/` will otherwise get committed or silently change
site behavior for the next person.

## Conventions worth knowing

- Reserved segments: any path segment starting with `_` (e.g. `_layout/`)
  or literally named `404` is never routable — `Router::resolve()` 404s on
  sight, don't try to serve content directly at those paths.
- Sidecars (`index.php`) return either an array (Twig context) or a
  `Response` (redirect/json/xml/html — `novaconium/src/Response.php`).
  `$params` (route captures) and `$cache` (the `Cache` instance, e.g. for
  `$cache->clear()`) are both in scope automatically — see
  `novaconium/src/Renderer.php::runSidecar()`.
- No Composer — `novaconium/autoload.php` is a hand-rolled PSR-4 loader.
  Adding a new framework-core class means adding it under `App\` in
  `novaconium/src/`; a new `Lib\` class goes in `App/lib/` or
  `novaconium/lib/` depending on whether it's project- or
  framework-specific.
- `novaconium/bin/` holds standalone CLI entry points meant to be run
  directly (`php novaconium/bin/<script>.php`) — distinct from
  `bootstrap.php`/`autoload.php`/`config.php`, which are only ever
  `require`'d, never invoked directly. `clear-cache.php` and
  `create-static-page.php` (scaffolds a new page from the `/admin/docs/seo`
  starter template) both live there; a new CLI tool goes there too.
- CSS is compiled from `novaconium/sass/main.sass` (indented syntax) to
  `public/css/main.css`. `dart-sass` is installed in this environment
  (Arch: `pacman -S dart-sass`) — after editing Sass source, run:
  `sass --load-path=App/sass --load-path=novaconium/sass/defaults --no-source-map novaconium/sass/main.sass public/css/main.css`
  and commit the regenerated `public/css/main.css` (`--no-source-map`
  avoids a stray `main.css.map` the project doesn't otherwise use). If
  `sass` isn't available in whatever environment you're in, either run it
  via Docker — `/admin/docs/styling` has a copy-pasteable
  Dockerfile that installs the same standalone Dart Sass release used in
  this environment (`1.101.0`) directly from GitHub, not via npm, plus
  the `docker build`/`docker run` commands adjusted to this repo's paths
  — or hand-edit both files in parallel and keep them in sync — that's
  how the dark/teal theme and the homepage hero/animation
  styling were originally written before `sass` was installed here.
- The Sass color palette follows the same App-over-novaconium override
  pattern as pages/lib, but with a twist worth understanding before
  touching it: `novaconium/sass/main.sass` does `@use 'colors' as *`, and
  its own directory (`novaconium/sass/`) deliberately has **no**
  `_colors.sass` sibling. Dart Sass resolves a bare `@use` relative to the
  importing file's own directory *before* consulting `--load-path`
  entries, so if `novaconium/sass/_colors.sass` existed next to
  `main.sass`, it would always win regardless of load-path order —
  silently defeating the override. Keeping the framework default at
  `novaconium/sass/defaults/_colors.sass` (a different directory) forces
  resolution through the load path, where `App/sass` (checked first) can
  actually override it with `App/sass/_colors.sass`. Don't move
  `defaults/_colors.sass` back next to `main.sass` — it was moved out on
  purpose, and doing so reintroduces this bug.
- Every color rule in `main.sass` reads a CSS custom property
  (`var(--bg)`, `var(--accent)`, etc.), never a Sass variable directly —
  that indirection is what makes the dark/light theme toggle possible,
  since Sass only runs at compile time and can't react to a runtime
  choice on its own. The two `_colors.sass` files seed `:root` (dark,
  the default) and `:root[data-theme="light"]` (via `-light`-suffixed
  variables — `$bg-light`, `$accent-light`, etc., same files, same
  override mechanism) once at compile time; the toggle button in
  `novaconium/pages/_layout/nav.twig` flips the `data-theme` attribute on
  `<html>` at runtime and persists it to `localStorage`.
  `novaconium/pages/_layout/theme-init.twig` re-applies a saved choice
  early in `<head>` (before the stylesheet link) to avoid a flash of the
  wrong theme on load. If you add a new color to the palette, add both
  the plain and `-light` variable in **both** `_colors.sass` files and
  wire it into both `:root` blocks in `main.sass` — a color that's only
  themed in one direction will look wrong after a toggle.
- Sidecars should read request data via `Lib\Input::post()`/`::get()`
  (`novaconium/lib/Input.php`) rather than `$_POST`/`$_GET` directly — it
  trims, strips tags, and strips null bytes automatically. This is
  defense-in-depth against HTML/script injection, **not** SQL-injection
  protection (no string transform makes input safe to concatenate into a
  query — use PDO prepared statements once a database layer exists); don't
  add an `sqlSafe()`-style method to `Input`. One documented exception: a
  field needing an exact, unmodified value (e.g. a password about to be
  hashed) should read `$_POST` directly instead — see
  `novaconium/pages/admin/password-hash/index.php`. `Lib\Csrf`
  (`novaconium/lib/Csrf.php`) is standalone session-token CSRF protection, not
  wired into `FormValidator` — a sidecar calls `Csrf::verify()` directly.
  It's the first thing in the framework to start a native PHP session (only
  lazily, when a form actually calls it), which is otherwise unrelated to
  `AdminAuth`'s own session-free Basic Auth.
- Don't use Twig's `|slice` filter on a **string** (as opposed to an
  array) — it unconditionally calls PHP's `mb_substr()` with no fallback
  (`novaconium/vendor/twig/src/Extension/CoreExtension.php`), which
  hard-requires the `mbstring` extension and will fatal
  (`Call to undefined function Twig\Extension\mb_substr()`) on a PHP
  install without it — a real regression this project hit once already,
  back when `/blog/hello-world` had a sidecar computing an excerpt this
  way (see the footnote on `App/pages/blog/twig-syntax-guide/index.twig`
  for the full story). Truncate strings in PHP instead, guarded with
  `function_exists('mb_substr')` falling back to `substr()`, and pass the
  already-truncated value into the template.
- Same class of bug, different filter: don't use Twig's `|escape('js')` (or
  the `'js'` arg to `|e`) either — it calls `Twig\Runtime\mb_ord()`
  (`novaconium/vendor/twig/src/Extension/EscaperExtension.php`), which
  hard-requires `mbstring` the same way `|slice` does, and fatals
  identically without it. Hit for real when
  `novaconium/pages/_layout/code-copy.twig` used it to pass SVG icon
  markup into an inline `<script>` as a JS string literal. Fixed by not
  needing string-escaped markup in JS at all: render the markup as plain
  HTML into a `<template>` element (default autoescaping, no mbstring
  dependency) and read it in JS via that template element's `.innerHTML`
  getter instead. Prefer that pattern — or a `data-*` attribute if the
  value is plain text, not markup — over `|escape('js')` any time a Twig
  value needs to reach JS.