openclaw-wiki/knowledge/wiki-optimization-research.md

# Wiki Optimization — Team Training Environments

## The Problem With Our Current Structure

### Current State
- Files buried in subdirectories: `entities/students/bruno.md`
- Compile scans `entities/` root only → entities count = 0
- Folders create rigid hierarchy → knowledge doesn't connect across siloes
- 90 sources but they don't cross-reference meaningfully

### What We're Missing
The wiki's power isn't in folders — it's in **links**. A wiki that surfaces data usefully for a team training environment needs:

1. **Atomic notes** — one concept per file, linked to everything related
2. **Topic notes** — "hub" pages that aggregate links to related content
3. **Training paths** — sequences of notes that guide learning
4. **Entity profiles** — student/mentor pages that track skills + progress

---

## Three Fix Options

### Option A: Move Files Up (Minimum Fix)
**What:** Move `entities/students/bruno.md` → `entities/bruno.md`

| Pros | Cons |
|------|------|
| Quick fix | Solves compile only, not structure |
| Entities show up | Rigid folder hierarchy persists |
| Low risk | Doesn't enable cross-topic views |

**Verdict:** Tactical patch. Doesn't fix the real problem.

---

### Option B: Flat Structure + Topic Hubs (Recommended)
**What:**
1. Move student files to `entities/` root
2. Create **topic hub pages** that link to relevant entities + sources
3. Use Obsidian Dataview to create dynamic skill-tracking views

**Example topic hub:**
```
# PathPlanner Training Hub
[[bruno]] — working through PathPlanner basics
[[riley]] — completed intro module
[[photonvision]] — integrated with autonomous routines
[[mothman-robot-code]] — YAGSL swerve implementation

## Learning Path
1. [[systemcore]] — understand the controller first
2. [[swere-modules]] — then how the drivetrain works
3. [[photonvision]] — then vision-based positioning
4. PathPlanner → finally, how to program paths
```

| Pros | Cons |
|------|------|
| Compile works | Requires more setup upfront |
| Teams see learning paths, not files | Topic hubs need maintenance |
| Cross-topic views via Dataview | — |
| Scales to any number of students | — |
| Each hub is a training module | — |

**Verdict:** Best for our scenario. Chris teaches — he needs learning paths, not file browsers.

---

### Option C: Recursive Compile Config
**What:** Configure the wiki plugin to recurse into subdirectories

| Pros | Cons |
|------|------|
| Keeps subdirectories | Requires config change |
| Existing structure preserved | May break with OpenClaw updates |
| — | Doesn't solve cross-linking problem |

**Verdict:** Avoid. Kicks the problem downstream.

---

## Recommendation: Option B

**Why Option B surfaces data most usefully for our scenario:**

Chris is a teacher. The Fabric watches all silos. The wiki should answer questions like:

| Question | How Option B Answers It |
|----------|------------------------|
| "Who's learning PathPlanner?" | [[pathplanner-hub]] → [[bruno]] + [[riley]] |
| "What does a new student need to learn?" | Topic hub shows prerequisites + links |
| "Where are the gaps in our training?" | Hub pages with missing/unfinished links |
| "What did Bruno complete?" | Dataview query: student + status + date |
| "Show me all sensor-related docs" | [[sensors-hub]] → links to all sensor sources |

**Topic hubs we'd need:**

| Hub | Purpose | Links |
|-----|---------|-------|
| `swere-training-hub` | Drivetrain learning path | Bruno, Riley, MK4i, NEO Vortex, YAGSL |
| `vision-training-hub` | Camera + AprilTag setup | PhotonVision, MegaTag, AprilTag field layout |
| `pathplanner-hub` | Autonomous programming | Student progress, YAGSL, Mothman code |
| `electrical-hub` | Wiring + CAN bus | SPARK Flex, CANcoder, PDH, Canjectors |
| `cad-training-hub` | Fusion 360 learning | Bruno, Riley, Fusion 360 module |

---

## Implementation Steps

### Step 1: Fix Entity Compile (5 min)
```bash
cd /home/topher/.openclaw/wiki/main
git mv entities/students/bruno.md entities/bruno.md
git mv entities/students/riley.md entities/riley.md
git commit -m "Flatten entities structure for compile"
git push
```

### Step 2: Create Topic Hub Pages (ongoing)
Start with the most important hub — the one Chris teaches from most:

**`training/hubs/swere-training-hub.md`**
- Links: MK4i, NEO Vortex, SPARK Flex, YAGSL, Bruno (learning), Riley (completed)
- Learning path with prerequisites
- Status indicators per student

### Step 3: Add Frontmatter for Dataview
Add to each student profile:
```yaml
---
type: student-profile
track: swerve
skills:
  - fusion-360: intermediate
  - pathplanner: beginner
  - welding: beginner
status:
  pathplanner: in-progress
  swere-basics: completed
---
```

Then Dataview can query: "Show all students with `skills.pathplanner: beginner`"

---

## Research Path for Chris

This IS the research path. The "fix" isn't a wiki plugin config — it's **restructuring the wiki around how Chris teaches**:

1. **Atomic notes** per hardware concept (we already have this)
2. **Topic hubs** that aggregate + sequence learning (we're missing this)
3. **Entity profiles** with structured skill tracking (we have the files, wrong location)
4. **Training paths** that show prerequisite chains (needed for system to surface gaps)

The Fabric then detects gaps by watching:
- Which hub links are broken?
- Which student profiles show no recent progress?
- Which hub has no topic hub page yet but students need it?

---

## Key Insight

**Folders are for files. Hubs are for learners.**

Chris teaches. The wiki should organize around what students need to learn, not where files live. Topic hubs do that — they group related content from across all silos into coherent learning paths.

**Option B is the fix.** Want me to start with the swerve training hub? 🎓