AI Brain Wiki

AI-Brain Wiki Maintenance

Key Facts

• Wiki root: ${AI_BRAIN_ROOT:-$HOME/AI-Brain} (NOT ~/OneDrive/AI-Brain)
• Tools: tools/lint.py, tools/search.py, tools/fix-media.py, tools/tl.py
• Wiki pages: wiki/
• Raw sources (immutable): raw/
• Search index: .qmd/ (auto-generated)
• Run all tools with: uv run python tools/.py

Search

# Build/rebuild index (required first time each session or after ingest)
cd ${AI_BRAIN_ROOT:-$HOME/AI-Brain}
uv run python tools/search.py index wiki/

# Search
uv run python tools/search.py search "your query"

Index is cached in .qmd/ — only rebuild if stale (after new ingests).

Lint

cd ${AI_BRAIN_ROOT:-$HOME/AI-Brain}
uv run python tools/lint.py

Run after every ingest. Fix all issues before ending session — they compound.

Common lint issues and fixes

1. Missing Counter-arguments section in concept page

   • Add "## Counter-arguments and data gaps" (exact casing — all lowercase after first word)
   • Minimum 4-6 bullet points; include strongest external critique even if all sources agree

2. Broken link [[some-slug]]

   • Check if the target file actually exists: search_files for the slug in wiki/
   • If it's a false positive from a code block: the lint.py bug was fixed (strips backtick spans before scanning links) — but re-check if lint.py was reverted
   • If genuinely broken: create the missing page or fix the wikilink

3. Heading casing mismatch

   • Lint checks for EXACT string "## Counter-arguments and data gaps"
   • Pages that wrote "## Counter-arguments and Data Gaps" (capital D/G) will fail
   • Fix: lowercase the heading

4. Orphan pages

   • Every page needs ≥1 inbound link from another wiki page AND entry in index.md
   • Add wikilink from a related page and add row to index.md

Known lint.py fix (applied 2026-04-11)

lint.py was patched to strip fenced code blocks ( ) and inline code spans ( ) before scanning for wikilinks. This prevents false-positive broken link reports when wikilinks appear as examples inside code spans.

If you see a broken link that looks like it lives inside backticks in the source file, check if lint.py has this fix:

# 4. Broken links — strip code blocks and inline code first
content_no_code = re.sub(r'```.*?```', '', content, flags=re.DOTALL)
content_no_code = re.sub(r'`[^`\n]+`', '', content_no_code)
links = re.findall(r'\[\[(.*?)\]\]', content_no_code)

If missing, patch tools/lint.py to add it.

Ingest workflow (summary)

1. Check ingest-manifest.md for dedup
2. Read + classify source
3. Write wiki/sources/.md
4. Update entities/, concepts/, overview.md as needed
5. Update index.md
6. Append log.md
7. Run: uv run python tools/fix-media.py --apply
8. Run: uv run python tools/search.py index wiki/
9. Every 5th ingest: PYTHONIOENCODING=utf-8 mempalace mine wiki/
10. Run lint: uv run python tools/lint.py — fix all issues
11. Append to ingest-manifest.md