LESSONS

Lessons Learned — Qidi Q2 Superuser Wiki

[W001] GitHub Wiki indexes subdirectory .md files — use _Sidebar.md to control navigation

• Category: gotcha
• Context: wiki repo structure

GitHub Wiki does index .md files in subdirectories (including _claude/) into the auto-generated sidebar. Files in _claude/ will appear in navigation unless suppressed. Create a _Sidebar.md at the repo root to take explicit control of sidebar contents and order. Any page not listed in _Sidebar.md is hidden from the sidebar but still accessible by URL.

[W002] _claude/ is obscurity, not security

• Category: gotcha
• Context: wiki repo structure

The _claude/ folder is not access-controlled. Anyone who clones the wiki repo (git clone https://github.com/Camden-Winder/Qidi-Q2-superuser.wiki.git) can read it. Do not store secrets, tokens, or private information here.

[W003] Wiki links must omit .md — .md links go to raw file view

• Category: gotcha
• Context: internal linking

GitHub Wiki URLs omit the .md extension (e.g. /wiki/SSH-Guide). Using [text](SSH-Guide.md) navigates to the raw file view, not the rendered wiki page. Always use [text](SSH-Guide) — no extension — for all internal wiki links.

[W004] WIKI_VERSION lives as an HTML comment on line 1 of Home.md

• Category: pattern
• Context: versioning

Format: <!-- WIKI_VERSION: Wiki-RC1.XX --> Bump the minor on every session that touches wiki files. Bump the major only for a structural overhaul. Always update this at the end of the session — never mid-session.

[W005] Do not create a session brief without explicit user permission

• Category: process
• Context: session management

Claude must not create or populate a session brief file unless the user has explicitly said yes in this session. Asking "should I write the brief?" and proceeding on any non-explicit or ambiguous response is not permitted. The user must clearly say yes before any brief file is written.