Installation and Setup

Installation and Setup

Getting the kit onto a machine — an agent sandbox, a CI runner, or a developer workstation — and proving the environment before spending effort on it. There is nothing to install in the package-manager sense: the kit is a git clone with zero declared dependencies. What does need setup is the surrounding environment (Python, bash, git, and a runtime for whatever subject you probe), which is exactly what setup/bootstrap.sh automates and reports on. Every command on this page was executed during this wiki run (T0, T12).

Contents

• Requirements
• Installation
  • What bootstrap.sh does, step by step
  • The runtime-floor gate
• Workspace layout for a run
• Non-root and offline environments
• Verifying the installation
• See also

---

Requirements

Requirement	Minimum	Verified in this run	Notes
Python	3.8+ (README floor claim)	3.11.2	CI matrix runs 3.9 / 3.11 / 3.12; the 3.8 floor is a claim, not a CI-tested fact
bash	any modern (4+)	5.2-class	three .sh tools; all pass bash -n
git	any modern	2.39.5	clone, snapshot, publish
PHP CLI	only for PHP subjects	8.2.34 (installed by bootstrap)	ServedApp's default serve command; session.py --self-test needs it
curl, jq, rg, unzip, zip, shellcheck	optional helpers	installed by bootstrap	the kit's Python never shells out to them; your wiki's documented commands might
node/npm	optional	present (v20.20.2)	--with-node; mermaid-cli or JS subjects
network egress	github.com for clone/publish; distro mirrors for bootstrap	github.com → 200, api.github.com → 200	fully offline runs are possible except clone/push
disk	small: kit is ~621 KB	—	plus subject clones, staged copies, evidence

Dependencies declared by the kit: none — no manifest of any ecosystem exists in the repository (scan/repo_scan.py reports "NO MANIFEST — zero declared dependencies"). Every import in the 12 Python files is stdlib. This is a deliberate supply-chain property, not an accident: there is no pip install step to go wrong, no lockfile to drift, no transitive tree to audit.

Installation

git clone https://github.com/paulmann/github-wiki-llm-writer.git
cd github-wiki-llm-writer
bash setup/bootstrap.sh

That is the whole installation. The clone is the toolkit; bootstrap.sh prepares the environment around it. Pin a known-good state by commit SHA when reproducibility matters (this wiki was verified against 7e17a11); note that the repository has no tags and no releases, so version pinning means commit SHAs and CHANGELOG.md entries (see Changelog and Versioning).

What bootstrap.sh does, step by step

Step	Action	Why it exists
0	Identity + package-manager detection (apt / dnf / apk)	knows what it is working with; prints uid and cwd
1	apt-get update	a fresh sandbox has empty package lists; every install fails with "Unable to locate package" until this runs (PITFALLS B1) — the single most common first-command failure
2	Installs git, curl, jq, python3, unzip, zip, ripgrep, shellcheck (each skipped if present; unzip/zip unconditionally because of the composer trap, B9)	idempotent; every install logs to /tmp/apt-<label>.log and reports success/failure per tool
3	Installs php-cli php-mbstring php-curl; prints the PHP version and loaded modules	lets you RUN PHP subjects instead of reading them
3b	--with-composer: downloads and installs composer	only when the subject needs it
4	--with-node: installs nodejs + npm	mermaid-cli, JS subjects
5	Capability report: versions of 10 tools + import check of 8 stdlib modules	know exactly what you have before writing tools around it
6	Network egress check: github.com, raw.githubusercontent.com, api.github.com	clone/publish feasibility in one glance
7	--subject DIR: runtime-floor gate via setup/check_runtime.py; exits non-zero on mismatch	"refusing to continue: probing a subject the runtime cannot boot produces silently wrong findings" (B10)

Measured (T0, root-privileged Debian-class sandbox): full run ~58 s dominated by apt; installed PHP 8.2.34 with curl json mbstring openssl modules; capability report complete; egress 200 / 301 / 200. Re-running is safe — every install step checks command -v first.

The runtime-floor gate

bash setup/bootstrap.sh --subject repo/SUBJECT
# or standalone:
python3 setup/check_runtime.py repo/SUBJECT

The gate reads the subject's declared floor (composer.json → require.php, package.json → engines.node, go.mod → go X.Y) and compares it with the installed runtime. Exit codes: 0 fine or nothing declared · 2 mismatch · 1 bad argument. On mismatch it prints a boxed banner and, on Debian bookworm with PHP, points at the Sury recipe:

# PHP newer than the distro default (PITFALLS B10 recipe)
apt-get install -y lsb-release ca-certificates apt-transport-https software-properties-common
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" \
  > /etc/apt/sources.list.d/php.list
apt-get update && apt-get install -y php8.3-cli php8.3-mbstring php8.3-curl

Note

The Sury path adds a third-party APT signing key to the machine. That is a supply-chain decision — review it before enabling --with-php83 in environments you do not own. The kit prints the recipe rather than silently running it. A lower-than-documented runtime is often acceptable for verification: "verified on PHP 8.2.34, documented target 8.3+" is an honest and useful statement in the final report, not a defect. What is not acceptable is probing a subject that cannot boot at all.

Verified (T12): a stub declaring php: >=8.3 under the installed 8.2.34 exits 2 with the banner; >=8.1 exits 0; a manifest-less subject exits 0 with "nothing declared — nothing to compare".

Workspace layout for a run

The kit expects (and its .gitignore protects) a run workspace next to the clone, never inside the kit tree:

workspace/
├── STATE.md              recovery orientation (from templates/STATE.md.tmpl)
├── REWORK-STATE.md       resume recipe + quirks + append-only log
├── PROGRESS.json         page tree, style contract, QA + delivery state
├── ban.json  terms.json  QA inputs (from templates/)
├── repo/SUBJECT/         the clone under documentation (read-only reference)
├── research/             Phase-1 outputs incl. scan.json, probe.{json,md}, evidence/
└── wiki/
    ├── OWNER.REPO.wiki/  THE DELIVERABLE (filenames with spaces)
    ├── publish/          prepared clone (publish.sh output)
    ├── *.bundle          verified git bundle
    ├── PUBLISH.md        hand-over instructions
    └── REPORT.md         closing report

Copy the templates and initialise the state files before Phase 1 ends:

cp templates/STATE.md.tmpl          workspace/STATE.md
cp templates/REWORK-STATE.md.tmpl   workspace/REWORK-STATE.md
cp templates/PROGRESS.json.tmpl     workspace/PROGRESS.json
cp templates/ban.json               workspace/ban.json
cp templates/terms.json             workspace/terms.json

Two rules from hard experience: everything must live under the persistent workspace root — files in /tmp do not survive agent sessions (A3; the original run lost its entire probe suite that way, which is why the kit exists in this shape); and never place deliverables in directories snapshot systems exclude (dist/, build/, out/, caches, node_modules/).

Non-root and offline environments

bootstrap.sh assumes a package manager and root (agent sandboxes typically run as root). On a workstation without root, treat the capability report as a checklist and install the equivalents yourself — the kit itself only needs python3, bash and git; PHP is per-subject. Offline: clone the kit and the subject in advance; skip step 6's expectations; publish.sh will take the fallback path (local git init + bundle) and the push happens later where network exists.

Verifying the installation

python3 qa/qa_wiki.py --self-test    # 22 detections expected
python3 qa/fix_toc.py --self-test    # 8 checks expected
python3 lib/evidence.py --self-test  # 3 checks expected

All three passed in this run (T1–T3). If any fails, the environment or the checkout is broken — do not proceed to a real run on top of a failing self-test. lib/session.py --self-test additionally needs PHP and exercises a live session app (8/8 in this run, T9).

---

See also

• Getting Started — the first full run, command by command
• Tool Reference — every flag of bootstrap.sh and check_runtime.py
• Sandbox Survival Guide — the environment traps the bootstrap defends against
• Security Considerations — supply-chain notes on the Sury recipe and badge hosts
• Changelog and Versioning — pinning by SHA in the absence of tags