rfcp/UMTC-Wiki-MEGA-TASK.md

# UMTC Wiki v2.0 — MEGA TASK: Integration & Polish

Read UMTC-Wiki-v2.0-REFACTOR.md and UMTC-Wiki-v2.0-ROADMAP.md for full context.

This is a comprehensive task covering all remaining fixes and integration work.
Take your time, think hard, work through each section systematically.
Report after completing each major section.

---

## SECTION A: Fix Critical Tauri 404 Bug

The sidebar loads the full content tree correctly but clicking ANY article shows 404.

### Debug steps:
1. In `frontend/src/lib/api.ts` — find where getPage is called with a slug
   Add `console.log('[WIKI] getPage called with slug:', slug)` 

2. In `frontend/src/lib/utils/backend.ts` — in the tauriGetPage function
   Add `console.log('[WIKI] Tauri invoke get_page with:', slug)`

3. In `desktop/src-tauri/src/commands/content.rs` — in the get_page handler
   Add `eprintln!("[WIKI] get_page received slug: {}", slug)`
   Add `eprintln!("[WIKI] trying path: {:?}", resolved_path)`

4. Check the Sidebar.svelte component — what href/slug does it generate when user clicks?
   The web version uses `/api/pages/{slug}` — in desktop mode it should invoke with just the slug part.

5. Common mismatches to check:
   - Leading slash: sidebar sends `/lte/bbu` but Rust expects `lte/bbu`
   - File extension: Rust looks for `lte/bbu.md` but file is `lte/bbu/index.md`
   - URL encoding: Ukrainian characters in slugs
   - The SvelteKit catch-all route `[...slug]` may pass the slug differently

6. Fix the mismatch. Test navigation to at least 10 different pages including:
   - Root sections (lte/, ran/, mikrotik/)
   - Nested pages (lte/bbu, ran/srsenb-config)
   - Glossary terms (glossary/prb)
   - Deep nesting if any

---

## SECTION B: Fix Web Deployment

The web version must keep working. Test and fix:

1. Check that `backend/content.py` imports work:
   - `from wiki_frontmatter import ArticleFrontmatter` 
   - `from wikilinks import WikiLinksExtension`
   - `from backlinks import BacklinksIndex`
   - `from admonitions import AdmonitionsExtension`
   
   If any import fails, fix the module.

2. Add the admonitions extension to the markdown pipeline in content.py
   (wikilinks was already integrated, verify admonitions too)

3. Make sure the backlinks API endpoint in main.py works:
   - GET /api/pages/{slug:path}/backlinks
   - Should return { "slug": "...", "backlinks": [...], "count": N }

4. Add grade/status/category to the page API response:
   - GET /api/pages/{slug} should now include grade, status, category fields

5. Create a simple test script `scripts/test_web.py`:
   ```python
   # Test that backend starts and key endpoints work
   import requests
   BASE = "http://localhost:8000"
   
   # Test navigation
   r = requests.get(f"{BASE}/api/navigation")
   assert r.status_code == 200
   nav = r.json()
   print(f"Navigation: {len(nav)} sections")
   
   # Test page load
   r = requests.get(f"{BASE}/api/pages/index")
   assert r.status_code == 200
   print(f"Home page: {r.json().get('title', 'OK')}")
   
   # Test search
   r = requests.get(f"{BASE}/api/search?q=LTE")
   assert r.status_code == 200
   print(f"Search 'LTE': {len(r.json())} results")
   
   # Test backlinks
   r = requests.get(f"{BASE}/api/pages/glossary/enb/backlinks")
   print(f"Backlinks for eNB: {r.status_code}")
   
   print("\nAll tests passed!")
   ```

---

## SECTION C: Frontend Wiki Components — Full Integration

### C.1: Article Grade Badge on Pages

In the wiki page view (`frontend/src/routes/[...slug]/+page.svelte` or equivalent):
- Import ArticleGrade component
- Display the grade badge next to the page title
- The grade comes from the page API response (field: `grade`)
- If no grade, don't show badge
- Style: small badge inline with title, not a separate block

### C.2: Breadcrumbs Component

Create/update `frontend/src/lib/components/wiki/Breadcrumbs.svelte`:
```svelte
<!-- Example: Головна > LTE > BBU Setup -->
<nav class="breadcrumbs">
  <a href="/">Головна</a>
  <span class="separator">/</span>
  <a href="/lte">LTE</a>
  <span class="separator">/</span>
  <span class="current">BBU Setup</span>
</nav>
```
- Generate from current page slug
- Each segment is a link except the last
- Use titles from navigation tree if available, otherwise humanize slug
- Works in both web and desktop mode
- Integrate into the page layout — show above article title

### C.3: Admonition CSS

Add styles for admonition boxes to the global CSS or a component:
```css
.admonition {
  border-left: 4px solid;
  border-radius: 4px;
  padding: 12px 16px;
  margin: 16px 0;
}
.admonition-note { border-color: #3b82f6; background: rgba(59,130,246,0.1); }
.admonition-warning { border-color: #f59e0b; background: rgba(245,158,11,0.1); }
.admonition-tip { border-color: #10b981; background: rgba(16,185,129,0.1); }
.admonition-danger { border-color: #ef4444; background: rgba(239,68,68,0.1); }

/* Dark mode */
:global(.dark) .admonition-note { background: rgba(59,130,246,0.15); }
:global(.dark) .admonition-warning { background: rgba(245,158,11,0.15); }
:global(.dark) .admonition-tip { background: rgba(16,185,129,0.15); }
:global(.dark) .admonition-danger { background: rgba(239,68,68,0.15); }

.admonition-title {
  font-weight: 600;
  margin-bottom: 4px;
}
.admonition-icon {
  margin-right: 8px;
}
```

### C.4: Wiki-Link CSS

Add styles for wiki-links:
```css
.wiki-link {
  color: #3b82f6;
  text-decoration: none;
  border-bottom: 1px dotted #3b82f6;
}
.wiki-link:hover {
  border-bottom-style: solid;
}
.red-link {
  color: #ef4444;
  border-bottom-color: #ef4444;
}
.red-link:hover::after {
  content: " (сторінку не знайдено)";
  font-size: 0.75em;
  color: #9ca3af;
}
```

### C.5: Backlinks Panel Integration

In the page view, after the article content:
- Show BacklinksPanel component
- Pass current page slug
- Works in both web (API) and desktop (Tauri IPC)
- Only show if there are backlinks (don't show empty panel)

### C.6: Table of Contents (sidebar)

If the page has headings, generate a table of contents:
- Extract h2/h3 from rendered HTML or use TOC data from backend
- Show as a floating sidebar on wide screens (>1200px)
- Collapsible on smaller screens
- Highlight current section on scroll (intersection observer)
- Works in both modes

---

## SECTION D: Search Integration for Desktop

1. Test Tantivy search in Tauri:
   - The search command should be wired to the Search component
   - Type in search bar → results appear
   - Cyrillic text should work (test: "мережа", "антена", "LTE")
   
2. If search doesn't work, debug:
   - Is the search index built on startup? Check Rust logs
   - Are content files found? Check content path resolution
   - Is the query reaching the search command?

3. Search results should show:
   - Page title
   - Brief excerpt (first 150 chars of content)
   - Click navigates to page

4. Keyboard shortcut: Ctrl+K should focus the search bar (already exists in web, verify in desktop)

---

## SECTION E: Content Quality Pass

### E.1: Content Audit Script

Create `scripts/analyze_content.py`:
- Scan all .md files in content/
- For each file report: has_frontmatter, word_count, has_code_blocks, grade, broken_wiki_links
- Summary: total articles, by grade, articles needing work
- Print actionable output

### E.2: Add More Glossary Terms (20 more)

Create glossary entries with proper frontmatter (grade: B, category: glossary):

**Radio/RF terms:**
- SGW (Serving Gateway)
- PGW (PDN Gateway)  
- HSS (Home Subscriber Server)
- RSRP (Reference Signal Received Power)
- RSRQ (Reference Signal Received Quality)
- SINR (Signal to Interference plus Noise Ratio)
- EARFCN (E-UTRA Absolute Radio Frequency Channel Number)
- OFDM (Orthogonal Frequency Division Multiplexing)
- MIMO (Multiple Input Multiple Output)
- QoS (Quality of Service)

**Infrastructure terms:**
- WireGuard
- MikroTik
- Mesh Network
- VLAN (Virtual LAN)
- BGP (Border Gateway Protocol)
- mTLS (Mutual TLS)
- Caddy (Web Server)

**Protocol terms:**
- S1AP (S1 Application Protocol)
- GTP (GPRS Tunnelling Protocol)
- SCTP (Stream Control Transmission Protocol)

Each glossary term should:
- Have title in English with Ukrainian description
- Use [[wiki-links]] to cross-reference other terms
- Include: what it is, why it matters for UMTC, key parameters
- Be 100-300 words

### E.3: Upgrade 5 Key Articles to Grade B

Pick the 5 most important articles and upgrade them:
- Add proper frontmatter with all fields
- Add :::note and :::warning admonitions where useful
- Add [[wiki-links]] to glossary terms
- Add "Див. також" (See also) section with related articles
- Verify technical accuracy
- Set grade: B

Good candidates: 
- Main LTE overview
- srsENB configuration  
- WireGuard setup
- Open5GS overview
- MikroTik basics

---

## SECTION F: Desktop App Polish

### F.1: Window Title

Show current page title in the window title bar:
`UMTC Wiki — {Page Title}`

### F.2: Keyboard Navigation

- Arrow keys in sidebar to navigate
- Enter to open selected item
- Backspace to go back
- Ctrl+K for search (verify)

### F.3: Error Handling

- If page not found, show a friendly Ukrainian message instead of generic 404
- If content directory is missing, show setup instructions
- If search index fails to build, log error but don't crash

### F.4: About Dialog

Add a simple about/info accessible from a gear icon or Help menu:
- UMTC Wiki v2.0
- Built with Tauri + SvelteKit + Rust
- Content articles count
- "Офлайн документація для УМТЗ"

---

## SECTION G: Production Builds

### G.1: Web Docker Build Test

Update docker-compose.yml if needed to include new backend modules.
Make sure Dockerfile copies:
- backend/wiki_frontmatter.py
- backend/wikilinks.py  
- backend/backlinks.py
- backend/admonitions.py
- All content/ files

### G.2: Tauri Production Build

Run `npx tauri build` and fix any remaining compilation errors.
Report the output binary size and location.

---

## Order of Operations

Do these in order — each section builds on the previous:

1. **SECTION A** — Fix 404 bug (CRITICAL, everything depends on this)
2. **SECTION B** — Verify web backend
3. **SECTION C** — Frontend components
4. **SECTION D** — Search
5. **SECTION E** — Content
6. **SECTION F** — Desktop polish
7. **SECTION G** — Production builds

Report after each section with:
- What was done
- What files were changed
- Any issues found
- Ready for next section?

Think hard about edge cases. Don't break existing functionality.
Good luck! 🚀