Kaburu Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# Wiki Structure Audit & Recommendations

## 1. Current State

### Raw Stats

| Metric | Value |
|--------|-------|
| Total .md files | 71 (excluding .git) |
| Total lines | 10,015 |
| Total content size | ~485 KB (markdown only) |
| Wiki + .git | 18 MB |
| Git-tracked | Yes (all changes committed) |
| Syncthing'd | Yes (Obsidian vault sync to desktop/laptop) |

### By Category

| Category | Pages | Lines | % of content |
|----------|-------|-------|--------------|
| Infrastructure | 29 | 3,346 | 33.4% |
| Web | 6 | 1,169 | 11.7% |
| Clients | 9 | 553 | 5.5% |
| Services | 5 | 405 | 4.0% |
| Procedures | 4 | 1,214 | 12.1% |
| Projects | 5 | 1,337 | 13.4% |
| Security | 4 | 518 | 5.2% |
| SEO | 0 | 0 | 0.0% |
| Log | 2 | 851 | 8.5% |
| Root orphans | 6 | ~400 | 4.0% |
| Nested subdirs | 1 | ~100 | 1.0% |

### Structural Issues Found

**1. Root orphans (6 files living outside any category):**
- `backup.md` — should be in `security/` or `infrastructure/`
- `CLAUDE.md` — intentional, meta-file, correct location
- `email-platform.md` — should be in `infrastructure/` or `services/`
- `index.md` — intentional, correct location
- `longniddrybowlingclub.md` — should be in `wiki/clients/`
- `ubuntu-svr.md` — **DUPLICATE** of `wiki/infrastructure/ubuntu-svr.md`; root copy is older and less complete

**2. Wikilinks: 13 broken of 61 total (21% failure rate)**
- `[[divi-5-builder-bot]]` → should be `[[divi-5-builder-bot]]`
- `[[z840]]` → should be `[[z840]]` (machine was renamed)
- `[[longniddrybowlingclub]]` → no page exists
- `[[mainwp]]`, `Ollama (local LLM server)`, `Wordfence (WAF)` → TODO items never created
- `[[opnsense]]` → should be `[[opnsense]]`
- `SSH hardening`, `[[index]]`, `[[index]]` → category-level links, no pages

**3. Orphan pages: 23 with zero incoming wikilinks**
- All 7 client pages except rainbowvapes have no incoming links
- `comfyui`, `false-flags`, `hermes-soul`, `home-assistant`, `opnsense-dns`, `permissions-fix`, `tailscale-acl`, `update-log`, `odoo-workflow-platform` — infrastructure/project pages with no cross-references
- Log files and index (expected orphans)

**4. Missing YAML frontmatter: 11 pages (16%)**
- Most critically: `truenas.md`, `divi-5-builder-bot.md`, `opnsense-dns.md`, `womenunlimited-perf.md`
- Logs are intentionally without frontmatter (append-only)

**5. Index.md is catastrophically stale**
- Claims "Pages: 21" — actual count is 71
- `last_updated: 2026-06-20` — 15 days stale at time of audit
- Missing sections: projects (entirely), 7 client pages, security pages beyond 2 listed
- Client section is completely empty ("TODO: one page per client" — but 9 client pages exist)
- Services section lists cloudflare and brevo as "TODO" — both pages exist

**6. CLAUDE.md partially out of date**
- Directory structure omits `wiki/projects/` (5 pages exist)
- Migration status frozen at 2026-06-13
- Page count embedded in text is wrong
- SEO directory listed but empty (content under clients/ instead)

**7. SEO category is empty**
- `wiki/seo/` directory exists, has 0 files
- SEO content lives in `wiki/clients/rainbowvapes-seo.md` instead
- Index lists SEO as "TODO" with items that partially exist

**8. Nested subdirectory `clients/longniddry/` contains mail.md**
- Only nested client subdirectory — breaks flat convention
- Inconsistent with all other client pages at `wiki/clients/*.md`

---

## 2. Agent Pain Points

### Scenario 1: "Where are the SSH credentials?"

Agent prompt (system message) says: `→ /home/kaburu/wiki/wiki/infrastructure/credentials.md`

**Hops needed:** 0. The system prompt gives the direct path.

**Actual content quality:** Credentials page is only 25 lines (926 bytes). It lists Cloudflare token location and FastPixel API key — literally in plaintext. No SSH key paths, no user accounts, no passwords. It's misleadingly named and incomplete. The *real* SSH instructions live scattered across the system prompt itself ("Ground Rules" section) and individual server pages (truenas.md, ubuntu-svr.md).

**Pain level:** LOW for navigation (system prompt has it), MEDIUM for content (page is incomplete, credentials are scattered).

### Scenario 2: "How to build a Divi page?"

Agent finds:
- `wiki/web/divi-5-lessons.md` (20,763 bytes — comprehensive reference)
- `wiki/projects/divi-5-module-api-calls.md` (35,633 bytes — API cheat sheet)
- `wiki/projects/divi-5-builder-bot.md` (13,734 bytes — builder bot design)

**Hops needed:** 1-2. Read one page, follow its cross-references.

**Pain level:** LOW. Content is rich, cross-referenced. These three pages are the best-maintained in the wiki.

### Scenario 3: "Context on a specific client site?"

Agent needs info on, say, bankhousecatering.co.uk:
- `wiki/clients/bankhousecatering.md` (1,300 bytes — 43 lines, mostly a todo list)
- No cross-references to other relevant pages (server info, SSL, migration status)

**Hops needed:** 2+. Read client page, then manually reason about which infrastructure pages apply.

**Pain level:** MEDIUM. Client pages are thin (avg 61 lines each). They're mostly SEO strategy notes and todo lists — not operational references. They don't link to the server, SSL, or migration pages that an agent needs to actually *do* work on the site. Scatter-gather required.

### Scenario 4: "Are the log entries useful?"

`log/log.md` is 839 lines (46,571 bytes). It's append-only with dated headers.

**Analysis:** The log is useful for "what happened recently" queries and session continuity. Explicit dates make `search_files` effective for temporal lookups. But it's 55% of a single page — at 800+ lines it's hitting the point where agents either skip it or spend tokens scrolling. Individual entries are generally useful (they capture decisions, fixes, and context).

**Pain level:** LOW-MEDIUM. Useful but getting long. No structural fix needed — just awareness that it's the single largest page and keeps growing.

### Scenario 5: "Find things by category?"

Agent asks: "What security pages exist?"

**Current approach:** `search_files` on the `security/` directory. Returns 4 files immediately.

**Pain level:** NONE. The directory structure IS the category system. `search_files` is fast. An agent finding "all security pages" takes one tool call.

But if the agent asks: "What SEO pages exist?" — `wiki/seo/` is empty, content is in `wiki/clients/rainbowvapes-seo.md`. That's a discoverability failure.

---

## 3. Reality Check

### 1. Is there actually a problem, or are we just building because we can?

**There is a hygiene problem, not a structural problem.**

The flat-file directory layout WORKS. `search_files` is FTS5-backed and fast. Agents navigate by reading the system prompt (which gives explicit paths) and then searching directories. The wiki is well-organized by category.

But there are real hygiene issues: 13 broken links (21% failure), a stale index claiming 21 pages when 71 exist, root orphans, duplicate content, and inconsistent frontmatter.

None of these issues are *blocking* agent work. They're friction — an agent might follow a broken link and have to search again, or not realize a page exists because the index doesn't mention it.

### 2. How often do agents fail to find info in the wiki?

**We have no telemetry on this.** The audit can't quantify agent failure rates because agents don't log "I couldn't find X in the wiki."

From log analysis (839 entries), there are zero logged instances of an agent saying "I can't find this in the wiki." Agents either find what they need or fabricate an answer.

The real risk isn't navigation failure — it's agents trusting broken cross-references or missing pages entirely because they're not in the index.

### 3. Would a database actually solve the problem, or just move it?

**A database would move it — to a worse place.**

The problems found are:
- Broken links → a DB doesn't prevent broken links
- Stale index → a DB needs queries, which also go stale if not maintained
- Missing frontmatter → a DB schema IS frontmatter with extra steps
- Root orphans → a DB has orphan rows instead
- Thin client pages → a DB doesn't write content for you

The wiki is git-tracked, Syncthing-synced, human-editable in any text editor, and searchable with FTS5. A SQLite database loses ALL of this. No git diff, no Obsidian editing, no grep, no Syncthing. You'd need a custom MCP server just to query it.

**A database adds complexity without solving a single problem the audit found.**

### 4. What's the SIMPLEST fix?

1. Fix 13 broken wikilinks (search/replace, 5 minutes)
2. Move 4 root orphans to correct directories (mv, 2 minutes)
3. Delete duplicate `ubuntu-svr.md` in root (rm, 10 seconds)
4. Add missing YAML frontmatter to 11 pages (copy/paste template, 10 minutes)
5. Regenerate index.md with actual page counts and categories (script or manual, 15 minutes)
6. Move `wiki/clients/longniddry/mail.md` → `wiki/clients/longniddry-mail.md` (flatten, 1 minute)

**Total: ~35 minutes of work. Zero tooling changes. Zero migration. Zero risk.**

### 5. Is this a wiki problem, or an agent-prompt problem?

**Mostly a wiki hygiene problem, but the agent prompt is actually doing its job well.**

The agent's system prompt explicitly maps "where to find things" with direct paths. This works. The prompt says "before running any command, check the relevant wiki page first." Agents do this.

The prompt also says "if the wiki doesn't have what you need, ask Steve" — this is the escape hatch that's working.

The wiki needs minor cleanup. The agent prompt needs zero changes.

### VERDICT: NOT NEEDED — no database, no restructure, no migration

**The threshold was: "fewer than 5 concrete agent failures to find info → recommend NO structural change."**

We found ZERO logged agent failures. The wiki works. It needs a cleanup pass, not a rebuild.

---

## 4. Recommendations

### Option A: Wiki Hygiene Pass (RECOMMENDED)

**Cost:** 35 minutes of agent work
**Benefit:** Eliminates 21% broken-link rate, fixes discoverability for 5 uncategorized pages, makes index accurate
**Risk:** Essentially zero (all changes are within the wiki, git-revertable)
**What to do:**
1. Fix broken wikilinks — batch search/replace
2. Relocate root orphans to proper directories
3. Delete duplicate `ubuntu-svr.md` in root
4. Add frontmatter to 11 missing pages
5. Regenerate index.md with actual counts and ALL pages listed
6. Flatten `clients/longniddry/mail.md` to `clients/longniddry-mail.md`
7. Update CLAUDE.md page counts and add missing `projects/` to directory structure

### Option B: Relational/SQLite

**Cost:** 2-3 days to design schema, write migration, build MCP server, test
**Benefit:** Structured queries, constraints, relational integrity
**Risk:** HIGH — loses git tracking, Syncthing sync, Obsidian editing, grepability, portability. Migration errors lose data. Agent workflows break.
**Verdict:** ❌ NOT RECOMMENDED. Solves zero problems found in audit.

### Option C: Hybrid (SQLite index + markdown content)

**Cost:** 1 day to build indexer + query tool
**Benefit:** Rich metadata queries without giving up markdown
**Risk:** MEDIUM — two sources of truth (file and DB index can drift), added complexity
**Verdict:** ❌ NOT RECOMMENDED. The `search_files` tool (FTS5-backed) already gives fast full-text search. Index regeneration is a simpler solution to the same problem.

### Option D: Automated Index Generation (BONUS — add to Option A)

**Cost:** 1 hour to write a script
**Benefit:** Never-stale index, always accurate counts
**Risk:** LOW — script reads files, doesn't modify them
**What:** A cron job or Hermes task that:
- Scans all .md files
- Extracts titles from frontmatter
- Groups by directory (category)
- Generates `index.md` with page counts, last_updated, and description snippets
- Runs daily or on wiki commit

**Verdict:** ✅ Worth doing AFTER the hygiene pass. Solves the "index is always stale" problem permanently.

---

## 5. Implementation Plan

### Phase 1: Immediate Cleanup (this session or next)

1. Fix 13 broken wikilinks
2. Move root orphans: `backup.md` → `wiki/security/`, `email-platform.md` → `wiki/infrastructure/`, `longniddrybowlingclub.md` → `wiki/clients/`
3. Delete `/home/kaburu/wiki/ubuntu-svr.md` (duplicate of `wiki/infrastructure/ubuntu-svr.md`)
4. Add YAML frontmatter to: `truenas.md`, `womenunlimited-perf.md`, `hermes-soul.md`, `opnsense-dns.md`, `divi-5-builder-bot.md`, `16wells-integration.md`, `longniddrybowlingclub.md`
5. Flatten `clients/longniddry/mail.md` → `wiki/clients/longniddry-mail.md`, remove nested dir
6. Regenerate `index.md` with accurate stats
7. Update `CLAUDE.md` with correct page count and `projects/` directory
8. Git commit all changes

### Phase 2: Automation (future session)

1. Write index generator script
2. Add to Hermes cron or git post-commit hook
3. Add automated broken-link checker to regular health checks

### Phase 3: Content Quality (ongoing)

1. Bulk up thin client pages with cross-references to relevant infra pages
2. Move/consolidate SEO content from `rainbowvapes-seo.md` into `wiki/seo/` directory
3. Consider log rotation when `log.md` exceeds 1,000 lines

---

## Appendix A: Full Broken Link Report

| Broken Link | Source File(s) | Fix |
|-------------|---------------|-----|
| `[[divi-5-builder-bot]]` | divi-5-lessons.md | → `[[divi-5-builder-bot]]` |
| `[[z840]]` | hermes.md, hermes-memory.md, kaburulink.md | → `[[z840]]` |
| `[[longniddrybowlingclub]]` | log.md | → `[[longniddrybowlingclub]]` |
| `[[mainwp]]` | wordpress-sites.md, kaburusvr.md | → Create page or remove link |
| `Ollama (local LLM server)` | z840.md | → Create page or remove link |
| `[[opnsense]]` | ubuntu-svr.md (wiki) | → `[[opnsense]]` |
| `SSH hardening` | hardening.md | → Create page or remove link |
| `Wordfence (WAF)` | hardening.md | → Create page or remove link |
| `[[index]]` | tailscale-acl.md | → Remove (category-level link) |
| `[[index]]` | email-platform.md | → Remove (self-referential) |

## Appendix B: Orphan Pages with No Incoming Links

| Page | Should Be Linked From |
|------|----------------------|
| `24hrresponse.md` | index.md, kaburusvr.md |
| `bankhousecatering.md` | index.md, kaburusvr.md |
| `chippy.md` | index.md, kaburusvr.md |
| `comfyui.md` | z840.md |
| `doctorfin.md` | index.md, kaburusvr.md |
| `false-flags.md` | hermes.md |
| `ggsgenerators.md` | index.md, kaburusvr.md |
| `hermes-soul.md` | hermes.md |
| `home-assistant.md` | topology.md |
| `jafricasafari.md` | index.md, kaburusvr.md |
| `odoo-workflow-platform.md` | kaburusvr.md |
| `opnsense-dns.md` | opnsense.md |
| `permissions-fix.md` | kaburusvr.md |
| `rainbowvapes-seo.md` | rainbowvapes.md |
| `tailscale-acl.md` | tailscale.md |
| `update-log.md` | CLAUDE.md, index.md |
| `womenunlimited-perf.md` | (no client page exists for this site) |