novaconium/AGENTS.md

NovaconiumPHP

A lightweight PHP 8.1+ MVC-ish web framework/CMS toolkit (router + controllers + Twig views + Sass styling), authored by Nick Yeoman (4lt.ca) and distributed via Composer as 4lt/novaconium. The canonical repo is hosted on a self-hosted Gitea instance (git.4lt.ca), not GitHub — do not assume gh CLI or GitHub Actions apply here.

Directory map

• src/ — core framework classes, namespace Novaconium\ (PSR-4 → src/): novaconium.php (bootstrap), Router.php, Database.php, Session.php, Redirect.php, Post.php, Logger.php, MessageHandler.php, functions.php, twig.php, and src/Services/ (Auth.php, TagManager.php).
• controllers/ — framework-level default controllers (dashboard, pages, messages, settings, auth/, sitemap, 404, init, create_admin, etc.).
• config/routes.php — framework-level default route definitions, merged with app-level App/routes.php at runtime.
• views/ — Twig views mirroring controller names (controllers/dashboard.php ↔ views/dashboard.html.twig).
• twig/ — shared/partial Twig templates (layout pieces: master.html.twig, nav.html.twig, head.html.twig, foot.html.twig, cp/ control-panel partials, javascript/).
• sass/ — framework's default Sass source (indented Sass, not SCSS), 7-1-ish structure: abstracts/, base/, framework/, controlPanel/, coming-soon/; has its own Dockerfile for compiling.
• skeleton/ — scaffold copied into a new consumer project on install: .env, docker-compose.yml, novaconium/App/{config.php,routes.php,controllers,views,templates}, novaconium/public/{index.php,.htaccess,css,js}, novaconium/sass/project.sass.
• docs/ — one short Markdown file per topic (see below).
• _assets/ — static assets (e.g. logo used in README).

Build / run (Docker-only — no host tooling assumed)

Agents (Claude Code, opencode, etc.) run inside containers and have no access to Docker. Do not attempt to run any docker/docker compose command below — they will fail. These commands are documented for a human maintainer to run on their own host. If you need to verify a change, do so by reading/reasoning about the code, not by invoking Docker.

Composer (per docs/Composer.md):

docker run --rm --interactive --tty --volume $PWD:/app composer:latest require 4lt/novaconium
docker run --rm --interactive --tty --volume $PWD:/app composer:latest update

Sass build (per docs/Sass.md), using sass/Dockerfile:

cd sass && docker build -t sass-container .
docker run --rm -v $(pwd):/usr/src/app -w /usr/src/app sass-container sass novaconium/sass/project.sass novaconium/public/css/novaconium.css

Compressed variant: add --style=compressed, e.g.

docker run --rm -v $(pwd):/usr/src/app -w /usr/src/app sass-container --style=compressed sass/novaconium.sass skeleton/novaconium/public/css/novaconium.css

Dev stack: docker compose up -d from skeleton/docker-compose.yml — services: 4lights/corxn:8.5.3 (Apache+PHP), redis, mariadb, phpmyadmin.

Testing a cloned copy without reinstalling via Composer: see docs/Dev-Fake_autoload.md for the fake-autoload dev trick.

No test suite / lint / CI

There is no phpunit.xml, no lint config (no PHPCS, .editorconfig, ESLint), and no CI pipeline in this repo. Don't hunt for npm test/phpunit/lint commands — none exist.

Conventions

• PSR-4 autoloading: Novaconium\ → src/.
• Controllers and views are name-paired by default (e.g. controllers/dashboard.php ↔ views/dashboard.html.twig), but this is only a convention — a controller can render any view, they are not required to match.
• Sass partials are prefixed _ (e.g. _forms.sass), aggregated per-folder via index.sass.
• App-level config (App/config.php) is a multi-dimensional PHP array: database credentials, base_url, secure_key, logfile, loglevel.
• Versioning strategy is semantic-versioning (declared in composer.json extra.versioning).

Git workflow

Single master branch (no main), tracking a self-hosted Gitea remote. Solo-maintainer, trunk-based, direct commits to master with short informal messages — no conventional-commits enforcement, no PR-based tooling assumptions.

Further reading

See docs/*.md for per-topic detail: 404.md, Composer.md, ConfigurationFile.md, Dev-Fake_autoload.md, Logs.md, Messages.md, Post.md, Redirect.md, Sass.md, Session.md, StyleSheets-sass.md, Twig-Views.md, docker.md.