06 Traps

Platform traps

Fifteen places where GitHub behaves differently from what a person writing documentation expects. Each is backed either by the GitHub documentation or by a measurement on a live repository.

Trap	Symptom	Action
The wiki repository is not created by a push	remote: Repository not found	save the first page in the web interface, then publish
Wikis are barely indexed	a page exists, search never shows it	per documentation only wikis with 500+ stars and public editing disabled are indexed; use GitHub Pages
A private wiki needs a paid plan	no wiki in a private repository	it will not exist on the free plan
Flat namespace	a link to docs/page fails	every page lives in the wiki root
A relative image in a wiki	does not render	commit it, reference an absolute raw URL
.md in a wiki link	raw file or 404	drop the extension
Cyrillic anchors	#Установка is not found	punctuation dropped, spaces to hyphens, lowercase
An em dash in a heading	a double hyphen in the anchor	the dash is removed; two spaces become two hyphens
PUT /topics replaces the list	topics you did not touch vanish	merge with the existing set, re-read
More than 20 topics	some topics disappear	the API stores 20
Pages in a private repository	422 Your current plan does not support GitHub Pages for this repository	not available on the free plan
Pages builds are asynchronous	404 right after enabling	poll the build, then the URL
gh api --jq .content	base64 with line breaks	-H 'Accept: application/vnd.github.raw'
An SVG as a social preview	the upload is rejected	PNG, JPG or GIF only
The platform's own anchor example	a capital Greek letter against a lowercase rule	compare anchors case-insensitively

Three traps that cost the most

A wiki does not replace a website

The GitHub documentation states it plainly: only wikis with 500+ stars and public editing disabled are indexed, and if indexing is what you need, use GitHub Pages. So "write a wiki and we will be found" is a wrong strategy: a wiki serves the people who already reached the repository.

--prune deletes foreign work

Publication keeps pages the build does not contain and prints their list. Deletion is a separate flag. The reason is simple: the server may hold pages written by hand, and losing them silently is not acceptable.

A wiki checkout is not a repository tree

In a wiki [Architecture](Architecture) is a page, not a file, and _Sidebar.md / _Footer.md are navigation that GitHub renders on every page. A checker that treats a wiki checkout like an ordinary tree reports every correct link as a missing file and every partial as a document without a title — measured on a 24-page wiki: 121 errors, 119 of them false. ghagent doc detects the context from the markers (_Sidebar.md, _Footer.md) and switches the link rule to page names inside that directory only; the same link in a repository stays an error.

wiki verify reads what you named

The command resolves its target in a fixed order: --out, then a --wiki-dir that already looks like a wiki (Home.md, _Sidebar.md or _Footer.md present), then .ghagent/wiki. The header of the report names the directory that was actually read, so --root <repo> --wiki-dir <clone> verifies the clone. A repository with neither sources nor a build gets one note, not an error: a wiki kept in its own repository is checked in that checkout.

A check that examined zero objects

An empty tree, a broken path, a missing file — none of these produce a green result. They produce an error or a coverage.skipped line. Otherwise an agent reports success having checked nothing, which is worse than a failure.

Checking the traps yourself

python tools/ghagent.py doc --root . --json
python tools/ghagent.py audit --repo owner/name
python tools/ghagent.py assets check
python tools/ghagent.py wiki verify

doc --json carries a rules_examined field: it shows how many objects each rule examined. A zero there means the rule did not run, not that it passed.

Next

• Import into another agent.
• File contracts.