novaconium/AGENTS.md

AGENTS.md

Context for any coding agent working in this repo — Claude, DeepSeek, or otherwise. Full narrative docs live at /admin/docs when the app is running. README.md is the GitHub-facing pitch, novaconium/ISSUES.md is the roadmap/backlog, and this file is the short, agent-facing version: load-bearing gotchas and conventions only, not narrative history.

This repo has a graphify knowledge graph (graphify-out/). For design rationale, "why was it built this way," or exploring how components relate, query the graph instead of expecting this file to carry that context — this file is kept intentionally short and only lists things that will cause a bug or a broken convention if you don't know them going in.

Docs live in one place: /admin/docs — README stays thin

Every topic (routing, sidecars, libraries, layouts, caching, SEO, Matomo, admin auth, styling, Docker, project layout, third-party) has exactly one canonical writeup: a page under novaconium/pages/admin/docs/<topic>/index.twig. README.md deliberately does not mirror this content — it's a short GitHub-facing pitch (what this is, minimal steps to get it running, a pointer into /admin/docs) plus the Third-party section, nothing more. The full feature list lives as a blog post, App/pages/blog/novaconium-features/ (sample content, replaceable like any other post), not in the README. This was a deliberate change (2026-07-15) away from an earlier "keep README and docs in sync" convention that had made the README long and hard to scan — don't re-add a feature list or per-topic bullet list to README.md.

Any change to framework behavior or a new feature:

1. Update/add the docs page, and if new, link it from both admin/docs/index.twig and the nav in admin/docs/_layout/layout.twig.
2. Update App/pages/blog/novaconium-features/index.twig (and its entry in App/pages/blog/index.php) if it affects the feature tour.
3. Update README.md only if it affects the one-paragraph pitch, the minimal getting-started steps, or the Third-party section — not a per-feature bullet.
4. Update this file only if it affects a convention an agent needs to know before editing code.

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

• App/ — the project: App/pages/, App/lib/ (Lib\ classes), App/config.php, App/migrations/. The only directory a site author is expected to touch.
• novaconium/ — the framework: router/renderer core (novaconium/src/), default pages/libs (including the css/main.css/, robots.txt/, humans.txt/ bundles), vendored Twig, autoloader, config, bootstrap.

Routing/rendering resolve against both roots, App/ first (via novaconium/src/Overlay.php for pages, novaconium/autoload.php for Lib\ classes) — same override-by-presence mechanism used for config.php and Twig's FilesystemLoader. A project only lists the config keys it's changing in App/config.php; never edit novaconium/config.php directly.

db_connections is the one config key that isn't a plain shallow-merge. Lib\Db::config() (and the duplicate in bin/migrate.php) merges it one level deeper, by connection name, so adding a second connection in App/config.php can't silently delete the framework's default connection. Capture the defaults before the top-level array_merge() overwrites $config['db_connections'], not after. See /admin/docs/database.

Lib\Db supports multiple, simultaneously-open named connections ('sqlite'/'mysql' drivers only). Each connection migrates lazily on first use, tracked by path relative to the repo root (not bare filename — two roots can share a filename). migrations_dir accepts an ordered list of roots, each fully processed before the next.

The default DB path (data/novaconium.sqlite) lives outside public/ (web-accessible) and novaconium/ (wholesale-replaced by framework updates) — it's a project-owned top-level dir, gitignored per-content with a tracked .gitkeep. Uploaded files (see Media manager, /admin/docs/media-manager) live under public/uploads/ instead, since they need to be web-reachable directly — a separate, plain static directory on its own volume, not coupled to the SQLite path, since a project may run MySQL or no DB at all.

Standing rule: caching vs. any content-hiding mechanism

Any mechanism that conditionally hides page content from the public must be threaded into Renderer::render()'s $excludeFromCache param, not just a pre-render auth gate. Renderer::render() writes a sidecar-less page's output to the static HTML cache, and .htaccess serves a cached file before PHP (and therefore any auth check) ever runs again. A route gated only at the auth-check level still leaks to the public the moment an authorized user views it once, if the page has no sidecar. draft_routes and every /admin/* route already pass true for this reason. Any new feature that gates a route by anything other than a sidecar check needs the same treatment — this has caused a real bug before, twice.

Corollary: Lib\Access (the sidecar-level content gate, see /admin/docs/access-control) is safe by construction — a page with no sidecar can't call Access, and only sidecar-less pages get cached, so a gated page can never leak through the cache with no extra wiring needed.

Reentrancy hazard: ContentIndexer

ContentIndexer::reindex() renders every routable page, including /search itself, which also calls ContentIndexer::ensureFresh(). Guarded by a private static bool $indexing flag checked at the top of both methods — don't remove it, any new consumer route inherits the same hazard automatically. reindex() also forces $_SERVER['REQUEST_METHOD'] to 'GET' for the duration of the crawl (restored in a finally) so a lazy reindex triggered from a POST can't leak that POST into an unrelated page's sidecar.

Vendored dependency placement

Server-side-only (PHP, autoloaded) → novaconium/vendor/. Anything a browser fetches (.js, .css, images) → public/vendor/ — novaconium/ is never web-reachable. This matters beyond correctness: public/ is project-owned and untouched by a framework update, so a public/vendor/ dependency bump does not propagate automatically the way a novaconium/vendor/ bump would — re-vendoring is a manual step per dependency (see /admin/docs/upgrading-highlightjs).

Twig gotchas that will fatal without mbstring

Don't use |slice on a string (calls mb_substr() unconditionally) or |escape('js')/'js' arg to |e (calls mb_ord()) — both hard-require mbstring and fatal without it; this project deliberately avoids that dependency. Truncate strings in PHP with an mb_substr/substr fallback instead. For markup destined for inline <script>, render into a <template> element and read .innerHTML in JS rather than |escape('js').

class="nohighlight" marks a <pre><code> block containing literal Twig syntax ({% %}/{{ }}) — highlight.js has no Twig grammar and a restricted auto-detect still always guesses wrong without this class. Any new Twig-syntax code sample needs it; PHP/Bash samples don't.

Typed text pages (CSS, robots.txt, humans.txt, …)

A sidecar-less page bundle whose directory segment ends in an extension in App\MediaType::MAP (.txt .css .xml .json .js) is a typed text page: Renderer renders its index.twig with no HTML layout and autoescaping off, serves it with that extension's Content-Type, and Cache writes it as a flat file (public/cache/css/main.css, not .../index.html). A rewrite in public/.htaccess (rule 2b) then serves that file straight from Apache on every later request — so the extension list is duplicated there; keep it in sync with MediaType::MAP. These pages are excluded from the content index (ContentIndexer::isCrawlable()). See /admin/docs/text-pages.

The framework ships three: novaconium/pages/css/main.css/ (route /css/main.css), novaconium/pages/robots.txt/, novaconium/pages/humans.txt/. A project overrides one the normal App-over-novaconium way — put its own bundle at the same relative path under App/pages/.

CSS is the interesting one: novaconium/pages/css/main.css/ holds index.twig ({{- sass('main.sass') -}}), main.sass, and _colors.sass. The sass() Twig function (App\SassExtension → Lib\SassCompiler) resolves the entry file through the overlay (App first) and shells out to Dart Sass with that file's own directory as the sole --load-path, so @use 'colors' resolves to the sibling _colors.sass in whichever copy of the bundle won. To customise styling, copy the whole css/main.css/ bundle to App/pages/css/main.css/ — there's no partial "just _colors.sass" override. Output is cached like any typed page; run php novaconium/bin/clear-cache.php after editing Sass. Every color rule reads a CSS custom property (var(--bg) …), never a Sass variable directly — required for the runtime dark/light toggle; adding a color means adding its plain and -light variable in _colors.sass and wiring both into the two :root blocks in main.sass.

Input handling

Sidecars read request data via Lib\Input::post()/::get(), not $_POST/$_GET directly (trims, strips tags/null bytes — XSS defense-in-depth, not SQL-injection protection; use PDO prepared statements via Lib\Db::query() for that, never string-interpolated SQL). Exception: fields needing an exact unmodified value (e.g. a password about to be hashed) read $_POST directly — see login/users sidecars. Lib\Csrf::verify() is called directly by a sidecar, not wired into FormValidator.

Running it

Only via the Docker image built from Dockerfile (Apache reads public/.htaccess directly — there is no php -S dev router). Typically:

docker compose up   # image + volumes from docker-compose.yml

There is no test suite — verification is manual route-by-route (see /admin/docs/design-notes's Verification section). After testing, clear stray cache with php novaconium/bin/clear-cache.php and remove any test-only debris from App/lib//App/pages/ — nothing there is gitignored except public/cache/* and novaconium/contact-log.txt.

Conventions worth knowing

• Reserved segments: any path segment starting with _ or literally named 404 is never routable — Router::resolve() 404s on sight.
• Sidecars (index.php) return an array (Twig context) or a Response. $params and $cache are in scope automatically — see novaconium/src/Renderer.php::runSidecar().
• No Composer — novaconium/autoload.php is a hand-rolled PSR-4 loader. A new framework-core class goes under App\ in novaconium/src/; a new Lib\ class goes in App/lib/ or novaconium/lib/.
• novaconium/bin/ holds standalone CLI entry points (php novaconium/bin/<script>.php) — distinct from bootstrap.php/autoload.php/config.php, which are only require'd.
• CSS is a typed text page (see that section above), not a build artifact: the Sass lives in novaconium/pages/css/main.css/ (override at App/pages/css/main.css/) and is compiled on demand by the sass() Twig function, cached to public/cache/css/main.css. There is nothing to pre-build or commit. The Docker image ships Dart Sass standalone (pinned DART_SASS_VERSION in the Dockerfile, symlinked to /usr/local/bin/sass) as a runtime dependency. See /admin/docs/styling and /admin/docs/text-pages.