Getting Started

Getting Started

From zero to a scaffolded, audited, publishable wiki skeleton in one sitting — the shortest honest path through the kit. Every command below was executed during this wiki run in a fresh sandbox (Debian-class, root, Python 3.11.2); the sample outputs are real, lightly trimmed. The full doctrine lives in The Four Phase Workflow; this page is the five-minute shape of it, plus where to go deep.

Contents

• Prerequisites
• Step 1 — get the kit and prepare the environment
• Step 2 — clone the subject and check its runtime floor
• Step 3 — inventory the subject in two minutes
• Step 4 — RUN the subject and probe it
• Step 5 — design the wiki before writing it
• Step 6 — scaffold the skeleton
• Step 7 — write, then audit to zero
• Step 8 — deliver
• Where to go next
• See also

---

Prerequisites

• An environment with python3 (3.8+), bash and git — the bootstrap will confirm and fill gaps.
• A subject repository URL you are allowed to clone and run.
• An LLM agent that can execute shell commands and write files (Claude Code, Codex-class tooling, or a human at a terminal — the kit is agent-operated but not agent-exclusive).

Step 1 — get the kit and prepare the environment

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

The bootstrap ends with a capability report and an egress check:

== 5. Capability report
  git          git version 2.39.5
  curl         curl 7.88.1 (x86_64-pc-linux-gnu) ...
  jq           jq-1.6
  python3      Python 3.11.2
  rg           ripgrep 13.0.0
  php          PHP 8.2.34 (cli) ...
== 6. Network egress
  https://github.com                     200
  https://raw.githubusercontent.com      301
  https://api.github.com                 200

Read setup/PITFALLS.md now — fifteen minutes that eliminate the mistakes which cost the reference run hours. Its first three entries produce silently wrong results.

Step 2 — clone the subject and check its runtime floor

mkdir -p workspace/repo && cd workspace/repo
git clone https://github.com/OWNER/REPO SUBJECT
cd ../..
python3 setup/check_runtime.py workspace/repo/SUBJECT

Exit 0 means fine (or nothing declared); exit 2 means the installed interpreter cannot boot the subject — fix the runtime first (the tool prints the recipe), because every probe of an unbootable subject measures a corpse.

Step 3 — inventory the subject in two minutes

python3 scan/repo_scan.py workspace/repo/SUBJECT --brief -o workspace/research/scan.json

The brief prints: git metadata including whether tags exist (this changes how you document versioning), license and extra attribution clauses, declared dependencies or their absence, the largest files (where the logic lives), entry points, version markers, every external host (your supply-chain facts), security-signal counts, and the configuration-key surface. Run against the kit itself, it reported: 8 commits, no tags, MIT, "NO MANIFEST — zero declared dependencies", 44 files / 5,523 code lines, entry point setup/bootstrap.sh.

Step 4 — RUN the subject and probe it

For a web app (PHP shown; other runtimes via --serve-cmd):

python3 probe/webapp_probe.py --repo workspace/repo/SUBJECT \
    --copy 'index.php,css,js' --entry /index.php --suite generic \
    -o workspace/research/probe.json --md workspace/research/probe.md

For a CLI or library subject, write a small driver that shells out and records stdout/stderr/exit codes — the shape matters, not the transport (see Research and Probing Guide).

The console summary flags every expectation mismatch with a verbatim marker, and the batteries report in one line each:

SUITE generic  ·  16 requests
    200  GET   /md.php
    404  GET   /.git/config
    ...
traversal : 17/20 denied, 0 leaked sensitive content
injection : 19/26 payloads survived into the response
headers   : /md.php missing → Content-Security-Policy, X-Content-Type-Options, ...

(The figures above are this run's real measurement against the reference subject MD.Viewer 2.18.0, staged locally — full battery in 0.46 s.)

Caution

Batteries fire path-traversal and injection payloads. Run them against the staged local copy (--repo), never against third-party or production hosts. See Security Considerations.

Step 5 — design the wiki before writing it

Copy and fill the three Phase-2 documents:

cp templates/PROGRESS.json.tmpl workspace/PROGRESS.json   # page tree + groups + style contract
cp templates/ban.json           workspace/ban.json        # from research/sources.md section D
cp templates/terms.json         workspace/terms.json      # from the domain-notes glossary

Write the five research files first if you have not (summary.md, architecture.md, domain-notes.md, facts.json, sources.md with its §D "claims deliberately not made") — §D is what you paste into ban.json, and it is the artefact that stops a future pass from re-adding a plausible falsehood.

Step 6 — scaffold the skeleton

python3 scaffold/new_page.py workspace/wiki/OWNER.REPO.wiki --init \
    --project "SUBJECT" --repo-url https://github.com/OWNER/REPO \
    --version X.Y.Z --commit abc1234 --license MIT \
    --progress workspace/PROGRESS.json

Output: Home.md, _Sidebar.md, _Footer.md and one stub per planned page — every stub already carrying the H1, lead-paragraph slot, ## Contents and ## See also that the auditor requires. Filenames use spaces (Security Hardening Guide.md); this is not cosmetic — GitHub resolves [[Security Hardening Guide]] against the space-named file, and a hyphenated filename makes every such link dead.

Step 7 — write, then audit to zero

Fill pages (hardest first — usually Security and the big reference matrices), then loop:

python3 qa/fix_toc.py workspace/wiki/OWNER.REPO.wiki --bak
python3 qa/qa_wiki.py workspace/wiki/OWNER.REPO.wiki \
    --terms workspace/terms.json --ban workspace/ban.json --strict

Run python3 qa/qa_wiki.py --self-test once per session first — it proves the checker can fail (22 detections). Then iterate on the audit until ERRORS (0). The scaffold alone already passes:

TOTAL  pages=5 (3 content)  words=378  alerts=1  mermaid=1  tables=13  code=2  wiki-links=13
ERRORS (0):
WARNINGS (0):

Step 8 — deliver

bash publish/publish.sh workspace/wiki/OWNER.REPO.wiki OWNER/REPO

QA-gates, clones the .wiki.git repo (branch master; falls back to a local git init with origin configured when the wiki was never initialised), commits, produces a verified bundle, writes PUBLISH.md with three push options, and stops — pushing needs credentials your sandbox probably lacks, and that is a planned outcome, not a failure. Finish with workspace/wiki/REPORT.md: what was verified, how, what the subject's own docs got wrong, and the limits of your analysis.

Where to go next

You want…	Page
the reasoning and rules behind each phase	The Four Phase Workflow
to probe something unusual (CLI, two layouts, sessions)	Research and Probing Guide
to write pages that pass the first time	Writing Pages Guide
to understand an auditor error	QA and Audit Guide and Troubleshooting
every flag of every tool	Tool Reference and Configuration Reference
to publish into an existing wiki with history	Publishing and Delivery
to survive a sandbox that fights back	Sandbox Survival Guide

---

See also

• Home — the wiki's entry point and navigation
• Installation and Setup — requirements and environment in depth
• Features and Verification Model — what the kit guarantees and how
• FAQ — common first-run questions
• Security Considerations — authorized-use doctrine before you probe