claudetools/.claude/specs/wiki-layer/plan.md

# Wiki Layer — Implementation Plan

**Status:** Phase 1 in progress (Cascades + GuruRMM seeded 2026-05-24)

---

## Phase 0 — Structure (no code, low effort, high foundation value)

**Goal:** Create the directory skeleton and article templates. Nothing else runs yet.

### Tasks

- [ ] Create `wiki/` root with `index.md` stub
- [ ] Create `wiki/clients/`, `wiki/projects/`, `wiki/systems/`, `wiki/patterns/` directories
- [ ] Write article templates (see `standards.md`)
- [ ] Add `.gitkeep` files so empty dirs commit
- [ ] Verify GrepAI watcher picks up `wiki/` automatically (it should — it watches the repo root)
- [ ] Add `wiki/` mention to `CLAUDE.md` context-loading section (read `wiki/<topic>.md` when topic is known)

**Done when:** Directory exists, templates written, GrepAI indexes it.

---

## Phase 1 — Seed Pass (high effort, immediate ROI)

**Goal:** Compile first-pass wiki articles for the two highest-value targets: GuruRMM and Cascades.

### Approach

Run `/wiki-compile` manually, read and correct output, commit. This is a supervised pass — we're validating the compilation quality before automating.

### Tasks

- [ ] Compile `wiki/projects/gururmm.md` from `projects/msp-tools/guru-rmm/session-logs/` + root session logs mentioning GuruRMM
- [ ] Compile `wiki/clients/cascades.md` from `clients/cascades/session-logs/` + root logs mentioning Cascades
- [ ] Compile `wiki/systems/` entries for Neptune, Jupiter, Pluto, Saturn (from session logs + credentials.md)
- [ ] Mike reviews each article, corrects factual errors, commits
- [ ] Run second seed pass for remaining active clients and projects

**Done when:** All active clients and systems have wiki articles. Mike has reviewed at least Cascades + GuruRMM.

---

## Phase 2 — `/wiki-compile` Command

**Goal:** Implement the compile command as a repeatable skill.

### Command behavior

```
/wiki-compile [scope]

Scopes:
  client:<name>        Compile from clients/<name>/session-logs/ + matching root logs
  project:<name>       Compile from projects/<name>/session-logs/ + matching root logs
  system:<name>        Compile from all logs mentioning the system name or hostname
  all                  Full pass — all articles, oldest-first by last_compiled date

Without scope: prompt user to select
```

### Steps Claude takes when `/wiki-compile` is invoked

1. Identify scope from argument
2. Find relevant session logs (by directory + GrepAI keyword search)
3. Read existing wiki article if it exists (note `last_compiled` date)
4. Read session logs newer than `last_compiled` (or all if new article)
5. Read relevant CONTEXT.md and memory entries for cross-reference
6. Call Ollama (qwen3:8b) to generate/update the article
   - Summarize new information, merge with existing
   - Update backlinks section
   - Update `last_compiled` frontmatter
7. Present diff to user for review before writing
8. On approval: write article, update `wiki/index.md`

### Tasks

- [ ] Write `.claude/commands/wiki-compile.md` (the skill file)
- [ ] Write Ollama prompt template for article compilation
- [ ] Implement index.md update logic
- [ ] Test with GuruRMM and Cascades

**Done when:** `/wiki-compile client:cascades` runs end-to-end, produces correct article, updates index.

---

## Phase 3 — `/context` Integration

**Goal:** `/context` checks wiki before raw logs.

### Updated `/context` flow

```
1. Search wiki/index.md for topic mentions
2. Read matching wiki/<type>/<name>.md articles (synthesized knowledge)
3. THEN search session logs for recent/specific detail not yet compiled
4. Check credentials.md for access details
5. Return synthesized answer: wiki content + relevant log excerpts
```

### Tasks

- [ ] Update `.claude/commands/context.md` with wiki-first search step
- [ ] Add "Check wiki/index.md" as Step 1 in context command
- [ ] Add note: if topic has a wiki article, read it first; use logs only for recency

**Done when:** Running `/context cascades` returns the wiki article summary + any recent-session additions.

---

## Phase 4 — `/wiki-lint` Command

**Goal:** Health-check the wiki for staleness and integrity issues.

### Lint rules

| Rule | What It Checks | Action |
|---|---|---|
| Stale IPs | IPs in wiki vs CONTEXT.md + credentials.md | Flag discrepancies |
| Rate conflicts | Billing rates in wiki vs memory entries | Flag conflicts |
| Orphaned articles | Wiki articles with no session log activity in 90+ days | Flag for review/archive |
| Missing articles | Clients/projects mentioned in recent logs with no wiki article | Suggest compile |
| Broken backlinks | `[[links]]` pointing to non-existent articles | Flag |
| Memory conflicts | Memory entries contradicting wiki facts | Flag with both versions |

### Tasks

- [ ] Write `.claude/commands/wiki-lint.md`
- [ ] Implement lint checks
- [ ] Decide: run as scheduled cron or manual-only? (recommend: manual initially, cron after 30 days)

**Done when:** `/wiki-lint` runs, produces a report with actionable issues.

---

## Phase 5 — `/save` Integration (optional, lower priority)

After writing session log, detect which clients/projects/systems were mentioned, prompt:

```
Session log saved. Detected topics: GuruRMM, Cascades.
Update wiki for these topics? [y/n]
```

If y: run `/wiki-compile` for each detected topic before sync.

### Tasks

- [ ] Add topic detection to `/save` (regex on session log content)
- [ ] Add post-save wiki update prompt
- [ ] Wire through to `/wiki-compile`

---

## Migration Strategy

| What | Risk | How |
|---|---|---|
| Session logs | None | Not touched, wiki reads from them |
| CONTEXT.md | None | Not touched, wiki reads from it |
| Memory entries | Low | Wiki links to memory; memory links to wiki |
| `/context` command | Low | Additive — wiki step added before log search |
| GrepAI index | None | Automatic — picks up `wiki/` files on next index cycle |
| Cross-machine sync | None | Wiki is tracked in Git, syncs via normal `sync.sh` |

**No existing functionality is removed or broken.** All changes are additive.

---

## Recommended Start Order

1. ~~Phase 0 (structure)~~ — DONE 2026-05-24
2. Phase 1 seed:
   - [x] Cascades of Tucson — `wiki/clients/cascades-tucson.md` — DONE 2026-05-24
   - [x] GuruRMM — `wiki/projects/gururmm.md` — DONE 2026-05-24
   - [ ] Systems: neptune, jupiter, pluto, saturn
   - [ ] `wiki/overview.md` — compile AFTER systems are seeded (reads other wiki articles)
3. Phase 2 command — implement and test — 2-3 hours
4. Phase 3 context integration — 30 minutes
5. Phase 4 lint — schedule for after 30 days of real wiki use
6. Phase 5 save integration — nice-to-have, do if Phase 1-4 prove value

## Overview Article (added 2026-05-24)

`wiki/overview.md` — scope `/wiki-compile overview`

The "cold-start" doc. Compiles from other wiki articles (not raw logs directly), so it is cheap to maintain.

Sections:
- **Team** — Mike (admin/owner), Howard (tech/employee), machines, roles
- **Active Clients** — one-liner per client with billing type, hours, primary open project, link to wiki article
- **Active Projects** — one-liner per project with version/status, link to wiki article
- **Key Infrastructure** — what runs where (Neptune, Jupiter, Pluto, Saturn, plus client-side infra)
- **Tooling Stack** — coord API, GrepAI, Ollama, SOPS vault, Gitea, Syncro PSA, GuruRMM
- **State of the Business** — current snapshot: active projects, open billing, near-term priorities

This article is the one Howard reads on a new machine before touching anything else.