# Squire: everything in one file
> Squire is the deploy kit for Citadel. It writes your app's build, release and health-check scripts from templates, and checks them with squire doctor. Running the app on your computer is Parity's job.
The README and the Markdown twin of every page, joined. The index is https://squire.apps.wayne.edu/llms.txt. Written by Squire's agent-ready kit; do not edit.
---
## README
Source: https://github.com/waynestate/squire/blob/HEAD/README.md
## Squire
**Suits you up for deploy day.** A squire carries the kit, readies the armor and gets the knight on the field.
Documentation: [squire.apps.wayne.edu/docs/](https://squire.apps.wayne.edu/docs/)
Checks: `composer ci` (the same command runs on GitLab and GitHub).
Squire is the Citadel kit: build.sh, the release script and the health check, from templates, checked by `squire doctor`. Its docs builder turns `docs/` into the committed pages under `site/docs/`, with a changelog page generated from `CHANGELOG.md` when the nav lists one. It is part of WELD, the Wayne State application stack, beside WayneUI (project 0, the interface layer), CREED, PROCTOR, Preflight, SESAME, HELMET, Pinstripe, Sourdough and [Parity](https://git.wayne.edu/enterprise-apps/parity). Squire gets the app onto Citadel; Parity runs Citadel on your computer, and took over from Squire's own parity kit, which left in 0.12.0 (see [Moved to Parity](https://squire.apps.wayne.edu/docs/guides/local-parity.html)).
**Not to be confused with:** `squire doctor` checks deploy setup only; standards checks are PROCTOR's.
> A knight never suits up alone. Your app shouldn't deploy alone either.
Front page: [`site/index.html`](https://github.com/waynestate/squire/blob/HEAD/site/index.html), a static page you can serve from anywhere.
On Citadel it is served by the raw-PHP deploy layer in [`deploy/`](https://github.com/waynestate/squire/blob/HEAD/deploy/): a Squire kit whose front controller serves `site/` behind HELMET's security headers. For local development, keep serving `site/` directly.
Status: 0.12.0, tagged and on Packagist.
### Where the code lives
The canonical repository is [git.wayne.edu/enterprise-apps/squire](https://git.wayne.edu/enterprise-apps/squire); clone it over SSH as `git@git.wayne.edu:enterprise-apps/squire.git` or over HTTPS as `https://git.wayne.edu/enterprise-apps/squire.git`. Open issues and merge requests there; tags are cut there, by a maintainer, with an approver.
GitHub ([waynestate/squire](https://github.com/waynestate/squire)) is a read-only push mirror of it: Packagist reads from it, and nobody pushes to it.
Your squire serves one banner, and it flies over git.wayne.edu.
### Docs
The pages under `docs/` build into the committed site at `site/docs/`: rebuild with `composer docs`, check with `composer docs:check`.
### What it does
- `squire init` writes the scripts a Citadel app needs from templates, for raw PHP, Laravel or a static site, and detects
a Vue/Inertia layer from `package.json`, adding the layer's `.npmrc`. `squire init
--check` reports when your copies have drifted from the templates (depend, do not copy). In a directory below the
repository root (a `deploy/` layer, say), `init` also keeps the `.gitignore` honest: it appends `/vendor/`, `.env` and
`.env.squire` when they are missing, never touches a line the app added, and leaves the repository root's `.gitignore`
to the app.
- `squire update` takes the new template versions for the files you never edited, writes the template files a newer
release added to a group the kit records (recording them in `.squire.json`), and shows a diff for the ones you did.
It never overwrites your edits, and it runs the same in CI and on a laptop.
- `squire doctor` checks an app against the best practices a machine can decide ([BEST_PRACTICES.md](https://github.com/waynestate/squire/blob/HEAD/BEST_PRACTICES.md)).
The lock file, composer audit and MySQL 5.6 checks are owned by PROCTOR; `doctor` hands off to it (S50) instead of repeating them.
- `squire facts` fills the marked `squire-facts:` regions in your files from the committed `.squire/facts.json`
snapshot; `squire facts --check` writes nothing and exits `1` when a region has drifted, so CI can gate on it.
`squire facts --snapshot` rebuilds the snapshot itself from the CREED policy and the ADVISOR project data in
vendor, so a scheduled bot can keep it honest while CI only checks.
- Opt-in image files (`--only=release,images`): a mirror of Citadel's image, a fallback base for machines without it,
and a portable image for OpenShift, Coolify and raw Docker. Running Citadel on your computer is
[Parity](https://git.wayne.edu/enterprise-apps/parity)'s job; Squire's own parity kit left in 0.12.0.
- Squire's maintainers send platform improvement proposals to the platform team privately. Squire never touches a server.
### Install
```
composer require waynestate/squire --dev
vendor/bin/squire init
vendor/bin/squire doctor
```
PHP `^8.3`. Tested on 8.3, 8.4 and 8.5. The package runs on your machine or in CI, not on Citadel; what lands on Citadel
is the scripts it wrote.
### Update notice
After any command finishes, Squire prints one line on stderr when a newer stable release exists, with the command that
updates this install: `squire 0.11.2 is out of date: 0.11.3 is the newest release. Update: composer update
waynestate/squire`. It asks Packagist at most once a day per machine and keeps the answer in the user cache dir
(`waynestate/squire/update-check.json`), so an offline machine stays quiet and tries again the next day. Nothing is
printed when `CI` is set to anything other than empty, `0` or `false`, when `WAYNE_NO_UPDATE_CHECK=1`, when the command
runs with `--quiet` or `-q`, or when the running copy is not a plain release; stdout and exit codes are never touched.
### Commands
```
vendor/bin/squire init [--path=.] [--target=auto|raw|laravel|static] [--only=release|images] [--check] [--force]
vendor/bin/squire update [--path=.] [--target=raw|laravel|static] [--only=release|images] [--dry-run]
vendor/bin/squire doctor [--path=.] [--format=text|json]
```
Exit codes: `0` pass, `1` findings (`init --check`: drift; `update`: an edited file still differs from the template;
`doctor`: a failed rule), `2` the tool itself could not run.
`vendor/bin/squire doctor oracle` runs the same plain-language Oracle connection check that `release.sh` runs on
Citadel, from your terminal or `sail php vendor/bin/squire doctor oracle`. It reads the `ORACLE_*` settings from the
environment and the app's `.env`, prints setting names and never values, and stays silent when the app has no Oracle
settings. Add `-v` for the client version.
`init` never overwrites a file you edited, or a file it did not write, unless you pass `--force`. It records a SHA-256 of
each file in `.squire.json`; commit that file. A fresh `init` writes the Citadel scripts (the `release` group); `--only=release,images`
adds the image files. `--only=parity` exits 2: the parity kit left in 0.12.0. On an app that still has its files,
`init` and `update` list them as `kit-leftover`, drop them from `.squire.json` and delete none, and end with one line
that points at `parity init --from-squire`; `doctor` notes them under S35.
The release installs from the lock file, so when the app has no `composer.json` or no `composer.lock`, `init` ends with a "Heads up" line: commit both before the first deploy (`composer init`, then `composer update`), or the release stops at step 1.
A Vue/Inertia app is a layer on `raw`, `laravel` or `static`, not a fourth target: `init` detects `vue` in `package.json`
(dependencies or devDependencies) and writes the layer's `.npmrc` beside the target's files.
Every app, Vue or not, gets the one common `scripts/release.sh`, which installs the frontend from the lock file and runs
the `build` script whenever there is a `package.json`.
A raw PHP app (`--target=raw`, the default without an `artisan` file) gets a front controller, `public/index.php`, and an
`.htaccess` that sends every request to it. The front controller has three answers:
- a real file in `public/` (CSS, images, fonts, an HTML page) is served with its type and an ETag: images and fonts
keep an hour of cache, while scripts, styles and data revalidate on every load (`no-cache`, a 304 when nothing
changed), so a fresh page never runs last release's script; with HELMET's headers when HELMET is installed, and HELMET's CSP nonce on every `` of an HTML page;
- a 404 for a dot file (`.htaccess`, `.git`), a NUL byte, a path that climbs out of `public/`, any `.php` or `.phar`
other than the front controller, and any file that is not a site asset (a `.sql` dump, a `.bak`, a `.md` with no
`.html` beside it);
- everything else goes to the app's entry: `app.php` beside `public/`, or the file `SQUIRE_APP_ENTRY` names (relative to
the app directory, for example `src/bootstrap.php`). A `POST`, `PUT` or `DELETE` always goes to the entry.
The entry is the only PHP file the front controller runs, and it must sit inside the app directory and end in `.php`;
anything else is a plain 500 that names `SQUIRE_APP_ENTRY` and no path. The entry boots its own HELMET with its own
settings: the front controller boots HELMET (citadel preset) only for the answers it gives itself, never before the
entry, so HELMET is never booted twice. `public/up.php` answers on its own, because the `.htaccess` lets Apache run it
directly. The path checks and the MIME map are the static target's, and the tests keep the two in step.
An app that already has its own `public/index.php` or `public/.htaccess` keeps it: `init` reports the file as
`app-owned`, never records or overwrites it (not even with `--force`), and `init --check` does not count it as drift.
Delete your copy and run `init` to take Squire's. A front controller Squire wrote is tracked like any other file.
A static site is a target of its own: `--target=static` writes everything the `raw` target writes, with its own front
controller, `public/index.php`, and an `.htaccess` that routes every request that is not a real file to it. The site
itself is plain files you commit; the front controller serves them with HELMET's headers, injects the CSP nonce into the
HTML, and caches the assets. The site folder is `../../site` by default (the app lives in `deploy/` beside it); point
`SQUIRE_STATIC_ROOT` at a different folder. `public/up.php` still answers the health check, because a real file is served
straight by Apache and never reaches the front controller.
`update` reads that record: a file you never edited takes the new template, a file you edited is left alone and shown as a
diff, a file a newer release added to a recorded group is written and recorded, and a file Squire did not write is never
touched. A squire polishes the armor; the knight keeps the sword.
`--dry-run` prints the plan and writes nothing.
#### Which command when
Several stack commands sound alike (`weld:doctor`, `squire doctor`, `proctor check`) and do different jobs. Find your question in the second column and run the command beside it. The doctors look at setup, the proctor grades against policy, and the gate decides deploys: same waiting room, different appointments.
| Command | What it checks | When to run it | Where it runs |
|---|---|---|---|
| `composer ci` | **Will my pipeline pass?** The repo's own CI contract, the same command the pipeline runs: validation, the tests, Pint, PHPStan, `composer audit` and whatever checks the repo adds. | Before every push. | App repo, CI |
| `bin/weld.sh doctor` or `.\bin\weld.ps1 doctor` (both run `php artisan weld:doctor`) | **Does my WELD app hold together?** The app key, writable `storage` and `bootstrap/cache`, the database connection and pending migrations. One PASS, WARN or FAIL line each; exit 1 on a FAIL. Standards are PROCTOR's. | After `up`, when the app will not start, and after every deploy off Citadel. | App repo (in the app container), deploy host (in the app container) |
| `vendor/bin/squire doctor` | **Is my Citadel release setup right?** `build.sh`, the release scripts, the health check, script hygiene, line endings and secrets kept out of git, against Squire's rules. Exit 1 on a failed rule. The lock file, audit and MySQL 5.6 checks are handed to PROCTOR. | After `squire init` or `squire update`, and before the first deploy. | App repo, CI |
| `vendor/bin/squire init --check` | **Have the files Squire wrote drifted from its templates?** Missing, outdated or edited copies. Writes nothing; exit 1 on drift. | After you upgrade Squire (then run `squire update`), and in CI. | App repo, CI |
| `vendor/bin/squire doctor oracle`, or `php artisan oracle:check` in WELD and Sourdough's Laravel apps | **Can my app reach Oracle?** The `ORACLE_*` settings, the host, the port, the `oci8` driver and the login, in plain language, printing setting names and never values. Silent when the app has no Oracle settings. | After you fill in the `ORACLE_*` settings, or when a connection fails. Squire's `release.sh` runs the same check on every release, as a report. | App repo, deploy host |
| `vendor/bin/proctor check` (`composer proctor` in WELD and Sourdough's apps) | **Does my app meet CREED's policy?** The PHP floor, Laravel, Node and MySQL end of life, the committed lock, `composer audit`, open-ended constraints, portability, MySQL 5.6 safety, overrides and the rest of its checks. Exit 1 on a FAIL. | Before you merge; the pipeline runs it too. | App repo, CI |
| `vendor/bin/proctor gate` | **May this commit deploy?** The deploy-time subset of `proctor check`, ratcheted against the last release's verdict, so a deploy that makes nothing worse goes. Exit 1 is a no-go. | At deploy time. Squire's `release.sh` calls it for you. | Deploy host |
| `sourdough manifest --check` | **Which managed files did I change since Sourdough baked my app?** Managed files that changed or are missing against `.sourdough/manifest.json`; seeded files are yours and never reported. Exit 1 on a change. | Before `sourdough feed`. | App repo, CI |
| `sourdough feed --dry-run` | **Is my app behind its Sourdough template?** The plan a feed would apply, with nothing written. Exit 1 when feeding would change files. | After you install a new Sourdough, and in CI to catch an app falling behind. | App repo, CI |
| `booster plan` | **What does my upgrade take?** The ordered PHP, Laravel and front-end hops, the dependencies that block them, and advisory PHPCompatibility and PHPStan scans. Changes nothing. | Before an upgrade, and when PROCTOR says your PHP or Laravel is past support. | App repo |
| `booster replay check` | **Does my app still answer the same after a change?** Replays the requests in `booster-replay.json` and compares the answers with the ones `booster replay record` saved. Exit 1 on a changed answer. | After an upgrade hop or a hand fix, once you have a recording. | App repo (in Docker) |
| `booster init --check` | **Are Booster's coding-tab playbooks current?** The playbooks in `.agents/skills`. Changes nothing; exit 1 when one is missing or out of date. | After you upgrade Booster, and in CI. | App repo, CI |
| `php bin/regen-check.php --generated ` | **Is WELD still Sourdough's Inertia shape?** WELD, file by file, against a fresh `sourdough new --inertia`; fails only on drift that `.sourdough/regen-baseline.json` does not already accept. | When Sourdough's Inertia shape or WELD changes. | WELD repo, CI |
| `rollcall report` | **Where does the whole fleet stand?** The latest scan's totals against CREED's policy: PHP, Laravel, the auth package, PROCTOR results and the end-of-life burn-down. Always exit 0; it never gates. | After `rollcall scan`, on the scan's schedule. | CI (a scheduled scan job) |
The canonical copy of this table is in WELD's docs: [Which command when](https://weld.apps.wayne.edu/docs/reference/which-command.html).
### What lands in your app
| File | What it is |
|---|---|
| `build.sh` | Citadel's build hook: system packages only, POSIX sh, runs as root with no app source. No Composer, no npm. |
| `deployments/001-first-release.sh` | Runs once per app: calls the release script with the smoke test off (Apache is not up yet). |
| `scripts/release.sh` | The idempotent release: preconditions, `composer install --no-dev` from the lock file, audit, PROCTOR's deploy gate (`proctor gate`, a report by default, a stop with `SQUIRE_PROCTOR=enforce`), frontend build, Laravel `migrate --force` and `optimize`, an Oracle connection check (a report, never a gate), `/up` smoke test. Use it as the Quick Update post-script as well. |
| `health.php` | Citadel's health check (`["php","health.php"]`): one HTTP request to `/up`, never boots the framework. |
| `oracle-check.php` | The plain-language Oracle connection check the release runs: settings, host, port, driver, login. A report, never a gate; silent when the app has no `ORACLE_*` settings. |
| `public/up.php` | Raw PHP and static: the endpoint that answers `ok`. Laravel has `/up` built in. |
| `public/index.php` | Raw: the front controller that serves `public/` files safely and hands the rest to the app's entry. Static: the one that serves the committed site with HELMET's headers. Never written over an app's own. |
| `public/.htaccess` | Raw: sends every request but `index.php` and `up.php` to the front controller. Static: routes every request that is not a real file to it. |
| `.npmrc` | Vue layer only: sets `min-release-age=1` for the frontend install. |
| `.squire/Dockerfile`, `.squire/base-fallback.Dockerfile`, `.squire/php.ini`, `.squire/php-web.ini` | With `--only=release,images`: the Citadel mirror, the fallback base and the images' hardened PHP settings. |
| `.squire/portable.Dockerfile`, `.squire/portable/` | With `--only=release,images`: the portable image for platforms other than Citadel: one image as web, worker, scheduler or migrate, non-root in group 0 on 8080. Citadel never reads it. |
Every shell script uses `set -euo pipefail` (`build.sh` uses `set -eu`, because Citadel runs it with `/bin/sh`), prints a
`[squire] ==> step N: ...` marker for each step, and can be run twice with the same result.
The release also runs an Oracle connection check (`oracle-check.php`) after the migrations and before the smoke test. It is a
report, never a gate: a finding prints in the deployment log and the release goes on. When the app does not use Oracle
(no `ORACLE_*` settings) it prints nothing. It checks, in order, that the settings are present, that the host resolves,
that the port answers within 3 seconds, that the `oci8` driver is loaded, and that the login works, stopping at the first
failure so a bad port never costs a login attempt. Settings: `ORACLE_USERNAME`, `ORACLE_PASSWORD`, and either `ORACLE_TNS`
(Easy Connect `host:port/service`, or a full `(DESCRIPTION=...)` descriptor) or `ORACLE_HOST`, `ORACLE_PORT` and
`ORACLE_SERVICE_NAME`. Only setting names are ever printed, never values.
### Copies of Squire's templates
Sourdough carries a generated copy of Squire's deploy templates instead of writing its own. The copy began when its
apps could not `composer require` Squire from an internal repository (no internal URLs may be committed). Squire is
on Packagist now, and Sourdough requires it as a dev dependency and regenerates its copy from the package. Squire owns the templates; the copy is checked in and verified, never hand-edited.
```
php bin/export-templates.php --to=templates/squire # write the copy
php bin/export-templates.php --to=templates/squire --check # verify it; exit 1 on drift
```
The copy holds, for each kind (`raw`, `laravel`, `static`) and for the Vue layer (`vue`), the files a new app gets from
`squire init`, at their target paths, with each file's mode recorded so executables stay executable. `catalog.json` lists
which files each kind and layer installs and where; `manifest.json` records the Squire version and a SHA-256 per file.
Refresh the copy when Squire's templates move on, and run `--check` in CI to keep it honest. A squire keeps the armor
polished; the copy stays in step.
### The agent-ready kit
Every stack repo carries the same bytes: a Markdown twin beside every page in the site folder, plus `llms.txt`,
`llms-full.txt`, `robots.txt` and `sitemap.xml`, styled by the kit's `agent-ready.css` and `agent-ready.js` in the
site's `assets/` folder. Squire owns the kit, and a site takes a new version from a Squire checkout with
`php bin/agent-ready.php --sync-to=`, which copies the kit and the tool itself. The site then regenerates its
files with `php bin/agent-ready.php` and commits them, and runs `--check` in CI to stay honest.
A library package that carries the kit should keep it out of Composer downloads: add to its `.gitattributes`
```
/bin/agent-ready.php export-ignore
/site export-ignore
```
so a `composer require` of the package never ships the kit. A squire packs what the knight will carry, and only that.
### The docs builder
`bin/docs-site.php` turns the Markdown under `docs/` into committed, accessible HTML pages under `site/docs/`: one page
per file, in the order of `docs/nav.json`, with a sidebar, an "On this page" list, prev and next links, and the version
stamped from the top of `CHANGELOG.md`. The optional `source` and `mirrors` keys in `docs/nav.json` render a Source link
in the header and footer, with the mirrors beside it, so the canonical repo home is one config value, never a hard-coded
URL. Pages are styled by WayneUI plus the kit's `docs.css` and `docs.js` in the site's
`assets/` folder, so every stack repo reads the same way. `docs.js` adds a copy button to every code block (it says
Copied or Failed, and tells screen readers too; over the code it keeps its resting width and shows a check or a cross
when the word would not fit, so it never covers the first line) and puts a block that scrolls sideways in the tab order, so a
keyboard can reach it (a block inside a code tab is measured again when its tab shows). Squire owns the kit, and a repo takes a new version from a
Squire checkout with `php bin/docs-site.php --sync-to=`, which copies the kit and the tool itself. The repo then
builds with `php bin/docs-site.php` (or `composer docs`) and commits `site/docs/`, and runs `--check` (or
`composer docs:check`) in CI to fail when a page is stale or a finding is present. A squire keeps the map current, so the
knight never asks for directions twice.
#### Generated blocks
A page may hold a region the builder owns, marked in the Markdown source:
```
...whatever the builder wrote last time...
```
`docs/docs.json` defines the blocks by name. Each block rewrites its region from the repo's own state: `json-table` and
`symfony-commands` run a command from the repo root (a leading `php ` means the PHP binary, so the same file works on
Windows, macOS and Linux) and render the command's JSON output, and `env` scans the source files for the environment
variables the code reads.
The `json-table` type runs its `run` command, takes the list at its `path` key from the JSON output, and renders a
Markdown table: each column is `[heading, key]` or `[heading, key, "code"]` for a code span, a missing key gives an
empty cell, booleans print `yes` or `no`, lists print comma separated, Symfony console style tags are stripped so a
help cell reads plain, and pipes in a cell are escaped.
```json
{
"blocks": {
"hops": {
"type": "json-table",
"run": "php bin/booster hops --format=json",
"path": "hops",
"columns": [["Hop", "id", "code"], ["What it does", "summary"]]
}
}
}
```
The `symfony-commands` type runs ` list --format=json` and renders the command reference: an overview table of
command and description, then per command a heading at `level` (default 3), its description, one `Usage:` line per
usage string, an Arguments table when it has arguments, and an Options table when it has options. An option prints its
shortcut first (`-p`, `--path=VALUE`) and gets `=VALUE` only when it takes a value; its default prints in a code span,
or stays empty when it is false. The built-in commands (`help`, `list`, `completion`, `_complete`) and hidden commands
are skipped, and the application-level options (`--help`, `--quiet`, `--verbose`, `--version`, `--ansi`, `--no-ansi`,
`--no-interaction`) are listed once, under "Options every command accepts".
```json
{
"blocks": {
"commands": {
"type": "symfony-commands",
"run": "php bin/console",
"cli": "bin/console",
"level": 3
}
}
}
```
The `env` type walks the `scan` folders for quoted environment variable names that start with `prefix`, skips the
names in `ignore` (an exact name, or a trailing `*` for a prefix), and renders one row per variable, sorted by name:
its meaning and default from `describe` (a `[meaning, default]` pair) and the first file that reads it. A variable the
code reads that `describe` does not list, and a variable `describe` lists that no scanned file reads, are findings.
```json
{
"blocks": {
"environment": {
"type": "env",
"scan": ["src", "config"],
"prefix": "APP_",
"ignore": ["APP_KEY"],
"describe": {
"APP_NAME": ["The app name", "Demo"],
"APP_ENV": ["The environment", "production"]
}
}
}
}
```
A plain run rewrites stale regions in the sources and then builds; `--check` reports a stale region instead of writing.
A region whose name is not in `docs.json`, a block no page places, a block placed twice, and an opening marker with no
closing marker are findings.
#### Changelog page
When `docs/nav.json` lists a page whose path is `changelog`, the builder owns `docs/changelog.md`: a plain run writes
it from the repo's `CHANGELOG.md` before building, and `--check` never writes. The page takes the usual front matter
(`title: "Changelog"` and a description), a marker comment naming its source, and the changelog's body with its
top-level heading dropped, so every version heading stays as written: `## Unreleased`, `## [Unreleased]`,
`## 0.5.0 (2026-11-03)` and `## [0.1.9] - 2026-11-03` all keep their shape and get the page's usual anchors. Links
follow the site's rules: an `http(s)` link stays, a relative link becomes a blob link under the nav.json `source`
when there is one, and loses its link, keeping its label, when there is not. The blob path follows the source's
host: a GitHub source (`github.com` or `www.github.com`) gets `/blob/main/`
(`https://github.com/acme/app/blob/main/README.md`) and any other host keeps GitLab's `/-/blob/main/`
(`https://repo.example.com/acme/app/-/blob/main/README.md`). Links inside a code span or a fenced code block are
left as written. A nav entry without a `CHANGELOG.md` is a finding, and a changed `CHANGELOG.md` or a missing
`docs/changelog.md` is drift.
#### Callouts
A blockquote whose first line is a marker alone becomes a callout instead of a quotation:
```
> [!NOTE]
> The body keeps the note.
```
The marker is case-insensitive and one of `[!NOTE]`, `[!TIP]`, `[!WARNING]` or `[!DANGER]`. The builder renders an
`` with the classes `docs-callout` and `docs-callout--note` (one per kind), `role="note"`, a visible label,
and the body below it, and drops the marker line from the body. A blockquote without a marker, or with a marker that
is not one of the four, stays a plain blockquote. The kit's `docs.css` styles all four kinds from WayneUI tokens, in
light and dark themes.
#### Code tabs
Consecutive fenced code blocks whose info string carries tab="LABEL" (double quotes, label up to 40 characters) render as
one labeled tab set instead of separate code blocks:
````
```bash tab="composer"
composer install
```
```bash tab="sail"
./vendor/bin/sail up
```
````
The word before tab="..." stays the language, so the first panel keeps its `language-bash` class. The builder wraps the
run in a `docs-tabs` element keyed by the lowercased labels joined by `|` (`data-tabs="composer|sail"`), and gives each
panel a `docs-tabs__panel` element carrying its label and the code escaped exactly like a plain fenced block, so every
example reads without JavaScript. A lone tab="..." block renders as a plain code block with the tab="..." word dropped
from its language class, and a run broken by anything else becomes separate sets. The kit's `docs.js` turns each set into
an accessible tablist (click, arrow keys, Home and End), remembers the chosen label per key in `localStorage`, and keeps
every set sharing a key in step; `docs.css` styles the tabs from WayneUI tokens, and print shows every panel.
#### Task lists
A GitHub task list item (`- [ ] Protect the default branch`) renders a disabled checkbox. The builder wraps the checkbox
and the item's own text in a ``, so the checkbox is named by what it checks; a nested list or a
second paragraph stays outside the label.
#### Theme
An optional `theme` key in `docs/docs.json` wears the site's own brand on the pages, without touching the kit:
```json
{
"theme": {
"css": "docs-theme.css",
"header": "_header.html"
}
}
```
Both members are optional and independent, and both are plain relative paths against `docs/`: no leading slash, no
drive letter, no `..` segment, no backslash. A non-object `theme`, a non-string member, an unknown key, an empty string
or a path that does not exist is a tool error naming the key.
`css` names a stylesheet the builder copies byte for byte to `site/docs/theme/` and links after `docs.css` on
every page, so its rules win. It is a builder-owned file like a copied image: `--check` compares it, reports it stale
when it differs, and flags a copy under `site/docs/theme/` as a leftover once the key goes away. The builder never reads
the CSS: colors, fonts and every `--dk-*` override live there, and its `url()` values are written relative to
`site/docs/theme/`. Dark mode lives in the theme CSS too (`prefers-color-scheme` and a `data-theme` override), not in
the builder.
`header` names an HTML fragment with exactly one `...` element. It replaces the generic docs header in
place, after the skip link; the skip link, the mobile menu, the sidebar, the pager and the footer stay. The fragment may
not carry a ``, an `id="main"`, a `wsu-skip-link`, a `docs-menu` or a ``: those belong to the builder.
Relative `href`, `src` and `srcset` URLs in the partial are written against `site/` (the way the front page writes
them), and the builder prefixes each with the page depth; `#`, `/`, `//` and scheme URLs stay put. On every page the
first link to `docs/index.html` or `docs/` gets `aria-current="page"`, unless it already carries an `aria-current`. The
placeholders `{{project}}` (the HTML-escaped project name) and `{{version}}` (the docs stamp) are filled; any other
`{{...}}` fails the build, naming it. With no `theme` key, or an empty one, every generated byte matches the unthemed
build.
The front page gets the same stamp: in a top-level `site/*.html` page, an element that carries `data-docs-version` (for
example `0.6.0`) holds the docs stamp as its only text. A plain
run writes it, `--check` reports the page stale when a release moves the stamp, and an element with markup inside is a
finding. So the header chip on the front page and the one on the docs can never disagree.
A small, realistic partial:
```html
{{project}}
```
Squire's own docs wear this hook: `docs/_header.html` is the front page's masthead (the satchel, Squire, the same
links and the version tag) and `docs/theme/squire.css` carries the front page's canvas, leather, Arvo titles, luggage
tags and terminals, with a derived dark set. To change how Squire's docs look, edit those two files and rebuild; never
edit the kit.
#### Dark mode
The kit's `docs.css` holds every color behind a `--dk-*` alias as `var(--wsu-token, fallback)`, and the fallbacks follow
WayneUI's own resolution order: an explicit choice first (`data-theme="dark"` or `data-theme="light"` on the root
element, which WayneUI writes from the reader's saved preference), then the reader's system setting through a
`prefers-color-scheme: dark` query scoped to `:root:not([data-theme="light"])`, else light. The light `:root` block stays
the default; `:root[data-theme="dark"]` and the media-query block carry the dark fallbacks, and each declares
`color-scheme` so form controls and scrollbars follow the theme. With WayneUI loaded its tokens resolve instead and it
switches them itself, so the hex fallbacks only apply when WayneUI is absent. Every text pair (ink, muted, links,
callout labels, code, and the accent's on-color) meets WCAG AA contrast in both themes, and nothing outside the three
alias blocks carries a hard-coded color.
#### What the check proves
- For a `symfony-commands` block, a code span or fenced line that starts with the CLI name must name a real command
(`help` and `list` always pass), and every `--option` on it must be an option of that command or an application
option; an unknown command or option is a finding.
- Every command and every option the CLI keeps must appear in the docs at least once (the generated block counts);
a command or option nobody documented is a finding.
- A fenced block whose info string contains `docs-test: skip` is not scanned, and plain prose is never scanned.
- Every link a person wrote in the docs reaches something the site serves: a built page, a file under `site/`, or an
external address; a relative link to a file the site does not serve (for example `../README.md`) is a finding.
- A fragment in a link must name a real heading on the page it points at, whether that is the page itself (`#setup`)
or another built page (`guides/start.html#setup`); a missing id is a finding.
- Every image a page references (a Markdown image or an HTML ``) must name a file under `docs/`, resolved against
the source page's folder, and the build copies it byte for byte to the same relative path under `site/docs/` so the
built page's relative src still resolves; a missing image is a finding, and unreferenced files are never copied.
- Every page carries the version stamp as a `docs-version` meta tag and in the footer, so a reader sees which release
the docs describe.
- A `composer.json` with a `version` field must agree with the stamp; a different version is a finding.
- `--require-release` fails when `CHANGELOG.md` has no released heading yet, because the stamp would be `unreleased`.
- `--require-tag` fails when the repo's latest version tag does not match the stamp (a tag such as `v1.6.0` counts as
`1.6.0`); the flag is off by default, so an untagged repo builds clean.
- When the nav lists a `changelog` page, `docs/changelog.md` mirrors `CHANGELOG.md` (front matter, marker comment, no
top-level heading); a changed `CHANGELOG.md` or a missing page is drift, and a nav entry without a `CHANGELOG.md` is
a finding.
#### Tested examples
`php bin/docs-site.php --examples` runs the tagged command examples in the docs and fails when reality drifts from
what they promise. A fenced block whose info string is `bash run`, `sh run`, `console run` or `shell run`
(optionally `exit=N`, default 0) is a command block: each non-empty line is a command (a leading `$ ` is stripped),
run in order in a fresh temp copy of the `examples.cwd` folder; the next fenced block, when its info string is exactly
`output`, is the expected output (stdout then stderr). Both sides are normalized before the comparison: CRLF to LF,
trailing spaces trimmed per line, trailing blank lines removed, the example working directory and the repo root
rewritten to the placeholders below, plus every regex rule in `examples.normalize`:
```
```
Every shell block (bash, sh, shell, console, powershell or pwsh) must be tagged `run` or carry an HTML comment line
reading `docs-test: skip REASON` directly before it; a block with neither, and a marker without a reason, are
findings naming the file and line. Skips are counted and grouped by the words before the first comma, case-folded, in
the one-line summary (`Examples: 7 run, 12 skipped (reasons: needs network 5, needs Docker 4)`), and `examples.maxSkips`
in `docs/docs.json` caps them. The other keys of `examples` are optional: `cwd` names the repo folder copied into each
example working directory, `alias` replaces a matching first word with another command (a leading `php ` means the
PHP binary, a relative script path resolves against the repo root), `env` adds environment variables, and `timeout`
caps each command in seconds (default 60). Generated-block regions are ignored, and a plain build and `--check`
never run examples.
#### JavaScript tests
The kit's `docs.js` carries its own tests in `tests/js/` (node:test with jsdom, pinned exactly in `package.json` and
`package-lock.json`), and they run the same way locally and in CI. With Node 22 on the PATH:
```
npm ci && npm test
```
or, with only Docker:
```
docker run --rm -v "$PWD:/app" -w /app node:22-alpine sh -c "npm ci && npm test"
```
The `js-tests` job runs the same two commands on GitLab and GitHub. It stays out of `composer ci` because the PHP
image has no Node.
### Use Squire from your coding agent (ADVISOR)
Squire ships an [ADVISOR](https://github.com/waynestate/advisor) module, so a coding agent that runs ADVISOR can run
Squire's checks without leaving its sandbox. In the app, install ADVISOR as a dev dependency (`composer require
--dev waynestate/advisor`), put the module in a manifest of your own (for example `advisor-modules.json`), and point
`ADVISOR_MODULES_FILE` at it. ADVISOR reads its own `modules.json` and that one extra file, nothing else:
```json
{
"modules": [
"Waynestate\\Squire\\Advisor\\SquireModule"
]
}
```
Two tools appear. Both are read-only, and each takes exactly one argument: a path inside the project root.
- `squire_doctor` runs Squire's deploy-setup checks (the S-rules, S1 to S78) against the app folder and returns the
same JSON report `vendor/bin/squire doctor --format=json` prints. It runs in-process: no subprocess, no network,
nothing written.
- `squire_drift` reports which of the files Squire wrote into the app have drifted from the current templates, the
same check `vendor/bin/squire init --check` performs: missing, outdated, edited or untracked, per file. It writes
nothing; `squire init` is the fix, and it never overwrites an edit.
Every answer labels its source and says plainly what ran. Squire reports; Squire in CI decides pass or fail. A squire
can tell you where the armor is dented; only the knight gets to charge.
### Citadel setup
1. In the dashboard set the build script to `build.sh`, the health check to `["php","health.php"]`, and the Quick Update
post-script to `./scripts/release.sh` (user `citadel`).
2. Commit `composer.lock`, and `package-lock.json`, `pnpm-lock.yaml` or `yarn.lock` if you have a frontend.
3. Mark the scripts executable in git. On Windows: `git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh`.
4. Set `SQUIRE_*` values in the app's `./.env` configuration file (below), not in a file in the repository. The
dashboard has no environment field; its configuration-files step, after the wizard, writes `./.env` into the
source tree. A Laravel app reads `./.env` already; a raw PHP app loads it with `vlucas/phpdotenv`
(`Dotenv\Dotenv::createUnsafeImmutable($root)->safeLoad()`), so `getenv()` sees the values and a real environment
variable wins.
### Run it locally: Parity
**Use [Parity](https://git.wayne.edu/enterprise-apps/parity) to run Citadel on your computer.** It is the stack's own
tool for this job: one program for Windows, macOS and Linux, for any app, with or without Squire, on Docker or Podman
(Podman recommended), with Citadel's PHP image, Citadel's proxy and MySQL 5.6. It runs the files Squire writes the way
Citadel does. In the app's folder: `parity init`, then `parity up`.
**Squire's parity kit left in 0.12.0.** An app that still has it runs `parity init --from-squire` (it carries the kit's
settings over, never its passwords, and deletes nothing), `parity image get` and `parity up`, then deletes the kit's
files: `docker-compose.squire.yml`, `.squire/haproxy.cfg`, `scripts/parity.sh`, `scripts/parity.ps1` and
`.env.squire.example`. Squire never deletes them: `squire update` lists them as `kit-leftover` and `squire doctor`
notes them under S35 until they are gone. The squire has hung up the traveling armor. Full page:
[Moved to Parity](https://squire.apps.wayne.edu/docs/guides/local-parity.html).
### The image files (opt-in)
`squire init --only=release,images` adds the image files to `.squire/`: the Citadel mirror (`.squire/Dockerfile`, the
app image on Citadel's own base), the fallback base for machines without that image, the hardened `php.ini` and
`php-web.ini`, and the portable image. Citadel never reads them.
#### Image hardening
What the kit's images harden, and the switch for each, is on the docs page
[Image hardening](https://squire.apps.wayne.edu/docs/guides/image-hardening.html). In short:
- **Apache** (the fallback base, `.squire/apache-hardening.conf`): `ServerTokens Prod`, `ServerSignature Off`,
`TraceEnable Off`. It lives in the base, not the app image, so a run on the real Citadel image shows what that image
really says.
- **opcache** (`.squire/php.ini`): on for the web, 128 MB, 20000 files, and set by how code arrives. Pulled into a
running container (Citadel, a bind mount, or unknown): files are checked every 2 seconds, the default. Baked into an
immutable image: build with `SQUIRE_OPCACHE_VALIDATE=0` and they are never checked. The release script warns when
a release in place meets `0`.
- **disable_functions** (`.squire/php-web.ini`, the web only): `exec`, `passthru`, `shell_exec`, `system`, `pcntl_exec`,
`phpinfo`, `show_source`, `highlight_file`. `proc_open` and `popen` stay for mail and Laravel's Process; the CLI
(Composer scripts, artisan, the health check) keeps everything. `SQUIRE_PHP_DISABLE_FUNCTIONS=none` turns it off.
- **Secrets** stay out of every image layer: on Citadel they are configuration files (`./.env`) written into the source
tree at deploy time; with Docker, Compose or OpenShift they are files mounted at `/run/secrets`, which the release
script and the fallback entrypoint turn into variables (`SQUIRE_SECRETS_DIR`). Tests keep secrets out of the
Dockerfiles, the build context and `build.sh`.
#### The portable image
Citadel builds its own image, and `.squire/Dockerfile` stays a mirror of it. For OpenShift, Coolify or raw Docker
(ADR-0010's portable path), `.squire/portable.Dockerfile` bakes the code in and runs as any of four roles, picked by the
first argument or `SQUIRE_ROLE`: `web` (Apache on 8080), `worker` (`php artisan queue:work --tries=3 --max-time=3600
--sleep=3`), `scheduler` (`php artisan schedule:work`) and `migrate` (once per release). It runs as `USER 10001:0`, and
every folder it writes belongs to group 0 and is group-writable, so OpenShift's arbitrary UID runs it as it is
(`docker run --user 1000123:0` shows the same). It stops gracefully on `SIGTERM`, logs to stdout and stderr, and caches
Laravel's config when a container starts, never at build. Run the four roles side by side with `docker run`, one
container each. Full page:
[The portable image](https://squire.apps.wayne.edu/docs/guides/portable-image.html).
### Oracle-ready images (local)
Apps that talk to Oracle need the Instant Client and the `oci8` extension. Squire ships two opt-in Docker recipes
that carry both, so nobody compiles them by hand:
- `squire/oracle-sail:`: Laravel Sail's own runtime plus the Oracle install. In your `docker-compose.yml`,
swap the service's `build:` block for `image: squire/oracle-sail:8.4` and keep the rest of the service as Sail
wrote it; the image keeps Sail's entrypoint contract, including the `WWWUSER` UID remap.
- `squire/oracle-parity:`: the official `php:-cli-bookworm` image with the extensions Citadel apps use
(intl, ldap, soap, zip, gd, pdo_mysql, mysqli, bcmath, pcntl, exif, redis, imagick), Composer and git, plus the
Oracle install. This is the flavour WELD's `compose.oracle.yaml` points its services at. It runs as a non-root
`app` user whose UID is a build argument (`APP_UID`) and can still be overridden at run time.
The names above are the local names of scripts/oracle-image-build.sh. The published images live in the group's
`images` project (the stack's shared image registry; Squire's own GitLab has no container registry), at
`/enterprise-apps/images/squire-oracle-parity:8.4` and `/enterprise-apps/images/squire-oracle-sail:8.4`
(`` is the registry address of the images project shown on its Container Registry page), plus
`:8.4-` for a fixed one; a Sail app swaps `build:` for `image:` with that path.
**Every tag so far published linux/arm64 only.** From Squire 0.10.5, a tag publishes both flavors for PHP 8.3,
8.4 and 8.5 for linux/arm64 (Apple silicon, arm64 Linux hosts). The pipeline now builds linux/amd64 natively on an
amd64 runner as well, so the next tag publishes both architectures in one list; until a tag has, on an amd64
computer, Citadel-shaped hosts included, build the images locally with scripts/oracle-image-build.sh
(MAINTAINING.md, Publishing the Oracle images). The 0.10.5 tag published all six; the
[Oracle guide](https://squire.apps.wayne.edu/docs/guides/oracle.html) lists their digests for pinning.
Both flavors download Oracle's Instant Client Basic Light at build time under Oracle's license and never commit
it: the install script pins the exact SHA-256 of each zip. Oracle does not publish a 21.x client for arm64, so the
line differs per architecture: linux/amd64 gets 21.7.0.0.0 and linux/arm64 gets 19.32.0.0.0.
```
scripts/oracle-image-build.sh --flavour sail --php 8.4 # or: --flavour parity
scripts/oracle-image-test.sh --flavour all --platform linux/amd64
```
### Configuration
All optional. On Citadel, add `./.env.squire` as a configuration file (the configuration-files step after the wizard;
the wizard has no environment field) and keep it out of git. `release.sh` reads the release options from it, and a
variable already in the environment wins.
Release script (`scripts/release.sh`):
| Variable | Default | Meaning |
|---|---|---|
| `SQUIRE_APP_DIR` | parent of `scripts/` | App root. |
| `SQUIRE_FRAMEWORK` | `auto` | `auto`, `laravel` or `raw`. Laravel is detected from `artisan`. |
| `SQUIRE_ALLOW_ROOT` | `0` | `1` allows running as root. |
| `SQUIRE_REQUIRE_ENV` | `auto` | `1` requires a `.env` file; `auto` means Laravel does. |
| `SQUIRE_WRITABLE_DIRS` | Laravel: `storage`, `bootstrap/cache` | Directories to create. |
| `SQUIRE_COMPOSER_AUDIT` | `report` | `report`, `fail` or `skip`. |
| `SQUIRE_NPM` | `auto` | `auto` or `skip` (for committed built assets). |
| `SQUIRE_NPM_IGNORE_SCRIPTS` | `1` | Install with `--ignore-scripts`. |
| `SQUIRE_NPM_REBUILD` | empty | Packages, separated by spaces, whose install scripts run after the install (`npm rebuild --ignore-scripts=false`, or `pnpm rebuild`; pnpm 10 also needs them in `pnpm.onlyBuiltDependencies`). The escape hatch for a package that needs its own scripts, such as a native addon. |
| `SQUIRE_NPM_BUILD_SCRIPT` | `build` | The `package.json` script to run. |
| `SQUIRE_CACHE_DIR` | `.cache/squire` | Where Composer and npm keep their download caches between releases, inside the app folder so a Citadel Update keeps them; `off` leaves their defaults. |
| `SQUIRE_MIGRATE` | `1` | Laravel: `migrate --force`. |
| `SQUIRE_ARTISAN_OPTIMIZE` | `1` | Laravel: `optimize`. |
| `SQUIRE_ARTISAN_RESTART` | `1` | Laravel: tell queue workers and `schedule:work` to restart on the new code (`reload`, or `queue:restart` and `schedule:interrupt`). Report only. |
| `SQUIRE_PROCTOR` | `auto` | `auto`, `skip` or `enforce`. The release asks `proctor gate` for a go or no-go (`proctor check` on a PROCTOR without the gate). By default a no-go is a report and never stops the release; `enforce` makes a no-go stop it, before the frontend build and the migrations. |
| `SQUIRE_PROCTOR_BIN` | `vendor/bin/proctor`, then `PATH`, then the fetch below | Where PROCTOR is. It is a dev dependency, so `--no-dev` removes it; set this to use a copy of your own (PROCTOR's tagged phar works, marked executable). |
| `SQUIRE_PROCTOR_FETCH` | `1` | When no PROCTOR is found, install the version `composer.lock` pins as a dev package into `.cache/squire/proctor/` (`composer create-project --no-dev`, once per version) and run that. `0` turns it off. A failed fetch is a warning, or a stop under `enforce`. Needs `SQUIRE_CACHE_DIR` on. |
| `SQUIRE_PROCTOR_POLICY` | `vendor/waynestate/creed/policy/policy.json`, when installed | Path to the policy file. When unset, the script falls back to the policy the CREED package ships (the deploy wizard has no environment field); when CREED is not installed, PROCTOR runs on its own default policy with a notice. An explicit value always wins. |
| `SQUIRE_PROCTOR_RECORD_DIR` | `storage/squire` | Where the gate keeps its verdicts, relative to the app root: `proctor-gate.json` (the last verdict) and `proctor-gate-baseline.json` (the verdict of the last release that went on, the next run's baseline). The folder gets a `.gitignore` of `*`, so it never reaches git. |
| `SQUIRE_PHP_RUNTIME` | `auto` | The PHP version the gate grades for PROCTOR's unpatched check, passed as `--php-runtime`: `auto` reads the php that runs `release.sh` (it is the one serving the app; a suffix such as `-dev` is cut), `skip` grades no runtime, and an `X.Y.Z` value is graded as given. A value that is not `X.Y.Z` is a note and grades nothing. Only `proctor gate` gets it; the older `proctor check` fallback does not. |
| `SQUIRE_SMOKE` | `1` | Request the health URL at the end and fail unless it answers 200. |
| `SQUIRE_SMOKE_URL` | `http://127.0.0.1:80/up` (Laravel), `/up.php` (raw and static) | Full URL. |
| `SQUIRE_SMOKE_RETRIES` | `5` | Attempts. |
| `SQUIRE_SMOKE_DELAY` | `2` | Seconds between attempts. |
| `SQUIRE_SECRETS_DIR` | `/run/secrets` | A folder of secret files: each file named like a variable becomes that variable, unless the environment sets it. |
Front controller (raw `public/index.php`): `SQUIRE_APP_ENTRY` (`app.php`), the app's entry, relative to the app
directory. Static `public/index.php`: `SQUIRE_STATIC_ROOT` (`../../site`).
Health check (`health.php`): `SQUIRE_HEALTH_PATH`, `SQUIRE_HEALTH_PORT` (80), `SQUIRE_HEALTH_TIMEOUT` (5, at most 14, inside
Citadel's 15), `SQUIRE_HEALTH_VENDOR` (`1` also requires `vendor/autoload.php`).
PHP in the image (`.squire/php.ini`, read from the container's environment): `SQUIRE_OPCACHE_VALIDATE` (`1`; `0` for an
image that bakes its code in), `SQUIRE_OPCACHE_MEMORY` (`128`), `SQUIRE_OPCACHE_MAX_FILES` (`20000`), `SQUIRE_PHP_DISABLE_FUNCTIONS` (the web's list, from
`.squire/php-web.ini`; `none` disables nothing).
The parity kit's settings (`SQUIRE_PROJECT`, `SQUIRE_DB_PASSWORD` and the rest) left with the kit in 0.12.0; Parity
keeps its own in `parity.json`.
### Development
Maintainers: how to build, test and release this project, and where its data comes from, is in [MAINTAINING.md](https://github.com/waynestate/squire/blob/HEAD/MAINTAINING.md).
```
composer install
composer ci # validate, phpunit, pint, phpstan, audit
```
PHPStan and Pint follow Pinstripe, the stack's coding standard: `phpstan.neon` includes Pinstripe's raw PHP preset
(`vendor/waynestate/pinstripe/phpstan/raw.neon`) and keeps only Squire's own paths and PHP version range, and Pint runs
the same built-in `per` preset that Pinstripe's `pint/per.json` wraps, so `pint.json` stays local with Squire's own
excludes.
Run it in Docker the same way CI does:
```
docker run --rm -v "$PWD:/app" -w /app composer:2.11.1 sh -c "composer install --no-interaction && composer ci"
```
The shell templates are linted with shellcheck in Docker (`scripts/lint-shell.sh`, or `scripts/lint-shell.ps1` on
Windows) and the PowerShell with PSScriptAnalyzer (`scripts/lint-powershell.ps1`). The tests run the real shell templates
against stub `composer`, `curl`, `npm`, `corepack` and `proctor` programs, and start a PHP server to test `health.php`.
The front page has its own accessibility gate: `scripts/a11y.sh` on Linux and macOS, `scripts\a11y.ps1` on Windows.
It runs Preflight's own a11y checker, vendored in `tools/a11y/check.mjs` from the same Preflight tag the CI job
runs at and pinned by `tests/A11yCheckerPinTest.php`, in a real Chromium (Playwright in Docker, so no host browser
is needed): every page of `site/` in light and dark mode at 320 px and 1280 px, with the WCAG 2.2 AA tag set and
the WCAG 1.4.10 reflow check. It stays out of `composer ci` because CI has no browser; GitHub runs it as a separate
`a11y` job.
### Known limits
See [OPEN_QUESTIONS.md](https://github.com/waynestate/squire/blob/HEAD/OPEN_QUESTIONS.md). The big ones: the local `php.ini` holds safe defaults rather than the
platform's file, the Citadel image has no digest to pin, and a full Update may not refresh `vendor/`. The release asks
PROCTOR's `proctor gate` for a go or no-go, and installs the PROCTOR version the lock pins when `--no-dev` left it out.
- The release script and the image hardening are contract-tested inside the built fallback image on GitHub (both
platforms), and by hand on Citadel's own `citadel/php-apache:8.5r3` (`scripts/contract-image.sh --base-image`,
2026-11-10), not yet in CI on the real image or on GitLab (OPEN_QUESTIONS 19, "Contract suite on the real image
and on GitLab").
### License
MIT, copyright Wayne State University. A squire carries the armor; the knight still has to show up.
Found a security problem? See [SECURITY.md](https://github.com/waynestate/squire/blob/HEAD/SECURITY.md); please do not open a public issue.
---
Source: https://squire.apps.wayne.edu/
The Citadel kit
## Squire
Suits you up for the Citadel.
A squire carries the knight's kit. This one carries your app's. `squire init` writes the scripts Citadel runs when you deploy and `squire doctor` checks them. To run your app on your laptop on the same PHP image and MySQL 5.6 as Citadel, behind the same kind of proxy, Squire rides with [Parity](https://parity.apps.wayne.edu/), which took that job over in Squire 0.12.0.
`$ composer require waynestate/squire --dev`
Already packed into every [Sourdough](https://sourdough.apps.wayne.edu/) app, and [WELD](https://weld.apps.wayne.edu/) deploys to Citadel through it. Use Squire on its own to bring an app you already have onto Citadel.
[See the packing list](https://squire.apps.wayne.edu/#kit) [Meet the party](https://squire.apps.wayne.edu/#party)
#### Get started with Squire
Pack your app for the Citadel; Parity lets you try it at home first.
A prompt for your coding agent. Copy it as it stands:
```text
You are a coding agent. Read https://squire.apps.wayne.edu/llms.txt and ask ADVISOR.
Install it with `composer require waynestate/squire --dev`, then run `vendor/bin/squire init` at the root of your app.
Ask me before you guess.
```
vendor/bin/squire init
### The packing list for deploy day
`squire init` writes the files Citadel needs from templates, for raw PHP, Laravel or a static site, and adds a Vue layer when `package.json` has Vue. It records a SHA-256 of each file in `.squire.json`. A file you edited is never written over unless you pass `--force`.
1. `build.sh` Citadel's build hook. System packages only, POSIX sh, no Composer or npm (S1).
2. `deployments/001-first-release.sh` Runs once per app and calls the release with the smoke test off; Apache is not up yet.
3. `scripts/release.sh` The idempotent release: install from the lock file, audit, ask PROCTOR's gate for a go or no-go, build, migrate, smoke-test `/up`. Also your Quick Update post-script.
4. `health.php` Citadel's health check: one request to `/up`, never boots the framework.
5. `oracle-check.php` The plain-language Oracle connection check the release runs: settings, host, port, driver, login. A report, never a gate. `.gitattributes` rides in the same pocket and keeps every script LF.

**To** the Citadel **From** my-app **Holds** 6 files
5 of 5 packed, buckled for deploy day
**Try the other commands**
~/my-app
$ vendor/bin/squire init
created build.sh (written from the template)
created deployments/001-first-release.sh (written from the template)
created scripts/release.sh (written from the template)
created health.php (written from the template)
created oracle-check.php (written from the template)
created .gitattributes (written from the template)
Target: laravel. Wrote .squire.json.
Next: git update-index --chmod=+x build.sh deployments/001-first-release.sh scripts/release.sh
Run it locally with Parity: parity init, then parity up (https://git.wayne.edu/enterprise-apps/parity).
Every shell script runs with `set -euo pipefail`, prints a `[squire] ==> step N` marker, and gives the same result when you run it twice. Building images too? `--only=release,images` adds the opt-in image files: the Citadel mirror, the fallback base and the portable image for OpenShift, Coolify and raw Docker.
vendor/bin/squire doctor
### The squire inspects the armor
Doctor reads your repository and checks the rules a machine can decide. It doesn't run your app or touch a server. A fail exits 1 and a warning or info note doesn't, so if you want doctor to block a merge, run it in CI.
fail exits 1 warn reported info noted
- S1`build.sh` runs no Composer or npm.
- S3Every script has `set -e`.
- S4No download piped into a shell.
- S8No CRLF in shell scripts.
- S9Build, first release and release are three jobs.
- S12Install from the lock file; never update.
- S14The release runs `proctor gate` or `proctor check`.
- S15`auth.json` stays out of git.
- S16Laravel runs `optimize`.
- S17Migrations run and stay old-code friendly.
- S19Refuses to run as root.
- S20PROCTOR is a report, never a bare command.
- S21The release requests `/up` at the end.
- S22One marker per step.
- S35No parity kit left over: use Parity.
- S42`.env` files stay out of git.
- S50Lock file, audit and MySQL 5.6 are PROCTOR's: run `proctor check`.
- S55The health check never boots the framework.
- S57npm installs with `--ignore-scripts`.
- S78A Vue app keeps `node_modules/` out of git.
Every rule, its level and why it matters: `BEST_PRACTICES.md`. Drift from the templates is a warning under S9, never a failure; your copies are yours to edit.
~/my-app excerpt
$ vendor/bin/squire doctor
PASS S1 build.sh runs no composer or npm commands. \[build.sh\]
PASS S12 \`composer install --no-dev\` from the lock file.
PASS S14 The release script runs PROCTOR (proctor gate or proctor check).
PASS S20 PROCTOR runs as a report and cannot stop the release.
PASS S55 health.php is an artisan-free health check. \[health.php\]
PASS S35 No parity kit files left over. Parity runs the app on your computer: https://git.wayne.edu/enterprise-apps/parity
WARN S8 .gitattributes does not force LF for shell scripts. Add \`\*.sh text eol=lf\`, and \`\*.conf text eol=lf\`, \`Dockerfile text eol=lf\` and \`\*.Dockerfile text eol=lf\`, which PROCTOR checks too.
RESULT: pass (0 fail, 1 warn, 0 info, 6 pass)
Run it locally
### Practice on the real field
[Parity](https://parity.apps.wayne.edu/) runs your app on Citadel's own PHP image, behind the same HAProxy that adds the forwarding headers, with MySQL 5.6.51 beside it. If something would only break on Citadel, you should see it on your laptop first.
Squire handed this job on
#### Parity runs Citadel on your computer
Parity is the stack's own tool for this: one program for Windows, macOS and Linux, for any app, with or without Squire, on Docker or Podman (Podman recommended). Squire dresses the knight for the castle; Parity builds a practice castle in your yard.
Squire's own parity kit left in 0.12.0. An app that still has it runs `parity init --from-squire`, then deletes the kit's files. `squire update` lists them and never deletes them; [Moved to Parity](https://squire.apps.wayne.edu/docs/guides/local-parity.html) has the four commands.
1. Your browser on localhost
2. HAProxy adds X-Forwarded-For and -Proto
3. Your app Citadel PHP image, run as `citadel`
4. MySQL 5.6.51 `mysql` inside, `127.0.0.1:3307` outside
**Linux and macOS**
Docker or Podman. Install Parity once, then in your app's folder:
```
curl -fsSL https://parity.apps.wayne.edu/install.sh | sh
parity init # or: parity init --from-squire
parity up
```
**Windows**
Podman Desktop or Docker Desktop, in PowerShell. Install Parity once, then in your app's folder:
```
irm https://parity.apps.wayne.edu/install.ps1 | iex
parity init # or: parity init --from-squire
parity up
```
#### Commands
- `check`
- `init`
- `image get`
- `up`
- `test`
- `down`
`check` tells you what to fix on this computer, one finding per line. `image get` downloads Citadel's image and checks it is Citadel's, byte for byte. `down` stops the app and keeps your data.
Building the images too? Squire's opt-in `images` group still writes the Citadel mirror, the fallback base and the portable image. Parity runs Citadel's own image and nothing else.
Citadel setup
### Onto the field
Squire itself runs on your machine and in CI. Only the scripts it wrote go to Citadel.
1. ### Point the dashboard at the kit
Build script `build.sh`, health check `["php","health.php"]`, Quick Update post-script `./scripts/release.sh` as user `citadel`.
2. ### Commit the lock files
`composer.lock`, and `package-lock.json` or `pnpm-lock.yaml` if you have a frontend. The release installs from them and never runs an update.
3. ### Mark the scripts executable
Git on Windows forgets: `git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh`
4. ### Settings in the configuration file
Set `SQUIRE_*` values in the app's `./.env` configuration file, never in a file in the repository. The dashboard has no environment field; its configuration-files step, after the wizard, writes `./.env` into the source tree. A Laravel app reads it already; a raw PHP app loads it with `vlucas/phpdotenv`. All of them are optional.
- **`0`**: pass
- **`1`**: findings: drift for `init --check`, a failed rule for `doctor`
- **`2`**: the tool itself could not run
Squire's own repository rides along: `php bin/docs-site.php` turns `docs/` into the committed pages under `site/docs/`, renders GitHub alert callouts (`[!NOTE]`, `[!TIP]`, `[!WARNING]` and `[!DANGER]`) as labeled asides, groups consecutive `tab="..."` code fences into labeled code tabs that read without JavaScript, generates a changelog page from `CHANGELOG.md` when the nav lists one, and lets a site theme its docs with a header partial and a stylesheet through a `theme` key in `docs/docs.json`. The kit's `docs.css` styles the pages in light and dark themes (an explicit reader choice first, then the system setting), with every text pair at WCAG AA contrast in both.
The platform
### Letters for the castle
A good squire carries messages too. When we find something Citadel could do better, we write it up and send it to the platform team privately. Squire never touches a server, and none of its scripts wait on a proposal.
Its place in WELD
### Every knight rides with a party
Squire is one part of WELD, the Wayne State application stack. It rides last. The parts ahead of it handle the headers, sign-in, the interface, the checks and CI, and Squire takes the finished app to Citadel.
1. **[HELMET](https://helmet.apps.wayne.edu/)** sets security headers
2. **[SESAME](https://sesame.apps.wayne.edu/)** signs the user in
3. **[WayneUI](https://wayneui.apps.wayne.edu/)** renders the page
4. **[PROCTOR](https://proctor.apps.wayne.edu/)** checks the code
5. **[Preflight](https://preflight.apps.wayne.edu/)** runs CI
6. **Squire** deploys you are here
#### Also in the stack
- **[CREED](https://creed.apps.wayne.edu/)** the standards and `policy.json`
- **[Pinstripe](https://pinstripe.apps.wayne.edu/)** the coding standard
- **[Sourdough](https://sourdough.apps.wayne.edu/)** starters you feed
- **[WELD](https://weld.apps.wayne.edu/)** every part, joined
#### Around your app
- **[Booster](https://booster.apps.wayne.edu/)** gets you onto a supported PHP
- **[Rollcall](https://rollcall.apps.wayne.edu/)** every app answers “present”
- **[ADVISOR](https://advisor.apps.wayne.edu/)** what applies, and what next
- **[Drawbridge](https://drawbridge.apps.wayne.edu/)** the Citadel sign-in gateway
- **Squire** the Citadel kit
- **[Parity](https://parity.apps.wayne.edu/)** Citadel on your computer
Known limits
### Scuffs on the leather
Squire 0.12.0 is tagged and on Packagist. Where we had to guess how Citadel behaves, `OPEN_QUESTIONS.md` lists each guess and the default it chose.
- The images group's `php.ini` holds the safe defaults HELMET also enforces at runtime, not the platform's file.
- Old parity kit files are listed, never deleted. Once Parity runs the app, delete them yourself; doctor notes them under S35 until you do.
- A full Update may not refresh `vendor/`. Use `scripts/release.sh` as the Quick Update post-script too.
- The release asks `proctor gate` for a go or no-go. A no-go is a report by default; set `SQUIRE_PROCTOR=enforce` and it stops the release before the build and the migrations.
---
Source: https://squire.apps.wayne.edu/docs/0.1-plan.html
## Squire 0.1 plan [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#squire-0-1-plan)
Sources: the Squire best-practice rules (S1 to S78), the Citadel facts gathered from a read-only clone of Citadel, and the WELD portfolio entry for Squire. This is the plan the 0.1 build followed; `OPEN_QUESTIONS.md` records where it had to guess.
### Goal [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#goal)
A WSU developer with a PHP app (raw PHP or Laravel) runs `vendor/bin/squire init` and gets the files Citadel needs, plus a local setup that behaves like Citadel. `vendor/bin/squire doctor` tells them which best practices the app breaks.
### Shape [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#shape)
1. **A Composer package**, `waynestate/squire`, PHP `^8.3`, tested on 8.3, 8.4 and 8.5, with a Symfony Console CLI.
2. **`squire init`** writes the scripts from templates and records a SHA-256 of each file in `.squire.json`. `squire init --check` reports drift and exits 1 (depend, do not copy). It never overwrites a file the team edited unless told to with `--force`.
3. **`squire doctor`** checks an app against the rules that a machine can decide, exits 1 on a failure, 2 on a tool error, and has a JSON format. Drift from the templates is a warning only.
4. **Templates** in two targets, raw PHP and Laravel (detected from `artisan`), in two groups:
- `release`: `build.sh`, `deployments/001-first-release.sh`, `scripts/release.sh`, `health.php`, `public/up.php` (raw only).
- `parity`: `docker-compose.squire.yml`, a `.squire/` folder (Dockerfile, proxy config, php.ini, vhost, a fallback base image), `scripts/parity.sh`, `scripts/parity.ps1`, `.env.squire.example`.
5. **Platform proposals.** Squire's maintainers send platform improvement proposals to the platform team privately; nothing in this repository touches a server.
### Constraints that shaped the templates [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#constraints-that-shaped-the-templates)
- Citadel runs `build.sh` with `/bin/sh` as root, with only that file copied in. So `build.sh` is POSIX sh and installs system packages only. Composer and npm never run there (S1).
- Deployment hooks run once per file name for the life of an app, as the `citadel` user, and Apache is not up yet. So the hook calls the release script with the smoke test off, and the same script is the Quick Update post-script, where the smoke test is on.
- A Quick Update post-script cannot roll anything back. So PROCTOR is a report there, never a gate (S20).
- The health check runs every five minutes with a 15 second timeout. So `health.php` is a small CLI script that makes one HTTP request and never boots the framework (S55).
- The shared MySQL is 5.6. So the Laravel template and `doctor` warn about JSON columns and 191 character indexes (S18).
### Build order [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#build-order)
1. Scaffold and CI files (GitLab and GitHub), Pint, PHPStan level 8, PHPUnit.
2. Template catalog, manifest, `init` and `--check`.
3. Templates and their tests, including running the real shell templates with stub programs.
4. `doctor` and its rules.
5. Local parity kit, run end to end once on Docker Desktop.
6. Shell and PowerShell linting in Docker (shellcheck, PSScriptAnalyzer).
7. README, best practices, changelog, open questions.
### Done means [#](https://squire.apps.wayne.edu/docs/0.1-plan.html#done-means)
`composer ci` passes in Docker, the shell templates pass shellcheck, the PowerShell passes PSScriptAnalyzer, the parity kit has been brought up once with a healthy app behind the proxy, and every guess is in `OPEN_QUESTIONS.md`.
---
Source: https://squire.apps.wayne.edu/docs/changelog.html
## Changelog [#](https://squire.apps.wayne.edu/docs/changelog.html#changelog)
All notable changes to Squire are recorded here. The format follows Keep a Changelog; the project follows Semantic Versioning once 1.0 is out.
### \[Unreleased\] [#](https://squire.apps.wayne.edu/docs/changelog.html#unreleased)
#### Changed [#](https://squire.apps.wayne.edu/docs/changelog.html#changed)
- Changed: CI pins Preflight 0.12.0 (components and the a11y checker copy). The php-test component now also runs an advisory PHP 8.6 job that may fail and never gates the pipeline.
- The dev dependency ADVISOR is `^0.4` (was `^0.3`, which does not allow 0.4.0); 0.4.0 adds the `advisor install --runner` option and changes nothing Squire uses.
- Docs: SECURITY.md says how to report a vulnerability privately.
#### Fixed [#](https://squire.apps.wayne.edu/docs/changelog.html#fixed)
- The PSScriptAnalyzer CI job analyzes scripts/ (it pointed at templates/, which holds no .ps1 files, and passed without checking anything); a listed folder with no .ps1 files now fails the job.
- Docs: current pages no longer name the stack's internal GitLab host.
### 0.12.0 (2026-11-20) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-12-0-2026-11-20)
Squire is the Citadel kit now: `build.sh`, the release script and the health check, from templates, checked by `squire doctor`. Running Citadel on your computer is [Parity](https://git.wayne.edu/enterprise-apps/parity)'s job. The upgrade steps are in [Upgrading](https://squire.apps.wayne.edu/docs/upgrading.html#0-12-0-2026-11-20).
#### Breaking [#](https://squire.apps.wayne.edu/docs/changelog.html#breaking)
- `squire init --only=parity` and `squire update --only=parity` stop with exit 2 and say where Parity is. The `parity` group is gone. The image files it held (the Citadel mirror `.squire/Dockerfile`, the fallback base, the hardened `php.ini` and `php-web.ini`, and the portable image) are a group of their own, `images`, still opt-in: `--only=release,images`.
- An app whose `.squire.json` records the `parity` group keeps working: Squire reads that record as `release,images`. On its next `squire init` or `squire update`, each kit file the record lists is reported as `kit-leftover`, dropped from the record, and left on disk. Squire deletes none of them. Run `parity init --from-squire` (it reads them), then delete them yourself.
- The kit's checks in `squire doctor` are retired with it: S36, S37, S41, S67, S70 and S71. S35 now notes any kit file still in the app (info, never a failure) and says to run `parity init --from-squire` and delete them.
- The compose file's `portable` profile (the portable image as four services) left with the compose file. The portable image and its four roles stay; run each role with `docker run`, as [the portable image guide](https://squire.apps.wayne.edu/docs/guides/portable-image.html) shows, or on the platform that hosts the app.
#### Removed [#](https://squire.apps.wayne.edu/docs/changelog.html#removed)
- The parity kit, announced as deprecated in 0.10.5 and planned for removal no sooner than 2027-01-08 (ADR-0022). The maintainer brought the date forward to 0.12.0, because Parity now covers everything the kit did. Removed: `docker-compose.squire.yml` (and the Vue layer's copy with its Node 22 service), `.squire/haproxy.cfg`, `scripts/parity.sh`, `scripts/parity.ps1` and `.env.squire.example` (raw and Laravel).
- The GitHub CI legs `contract-parity-sh` and `contract-parity-pwsh`. The `contract-image` leg stays and now asks for `--only=release,images`.
#### Fixed [#](https://squire.apps.wayne.edu/docs/changelog.html#fixed-1)
- The raw and static front controllers send scripts, styles and data (`.css`, `.js`, `.mjs`, `.json`, `.md`, `.txt`, `.xml`, `.webmanifest`) with `Cache-Control: no-cache` and their ETag, so the browser asks on every load and gets a 304 when nothing changed. They had an hour of cache, and the HTML is never cached, so for up to an hour after a release a browser ran the old script on the new page (CREED found it). Images and fonts keep their hour. `public/index.php` is the app's own file, so `squire update` never rewrites it: an app that already has one takes the change by hand (the diff is in [Upgrading](https://squire.apps.wayne.edu/docs/upgrading.html#0-12-0-2026-11-20)).
#### Added [#](https://squire.apps.wayne.edu/docs/changelog.html#added)
- PHP line 8.6r1 is selectable (`squire init --php 8.6r1`): the fallback base for it is the official `php:8.6.0-apache`, pinned by its multi-arch list digest. The default line stays 8.5r3. Citadel's 8.6r1 is ZTS with Apache prefork, with PEAR/PECL, mbstring, oci8, and redis and imagick built with remirepo patches; it has no xdebug, pcov or apcu. The fallback stand-in has none of those extensions and is not proven with the container contract yet.
#### Changed [#](https://squire.apps.wayne.edu/docs/changelog.html#changed-1)
- Squire describes itself as the Citadel kit everywhere: the Composer description, the README, the docs and the front page. The front page's packing list holds the five release tags (`oracle-check.php` took the parity kit's place), and its "Run it locally" section shows Parity's commands. The Local parity docs page is now [Moved to Parity](https://squire.apps.wayne.edu/docs/guides/local-parity.html).
- Squire's own `deploy/` takes the 0.12.0 templates (`squire update`), records `release,images`, and deletes its own five kit files by hand, as the upgrade steps say.
- Added: an update notice: after any command, one line on stderr when a newer stable release exists, with the command that updates this install (Packagist, at most one check a day per machine, cached in the user cache dir). Silent in CI, under `WAYNE_NO_UPDATE_CHECK=1`, with `--quiet` or `-q`, and on non-release builds; stdout and exit codes are never touched.
### 0.11.2 (2026-11-19) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-11-2-2026-11-19)
- Changed: the kit templates take newer pins: the HAProxy digest in `docker-compose.squire.yml` (common and vue kits) and the Node 22.23.5 digest in `.squire/base-fallback.Dockerfile`. Run `squire update` to take them.
- Changed: `deploy/` requires PROCTOR `^0.16` (was `^0.15`, which does not allow 0.16), whose `ci-pipelines` check no longer asks for a GitHub workflow (D-069).
- Changed: the dev dependency Pinstripe is `^0.4` (was `^0.3`, which does not allow 0.4.0); 0.4.0 adds two opt-in Rector presets and changes no rule this repo uses.
- Changed: Squire's own `deploy/` takes the 0.11.1 templates (`squire update`): the fallback base names its line (8.4r5), the release script, the parity scripts with their deprecation note, and the compose and env examples (D-113 step 1).
- Changed: CI pins Preflight 0.9.0 (components and the a11y checker copy).
- CI: the GitHub workflow calls Preflight 0.9.0's reusable workflow (commit fb73b53), the release the GitLab pipeline pins.
### 0.11.1 (2026-11-13) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-11-1-2026-11-13)
- Fixed: the fallback base follows the app's PHP line: an 8.5r3 app's fallback is built on php 8.5.12, an 8.4r5 app's stays on 8.4.27 (D-113).
### 0.11.0 (2026-11-13) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-11-0-2026-11-13)
- Changed: the MySQL upgrade guide now says plainly that the supported path ends at MySQL 8.4 LTS; 9.7 LTS is a later hop, revisited once Citadel has reached 8.4 and PHP and Laravel driver support for 9.7 is checked (SQUIRE-14).
- Added: squire site build runs docs.json block commands from the installed library and copies the pin's files into the build (ADR-0023).
- Fixed: squire site build keeps a Windows drive letter in the output path.
- Added: squire site build --check compares a fresh build with the committed output and writes nothing (ADR-0023).
- Added: squire site build exports a pinned library tag and builds its docs site and agent-ready files with a sha256 manifest (ADR-0023).
- Added: `src/Site` generator drivers, the first piece of squire site build (ADR-0023).
- Added: `src/Site` pin parsing and tag export for the site build (ADR-0023).
- Added: `squire facts --snapshot` rebuilds `.squire/facts.json` offline from the CREED policy and ADVISOR project data in vendor, with the first three regions (`cast-md`, `php-supported-md`, `preflight-pin`).
- Fixed: the GitHub contract legs (`contract-parity-sh`, `contract-parity-pwsh`, and `contract-image` on linux/amd64 and linux/arm64) failed since `squire init` stopped writing the `parity` group by default (D-095): the fixture had no `.squire/Dockerfile` or `.env.squire.example`. The workflow and `scripts/contract-image.sh` now ask for it with `--only=release,parity`.
- Added: `squire facts` fills marked regions from a committed `.squire/facts.json`, and `squire facts --check` fails CI on drift (D-109; the snapshot writer comes next).
### 0.10.9 (2026-11-11) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-9-2026-11-11)
- Changed: the parity kit's HAProxy pin moves to the current `haproxy:3.0-alpine` digest (`sha256:1c15903c50d5510dcc01de755049e7015a6dd3f35bb2dc4582e888116cb71d8f`) in `docker-compose.squire.yml`, for the common and vue kits and Squire's own deploy layer. Run `squire update` to take it.
- Changed: new apps start on the Citadel PHP line 8.5r3 and record it as `php` in .squire.json; existing apps without the key stay on 8.4r5, and `squire update` never moves them. `squire init --php ` picks one.
- Added: the `{{PHP_LINE}}` token and a manifest `php` key (D-090, slice A). Templates say `{{PHP_LINE}}` where they named the Citadel PHP image line, `Catalog::content()` fills it (default `8.4r5`), and `.squire.json` can record `php`. Nothing changes for any app yet: every rendered file still says `8.4r5`.
- Changed: `squire update --only` help calls the `parity` group opt-in, not deprecated.
- Changed: a fresh `squire init` writes only the `release` group; the `parity` group is opt-in (`--only release,parity`), because Parity runs the app locally now (D-095). An app with a `.squire.json` keeps its recorded groups, and `init` points at `parity init --from-squire` when the group is not in play. The drift check in the ADVISOR module follows the recorded groups too.
- Added: a GitLab Release for every tag. On a tag, the new `gitlab-release` job posts the tag's `CHANGELOG.md` section to git.wayne.edu's releases API with the job's own token: 201 is a new release, 409 (one already exists) is left as it is, and anything else fails the job. It never creates, moves or deletes a tag. The notes come from `scripts/release-notes.sh TAG [CHANGELOG]`, which the GitHub release workflow now calls too, so both homes cut the same notes; it drops the section's blank edges and fails loudly when the section is missing or empty (`ReleaseNotesScriptTest`). OPEN_QUESTIONS no longer lists the GitLab release job as not built.
- Changed: docs tables fit their column. A table of three or more columns becomes one card per row when the table itself is 560 px wide or less (a phone, or a tablet beside the sidebar; a container query, not a screen width): the first cell names the card and every other value sits under its column's header, so the column that explains everything is no longer off screen behind a sideways scroll. The builder writes each body cell's header text into a `data-label` attribute, and puts a `` in long code tokens in cells (after slashes, underscores, commas, colons and a dot before a letter, and every 16 characters of a digest) so a path or digest wraps at a seam instead of pushing the table past the page; the first column of a wider table keeps its names whole. Measured on Squire's 34 docs tables: none overflows from 390 px up (15 did at 800 px, and one ran to 1100 px on a desktop). Tables of two columns keep their grid, the header row stays in the page for screen readers, and every site on the kit takes it with its next docs build. Squire's own theme stitches the cards apart with its dashed rule and lets a long header wrap.
- Added: the release script fetches PROCTOR when `--no-dev` left it out, so the deploy gate runs on Citadel instead of reporting itself missing on every release. When no PROCTOR is found (`SQUIRE_PROCTOR_BIN`, `vendor/bin/proctor`, then `PATH`), it installs the version the app's `composer.lock` pins under `packages-dev` with `composer create-project waynestate/proctor --no-dev --no-scripts --no-plugins` into `.cache/squire/proctor/`, once per version, and gates the release with the same PROCTOR CI ran. A failed fetch leaves nothing behind and is a warning (a stop under `SQUIRE_PROCTOR=enforce`); `SQUIRE_PROCTOR_FETCH=0` turns it off, and `SQUIRE_CACHE_DIR=off` skips it. Run `squire update` to take the new `scripts/release.sh` and `.env.squire.example`.
- Docs: OPEN_QUESTIONS, the README and the contributing page no longer say PROCTOR has no published phar (each of its GitLab Releases carries one since 0.6.0), and say the image contract has run by hand on Citadel's own `citadel/php-apache:8.5r3`.
- Site: on a phone the packing list's PACKED stamp no longer covers a long file name (`deployments/001-first-release.sh`, `scripts/release.sh`), the toast after packing spans the screen instead of folding into a narrow ribbon over the page, and an option such as `--force` in running text no longer splits at its hyphens at 320 px.
- CI pins Preflight 0.8.0.
- Fixed: The parity kit's HAProxy reads the engine's nameserver (`parse-resolv-conf`) instead of Docker's fixed 127.0.0.11, so Podman no longer drops the app a minute after `up` (503). Same fix as Parity 64bf3e8.
- Added: `scripts/contract-image.sh --base-image=REF` runs the image contract on an image already on your machine instead of the fallback, above all Citadel's own `citadel/php-apache:8.5r3` (which `parity image get` loads). It never pulls, and stops when the image is missing or built for another platform. The three checks that only the base image decides (the Apache server directives and the entrypoint's `/run/secrets` loading) print `GAP:` lines there instead of failing; on the fallback they still fail. The first run on Citadel's image (2026-11-10) passed every check the kit owns and showed three gaps, recorded on the Proof and Image hardening pages.
- Added: the release script installs the frontend from a `yarn.lock` too, through corepack, as Citadel's images ship Yarn: Yarn 1 with `corepack yarn install --frozen-lockfile --non-interactive --ignore-scripts`, Yarn 2 and later (a lock with a `__metadata:` block) with `corepack yarn install --immutable --mode=skip-build`, then `corepack yarn run build`. A Yarn 2 lock needs `"packageManager": "yarn@..."` in `package.json`; without it the release stops before installing and says so, since corepack would hand the lock to Yarn 1. `SQUIRE_NPM_REBUILD` works with both (`yarn rebuild`, or `npm rebuild` for Yarn 1). Until now a committed `yarn.lock` stopped the release with "commit a lock file" (two apps in the 82-app proof). Doctor rule S12 accepts either Yarn install as installing from the lock. Run `squire update` to take the new `scripts/release.sh`.
- Fixed: `scripts\parity.ps1` on Windows PowerShell 5.1. There a native command's redirected stderr is a terminating error under `$ErrorActionPreference = 'Stop'`, so `up` with no base image on the machine died on a raw `NativeCommandError` instead of saying the image is missing, and `pin` could die the same way. The quiet docker calls now run through `Invoke-NativeQuiet`, and the script's own errors print one plain `parity: ...` line and exit 1 instead of a `Write-Error` record. First run on 5.1 itself: `up -Fallback`, `up` on `citadel/php-apache:8.5r3`, `status`, `pin`, `down` and `reset` all passed. Run `squire update` to take the new script.
- Changed: `parity up` (both twins) warns while `SQUIRE_PROJECT` is the default `squire-app`, and `.env.squire.example` says why: apps on one name are one compose project, sharing the database and the logs volume that records which `deployments/` files already ran, so a second app's first release is skipped and its health check only says `vendor/autoload.php is missing`. Found on the PowerShell 5.1 run, where a fixture inherited another app's release record. A new Troubleshooting entry names the symptom. Run `squire update` to take the new scripts.
- Changed: the image contract runs the app containers with the kit's compose file's least privilege (`--cap-drop=ALL`, the same seven capabilities back, `no-new-privileges`, 256 processes, 512 MB), and a test fails when the two disagree. The baked-code container starts through the image's own entrypoint, as Citadel starts it, instead of Apache alone.
### 0.10.8 (2026-11-10) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-8-2026-11-10)
- Docs: the Local parity guide points at Preflight 0.6.0's `mysql56-migrate` component and PROCTOR's `mysql56-ci` check, the CI side of the same MySQL 5.6.51 pin (D-078).
- Changed: the Oracle image tag jobs build linux/amd64 again, natively on a runner tagged `amd64`, while linux/arm64 stays on the default runner; the new `oracle-images-manifest` job stitches both halves into one manifest list per image. `SQUIRE_BUILD_AMD64` now defaults to `"1"`; `"0"` publishes linux/arm64 only. Only the two amd64 jobs carry the `amd64` tag.
- Changed: the deploy layer requires PROCTOR ^0.15 (locked 0.15.0, was ^0.12): 0.13 checks the release cooldown against the CREED policy, 0.14 adds `script-pair` and 0.15 adds `mysql56-ci`; all only warn, nothing breaks.
- Changed: the deploy layer requires PROCTOR ^0.12 (locked 0.12.0, was ^0.11): two new warning-only checks, nothing breaks.
- Changed: Renovate proposes only patch and digest updates for the two PHP 8.4 base images (the Oracle parity image and the fallback base), so it stops opening 8.5 bumps the image tests reject.
- Docs: the ADVISOR guide and README say to list `SquireModule` in a manifest of your own and point `ADVISOR_MODULES_FILE` at it; ADVISOR never reads an app's `modules.json`.
- Site: the front page's stale facts are current (Squire 0.10.7 on Packagist, the bag holds 25 files, the full `squire init` output for laravel, the whole S8 message, S78 on the rule list; the README's packing-list image says 25 files too).
- Fixed: `squire update` reports a file current, and records it, when an app's edit already matches the new template byte for byte (an edit taken upstream), instead of reporting drift.
### 0.10.7 (2026-11-10) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-7-2026-11-10)
- Added: the kit ships a `.gitattributes` that pins line endings (LF for shell scripts, `.conf` files and Dockerfiles, CRLF for PowerShell and batch files), so a deploy layer in its own folder clears PROCTOR's `gitattributes-eol` and `crlf-deploy-script` warnings. An app that has its own `.gitattributes` keeps it: Squire never writes over it.
- Changed: doctor rule S8 names every `.gitattributes` line to add (shell scripts, `.conf` files, Dockerfiles and PowerShell), the same pins PROCTOR's `gitattributes-eol` check wants, so following the doctor clears PROCTOR too.
- Changed: the GitHub workflow calls Preflight 0.5.0 (was 0.1.4), now that GitHub's copy of Preflight has the tag. MAINTAINING.md says the arm64 contract leg blocks, as it has since it passed on 2026-11-08.
### 0.10.6 (2026-11-10) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-6-2026-11-10)
- Fixed: the docs builder, agent-ready generator, template export and doctor scans walk folders with scandir, because PHP's recursive directory iterator lists only some files on Docker Desktop mounts (22 of Preflight's 28 guide pages went missing).
- Site: `assets/stack-env.js` knows Parity, so a pre-production page links Parity's pre-production site and a dev page links its local `site/` folder. Until now Parity, of all parts, was the one link that ignored its environment.
- Site: Parity is out; the party list links its site.
- Changed: requires waynestate/pinstripe ^0.3 and waynestate/advisor ^0.3.
- Docs: the 0.10.5 tag published the Oracle images, the first tag to do so: both flavors for PHP 8.3, 8.4 and 8.5, linux/arm64 only. The Oracle guide and MAINTAINING.md (What each tag published) list each image's list digest, for example `squire-oracle-sail:8.4-0.10.5@sha256:3d942883ea31c802e2a958542697941c6bff4b36989931e12e2c24289b690a87` and `squire-oracle-parity:8.4-0.10.5@sha256:531b22047eedfd4e8bceee4583cbce2d0aac3129d27afdae97aec8b22bb54367`. amd64 hosts still build locally until `SQUIRE_BUILD_AMD64=1`.
- Docs: US spelling in the README and OPEN_QUESTIONS.md (flavors).
### 0.10.5 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-5-2026-11-09)
- Deprecated: the `parity` group (`docker-compose.squire.yml`, `.squire/`, `.env.squire.example`, `scripts/parity.sh` and `scripts/parity.ps1`). [Parity](https://git.wayne.edu/enterprise-apps/parity), the stack's own tool, runs Citadel on your computer now: one program for Windows, macOS and Linux, for any app, with or without Squire, on Docker or Podman, with Citadel's PHP image, Citadel's proxy and MySQL 5.6. `parity init --from-squire` carries the kit's settings over and deletes nothing. The kit still works and nothing is removed in this release. It goes no sooner than two minor releases and 60 days from now (the stack's ADR-0022): Squire 0.12.0, and not before 2027-01-08. The portable image files stay with Squire and move to a group of their own. The local parity guide, the README, the commands, files, quick start, doctor and troubleshooting pages and the front page say so and recommend Parity. Squire still carries the bag to Citadel; it just stops pretending to be Citadel at home.
- Added: `squire init` (not `--check`) and `squire update` end with one line that points at Parity whenever the `parity` group is in play, and their `--only` help marks the group deprecated. `squire doctor` adds an S35 info finding that says the same when the kit is there; without it, the S35 info line now says how to start with Parity instead of suggesting `init --only=parity`. No exit code changes. Tests pin the line, where it prints, and where it does not.
- Changed: the `oracle-images` tag jobs publish linux/arm64 only, both flavors, PHP 8.3, 8.4 and 8.5: Apple silicon and arm64 Linux hosts can pull them, and amd64 users, Citadel-shaped hosts included, build locally with `scripts/oracle-image-build.sh`. The CI runner is arm64 and cannot run amd64 binaries, so the amd64 legs used to fail every tag pipeline. One switch turns amd64 back on: the CI variable `SQUIRE_BUILD_AMD64=1` (default `0`, in the `.oracle-platforms` block both Oracle jobs extend), once the runner host has qemu-user-static. `scripts/oracle-image-publish.sh` takes `--platforms` (`amd64`, `arm64` or both; both is still the default by hand), puts only what it built into the manifest list, and refuses an unknown platform with exit 2. MAINTAINING.md records what each tag published.
- Docs: Parity joins the party. The README cast, the front page's party roster and the docs overview list Parity right after Squire, with its spirit-level mark, linking its repository until its site is live. The front page's parity section gets a handoff card, and Parity's level tilts in and finds level when it scrolls into view (rotation only, and only without a reduced-motion request).
- Fixed: every PHP 8.5 Oracle image build (both flavors, every architecture, in CI and with `scripts/oracle-image-build.sh --php 8.5`) failed in `images/oracle/install-oracle.sh`. PHP 8.5's `php --ini` prints the ini scan directory in double quotes (8.4 and older print it bare), and the script wrote `zz-oci8.ini` into a path with the quotes in it, a folder that does not exist. It strips the quotes now, fails by name if the folder is missing, and a test pins both.
### 0.10.4 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-4-2026-11-09)
- Fixed: the Sail flavor of the `oracle-images` CI jobs failed before it built anything, on every tag since 0.6.0: `scripts/oracle-image-publish.sh` ran `buildah from docker://composer:2.11.1@sha256:...`, and buildah's `docker://` transport refuses a tag and a digest together (`invalid reference format`). The script now names the image in full without the prefix (`docker.io/library/composer:2.11.1@sha256:...`, same digest), and a test fails on a tag and a digest after `docker://` in either Oracle script.
- Fixed: every linux/arm64 Oracle image build (both flavors, in CI and with `scripts/oracle-image-build.sh` on an arm64 machine) failed in `images/oracle/install-oracle.sh`. The arm64 Instant Client 19.32 Basic Light and SDK zips share their `META-INF/` signing files, so the second `unzip` stopped to ask whether to replace them, read end of input and failed. The SDK now unpacks with `unzip -n` (Basic Light's files always win), the unused `META-INF/` is removed, and a test pins it. The amd64 21.7 zips share no files, so amd64 builds were never affected.
- Fixed: when a build dies because the runner cannot run the other architecture, the publish script now says so plainly; it looked for `Exec format error`, but buildah prints it in lower case, so the job showed only a raw log tail. It also builds the runner's own architecture first, so a dry run proves that half before it stops.
- Docs: MAINTAINING.md, OPEN_QUESTIONS.md, the README and the Oracle guide say what is true today: no tag has published the Oracle images yet, because the only CI runner is linux/arm64, cannot run linux/amd64 binaries, and its jobs are not privileged to register qemu emulation themselves. Build the images locally with `scripts/oracle-image-build.sh` until the runner host gets emulation or an amd64 runner joins.
### 0.10.3 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-3-2026-11-09)
- Changed: the `wayneui-copies` and `composer-ci` CI jobs pin `composer:2.11.1` by its multi-arch list digest (`sha256:8de2184c...`), as the kit already does, instead of the bare tag.
- Changed: the deploy layer requires CREED ^0.1.8, HELMET ^1.3 and PROCTOR ^0.11 (locked 0.1.8, 1.3.0 and 0.11.1; were ^0.1, ^1.0 and ^0.8), and the Pinstripe dev dependency is ^0.1.4 (locked 0.1.4, was 0.1.0). `proctor check` on `deploy/` still passes.
- Changed: CI pins the Preflight components to 0.5.0 (was 0.4.0). The composer-audit job drops its own image input, since 0.5.0's default is `composer:2.11.1` by digest, and the PROCTOR job now keeps `proctor.json` for Rollcall. The a11y checker is the same at 0.5.0, so `tools/a11y/` does not change.
- Changed: the kit's templates say in plain words what each comment used to point at with an internal item ID (the opcache switch, the web's `disable_functions` list, secrets as files, the digest pins, the npm install-script escape hatch, the Oracle check), so an app's copied files no longer cite numbers it cannot look up. Comments only: no setting, default or behavior changes. Run `squire update` to take them; until then `init --check` reports those files as outdated, as it does for any kit change. Squire's own `deploy/` takes them in this release, and the docs, tests, scripts and CI comments drop the same IDs.
- Docs: MAINTAINING.md names the maintainer as a role (the stack maintainer), reached through an issue on git.wayne.edu.
### 0.10.2 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-2-2026-11-09)
- Fixed: the kit's Dockerfiles name every image in full (`docker.io/library/php:...`, `docker.io/library/node:...`, `docker.io/library/composer:...`, tags and digests unchanged), so Buildah and Podman build them with short-name mode enforcing; Buildah refused the fallback base's `COPY --from=composer:2.11.1@sha256:...` outright. The fallback base's Composer now comes from a `FROM ${COMPOSER_IMAGE} AS composer` stage, so all three images (`PHP_IMAGE`, `NODE_IMAGE`, `COMPOSER_IMAGE`) are build arguments a proxy or mirror can swap; Image hardening in the docs has the Dependency Proxy recipe. The Oracle parity image's bases in `images/oracle/php-images.txt` are named in full too. A test fails on a short name in any of the kit's Dockerfiles.
- Changed: the portable image drops `node_modules/` after the frontend build, in the same step, so no layer keeps it; the image ships the built assets and no role runs Node. `--build-arg SQUIRE_KEEP_NODE_MODULES=1` keeps it for an app that reads it at run time.
- Changed: raw PHP apps get SameSite=Lax session cookies. The kit's `php.ini` sets `session.cookie_samesite = Lax` (it was empty), next to the `session.cookie_httponly = 1` and `session.cookie_secure = 1` it already set, so an app that never calls `helmet_boot()` sends a session cookie SESAME 0.7.0 does not warn about. Lax still sends the cookie on a top-level GET from another site (a CAS ticket, an OIDC code), not on a cross-site POST. Applies wherever the kit's `php.ini` is used (local parity, the portable image); on Citadel the platform's `php.ini` decides. A test pins the three settings and reads them back through PHP.
- Changed: Squire's own `deploy/` is on the 0.10.2 kit (the new `php.ini`, fallback base and portable image).
### 0.10.1 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-1-2026-11-09)
- Changed: the kit's Composer moves from 2.10.3 to 2.11.1 (`composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0`, the multi-arch list) in the fallback base, the Oracle parity image, the contract and Oracle build scripts, CI and the Docker-only commands in the docs. 2.10 is no longer maintained, and 2.11.0 fixed GHSA-c968-33g3-wh7p (package names in `installed.json` could escape the vendor directory) and GHSA-fm2w-xgf2-f9fh (inline repository HTTP headers could be written into `composer.lock`). 2.11 drops the `source-fallback` setting, which Squire never used, and the new `policy.cooldown` stays off by default. Run `squire update` to take the new fallback base.
- Changed: the deploy kit is Squire 0.10.0 (was 0.8.0): release.sh gains the release env guard (a Laravel release stops when APP_KEY is unset or APP_DEBUG is on in production).
- Fixed: scripts/a11y.ps1 works on a Windows checkout with CRLF line endings; it strips the carriage returns from the shell command it hands to Docker, which sh rejected with a syntax error.
### 0.10.0 (2026-11-09) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-10-0-2026-11-09)
- Added: the MySQL upgrade path guide (`docs/guides/mysql-upgrade-path.md`): 5.6.51 to 5.7 to 8.0 to 8.4 LTS one series at a time, with the checker to run, the backup (a dump made with the source's own client) and the driver and Laravel floor for each hop, and a rollback for each hop, since MySQL cannot downgrade in place across series. With it, `scripts/mysql-preupgrade-checks.sql`, a read-only script for a copy of the data that lists old temporal columns, names of 64 characters or more, tables not on `utf8mb4_unicode_ci`, and what 8.4 rejects (foreign keys on a non-unique or partial key, `AUTO_INCREMENT` on `FLOAT` or `DOUBLE`); a test refuses any statement that is not a `SELECT` or `SET SESSION`.
- Docs: MAINTAINING.md records the Code Quality check (SQUIRE-33): the pipeline uploads PROCTOR's findings as a `codequality` report artifact and never uses GitLab's deprecated CodeClimate template, so its planned removal changes nothing; OPEN_QUESTIONS.md names the 0.4.0 Preflight pin and the queue worker that is still missing on Citadel.
- Changed: the GitHub workflows pin every action by its commit SHA with the version in a comment (`actions/checkout` v4.4.0, `shivammathur/setup-php` 2.40.0, `docker/setup-qemu-action` v3.7.0, `docker/setup-buildx-action` v3.12.0, the same code their moving tags ran), so a moved tag cannot change what CI runs; a test fails on any tag pin.
- Fixed: the generated changelog page links relative paths with GitHub's blob path when the source is GitHub, and leaves links inside code spans and fenced code alone.
- Fixed: the docs kit keeps a heading's "#" permalink on the line of its last word (the builder wraps the pair in `.docs-heading-tail`), so it never wraps onto a line of its own. On phones, narrow windows and touch screens, and for the page title at every width, the "#" takes no room and no tap area and shows on keyboard focus. A heading word too long for its line breaks or hyphenates instead of widening the page.
- Added: the docs kit's "On this page" list marks the section in view with `aria-current="true"` and `is-current` (an accent bar on the list's rule, light and dark); a clicked entry stays marked through a smooth jump instead of flashing every section it passes. It is a docs.js enhancement that never scrolls, so without JavaScript the page reads as before. Resync the kit and builder with `--sync-to` to take both.
- Fixed: agent-ready reads the project name from a README title inside a centered block or an `
`, then the Composer package name, so a site built in place is no longer titled "# ." (Sourdough's was).
### 0.9.0 (2026-11-08) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-9-0-2026-11-08)
- Changed: the release script refuses a Laravel release when APP_KEY is unset or APP_DEBUG is true in production, and warns when APP_ENV is not production (Sourdough practice 4.14).
- Changed: CI pins the Preflight components to 0.4.0 (the proctor job clones the full history, so the override-approver check can read git blame).
- Changed: the release gate passes `--php-runtime` (SQUIRE_PHP_RUNTIME, default `auto`: the php that runs release.sh, which is the one serving the app), so the deploy path grades the runtime for PROCTOR's unpatched check.
- Changed: the GitHub workflow's arm64 image leg and pwsh parity leg block the run (no `continue-on-error`): both passed in five pushes in a row on 2026-11-08.
### 0.8.0 (2026-11-08) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-8-0-2026-11-08)
- Added: the portable image (`.squire/portable.Dockerfile`, ADR-0010), for OpenShift, Coolify and raw Docker. One image with the code baked in runs as `web`, `worker` (`queue:work --tries=3 --max-time=3600 --sleep=3`), `scheduler` (`schedule:work`) or `migrate`, picked by argument or `SQUIRE_ROLE`, as `USER 10001:0` with group-0 writable folders (any arbitrary UID in group 0 runs it), Apache on 8080 (`SQUIRE_PORT`, else `PORT`), logs to stdout and stderr, and a graceful stop on `SIGTERM` (WELD W8, W13). The compose file's new `portable` profile runs the four roles; a plain `up` is unchanged. The Citadel mirror (`.squire/Dockerfile`, port 80) does not change. Run `squire update` to take the five new files.
- Added: `health.php` reads `SQUIRE_APP_DIR` for the app root, so a kit kept in a subfolder (WELD's `deploy/`) checks the app it serves.
- Fixed: the front page and the README's packing list count the parity kit as it ships (19 files; they still said 12).
- Added: release.sh keeps Composer's and npm's download caches in .cache/squire inside the app folder (SQUIRE_CACHE_DIR, off to disable), so a Citadel Update no longer downloads every package again, and npm ci prefers the cache.
### 0.7.1 (2026-11-08) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-7-1-2026-11-08)
- Fixed: Squire's own deploy/.squire.json records the release.sh it ships (it kept the 0.6.0 hash after the W22 restart step), so squire update no longer refuses it; a test now checks every recorded hash.
- Docs: the queue-workers guide names the QUEUE_WORKER_MODE switch (scheduler or none) that Sourdough's Laravel shapes ship, with --tries=3 and the test that covers both modes.
- Fixed: the kit's php.ini no longer sets session.sid_length or session.sid_bits_per_character, so PHP 8.4 and later raise no deprecation notices and session IDs use PHP's default (32 hex characters, 128 bits), as HELMET and SESAME S45 say. Run squire update to take it.
- Changed: the local a11y scripts run Preflight's own checker (vendored from 0.3.1 and pinned by a test), so they check what CI checks: axe-core 4.14.0, 320 and 1280 px, and the reflow check.
### 0.7.0 (2026-11-08) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-7-0-2026-11-08)
- Added: the release script restarts Laravel's long-lived processes after optimize (reload, or queue:restart and schedule:interrupt), report only; SQUIRE_ARTISAN_RESTART=0 turns it off (WELD W22).
- Added: CI runs Preflight's a11y component (0.3.1) on site/, every page in light and dark at 320 and 1280 px with the WCAG 1.4.10 reflow check, blocking.
- Changed: CI pins the Preflight components to 0.3.1 (fixed cache keys, and caches saved even when a job fails; D-072).
- Changed: CI saves its Composer and npm caches even when a job fails, so a retry after a dropped download fetches only what is missing (D-072).
- Changed: CI caches Composer and npm downloads under a fixed key, so a lock change downloads only what changed (D-072).
- Changed: HELMET moves to `^1.0`, its first stable release, wherever this repo requires it.
- Fixed: OPEN_QUESTIONS.md no longer says there is no GitHub release job; only the GitLab one is missing.
- Docs: OPEN_QUESTIONS 13 records the Node every current Citadel image ships (Node 22 from NodeSource, npm bundled, pnpm and yarn through corepack).
- Added: the docs builder stamps the front page too. An element in a top-level `site/*.html` page that carries `data-docs-version` holds the docs stamp (the first released CHANGELOG heading, the same value as the docs header's `{{version}}`); a plain run writes it, `--check` reports the page stale after a release, and an element with markup inside is a finding. Squire's own chip now carries it. Other sites get it on their next kit sync.
- Fixed: the docs kit's copy button no longer covers the first line of code when it says Copied or Copy failed. It grows only where it stays clear of the code; over the code it keeps its resting width and shows a check or a cross when the word does not fit (the live region still says it in words). The failure word is now Failed.
- Fixed: the front page's quick start command folds at its spaces on a phone (560 px and narrower), with the `--dev` flag kept whole, instead of hiding its tail behind a sideways scrollbar.
- Changed: the deploy layer requires PROCTOR ^0.8 (locked 0.8.0).
- Fixed: the front page's Get started prompt wears the site's look (paper card, stitched seam, Arvo title, green buttons) inside the page width; it came out plain white and full-bleed because `squire.css` mapped none of the kit's `--ar-*` tokens.
- Fixed: the docs kit's mobile menu closes with Escape and puts focus back on its summary (`kit/docs/docs.js`; Enter and Space already toggled it). Other sites get it on their next kit sync.
- Changed: the pipeline pins every Preflight CI component to 0.3.0 ([preflight@0.3.0](mailto:preflight@0.3.0)); component image inputs are plain image names, since Preflight adds the Dependency Proxy prefix itself.
- Docs: the README's Commands section gains the stack's "Which command when" table, copied word for word from WELD's docs: `squire doctor`, `squire init --check`, `weld:doctor`, `proctor check` and the other look-alikes, with what each checks, when to run it and where it runs (D-064).
- Docs: the build.sh template and MAINTAINING.md say what a Citadel test showed (SQUIRE-16): an edited build.sh rebuilds its image step on a full Update, and a Quick Update never runs it; the revision marker stays.
- Docs: a queue workers guide (the scheduler-driven short worker that works today, the timeout rule, and the supervised-worker request for Citadel).
- Changed: the GitHub a11y job is blocking now that it has been seen green on GitHub (SQUIRE-35).
- Fixed: the front page accessibility gate installs again on GitHub: `tools/a11y/package-lock.json` now matches the `@axe-core/playwright` 4.14.0 pin (the dependency update had changed only `package.json`).
- Docs: source comments, messages and art titles write Squire as a word, not in capitals; wordmarks keep their display type.
- Fixed: the front page's deploy layer (`deploy/`) really runs kit 0.6.0 now: the earlier update kept the old record and missed `release.sh`, the Dockerfiles, `php.ini`, the compose file and the two hardening files (`.squire/apache-hardening.conf`, `.squire/php-web.ini`); `squire init --check` passes on all 23 files.
- Fixed: `squire update` records the current release in `.squire.json` even when every file already matches it; it kept the old version, so Squire's own deploy layer said 0.5.0 on 0.6.0 files.
- Fixed: the pipeline's PROCTOR jobs no longer pass `--policy`, which PROCTOR 0.7 refuses in CI; PROCTOR checks against the CREED policy it bundles.
- Changed: the front page's deploy layer (`deploy/`) pins HELMET `^0.4` (locked 0.4.0) and PROCTOR `^0.7` (locked 0.7.0).
- Added: the image contract suite checks the hardening inside the running image (SQUIRE-40): after the release, `scripts/contract-image.sh` pipes the new `scripts/contract-image-checks.php` to `php` in the container, which asks Apache for a probe page (`scripts/contract-image-probe.php`, the fixture's `app.php`) and checks the `Server` header, `X-Powered-By`, `TRACE`, the web's opcache and `disable_functions`, the CLI's full function set, a Composer `post-install-cmd` that shells out, and a throwaway secret mounted at `/run/secrets` (seen by the web, named by the release, absent from every log, layer and image config). Green on linux/amd64 locally (23 assertions); GitHub's `contract-image` job runs it on both platforms. The driver's Composer image is pinned by digest.
- Changed: every image the kit pulls is pinned by its multi-arch list digest (SQUIRE-30): the fallback base's `php:8.4.27-apache`, `node:22.23.4-trixie-slim` and `composer:2.10.3`, the Vue layer's Node service (`node:22.23.4-bookworm-slim`, was the moving `node:22-bookworm-slim`), the Oracle parity image's PHP base and Composer, and the Composer image the Oracle build scripts run. The parity bases move to `images/oracle/php-images.txt`, one pinned row per PHP line (8.3, 8.4, 8.5), which both Oracle build scripts read and pass as `PHP_IMAGE`; a line without a row is refused. A test fails on any unpinned reference. Bump procedure: Image hardening in the docs and MAINTAINING.md.
- Added: an escape hatch for npm install scripts and a written release-age policy (SQUIRE-26): `SQUIRE_NPM_REBUILD` names the packages (space-separated, each checked against the shape of a package name) that run their own install scripts after `npm ci --ignore-scripts` (`npm rebuild --ignore-scripts=false`, or `pnpm rebuild`), so one native addon no longer means turning scripts back on for every package. The release logs the npm version and notes when that npm (older than 11.10) ignores `min-release-age`. The Vue layer's `.npmrc` keeps `min-release-age=1` and explains it, with the deliberate `--min-release-age=0` install for an urgent fix. Docs: Image hardening, The release script, Configuration reference.
- Added: secrets as files at run time (SQUIRE-18): `scripts/release.sh` and the fallback entrypoint share one loader that turns each file in `SQUIRE_SECRETS_DIR` (default `/run/secrets`, where Docker, Compose and Kubernetes mount secrets) named like a variable into that variable, unless the environment already sets it; names that change how the shell runs are skipped, and only names are printed. The entrypoint loads them before Apache starts; the release loads them again after `su -l`. `SQUIRE_SECRETS_DIR` joins the settings-file allow list. Tests run the loader in bash, keep the two copies identical, and keep secrets out of the Dockerfiles, the build context and `build.sh`. Docs: Image hardening (Citadel, Compose, `docker run`, OpenShift), Citadel setup, The release script, Configuration reference.
- Added: the web loses the shell (SQUIRE-29): the new parity file `.squire/php-web.ini` sets `disable_functions` to `exec`, `passthru`, `shell_exec`, `system`, `pcntl_exec`, `phpinfo`, `show_source` and `highlight_file`, and the app image appends it to `php.ini` as `php-apache2handler.ini`, the file mod_php reads, so the CLI (Composer scripts, artisan, the health check, the release script) keeps every function. `proc_open` and `popen` stay for Symfony Mailer, Laravel's Process and PHPMailer. `SQUIRE_PHP_DISABLE_FUNCTIONS` replaces the list and `none` disables nothing; PHP's `${NAME:-default}` falls back only when the variable is unset, so the parity compose files pass it by name only and an unset one never reaches the container as an empty value. `php.ini` no longer sets `disable_classes`, which PHP 8.5 removed. Tests run PHP on both files.
- Added: production opcache in the kit's `php.ini` (SQUIRE-10), set by how code arrives: opcache on for the web and off for the CLI, 128 MB, 20000 files and a 16 MB interned strings buffer. One switch, `SQUIRE_OPCACHE_VALIDATE`: `1`, the default, wherever code is pulled into a running container (a Citadel Quick Update, a bind mount, or anywhere Squire cannot tell), checks files every 2 seconds (`revalidate_freq` 2), so a release is never served stale; `0`, for an image that bakes its code in and never changes (OpenShift, Coolify, raw Docker), never checks. It is a build argument of `.squire/Dockerfile` (default `1`, never empty) and a run-time variable (the run-time value wins), and the parity compose files pass it from `.env.squire` by name only. `SQUIRE_OPCACHE_MEMORY` and `SQUIRE_OPCACHE_MAX_FILES` set the sizes. The fallback base loads opcache when its image does not. The release script gains a "check opcache" step that never fails: a note when files are checked, a warning when a release in place meets `0`. The image contract checks both cases. Docs: Image hardening, The release script, Configuration reference.
- Added: the fallback base says less about itself (SQUIRE-9): the new parity file `.squire/apache-hardening.conf` sets `ServerTokens Prod`, `ServerSignature Off` and `TraceEnable Off`, and the base enables it as `zz-squire-hardening.conf`, after Debian's `security.conf` (which ships `ServerTokens OS` and `ServerSignature On`), so the `Server` header reads `Apache` and Apache's own error pages carry no version footer. The app image is unchanged, so a run on the real Citadel image still shows what that image says. New docs page: Guides, Image hardening.
- Changed: CI caches Composer and npm downloads per lock file (`.composer-cache`, keyed on `composer.lock` and `deploy/composer.lock`, and `.npm-cache`), so a pipeline stops fetching every package from Packagist and npm on every run. Images already come through the Dependency Proxy.
### 0.6.0 (2026-11-07) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-6-0-2026-11-07)
- Changed: the release script asks PROCTOR's deploy gate, `proctor gate`, for a go or no-go instead of running `proctor check`, and runs it right after `composer audit`, before the frontend build and the migrations, so an enforced no-go stops the release before it touches the database. The verdict is written to `storage/squire/proctor-gate.json` (new setting `SQUIRE_PROCTOR_RECORD_DIR`, in the settings-file allow list and the `.env.squire.example` files); when the release goes on, the verdict becomes the baseline the next release is ratcheted against, so a failure that is already live is held and only a new one blocks. `SQUIRE_PROCTOR=auto` still only reports a no-go, and `enforce` stops on it. With a PROCTOR that has no `gate` command the step warns, names the PROCTOR version, and runs `proctor check` as before. Needs a PROCTOR release with `proctor gate` to take effect.
- Changed: `doctor` S14 passes when the release runs `proctor gate` as well as `proctor check`, and the S50 hand-off names `proctor gate`.
- Changed: Squire's own deploy layer (`deploy/`) is updated to the current templates with `squire update`.
- Changed: The canonical repository is git.wayne.edu (ADR-0021); docs, links and package metadata no longer point at the archived nougat copy.
- Changed: the Oracle images publish to the group's images project (`images/squire-oracle-sail`, `images/squire-oracle-parity`) because git.wayne.edu has no registry.
- Fixed: `squire update` writes the template files a newer release added to a group the kit records: a file the target release has that `.squire.json` does not list is written from the template, recorded, and printed as added, so one `update` converges the kit (a kit made before 0.4.0 gains `oracle-check.php` when it moves past it) instead of leaving the new files to `squire init`; a file the app already has is still left alone, and an edited file is still refused and shown as a diff.
- Fixed: `squire init` without `--only` defaults to the groups the `.squire.json` records instead of `release,parity`, so a bare `init` completes an existing kit without dropping its groups; with no manifest it still writes `release,parity`, and `--only` still wins.
- Added: the Proof page records its last run: a dated table of the checks run against Squire itself (`composer ci` and the local parity rig) with their results and durations, so a reader can see when the page was last verified and how to refresh it.
- Fixed: the docs builder turns an article image whose src leaves the site (an http:, https: or // address) into a text link, because the stack's CSPs block external images: inside an anchor the tag becomes its alt text (the last path segment of the src when the alt is empty) and the link stays, so a README badge reads as a link to its page, and a bare tag becomes a link to the image itself with rel="noopener"; relative, /-absolute and data: srcs are the site's own and stay put, for Markdown images and raw HTML `` alike.
- Fixed: images in a docs page sit in rows again instead of stacking one per line (WayneUI's reset makes every image a block): the kit's docs.css puts article images back in the line, centered on the text, while an image alone in its paragraph (or followed only by a `` credit) stays a block; a paragraph or block of only images or linked images (badge rows, a README cast row) wraps in balanced lines with even spacing and keeps align="center"; a list whose every item is one image or linked image becomes a wrapping row of 4rem tiles with no bullets; and linked tiles show an accent hairline on hover, the kit's focus ring on keyboard focus, and a 2px lift only without a reduced-motion request.
- Fixed: the kit's docs.css and docs-site.php answer three findings the new axe-core gates raised on SESAME, HELMET and Booster: inline code in a table header cell now inherits the cell's own colors (color: inherit, background: none) so it keeps the header text's contrast in light and dark themes; every code block gets tabindex="0" from the builder, like the table wrappers, so a block that scrolls sideways on a narrow screen is keyboard reachable; and the level-3 "On this page" entries carry the docs-toc\_\_item base class as well as docs-toc\_\_item--sub so the kit's target-size rules reach them.
- Security: the front-page deploy layer moves to Symfony 7.4.23 (symfony/http-foundation and symfony/yaml advisories, including CVE-2026-118514).
- Fixed: GitHub CI's js-tests job installs git first, so checkout keeps package-lock.json.
- Added: a Proof page in the docs (Reference, Proof): Squire run against 82 Wayne State applications and 13 more repositories on 2026-11-05 (doctor, init, init --check, a second init, doctor again, update --dry-run, and a lint of every file init wrote), plus four of them booted on local parity; what it caught in Squire itself, what it does not prove, and how to run the same on your own app.
- Changed: `squire init` says so when the release it just wrote cannot pass its own first step: an app with no `composer.json` or no `composer.lock` gets a "Heads up" line naming the missing file and how to make it, instead of finding out from a failed first deploy. Found by the proof run (31 of the 82 apps have no lock file). New tests in ConsoleTest.
- Changed: Squire's docs theme tidies two rough edges the front page never shows: the phone Menu button keeps a clear line of canvas between itself and the page title, and the sidebar and terminal scrollbars are thin stitches in the theme's colors instead of the browser's grey rail.
- Fixed: a docs code block that overflows only once the web fonts load joins the tab order: the kit's docs.js re-measures every code block once document.fonts.ready settles (when the browser exposes the Font Loading API), so a block whose width grows with the final font gets tabindex="0" like one measured after a resize; browsers and pages without the API behave exactly as before.
- Fixed: the docs builder's changelog page writes its own `# Changelog` heading after the marker comment, so the built page has an h1 like every other docs page; the source's first heading is still dropped, whatever it said.
- Fixed: the agent-ready Markdown twin keeps the text of a label, which the docs builder wraps around every task-list checkbox and its item text: a list item that opens with a checkbox input (directly in the li, or in a label or paragraph that starts the item) renders as `- [ ] Item text`, or `- [x] Item text` when the input carries a checked attribute, ordered lists keep their number, and a label outside a list keeps its text inline.
- Changed: Squire's own docs pages wear the front page's look through the theme key: docs/\_header.html is the front page masthead (satchel, SQUIRE, the same links, the version tag, Documentation marked current) and docs/theme/squire.css maps the front page's canvas, leather, gold and Arvo onto the kit's --dk-\* tokens, with luggage tags for labels, the current page and the pager, stitched seams above sections, the hero's strap and buckle under each title, terminals with the gold Copy in the corner, code tabs styled like the front page's OS switcher, a derived dark set (prefers-color-scheme and data-theme), and motion only without a reduced-motion request. The kit's docs.css and docs.js are unchanged.
- Fixed: the front page footer's Documentation link was green on the deep green footer (contrast 1.43, axe color-contrast); it is gold now, like the footer's line.
- Added: dark mode in the docs kit: docs.css redefines its twelve --dk-\* color aliases with dark fallbacks in :root\[data-theme="dark"\] and in a prefers-color-scheme: dark query scoped to :root:not(\[data-theme="light"\]), in WayneUI's own resolution order (an explicit choice first, then the reader's system setting, else light), declares color-scheme in each theme so form controls and scrollbars follow, and keeps every text pair at WCAG AA contrast in both themes; the hex fallbacks only apply when WayneUI is absent.
- Fixed: code tab labels may contain spaces: the docs builder now finds the first tab="..." token anywhere in a fence's info string (the quoted label may hold spaces but no double quote, 1 to 40 characters after trimming) instead of only when it is its own whitespace-separated word, so a fence such as `bash tab="Linux / macOS"` joins its tab set with the full label; the token is still dropped from the kept info (the language is the first remaining word), an empty or over-long label still leaves the fence as a plain block, and the ids the builder derives from spaced labels stay valid (no spaces).
- Added: code tabs in the docs builder: consecutive fenced code blocks whose info string carries tab="LABEL" (double quotes, label up to 40 characters) render as one labeled tab set (a docs-tabs element keyed by the lowercased labels joined by |, each panel a docs-tabs\_\_panel with a visible label and the code escaped exactly like a plain fenced block), so every example reads without JavaScript; a lone tab="..." fence stays a plain code block with the tab="..." word dropped from its language class, a run broken by anything else becomes separate sets, and the kit's docs.js turns each set into an accessible tablist (click, arrow keys, Home and End), remembers the chosen label per key in localStorage, and keeps every set sharing a key in step, while docs.css styles the tabs from WayneUI tokens and print shows every panel.
- Added: Squire's own docs site (docs/ built to site/docs/ by its docs builder) and the composer scripts site:agent-ready, site:agent-ready-check; ci now runs both checks.
- Added: GitHub alert callouts in the docs builder: a blockquote whose first line is a marker alone (\[!NOTE\], \[!TIP\], \[!WARNING\] or \[!DANGER\], case-insensitive) renders as an aside with the classes docs-callout and docs-callout--note (one per kind), role="note", a visible label, and the body below it, and the marker line leaves the body; a blockquote without a marker, or with a marker that is not one of the four, stays a plain blockquote, and the kit's docs.css styles all four kinds from WayneUI tokens in light and dark themes.
- Fixed: the kit's agent-ready.js drops two unused variables in enhancePrompt, so eslint no-unused-vars passes.
- Fixed: the kit's agent-ready.js and stack-env.js use bindingless catch blocks, so a linter with no-unused-vars passes on them.
- Fixed: a docs code block that scrolls sideways is keyboard reachable: the kit's docs.js gives a block wider than its box tabindex="0" and takes it away again when a resize makes it fit, so axe's scrollable-region-focusable rule passes on pages with long commands.
- Fixed: a scrolling code block inside a code tab stays keyboard reachable: docs.js measures a block again when its tab shows, and a resize leaves a block in a hidden panel as it was (it has no box to measure), so axe's scrollable-region-focusable rule passes on whichever tab is open.
- Fixed: a GitHub task list checkbox in the docs has an accessible name: the builder wraps the checkbox and its item's own inline text in a label (class docs-task), stopping before a nested list or a second paragraph, so axe's label rule passes on pages with task lists.
- Fixed: sub-items in the docs "On this page" list carry docs-toc\_\_item as well as docs-toc\_\_item--sub, so the kit's item rules (muted color, padding, hover) and a theme's reach them; docs.css also matches a bare --sub item, so pages built before a resync still look right.
- Fixed: the docs builder ignores generated: markers inside fenced code blocks, so a page can show the marker syntax in an example without the builder filling or checking it.
- Fixed: the docs kit's copy button says Copied after a successful copy; clipboard.writeText resolves with undefined, which docs.js read as a failure, so every working copy said Copy failed, and a refused write now says Copy failed instead of staying silent.
- Added: the docs builder's theme hook: an optional theme key in docs/docs.json with css and header members (both optional and independent, both plain relative paths against docs/); css names a stylesheet copied byte for byte to site/docs/theme/ and linked after docs.css on every page, builder-owned like a copied image (--check compares it, reports it stale when it differs, and flags a copy under site/docs/theme/ as a leftover once the key goes away), and header names an HTML fragment whose single element replaces the generic docs header in place, its relative href, src and srcset URLs prefixed with the page depth (#, /, // and scheme URLs stay put), its first link to docs/index.html or docs/ marked aria-current="page" unless it already carries one, and its {{project}} and {{version}} placeholders filled (any other {{...}} fails the build, naming it); a non-object theme, a non-string member, an unknown key, an empty string or a path that does not exist is a tool error naming the key, and with no theme key, or an empty one, every generated byte matches the unthemed build.
- Changed: the docs builder's table cells strip Symfony console style tags (, , , , \ and \>) before escaping, so a symfony-commands help cell shows list instead of list; other angle text stays.
- Added: the docs builder's changelog page: when docs/nav.json lists a page whose path is changelog, a plain run writes docs/changelog.md from CHANGELOG.md before building (the usual front matter, a marker comment naming its source, the body without its top-level heading, every version heading kept as written), a relative link becomes a blob link under the nav.json source or loses its link keeping its label when there is none, --check reports docs/changelog.md (missing) or (out of date) instead of writing, and a nav entry without a CHANGELOG.md is a finding.
- Added: the docs builder's --examples mode runs the tagged command examples in the docs and fails when reality drifts from what they promise: a fenced block tagged run (bash, sh, shell or console, optionally exit=N) runs its lines in order in a fresh temp copy of the examples.cwd folder and compares the output with the following output block, every shell block must be tagged run or carry a docs-test: skip REASON line directly before it, skips are counted and grouped by reason in the summary and capped by examples.maxSkips, and a plain build or --check never runs examples.
- Added: the docs builder's two-way command and option coverage gate for a symfony-commands block: a code span or fenced line that starts with the CLI name must name a real command (help and list always pass) and may only use options of that command or the application options, every kept command and option must appear in the docs at least once (the generated block counts), and a fenced block whose info string contains docs-test: skip is not scanned.
- Changed: the front-page deploy layer pins HELMET ^0.3, PROCTOR ^0.4 and CREED ^0.1 (lock: HELMET 0.3.0, PROCTOR 0.4.0, CREED 0.1.6).
- Changed: CI pins Preflight 0.1.4 (GitLab component includes and the GitHub reusable workflow at its tag commit); the deploy layer sets minimum-stability to stable.
- Added: the docs builder's link gate for the built pages: every content link must reach a built page, a file under site/, or an external address, a fragment must name a real heading on the page it points at, and a relative link to a file the site does not serve (for example ../README.md) is a finding.
- Added: a GitHub release workflow (`.github/workflows/release.yml`) creates the release when a version tag arrives through the push mirror, using the CHANGELOG section for the notes and only the built-in `GITHUB_TOKEN`.
- Added: the docs builder's image gate for the built pages: every image a page references (a Markdown image or an HTML img) must name a file under docs/, resolved against the source page's folder, and is copied byte for byte to the same relative path under site/docs/ so the built page's relative src still resolves; a missing image is a finding, unreferenced files are never copied, and --check fails when a copy is missing or out of date.
- Added: the docs builder compares composer.json's version field with the docs stamp; a different version is a finding.
- Added: the docs builder's --require-release flag fails when CHANGELOG.md has no released heading yet, so the stamp cannot be unreleased in a checked repo.
- Added: the docs builder's --require-tag flag fails when the repo's latest version tag does not match the docs stamp (a tag such as v1.6.0 counts as 1.6.0); the flag is off by default.
- Added: a JavaScript test harness for the docs kit (tests/js, node:test with jsdom pinned exactly in package.json and package-lock.json) and a js-tests CI job on GitLab and GitHub that runs npm ci and npm test in a pinned multi-arch Node 22 image; composer js runs the same two commands locally and stays out of composer ci because the PHP image has no Node.
- Fixed: the oracle image jobs pin the Buildah image to the v1.43.5-immutable tag and its manifest list digest, because the previous digest was removed upstream.
- Fixed: a directory asked for without its trailing slash (for example `/docs`) now redirects to `/docs/`, so the page's relative images and links resolve.
### 0.5.0 (2026-11-03) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-5-0-2026-11-03)
- GitHub CI now pins the PREFLIGHT reusable workflow to the 0.1.3 tag instead of a commit SHA.
- Added: an ADVISOR module (waynestate/advisor) with squire_doctor and squire_drift.
- Added: squire doctor oracle runs the Oracle connection check on demand, reading ORACLE\_\* settings from the environment and .env.
- Changed: the deploy layer's Squire kit is refreshed to 0.4.0 (the Oracle check script and the updated build and release scripts).
- Added: CI publishes the multi-arch Oracle images to the project's container registry when a version is tagged.
- Changed: the docs name the real image path instead of placeholders.
- Changed: Oracle image recipes use fully qualified `COPY --from` names so buildah can resolve them; the CI dry run shows amd64 builds need qemu binfmt on the runner (see OPEN_QUESTIONS).
- Docs: WSL 2 file-location advice and an engines and licenses note for local parity.
- Added: scripts/contract-image.sh runs release.sh inside the fallback image and asserts the smoke URL, health.php and the first-release log.
- Added: a contract-image CI job (GitHub) that runs scripts/contract-image.sh on amd64 and arm64.
- Changed: CI pulls its Docker Hub images through the GitLab Dependency Proxy (the group's CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX), so pipelines no longer hit Docker Hub's anonymous pull limit.
- Added: contract-parity-sh and contract-parity-pwsh CI jobs (GitHub) that bring the local parity stack up on the fallback image and check the proxy answers.
- Docs: the contract suite gap on GitLab and the real image is recorded as an open question.
- Fixed: the fallback base image builds when the host's uid or gid already exists in the image (GitHub runners use 1001).
- Fixed: the front page shows the current version.
- Fixed: the contract-image CI job installs PHP and the Composer dependencies before running scripts/contract-image.sh, so it no longer stops on the missing vendor/autoload.php.
- Fixed: the PowerShell parity script passes the host's uid and gid to the fallback base image build (1000 on Windows, the current user's ids on Linux and macOS) instead of hard-coded 1000, so the app container starts when the bind-mounted source is owned by another user.
- Added: a front page accessibility gate (tools/a11y: axe-core in Playwright, WCAG 2.2 AA) with scripts/a11y.sh and scripts/a11y.ps1 that run it in Docker; GitHub gets an a11y job, continue-on-error until it has been seen green once.
- Fixed: scripts/a11y.sh and scripts/a11y.ps1 create tools/a11y/node_modules on the host before docker run, so the named volume's mount point exists when the repo is mounted read-only.
- Changed: the PROCTOR deploy job is blocking now.
- Fixed: the contract-image job builds with the docker buildx driver so the app image finds the freshly built fallback base.
- Added: bin/docs-site.php, the shared docs builder, with the kit's docs.css and docs.js; it turns docs/ into a committed, WayneUI-styled site/docs/ and fails CI when the pages are stale or a finding is present.
- Changed: docs and package metadata name nougat as the canonical repository, with git.wayne.edu and GitHub as read-only mirrors, until git.wayne.edu has CI runners.
- Added: the docs builder renders a Source link in the header and footer, with a Mirrors list beside it, from the optional `source` and `mirrors` keys in docs/nav.json; a source or mirror URL that is not https is a finding.
- Added: the docs builder's generated blocks: docs/docs.json defines blocks that own marked regions in docs/\*\*/\*.md, the json-table type renders a Markdown table from a command's JSON output, and --check reports a stale block instead of writing.
- Added: the docs builder's symfony-commands block type runs list --format=json and renders the command reference (overview table, per-command headings with usage, argument and option tables, application options listed once), and its env block type scans the scan folders for prefixed environment variable names and renders them with describe meanings and defaults; a read variable without a describe entry, or a described variable no scanned file reads, is a finding.
### 0.4.0 (2026-11-01) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-4-0-2026-11-01)
- Added: oracle-check.php, a plain-language Oracle connection check (settings, host, port, driver, login) shipped in the kit's deploy scripts. release.sh runs it after PROCTOR and before the smoke test; it is a report, never a gate, and stays silent when the app has no ORACLE\_\* settings.
- Added: opt-in Oracle-ready Docker images, a Laravel Sail flavour (squire/oracle-sail) and a parity flavour (squire/oracle-parity), with scripts/oracle-image-build.sh and scripts/oracle-image-test.sh. Oracle Instant Client 21.7 on amd64 and 19.32 on arm64 is downloaded at build time and checksum-pinned; nothing from Oracle is committed.
- Changed: the site's agent-ready files cover the Oracle check.
- Changed: the readme art check allows the word Citadel.
- Changed: the deploy layer's Squire kit is refreshed to 0.3.4 (the local .env.squire file is now git-ignored).
### 0.3.4 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-3-4-2026-10-29)
- Changed: the deploy layer's Squire kit is refreshed to 0.3.3 (release options can now live in ./.env.squire).
- Fixed: squire init now adds .env and .env.squire to the target .gitignore, so the local deploy secrets file is never committed.
### 0.3.3 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-3-3-2026-10-29)
- Fixed: docs say app settings go in a ./.env configuration file; Citadel has no dashboard environment field.
- Fixed: the .env.squire template says to add it as a Citadel configuration file; Citadel has no dashboard environment field.
- Added: release.sh reads release options from ./.env.squire (parsed, never sourced; allow-listed keys; the environment wins), so they can be set on Citadel.
### 0.3.2 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-3-2-2026-10-29)
- Added: collapsed prompt blocks show a "Show the whole prompt" button; the fade stays inside the panel.
- Changed: a long command in the "Run it in" panel folds the same way, behind a "Show the whole command" button, instead of a scroll box with no cue.
### 0.3.1 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-3-1-2026-10-29)
- Changed: README, site and open questions match 0.3.0 (Sourdough requires Squire, the policy default, the Preflight pin, the static target).
- Fixed: the agent-ready tool's messages write Squire as a word; the static template's SQUIRE_STATIC_ROOT comment matches the code.
- Changed: bin/agent-ready.php is clean under Pint's laravel preset (CI checks it); the README says how consumers keep the kit out of Composer downloads.
### 0.3.0 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-3-0-2026-10-29)
- Added: the raw target ships a front controller.
### 0.2.2 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-2-2-2026-10-29)
- Fixed: stale capability claims in the site and README.
- Changed: project names written as words except acronyms.
- Changed: templates and the agent-ready label write Squire as a word; older labels are still recognised.
- Changed: CI uses Preflight 0.1.1.
### 0.2.1 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-2-1-2026-10-29)
#### Fixed [#](https://squire.apps.wayne.edu/docs/changelog.html#fixed-2)
- Fixed: SQUIRE reported 0.1.0 after the 0.2.0 release.
### 0.2.0 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-2-0-2026-10-29)
#### Added [#](https://squire.apps.wayne.edu/docs/changelog.html#added-1)
- `--target=static`: writes everything the `raw` target writes plus a front controller (`public/index.php`) and an `.htaccess` that serve a committed static site behind HELMET. The site folder is `../../site` by default; point `SQUIRE_STATIC_ROOT` at another. `squire init --check` and `squire update` cover the new files, and the template export carries them under `static/`.
- `SQUIRE_PROCTOR=enforce`: a failed PROCTOR check now stops the release. The default stays report-only, so existing apps are unaffected.
- `SQUIRE_PROCTOR_POLICY` defaults to `vendor/waynestate/creed/policy/policy.json` when unset and present, so a static site needs no environment variables in the deploy wizard. When CREED is not installed, PROCTOR runs on its own default policy with a notice instead of the release failing. An explicit value always wins.
#### Changed [#](https://squire.apps.wayne.edu/docs/changelog.html#changed-2)
- PHPStan now includes Pinstripe's raw PHP preset (`waynestate/pinstripe` 0.1) instead of carrying a hand copy of the settings; `phpstan.neon` keeps only SQUIRE's own paths and PHP version range, and the preset's deprecation checks come along with it.
- `symfony/console` floor raised to `^7.4`: `Application::add()` is deprecated since 7.4, and the CLI now calls `addCommand()`.
### 0.1.0 (2026-10-29) [#](https://squire.apps.wayne.edu/docs/changelog.html#0-1-0-2026-10-29)
#### Added [#](https://squire.apps.wayne.edu/docs/changelog.html#added-2)
- `squire init` with `--target`, `--only`, `--check` and `--force`; a `.squire.json` manifest of SHA-256 hashes.
- `squire doctor` with text and JSON output, checking 26 rules (see `BEST_PRACTICES.md`).
- Templates for raw PHP and Laravel: `build.sh`, `deployments/001-first-release.sh`, `scripts/release.sh`, `health.php`, `public/up.php`.
- Vue/Inertia layer: `squire init` detects `vue` in `package.json` and writes `.npmrc` with `min-release-age=1` and a Vue `docker-compose.squire.yml` with a Node 22 service (the frontend install and build stay in the one common `scripts/release.sh`); `squire doctor` reports the layer and warns when `node_modules/` is tracked in git (S78); the template export includes the layer under `vue/`.
- Local parity kit: compose file with digest-pinned HA-Proxy and MySQL 5.6.51 images, `.squire/` build context, a fallback base image, `scripts/parity.sh` and `scripts/parity.ps1`.
- CI for GitLab and GitHub: `composer ci`, shellcheck and PSScriptAnalyzer, run in Docker.
- `bin/export-templates.php`: export a generated copy of SQUIRE's templates (for Sourdough and other projects that cannot `composer require` SQUIRE), with a `catalog.json` and a `manifest.json`; `--check` verifies the copy and exits 1 on drift.
#### Changed [#](https://squire.apps.wayne.edu/docs/changelog.html#changed-3)
---
Source: https://squire.apps.wayne.edu/docs/contributing.html
## Contributing [#](https://squire.apps.wayne.edu/docs/contributing.html#contributing)
A squire who forgets a buckle hears about it in the build log, so this page lists where the code lives, the development commands, and the release steps. Before you open a change, read [Quick start](https://squire.apps.wayne.edu/docs/guides/quick-start.html) to see what the kit writes, and keep [Upgrading](https://squire.apps.wayne.edu/docs/upgrading.html) in mind for what a version bump means to apps.
### Where the code lives [#](https://squire.apps.wayne.edu/docs/contributing.html#where-the-code-lives)
The canonical repository is on git.wayne.edu: [enterprise-apps/squire](https://git.wayne.edu/enterprise-apps/squire) (clone over SSH as `git@git.wayne.edu:enterprise-apps/squire.git`, or over HTTPS). Open issues and merge requests there; tags are cut there, by a maintainer, with an approver. GitHub ([waynestate/squire](https://github.com/waynestate/squire)) is a read-only push mirror of it: `main` and tags are copied automatically, Packagist reads from it, and nobody pushes to it. Your squire serves one banner, and it flies over git.wayne.edu.
### Development commands [#](https://squire.apps.wayne.edu/docs/contributing.html#development-commands)
Install the dependencies and run the full check suite, the same command that runs on GitLab and GitHub:
composer install composer ci
`composer ci` runs `composer validate --strict`, PHPUnit, Pint, PHPStan and `composer audit`. With only Docker, run it the same way CI does:
docker run --rm -v "$PWD:/app" -w /app composer:2.11.1 sh -c "composer install --no-interaction && composer ci"
The other gates, by platform:
| Task | Windows (PowerShell) | Linux and macOS |
| --- | --- | --- |
| Lint the shell templates (ShellCheck in Docker) | `scripts\lint-shell.ps1` | `scripts/lint-shell.sh` |
| Lint the PowerShell templates (PSScriptAnalyzer) | `scripts\lint-powershell.ps1` | `pwsh -File scripts/lint-powershell.ps1` |
| Front page accessibility gate (Preflight's a11y checker, in Docker) | `scripts\a11y.ps1` | `scripts/a11y.sh` |
| Docs kit JavaScript tests (needs Node, or Docker) | `npm ci && npm test` | `npm ci && npm test` |
PHPStan and Pint follow Pinstripe, the stack's coding standard: `phpstan.neon` includes Pinstripe's raw PHP preset (`vendor/waynestate/pinstripe/phpstan/raw.neon`) and keeps only Squire's own paths and PHP version range, and Pint runs the same built-in `per` preset that Pinstripe's `pint/per.json` wraps, so `pint.json` stays local with Squire's own excludes. The tests run the real shell templates against stub `composer`, `curl`, `npm`, `corepack` and `proctor` programs, and start a PHP server to test `health.php`.
#### The accessibility gate [#](https://squire.apps.wayne.edu/docs/contributing.html#the-accessibility-gate)
The front page has its own accessibility gate: `scripts/a11y.sh` on Linux and macOS, `scripts\a11y.ps1` on Windows. It runs Preflight's own a11y checker, vendored in `tools/a11y/check.mjs` from the same Preflight tag the CI job runs at and pinned by `tests/A11yCheckerPinTest.php`, in a real Chromium (Playwright in Docker, so no host browser is needed): every page of `site/` in light and dark mode at 320 px and 1280 px, with the WCAG 2.2 AA tag set and the WCAG 1.4.10 reflow check. The reports land in `build/a11y/` (gitignored). It stays out of `composer ci` because CI has no browser; GitHub runs it as a separate `a11y` job.
#### The docs builder [#](https://squire.apps.wayne.edu/docs/contributing.html#the-docs-builder)
The pages under `docs/` build into the committed site at `site/docs/`: rebuild with `composer docs`, check with `composer docs:check`. The builder is `bin/docs-site.php`; see [The docs builder](https://squire.apps.wayne.edu/docs/guides/docs-builder.html) for generated blocks, callouts and what the check proves. Other stack repos take the kit from a Squire checkout with `php bin/docs-site.php --sync-to=`, then build and commit their own `site/docs/`. Squire's docs wear the front page's look through the theme key in `docs/docs.json`: the masthead is `docs/_header.html` and the styles are `docs/theme/squire.css`. Change those two files, not the kit's `docs.css` or `docs.js`, then rebuild.
The docs kit's JavaScript tests run with Node 22 on the PATH (`npm ci && npm test`) or, with only Docker:
docker run --rm -v "$PWD:/app" -w /app node:22-alpine sh -c "npm ci && npm test"
They run the same way locally and in CI (the `js-tests` job on GitLab and GitHub) and stay out of `composer ci` because the PHP image has no Node.
#### The contract suite [#](https://squire.apps.wayne.edu/docs/contributing.html#the-contract-suite)
`scripts/contract-image.sh` proves that `release.sh` runs inside an image. The real Citadel image is internal, so it uses the fallback base the `images` group ships (`.squire/base-fallback.Dockerfile`, tag `squire/php-parity-base:8.4`): php:8.4-apache plus Node 22, multi-arch. It makes a throwaway fixture app, builds the fallback base and the app image for the platform, runs `release.sh` as the `citadel` user with the smoke test on, and prints one PASS or FAIL line per assertion. A green run is a contract, not a certificate: the fallback has no `oci8`, `imagick` or `ssmtp`, and nothing here touches Citadel itself. For Citadel's own image on your computer, use [Parity](https://git.wayne.edu/enterprise-apps/parity).
### Keeping the docs honest [#](https://squire.apps.wayne.edu/docs/contributing.html#keeping-the-docs-honest)
Every behavior change updates README, docs pages, CHANGELOG (Unreleased), site/llms.txt, site/llms-full.txt and the front page. When the nav lists a `changelog` page, the docs builder owns `docs/changelog.md` from `CHANGELOG.md`, so a changed `CHANGELOG.md` is drift until the page is rewritten.
### Releasing [#](https://squire.apps.wayne.edu/docs/contributing.html#releasing)
1. Move the lines under `## Unreleased` in `CHANGELOG.md` to a new `## X.Y.Z (YYYY-MM-DD)` heading, and bump `Squire::VERSION` in `src/Squire.php` to the same number in the release commit: the version guard test fails when the two disagree.
2. `composer ci` and both linters green locally, then both pipelines green for that commit.
3. Run a secrets scan of the history and check that nothing internal (server names, people, IDs) is in the tree.
4. Tag `X.Y.Z` (no `v`) on git.wayne.edu, with an approver. The mirror carries the tag to GitHub, and Packagist picks it up from there. Both homes then publish a release whose notes are the matching `## X.Y.Z (` section of `CHANGELOG.md`, cut by one script, `scripts/release-notes.sh`, which fails loudly when the section is missing or empty: on git.wayne.edu the `gitlab-release` job creates the GitLab Release with the job's own token (a release that already exists is left as it is), and on GitHub `.github/workflows/release.yml` creates the GitHub Release with only the built-in `GITHUB_TOKEN`. Neither creates, moves or deletes a tag.
5. A release needs a maintainer's approval. Never move or delete a published tag.
6. When Preflight releases, update both of this repo's pins: the component tag in `.gitlab-ci.yml` and the tag in `.github/workflows/ci.yml`.
### Known limits [#](https://squire.apps.wayne.edu/docs/contributing.html#known-limits)
See OPEN_QUESTIONS.md in the repository. The big ones: the local `php.ini` holds safe defaults rather than the platform's file, the Citadel image has no digest to pin, and a full Update may not refresh `vendor/`. The release asks PROCTOR's `proctor gate` for a go or no-go, and installs the PROCTOR version the lock pins when `--no-dev` left it out. The release script is contract-tested inside the fallback image on GitHub and by hand on Citadel's own `citadel/php-apache:8.5r3`, not yet in CI on the real image (OPEN_QUESTIONS 19, "Contract suite on the real image and on GitLab").
### Who maintains it [#](https://squire.apps.wayne.edu/docs/contributing.html#who-maintains-it)
Wayne State University Enterprise Applications maintains Squire. The internal runbook (accounts, tokens, mirrors, Citadel access) lives with Enterprise Applications; ask them.
---
Source: https://squire.apps.wayne.edu/docs/guides/advisor.html
## Use Squire from your coding agent (ADVISOR) [#](https://squire.apps.wayne.edu/docs/guides/advisor.html#use-squire-from-your-coding-agent-advisor)
Squire ships an [ADVISOR](https://github.com/waynestate/advisor) module, so a coding agent that runs ADVISOR can run Squire's checks without leaving its sandbox. Install ADVISOR in the app, register the Squire module, and the agent gains two read-only tools. Next, see [Doctor](https://squire.apps.wayne.edu/docs/guides/doctor.html) for what the checks cover and [Update and drift](https://squire.apps.wayne.edu/docs/guides/update-and-drift.html) for what the drift report means.
### Install ADVISOR [#](https://squire.apps.wayne.edu/docs/guides/advisor.html#install-advisor)
In the app, install ADVISOR as a dev dependency:
```bash
composer require --dev waynestate/advisor
```
Then put the module in a manifest of your own (for example `advisor-modules.json` in the app) and point `ADVISOR_MODULES_FILE` at it. ADVISOR reads its own `modules.json` and that one extra file, nothing else:
```json
{
"modules": [
"Waynestate\\Squire\\Advisor\\SquireModule"
]
}
```
### The two read-only tools [#](https://squire.apps.wayne.edu/docs/guides/advisor.html#the-two-read-only-tools)
Two tools appear. Both are read-only, and each takes exactly one argument: a path inside the project root.
#### squire_doctor [#](https://squire.apps.wayne.edu/docs/guides/advisor.html#squire-doctor)
`squire_doctor` runs Squire's deploy-setup checks (the S-rules, S1 to S78) against the app folder and returns the same JSON report `vendor/bin/squire doctor --format=json` prints. It runs in-process: no subprocess, no network, nothing written.
#### squire_drift [#](https://squire.apps.wayne.edu/docs/guides/advisor.html#squire-drift)
`squire_drift` reports which of the files Squire wrote into the app have drifted from the current templates, the same check `vendor/bin/squire init --check` performs: missing, outdated, edited or untracked, per file. It writes nothing; `squire init` is the fix, and it never overwrites an edit.
Note
Every answer labels its source and says plainly what ran. Squire reports; Squire in CI decides pass or fail. A squire can tell you where the armor is dented; only the knight gets to charge.
---
Source: https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html
## The agent-ready kit [#](https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html#the-agent-ready-kit)
Every stack repo carries the same bytes so that agents and crawlers find the same material as people do. This page lists what the kit ships, how a site takes a new version, and the export-ignore lines a library package adds. Next, see [The docs builder](https://squire.apps.wayne.edu/docs/guides/docs-builder.html) for the pages the kit styles.
### What the kit carries [#](https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html#what-the-kit-carries)
Every stack repo carries the same bytes: a Markdown twin beside every page in the site folder, plus `llms.txt`, `llms-full.txt`, `robots.txt` and `sitemap.xml`, styled by the kit's `agent-ready.css` and `agent-ready.js` in the site's `assets/` folder. Squire owns the kit.
### Taking a new version of the kit [#](https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html#taking-a-new-version-of-the-kit)
A site takes a new version from a Squire checkout with `php bin/agent-ready.php --sync-to=`, which copies the kit and the tool itself. The site then regenerates its files with `php bin/agent-ready.php` and commits them, and runs `--check` in CI to stay honest.
```bash
php bin/agent-ready.php --sync-to= # copy the kit and the tool into the repo
php bin/agent-ready.php # regenerate the files
php bin/agent-ready.php --check # verify in CI; fail on drift
```
### Keeping the kit out of library packages [#](https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html#keeping-the-kit-out-of-library-packages)
A library package that carries the kit should keep it out of Composer downloads: add to its `.gitattributes`
```
/bin/agent-ready.php export-ignore
/site export-ignore
```
so a `composer require` of the package never ships the kit. A squire packs what the knight will carry, and only that.
---
Source: https://squire.apps.wayne.edu/docs/guides/citadel-setup.html
## Citadel setup [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#citadel-setup)
This page lists the numbered steps that connect a new app to the scripts Squire wrote: what to set in the dashboard, what to commit, and where the configuration lives. Finish the steps below, then read [The release script](https://squire.apps.wayne.edu/docs/guides/release-script.html) to see what runs on every deploy, or run it on your computer first with [Parity](https://git.wayne.edu/enterprise-apps/parity).
### The steps [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#the-steps)
1. In the dashboard set the build script to `build.sh`, the health check to `["php","health.php"]`, and the Quick Update post-script to `./scripts/release.sh` (user `citadel`).
2. Commit `composer.lock`, and `package-lock.json`, `pnpm-lock.yaml` or `yarn.lock` if you have a frontend.
3. Mark the scripts executable in git. On Windows: `git update-index --chmod=+x build.sh scripts/*.sh deployments/*.sh`.
4. Set `SQUIRE_*` values in the app's `./.env` configuration file (below), not in a file in the repository. The dashboard has no environment field; its configuration-files step, after the wizard, writes `./.env` into the source tree. A Laravel app reads `./.env` already; a raw PHP app loads it with `vlucas/phpdotenv` (`Dotenv\Dotenv::createUnsafeImmutable($root)->safeLoad()`), so `getenv()` sees the values and a real environment variable wins.
### Executable bits [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#executable-bits)
Citadel runs the scripts as files, so git must record them as executable. Step 3 above does that with `git update-index --chmod=+x`; the release script itself starts with `set -euo pipefail` and expects to run as the `citadel` user from the Quick Update post-script.
### ./.env [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#env)
`./.env` is the app's own configuration, written into the source tree by the dashboard's configuration-files step (after the wizard; the wizard has no environment field). A Laravel app reads it already; a raw PHP app loads it with `vlucas/phpdotenv` (`Dotenv\Dotenv::createUnsafeImmutable($root)->safeLoad()`), so `getenv()` sees the values and a real environment variable wins.
### ./.env.squire [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#env-squire)
`./.env.squire` is Squire's file: the release options for `scripts/release.sh`. All of its values are optional. On Citadel, add `./.env.squire` as a configuration file (the configuration-files step after the wizard; the wizard has no environment field) and keep it out of git. `release.sh` reads the release options from it, and a variable already in the environment wins. The options are listed at the top of `scripts/release.sh` and in [Configuration](https://squire.apps.wayne.edu/docs/reference/configuration.html).
Note
\[!IMPORTANT\] Secrets (a database password, `APP_KEY`, an Oracle login) go in `./.env`, never in the repository, `build.sh` or a Dockerfile: the configuration-files step writes `./.env` into the source tree when the app deploys, so it never lands in an image layer. `build.sh` runs as root while the image builds, with no app source, so it must never fetch a secret either. See [Image hardening](https://squire.apps.wayne.edu/docs/guides/image-hardening.html#secrets-files-at-run-time-never-in-a-layer).
> Two files, two owners. `./.env` is yours and the app reads it; `./.env.squire` is Squire's and the release script reads it. Neither belongs in git.
### Next [#](https://squire.apps.wayne.edu/docs/guides/citadel-setup.html#next)
Read [The release script](https://squire.apps.wayne.edu/docs/guides/release-script.html) for what `scripts/release.sh` does step by step, or [Parity](https://git.wayne.edu/enterprise-apps/parity) to run the same setup on your machine.
---
Source: https://squire.apps.wayne.edu/docs/guides/docs-builder.html
## The docs builder [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#the-docs-builder)
For maintainers of other stack repos: this page explains how Squire's docs builder turns Markdown into committed, accessible pages, and how to adopt it. Next, see [The agent-ready kit](https://squire.apps.wayne.edu/docs/guides/agent-ready-kit.html) for the files that style the result.
### How the build works [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#how-the-build-works)
`bin/docs-site.php` turns the Markdown under `docs/` into committed, accessible HTML pages under `site/docs/`: one page per file, in the order of `docs/nav.json`, with a sidebar, an "On this page" list, prev and next links, and the version stamped from the top of `CHANGELOG.md`. The optional `source` and `mirrors` keys in `docs/nav.json` render a Source link in the header and footer, with the mirrors beside it, so the canonical repo home is one config value, never a hard-coded URL. Pages are styled by WayneUI plus the kit's `docs.css` and `docs.js` in the site's `assets/` folder, so every stack repo reads the same way. The same stamp lands on the front page: any element in a top-level `site/*.html` page that carries `data-docs-version` gets it as its text, and `--check` reports that page stale after a release (see [Theming your docs](https://squire.apps.wayne.edu/docs/guides/theming.html)). `docs.js` adds a copy button to each code block; it says Copied or Failed where there is room, and over the code it keeps its resting width and shows a check or a cross instead, so it never covers a line. Tables fit their column: each body cell carries its column's header in `data-label`, so a table of three or more columns becomes one card per row when the table is 560 px wide or less (a container query, so a tablet beside the sidebar gets cards too), and a long code token in a cell gets a `` at its slashes, underscores, commas, colons and dots before a letter (a digest, every 16 characters) so it wraps at a seam; the first column of a wider table keeps its names whole. A table that still cannot fit, on the narrowest phones, scrolls inside a keyboard-focusable region.
Squire owns the kit, and a repo takes a new version from a Squire checkout with `php bin/docs-site.php --sync-to=`, which copies the kit and the tool itself. The repo then builds with `php bin/docs-site.php` (or `composer docs`) and commits `site/docs/`, and runs `--check` (or `composer docs:check`) in CI to fail when a page is stale or a finding is present. A squire keeps the map current, so the knight never asks for directions twice.
```bash
php bin/docs-site.php --sync-to= # copy the kit and the tool into the repo
php bin/docs-site.php # build (or: composer docs)
php bin/docs-site.php --check # verify in CI (or: composer docs:check)
```
### Generated blocks [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#generated-blocks)
A page may hold a region the builder owns, marked in the Markdown source:
```text
...whatever the builder wrote last time...
```
`docs/docs.json` defines the blocks by name. Each block rewrites its region from the repo's own state: `json-table` and `symfony-commands` run a command from the repo root (a leading `php ` means the PHP binary, so the same file works on Windows, macOS and Linux) and render the command's JSON output, and `env` scans the source files for the environment variables the code reads.
#### The json-table type [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#the-json-table-type)
The `json-table` type runs its `run` command, takes the list at its `path` key from the JSON output, and renders a Markdown table: each column is `[heading, key]` or `[heading, key, "code"]` for a code span, a missing key gives an empty cell, booleans print `yes` or `no`, lists print comma separated, Symfony console style tags are stripped so a help cell reads plain, and pipes in a cell are escaped.
```json
{
"blocks": {
"hops": {
"type": "json-table",
"run": "php bin/booster hops --format=json",
"path": "hops",
"columns": [["Hop", "id", "code"], ["What it does", "summary"]]
}
}
}
```
#### The symfony-commands type [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#the-symfony-commands-type)
The `symfony-commands` type runs ` list --format=json` and renders the command reference: an overview table of command and description, then per command a heading at `level` (default 3), its description, one `Usage:` line per usage string, an Arguments table when it has arguments, and an Options table when it has options. An option prints its shortcut first (`-p`, `--path=VALUE`) and gets `=VALUE` only when it takes a value; its default prints in a code span, or stays empty when it is false. The built-in commands (`help`, `list`, `completion`, `_complete`) and hidden commands are skipped, and the application-level options (`--help`, `--quiet`, `--verbose`, `--version`, `--ansi`, `--no-ansi`, `--no-interaction`) are listed once, under "Options every command accepts".
```json
{
"blocks": {
"commands": {
"type": "symfony-commands",
"run": "php bin/console",
"cli": "bin/console",
"level": 3
}
}
}
```
#### The env type [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#the-env-type)
The `env` type walks the `scan` folders for quoted environment variable names that start with `prefix`, skips the names in `ignore` (an exact name, or a trailing `*` for a prefix), and renders one row per variable, sorted by name: its meaning and default from `describe` (a `[meaning, default]` pair) and the first file that reads it. A variable the code reads that `describe` does not list, and a variable `describe` lists that no scanned file reads, are findings.
```json
{
"blocks": {
"environment": {
"type": "env",
"scan": ["src", "config"],
"prefix": "APP_",
"ignore": ["APP_KEY"],
"describe": {
"APP_NAME": ["The app name", "Demo"],
"APP_ENV": ["The environment", "production"]
}
}
}
}
```
A plain run rewrites stale regions in the sources and then builds; `--check` reports a stale region instead of writing. A region whose name is not in `docs.json`, a block no page places, a block placed twice, and an opening marker with no closing marker are findings.
### Changelog page [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#changelog-page)
When `docs/nav.json` lists a page whose path is `changelog`, the builder owns `docs/changelog.md`: a plain run writes it from the repo's `CHANGELOG.md` before building, and `--check` never writes. The page takes the usual front matter (`title: "Changelog"` and a description), a marker comment naming its source, and the changelog's body with its top-level heading dropped, so every version heading stays as written: `## Unreleased`, `## [Unreleased]`, `## 0.5.0 (2026-11-03)` and `## [0.1.9] - 2026-11-03` all keep their shape and get the page's usual anchors. Links follow the site's rules: an `http(s)` link stays, a relative link becomes a blob link under the nav.json `source` when there is one, and loses its link, keeping its label, when there is not. The blob path follows the source's host: a GitHub source (`github.com` or `www.github.com`) gets `/blob/main/` (`https://github.com/acme/app/blob/main/README.md`) and any other host keeps GitLab's `/-/blob/main/` (`https://repo.example.com/acme/app/-/blob/main/README.md`). Links inside a code span or a fenced code block are left as written. A nav entry without a `CHANGELOG.md` is a finding, and a changed `CHANGELOG.md` or a missing `docs/changelog.md` is drift.
### Callouts [#](https://squire.apps.wayne.edu/docs/guides/docs-builder.html#callouts)
A blockquote whose first line is a marker alone becomes a callout instead of a quotation:
```text
> [!NOTE]
> The body keeps the note.
```
The marker is case-insensitive and one of `[!NOTE]`, `[!TIP]`, `[!WARNING]` or `[!DANGER]`. The builder renders an `