Configuration Reference

Configuration Reference

The kit has no runtime configuration file and no config daemon — it is a toolbox. Its configuration surface is exactly four things: command-line flags of fourteen tools, three JSON documents you author per run (ban.json, terms.json, PROGRESS.json), environment variables consumed by publish/publish.sh, and five templates you copy and fill. This page is the complete inventory at commit 7e17a11; every flag was read from the argparse/getopts definitions and exercised where testable (test IDs refer to this wiki run's evidence logs).

Contents

• Quick orientation
• Command-line flags by tool
  • scan/repo_scan.py
  • probe/webapp_probe.py
  • lib/serve.py (CLI mode)
  • lib/req.py (CLI mode)
  • scaffold/new_page.py
  • qa/qa_wiki.py
  • qa/fix_toc.py
  • setup/check_runtime.py · setup/bootstrap.sh · setup/snapshot.sh · publish/publish.sh
• JSON documents
  • ban.json — phrases that must never appear
  • terms.json — canonical terms + banned synonyms
  • PROGRESS.json — the run's state document
• Environment variables
• Templates
• Defaults worth knowing
• See also

---

Quick orientation

You want to…	Configure…	Where
Ban a false claim	ban.json	Phase 2, from research/sources.md §D
Lock terminology	terms.json	Phase 2, from the domain-notes glossary
Record the page tree	PROGRESS.json	Phase 2, from templates/PROGRESS.json.tmpl
Change what gets probed	--suite, --copy, --entry, custom suite function	probe/webapp_probe.py
Change how the subject is served	--serve-cmd, --port	lib/serve.py / probe CLI
Change the delivery artefacts	PUBLISH_OUT, PUBLISH_BUNDLE, GIT_AUTHOR_*, WIKI_COMMIT_SUBJECT	publish/publish.sh
Change bootstrap behaviour	--with-node, --with-php83, --with-composer, --subject	setup/bootstrap.sh

Command-line flags by tool

scan/repo_scan.py

Flag	Type / default	Effect
root	positional, required	repository directory to inventory
-o, --out FILE	path	write the full JSON here (parents auto-created)
--brief	flag	print the two-minute human summary; implied when --out is absent
--max-files N	int, 4000	walk cap for very large repositories

Exit codes: 0 ok · 2 root is not a directory.

probe/webapp_probe.py

Flag	Type / default	Effect
--repo DIR	path	stage a fresh ServedApp copy and probe it (mutually exclusive with --base-url; one is required)
--base-url URL	URL	probe an already-running instance (batteries that mutate config need --repo)
--copy "a,b,c"	CSV	names to stage from --repo (default: everything except VCS dirs)
--serve-cmd TMPL	string	server command template; {host} {port} {root} substituted (default php -S {host}:{port} -t {root})
--entry PATH	path, /	entry point the suites build on
--suite NAME	generic | php-mdviewer	battery set to run
-o, --out FILE	path	evidence JSON
--md FILE	path	Markdown evidence tables (per group: request, status, bytes, ms, expected, ok)
--keep	flag	keep the staged docroot for post-mortem

lib/serve.py (CLI mode)

Flag	Type / default	Effect
source	positional	directory containing the app
--copy	CSV	staging list
--serve-cmd	template	as above
--port N	int	fixed port; fails loudly if busy (never silently drifts to another port)
--keep	flag	keep staged dir
--check PATH	path	GET once ready and print status + byte count

Module parameters (ServedApp.__init__): source, copy, serve_cmd, port, host="127.0.0.1", keep=False, quiet=True.

lib/req.py (CLI mode)

python3 lib/req.py METHOD URL [-d key=value]... [-H 'Header: value']... [-o FILE] [--headers-only]

Flag	Effect
-d k=v	repeatable; switches the request to POST form-encoded
-H 'K: V'	repeatable request header
-o FILE	write the body to FILE
--headers-only	print status line + headers, skip the body

scaffold/new_page.py

Flag	Type / default	Effect
wiki_dir	positional, required	target directory (created if absent)
title	positional, optional	single-page mode title
--init	flag	full skeleton: Home.md, _Sidebar.md, _Footer.md, one stub per page
--pages "A,B,…"	CSV	page list; Home auto-prepended
--project NAME	Project	footer/badge/facts project name
--repo-url URL	placeholder	repository link in footer + Home facts
--version V	0.0.0	footer/sidebar version line
--license L	MIT	Home badge + footer
--commit SHA	HEAD	footer "verified against commit" line
--progress FILE	path	preferred grouping source: reads page tree + pages[].group
--groups "L:A,B|L2:C"	string	explicit sidebar grouping (second preference)
--sections "X,Y"	CSV	H2 stubs in single-page mode (default Overview,Details,Examples)
--force	flag	overwrite existing files (default: skip + note)

qa/qa_wiki.py

Flag	Effect
wiki_dir	positional (optional only with --self-test)
--strict	exit 1 on any error
--json FILE	machine-readable full result
--terms FILE	terminology checking (terms.json)
--ban FILE	banned-claim checking (ban.json)
--quiet	tables off, exit code + JSON only
--self-test	22-detection fixture suite

qa/fix_toc.py

Flag	Effect
wiki_dir	positional (optional only with --self-test)
--bak	write <file>.bak before touching each page
--dry-run	report what would change
--self-test	the accident fixture (lead/badge/alert must survive)

setup/check_runtime.py · setup/bootstrap.sh · setup/snapshot.sh · publish/publish.sh

Tool	Arguments
check_runtime.py	subject-dir positional; --quiet; exit 0 fine/nothing declared, 2 mismatch, 1 bad argument
bootstrap.sh	--with-node · --with-php83 · --with-composer · --subject DIR (gate; non-zero exit stops you) · -h/--help
snapshot.sh	$1 workspace dir (default workspace), $2 commit message (default UTC timestamp)
publish.sh	$1 wiki dir (required), $2 OWNER/REPO (required), $3 --push (optional)

JSON documents

ban.json — phrases that must never appear

Shape: { "<phrase>": "<why it is banned>", …, "exemptions": [...], "fluff_exemptions": [...] }.

Key	Type	Semantics
top-level phrase: reason	string → string/list/dict	case-insensitive substring match on the scrubbed view of every page → ERROR with the reason and a 110-char context excerpt
_-prefixed keys	any	documentation; never treated as phrases (the 1.0.1/1.2.1 loader fixes)
exemptions	list	structural key — never a phrase
fluff_exemptions	list	structural key — exempts marketing-filler hits (e.g. domain terms like "unlock a hard lock" in lock-management prose)
exemption object	{phrase, file?, quote?, reason}	file and quote narrow the match; matched hits report as INFO, never silently dropped

Matching semantics you can rely on (all verified in the --self-test context fixture, T1):

1. Fenced code, inline code, [[wiki-links]], ](#anchor) targets and filenames (*.py|md|php|js|json|sh|…) are blanked before matching — a GitHub anchor slug or a probe filename cannot fire.
2. A negation or hedge (no, not, never, without, lacks, false, myth, claims, asserts, allegedly, reportedly, "the docs say", …) within ~90 characters before the hit, in the same sentence, downgrades ERROR → WARNING. It never suppresses: "There is no GPG verification" must stay visible to a human.
3. An all-meta ban file (every key _-prefixed) produces a WARNING ("no active phrases") — a silent no-op would let you believe bans are enforced.
4. Authoring rule (PITFALLS C8): never quote a banned phrase even to refute it — paraphrase. Substring matching cannot tell a refutation from an assertion.

terms.json — canonical terms + banned synonyms

{
  "canonical": { "browse root": "browse root", "machine API": "machine (json )?api" },
  "avoid":     { "API token (use 'API_KEY' or 'key')": "\\bapi token\\b" },
  "exemptions": [ {"phrase": "<the avoid key>", "file": "Troubleshooting.md",
                   "quote": "<verbatim fragment>", "reason": "verbatim 404 string of the subject"} ],
  "_tuning_log": ["what was narrowed and why"]
}

Section	Semantics
canonical	term → regex; counts usage per term and prints the top 12 in the report. Never fails. Use the counts to spot a glossary term you defined but never used, or one used 90 times next to a synonym used twice
avoid	term → regex; any match on the scrubbed view is an ERROR with a 120-char context window
exemptions	same mechanism as ban.json; the error message itself tells you the escape hatch: "verbatim subject strings and filenames win: narrow the pattern and log it in _tuning_log, or record an exemption"
_tuning_log	append-only history of patterns narrowed/deleted after false positives

Tuning doctrine (PITFALLS D6, learned on a real 73k-word wiki): prefer patterns that match a specific wrong phrase over patterns that match a common noun. Two shipped patterns had to be removed after firing on correct prose (base director — legitimate when describing a function whose job is a base directory; config file — legitimate generic prose). A checker that cries wolf trains you to ignore it, which is worse than not having it.

PROGRESS.json — the run's state document

From templates/PROGRESS.json.tmpl. Fields:

Field	Purpose
project, subject_repo, subject_commit, phase, updated, target_dir	orientation for a resuming agent
style_contract	language, format, filenames-with-spaces rule, link convention, every-page structure, devices (alerts/mermaid/tables/code), tone, the hard rule
do_not_claim	filled from sources.md §D; mirrored into ban.json for enforcement
pages[]	{file, title, group, status, words, notes} — --progress reads title + group to build the sidebar; status (todo/draft/done) and words track Phase 3
qa	latest audit numbers (link/anchor/fence errors, shell blocks checked, alerts, mermaid, wiki-links, fluff hits)
delivery	canonical dir, prepared commit, bundle path, bundle_verified, instructions/report paths, push_status

Environment variables

Variable	Consumer	Effect
PUBLISH_OUT	publish.sh	clone/hand-over directory (default <wiki-parent>/publish)
PUBLISH_BUNDLE	publish.sh	bundle path (default <wiki-parent>/<REPO>.wiki.bundle)
GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL	publish.sh step 4	commit identity (default wiki-bot <wiki-bot@localhost>)
WIKI_COMMIT_SUBJECT	publish.sh step 4	commit subject line (default docs(wiki): complete wiki for <REPO>)

No other tool reads the environment. In agent sandboxes, an additional variable may matter for your own scripts: some harnesses remap the workspace root (this wiki run's sandbox exported ARENA_WORKSPACE and rewrote /home/user in command strings — see Sandbox Survival Guide for why scripts must resolve such paths at runtime rather than hardcode them).

Templates

File	Becomes	Filled from
templates/ban.json	workspace/ban.json	research/sources.md §D (claims deliberately not made)
templates/terms.json	workspace/terms.json	research/domain-notes.md glossary
templates/PROGRESS.json.tmpl	workspace/PROGRESS.json	Phase 2 page-tree decisions
templates/STATE.md.tmpl	workspace/STATE.md	orientation: phase, layout, confirmed facts, checklist, next action
templates/REWORK-STATE.md.tmpl	workspace/REWORK-STATE.md	recovery artefact: resume recipe, environment rebuild, key paths, sandbox quirks, checklist, next action, append-only log

Template conventions: {{PLACEHOLDER}} tokens; _-prefixed JSON keys are documentation and are ignored by loaders; _template_delete_me blocks show the shape and must be promoted or deleted when you fill a real ban list.

Defaults worth knowing

Default	Value	Why it matters
ServedApp host	127.0.0.1	staged servers are never exposed on the network
ServedApp serve command	php -S {host}:{port} -t {root}	non-PHP subjects must pass --serve-cmd
Port selection	OS-chosen verified-free port	a busy preferred port raises instead of drifting (PITFALLS A1)
HTTP redirects	not followed (req.py, session.py)	a 302 is part of the contract you document
HTTP errors	returned as data	a probe suite that raised on 404 would lose exactly the cases it exists to document
Evidence excerpt	180 chars	keeps evidence files small and limits secret exposure
repo_scan file cap	4 MB / 4000 files	huge repos need --max-files
QA strictness	warnings never fail --strict	errors are contract; warnings are judgement calls (emoji, lead-paragraph length, relative links)
Publish push	off unless --push	the sandbox has no credentials; the hand-over is the deliverable

---

See also

• Tool Reference — the same tools described by behaviour and internals
• QA and Audit Guide — ban/terms tuning in practice
• The Four Phase Workflow — when each document gets authored
• Publishing and Delivery — the hand-over artefacts in detail
• Glossary — canonical vocabulary