🧭 QuizWizz orientation

Abstract

This page is the map: it separates the test place, the written truth, and the product code. It teaches the proper terms beside plain words, then points to the pages that own each deeper topic.

The three things

Thing in plain words	Proper term	Where it lives	What breaks if it is wrong
A running WordPress copy used only to try changes safely.	Bench / staging or test environment	Remote host: the bench working directory on the host; public face: https://wrdp.loca.zone	Testing lies; a bad change can be mistaken for a good one.
The written place that says what is true and how to operate.	SSOT (single source of truth)	Vault: the vault directory inside the bench working directory; published at https://wiki.wrdp.loca.zone	People act from stale or conflicting instructions.
The code that makes QuizWizz work inside WordPress.	WordPress plugin	wp/wp-content/plugins/quizwizz on the bench	QuizWizz behaviour, data, or admin screens fail.

A source of truth is the version you trust to describe the present; an archive is an old copy kept for reference, not authority. The bench is truth for the deployed plugin, not a local archive.

Guided tour of the bench

• Open https://wrdp.loca.zone, then use /wp-admin; the administrator password is in the operator secret file as the operator-held admin credential.
• Reverse proxy means a front-door web server passes requests to the app behind it: nginx is the doorman and forwards TLS traffic to the app on a loopback-only port.
• TLS means encrypted browser-to-server traffic; it is why the public address uses https.
• Container means an isolated running package; Docker Compose starts the wordpress, mariadb, and one-off wordpress:cli containers with sudo docker compose up -d.
• Image means the packaged blueprint from which a container starts; this bench uses wordpress:latest and mariadb:11.4 images.
• Network isolation means a service is reachable only inside its private network; the database runs on a private container network with no host port, so it cannot be reached from outside the stack.
• Bind mount means a host folder is shown directly inside a container; core and wp-content use ./wp/, the database uses ./db_data/, and logs use ./logs/.
• Persistence means data survives stopping containers; sudo docker compose down stops the stack while retaining those bind-mounted folders.
• Volume means storage managed separately from a running container; treat the bench’s mounted storage as real data even when Docker is not running.
• WP-CLI is WordPress’s command-line runner; invoke it through the one-off CLI service, for example sudo -n docker compose --profile cli run --rm wpcli wp option get qw_exposure_settings.
• Debug log means the file that records server-side warnings and errors; with WP_DEBUG and WP_DEBUG_LOG on but display off, read logs/debug.log rather than exposing errors to visitors.
• Lifecycle, reset, backup, health and ingress are the operator manual’s job, not this page’s: 🛡️ Service Operations.

Warning

The full-reset path deletes the database and the WordPress tree. Treat it as destructive and use it only when discarding the bench is intentional; the exact commands live under Lifecycle commands in 🛡️ Service Operations.

Guided tour of the wiki

• The wiki is Markdown files in a vault, meaning the folder Obsidian treats as one linked knowledge base: the vault directory inside the bench working directory.
• Frontmatter is the metadata block at a Markdown file’s top, such as title, description, tags, and date; it controls page information without becoming body prose.
• Wikilinks are double-bracket links with an optional readable label links between vault pages; use them to keep knowledge connected instead of pasting fragile URLs.
• Callouts are the > [!note]-style blocks that mark a note, warning, tip, or summary for a reader.
• Static site generator means software that turns files into a site before visitors arrive; Quartz v5 generates this wiki’s static pages.
• The Quartz content folder the wiki build directory content symlink is a symlink, meaning a pointer to the real vault rather than another copy.
• Run the wiki build script on the host wrdp --check-only to validate a proposed publish without changing the public site.
• Run the wiki build script on the host wrdp to build and publish; it creates a dist-* directory then swaps the current symlink.
• Atomic publish means readers see either the old complete site or the new complete site, not a half-built mix; the dist-* plus current swap provides that property.
• build.sh resolves python3.11 || python3 (fixed 2026-08-19); no PATH shim is needed.
• wrdp deliberately ships no wiki-ia.json, so validate-ssot.py does not gate this vault — see Service Operations.

Publish a wiki change

1. Edit the Markdown file in the vault directory inside the bench working directory and check its frontmatter and wikilinks.
2. Run the wiki build script on the host wrdp --check-only.
3. Fix any reported validation problem; do not publish around it.
4. Run the wiki build script on the host wrdp.
5. Open https://wiki.wrdp.loca.zone and confirm the page is visible after the atomic publish.

Guided tour of the plugin: follow the data

• A question is a WordPress custom post type: a named kind of post, here qw_question, rather than a normal blog post.
• Its subjects and difficulty use a taxonomy, a reusable classification system; qw_subject and qw_difficulty are the classifications.
• A term is one item inside a taxonomy, such as a subject; a slug is its URL-safe identifier, such as games-chess.
• A canonical slug is the one official slug stored for a term; question saving resolves a supplied subject by slug, numeric term ID, or exact name, then stores that canonical slug.
• Post meta is extra key-and-value data attached to one post; question details belong with the question rather than in a new WordPress screen setting.
• The question index and subject tables are a denormalised read model: a second, speed-focused copy of question data. Keeping a copy is worthwhile when answering selection queries quickly would otherwise require expensive joins; drift means the copy and its original no longer agree.
• A transient is temporary cached WordPress data that can expire; a cron hook is a scheduled WordPress action. Do not treat either as the permanent source of a question or setting.
• Settings live together in the qw_exposure_settings option, meaning one WordPress-wide saved value. Sanitisation means cleaning and normalising input before saving it; includes/ExposureSettings.php owns that boundary.
• A schema version labels the expected data shape; a migration changes stored data or structure safely when that shape evolves. QuizWizz uses DB schema 1.6.8.
• The browser sends settings through a REST route, an HTTP endpoint for programmatic requests. A nonce is a short-lived request token that helps reject forged requests, and a capability check confirms the current user is allowed to act.
• Settings saves include a revision. Optimistic concurrency / revision guard means the server rejects a save based on an old version rather than silently overwriting someone else; the conflict code is qw_settings_conflict.
• A no-script fallback exists, but its partial POST can reset absent fields; use the normal settings UI or send the complete settings value.
• Gettext is the translation system WordPress uses. A POT is the template of source strings, a PO is the human-translated text file, an MO is its compiled runtime form, and JSON catalogs supply translated strings to browser scripts.
• Catalog parity means the translation catalogs match the strings actually in source; compare regenerated catalogs rather than assuming shipped files are current.
• A locale is a language-and-region setting; QuizWizz currently exposes en and has German translation assets including quizwizz-de_DE.po.

Note

The settings screen intentionally renders all nine sections at once. Its information architecture is how content is organised for understanding; progressive disclosure would hide detail until needed, but is not the current design. An accessible name is the label assistive technology announces for a control. The section tracker is a scroll-spy: it changes the active tab as the reader scrolls.

The five workflows you will actually use

1. Look at the site

1. Open https://wrdp.loca.zone for the public surface.
2. Open https://wrdp.loca.zone/wp-admin for administration.
3. If the stack is down, run sudo docker compose up -d from the bench working directory on the host.
4. If behaviour looks wrong, inspect logs/debug.log.

How you know it worked: the intended public or admin screen loads, and any relevant error is either absent from the debug log or understood.

2. Change a plugin file safely

The stage-then-install protocol, its PHP lint step and the probe gate live in one place: Dropping in a plugin for testing in 🛡️ Service Operations. The rule that matters here is conceptual — never edit the bind mount in place; stage a complete replacement and install it atomically as www-data.

How you know it worked: PHP lint reports no syntax error and the current all-wave probe completes with 1..94, assertions=94 failures=0; the standing contract and dated result are in the QuizWizz probe authority.

3. Import questions from a pack

1. Prepare a quizwizz.question-pack v1 file with exactly format, version, quiz, subjects, and questions at the top level.
2. Keep the pack at or below 100 questions, 100 subjects, and 1 MB.
3. Start the bench if needed with sudo docker compose up -d from the bench working directory on the host, then use the QuizWizz import flow in /wp-admin to upload it.
4. Check that questions are published and the imported quiz is a draft before choosing what to do next.

How you know it worked: the expected questions exist as published qw_question posts and the new quiz exists as a draft.

4. Inspect or change a setting from the command line

1. Inspect the full option with sudo -n docker compose --profile cli run --rm wpcli wp option get qw_exposure_settings.
2. Treat the output as one complete settings object: current values include iface_lang, langs, theme_default, and count.default.
3. Make any change through the normal Settings screen so sanitisation and the revision guard run.
4. Re-run sudo -n docker compose --profile cli run --rm wpcli wp option get qw_exposure_settings to inspect the saved value.

How you know it worked: the option contains the intended complete value and the Settings screen still saves without qw_settings_conflict.

5. Publish a wiki change

1. Edit the relevant vault Markdown under the vault directory inside the bench working directory.
2. Run the wiki build script on the host wrdp --check-only.
3. Run the wiki build script on the host wrdp.
4. Visit https://wiki.wrdp.loca.zone and follow the changed page’s wikilink.

How you know it worked: validation completes, the page is public, and its links resolve to the intended pages.

Safety map

Boundary	What belongs here	Why
Safe to touch alone	Vault Markdown, a staged replacement under /tmp/qwfix/, question packs that meet the importer format	These have a defined edit or import path and a direct check.
Ask first	Plugin behaviour, settings structure, database schema, translation catalogs, reset operations	These can affect shared data, users, or a broad runtime contract.
Never by hand	build/, vendor/, provenance output, the wp/ bind mount	They are generated, dependency-managed, evidence output, or live mounted runtime state; regenerate, reinstall atomically, or use the owning workflow instead.

Provenance means evidence of where an artifact came from and how it was produced. Do not edit provenance output, because changing evidence by hand makes it untrustworthy.

Working principles

• Validation means checking input or a result against required rules; the question validator requires multiple or boolean, 2–8 distinct non-empty choices, exactly one correct answer, allowed difficulty, and an explanation no longer than 4000 characters.
• Lint means a fast syntax check; PHP lint catches a broken PHP file before it reaches normal use.
• A probe is an automated focused check; an assertion is one fact it verifies. The QuizWizz probe wave reports its assertions and failures.
• A regression is a behaviour that used to work but breaks after a change; probes help catch regressions.
• Acceptance criteria are observable conditions that define success; write them before deciding a change is done.
• Idempotent means safe to run again because repeating it reaches the same intended state; prefer idempotent operations for routine repairs.
• Rollback means returning to a known-good prior version when a change proves bad; atomic installation makes the replacement boundary clear.
• Atomic install means the complete staged file replaces the old file in one operation, rather than exposing a partially written file.
• Fixture means a known, controlled sample used to exercise a path; a question pack can be a fixture for import checking.
• A smoke test is a small, real-use check that the surface starts and does something essential; scripts/quizwizz-browser-smoke.js is the named browser smoke script.
• YAGNI means “you aren’t going to need it”: do not add complexity without a present, evidenced need.
• An orphan page is a wiki page with no meaningful links from the rest of the vault; wikilinks prevent knowledge from becoming lost.

Programme codenames

Every identifier used by the QuizWizz programme, decoded once. Source anchors are in the program masterplan unless another page is named.

Code	Meaning	Source
W0 — truth and fixtures	Reconcile dated visual-ledger rows with later repair measurements; keep A48/A59/A64/A75/A78 as fixture/contract gaps; establish fixtures and capture recipes.	masterplan ordered-waves table
W1 — public shell	Resolve UX-01, FE-5, and the UI portion of PL-17 via theme/content configuration, keeping QuizWizz token inheritance.	masterplan ordered-waves table
W2 — released block authoring	A70/A71/A73/A77 via companion editor filter and editor stylesheet; A72 under the owner-approved Craft contract; build/ stays unedited.	masterplan ordered-waves table
W3 — localization proof	The German catalog work and forced-German matrix (parity claim retracted 2026-08-19; see the masterplan).	masterplan ordered-waves table
W4 — cache proof	Mtime-derived asset versions and warm-cache capture proof across all enqueue/register paths.	masterplan ordered-waves table
W5 — integration evidence	Settled Site Health and Privacy Guide states visibly including QuizWizz checks/guidance.	masterplan ordered-waves table
W6 — standing discovery	Run PL-05 as a dated browser-led regression sweep after each substantive change.	masterplan ordered-waves table
W7	2026-07-31 final-push evidence: microcopy, German catalog update, direct asset-version proofs.	masterplan, “W7 final-push evidence”
W8	The SSOT capability pass closing W3/W4 gaps and the A-series verifications.	W8 SSOT capability pass
W9-01…W9-08	Resolution-ledger reconciliation items from the 2026-08 evidence-drift pass.	masterplan resolution ledger
W10-01…W10-08	The eight 2026-08-15 visual and IA repairs authorized by the 2026-08-14 fourteen-slice audit.	masterplan resolution ledger; dated record
PW-01	Publication-workflow frontier item: subscriber publication lifecycle; owner-blocked pending policy choice.	masterplan frontier table; owner decision intake
PW-02	Publication-workflow frontier item: public Builder semantic h1 heading; closed 2026-08-17.	masterplan frontier table
PW-03	Publication-workflow frontier item closed in the PL-05 sweep.	PL-05 sweep
A70, A71, A72, A73, A77	Gutenberg block-authoring findings: A70 core inserter geometry (measured, closed); A71/A77 chooser placeholder/help; A72 full-experience Craft contract; A73 editor stylesheet/token route.	masterplan W2 row and Gutenberg ledger row
A48, A59, A64, A75, A78	Fixture/contract gaps, not defects.	masterplan W0 row
PL-05	The standing dated browser-led cross-surface regression sweep.	masterplan W6 row; 2026-08-16 record
PL-06…PL-18	Launch-frontier infrastructure, policy, and operator items outside the UI/UX waves.	masterplan “Deliberately separate” section; launch frontier
Option F	The current launch posture: bench-verified operations under a standing NO-GO, with the four-page decision contract as authority.	front page; F program
FE-* / BE-* / UX-*	Finding prefixes from the 2026-07-27 full plugin audit: front end, back end, user experience.	full audit
T*-nn (for example T5-03)	Capability-ledger items in what can still be done on this bench.	can-do ledger

Status vocabulary

Exactly five tokens, defined here and used by every status ledger (superseding the eight-token set the masterplan declared before 2026-08-19):

done · verified · open · blocked(<what>) · retracted

• done — the work landed; the historical fix persists.
• verified — landed and re-proven on the live bench with a named command or measurement.
• open — known, unfinished, unclaimed.
• blocked(<what>) — cannot move until the named thing (owner decision, release input, upstream fix) arrives.
• retracted — the original claim was wrong; the retraction stays where the claim was made.

Glossary

Plain words definition	Proper term
The one written place that should settle a factual disagreement.	SSOT
The current authoritative version, unlike an old reference copy.	Source of truth vs archive
A safe running copy used for testing, not production.	Bench / staging
A front-door server that passes web traffic to an application behind it.	Reverse proxy
Encryption for traffic between a browser and server.	TLS
An isolated running software package.	Container
A packaged blueprint used to create a container.	Image
Storage that exists separately from a running container.	Volume
A host folder presented directly inside a container.	Bind mount
WordPress operated from commands rather than its browser screens.	WP-CLI
A named WordPress content kind made by a plugin.	Custom post type
A WordPress classification system.	Taxonomy
One category or label inside a taxonomy.	Term
A URL-safe identifier for a term.	Slug
The one official slug chosen for a term.	Canonical slug
Extra key-and-value data attached to a single WordPress post.	Post meta
One saved WordPress-wide value.	Option
Temporary cached WordPress data that may expire.	Transient
A scheduled WordPress action hook.	Cron hook
An HTTP endpoint the browser or another program calls.	REST route
A short-lived token that helps block forged requests.	Nonce
A permission a WordPress user must have to perform an action.	Capability
Cleaning and normalising data before storing it.	Sanitisation
Checking that data meets required rules.	Validation
A label for the expected shape of stored data.	Schema version
A controlled change from one stored-data shape to another.	Migration
A speed-focused second copy of data used for reading.	Index / denormalised read model
Disagreement between copied data and its original.	Drift
Safe to repeat because another run reaches the same desired state.	Idempotent
Returning to a known-good previous state.	Rollback
Replacing a complete staged file in one indivisible operation.	Atomic install
A fast syntax check.	Lint
A focused automated check and one fact it checks.	Probe / assertion
A previously working behaviour broken by a change.	Regression
Observable conditions that define what success means.	Acceptance criteria
Evidence showing where an artifact came from and how it was made.	Provenance
The translation system used by WordPress.	Gettext
A template listing source strings that need translation.	POT
A text file containing translations.	PO
A compiled translation file used at runtime.	MO
Agreement between translation files and the source strings.	Catalog parity
A language-and-region setting.	Locale
The way content is organised so people can understand it.	Information architecture
Showing detail only when it becomes useful.	Progressive disclosure
The label a screen reader announces for a control.	Accessible name
A UI tracker that changes navigation as the reader scrolls.	Scroll-spy
Rejecting an old save instead of overwriting a newer one.	Optimistic concurrency / revision guard
Avoiding complexity until a real need exists.	YAGNI
A known controlled sample used in testing.	Fixture
A small real-use check that essential behaviour still works.	Smoke test
A wiki page that nothing else meaningfully links to.	Orphan page
Metadata at the start of a Markdown page.	Frontmatter
A link between Markdown vault pages using double square brackets.	Wikilink
Software that turns source files into a ready-to-serve website.	Static site generator
A filesystem pointer to another location rather than a second copy.	Symlink
Publishing so readers receive either the old complete site or new complete site.	Atomic publish
A private service boundary that prevents a host connection.	Network isolation
A file recording server-side errors and warnings.	Debug log
A visually distinguished Markdown note, warning, tip, or summary.	Callout

Where to go next

If you want to…	Go here
Know what is true now	📍 Now
See what is still open, and who owns it	open-work ledger
Read the dated history of what changed	Changelog
Run or improve a guided Ego Lite showcase	tandem showcase guide
Fix the settings screen	admin IA strategy
Get more questions	question corpus hub
Change the plugin safely	Service Operations
Operate, back up or reset the bench	Service Operations
Publish docs	The “Publish a wiki change” recipe above, then Service Operations
Review QuizWizz evidence	QuizWizz audits