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`, filename-ordered, tracked in that connection's own
auto-created `schema_migrations` table (each connection's applied
migrations are independent of any other connection's), run once each.
`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. Only `App/migrations/` (the framework default connection's
`migrations_dir`) is scanned by default — the framework ships no core
tables of its own yet — if a future framework feature needs a shipped
migration, extend this to the same App-over-novaconium two-root scan
`Overlay.php` already does for pages/lib, don't invent a second mechanism.

`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.

## 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.