786 lines
36 KiB
Markdown
786 lines
36 KiB
Markdown
# Void Docs Consolidation & Wiki Restructure — Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Collapse the Void's 7 overlapping spaces into 3 meaningful ones (Wiki / The Void / Bookmarks), turn the Wiki into an ordered, sectioned "traditional lab documentation" area that is the single source of truth, preserve the Void 1.x record + doc lineage, and retire BookStack to a passive secondary mirror.
|
||
|
||
**Architecture:** Most work is data manipulation on the **prod** Postgres DB (`void` @ `192.168.1.215`). One small code change adds page ordering + sectioned rendering to the `void-v2` app. Pure structural moves (space/parent/position changes, deletes) are done via SQL transactions; content **merges** (where two copies of a doc diverge) are done through the Void web page-editor so `body_html` + embeddings regenerate. Lineage between projects (The Void) and service docs (Wiki) is expressed with `entity_links`.
|
||
|
||
**Tech Stack:** PostgreSQL 16 + pgvector (prod DB on CT 310 `.215`), Node 22 / Express app (`void-v2`, CT 311 `.216`), `node lib/db/migrate.js up`, deploy via `deploy/push.sh`. PVE snapshots for safety (CT 310 + 311 on host Z).
|
||
|
||
**Authoritative reference data** (gathered 2026-06-05; re-verify counts before destructive steps):
|
||
- Spaces today: `void` (1 pg, 3 proj), `void1` (25 pg, 17 proj, 30 convo), `wiki` (24 pg), `plans` (6 pg), `void3` (8 pg), `bookmarks` (2 refs), `external-research` (empty).
|
||
- Wiki root page: slug `hynesy-homelab`, title "Hynesy Homelab" (all 23 other wiki pages are its direct children).
|
||
- DB creds for this work: `DATABASE_URL` in `/project/src/void-v2/.env` (`postgres://void:…@192.168.1.215:5432/void`). Prod app OWNER_TOKEN lives in `/opt/void-server/.env` on CT 311 (`.216`) — fetch at execution for API edits (the `.env` token in the repo is dev-only and is rejected by prod).
|
||
- Latest applied migration: `019_project_research.sql`. Next: `020`.
|
||
- `projects.status` CHECK allows: `idea | active | paused | done | abandoned`.
|
||
|
||
---
|
||
|
||
## Pre-flight verdict table (void1 ↔ wiki duplicates)
|
||
|
||
Classification computed by line-diff on 2026-06-05. Drives Task 5. "Drop v1" = delete the void1 copy, wiki copy is canonical. "Merge" = fold void1-only facts into the wiki copy first.
|
||
|
||
| void1 page | wiki counterpart | verdict | action |
|
||
|---|---|---|---|
|
||
| Next steps & follow-ups | (same) | IDENTICAL | drop v1 |
|
||
| Open WebUI LXC (103) | (same) | IDENTICAL | drop v1 |
|
||
| OpenClaw VM (200) | (same) | IDENTICAL | drop v1 |
|
||
| BookStack LXC (104) | (same) | ±5 lines | drop v1 (cosmetic) |
|
||
| Claude Code LXC deployer (agentic.sh) | (same) | ±2 lines | drop v1 (cosmetic) |
|
||
| Iventoy Pxe Lxc | iVentoy PXE LXC (107) | ±2 lines | drop v1 (cosmetic) |
|
||
| Mediastack Lxc | Mediastack LXC (100) | ±2 lines | drop v1 (cosmetic) |
|
||
| Usb Autosync | USB auto-sync drive | ±3 lines | drop v1 (cosmetic) |
|
||
| Operations notes | (same) | wiki ⊇ v1 (+26/-4) | merge 4 v1-only lines → wiki, drop v1 |
|
||
| Overview | (same) | wiki fuller (+10/-11) | merge 11 v1-only lines → wiki, drop v1 |
|
||
| Network map | (same) | wiki fuller (+34/-19) | merge 19 v1-only lines → wiki, drop v1 |
|
||
| Master Index | (same) | wiki fuller (+48/-28) | rewrite (Task 9), drop both old |
|
||
| Gramps Web — CT 109 | Gramps LXC (109) | wiki 14.5KB ⊇ v1 1.8KB | salvage ≤29 v1 lines → wiki, drop v1 |
|
||
| **Ollama LXC (102)** | (same) | **DIVERGE (conflicting facts)** | **real merge → wiki, drop v1** |
|
||
| Claude LXC deployer | (intra-v1 dup of agentic.sh, same md5) | EXACT DUP | drop v1 (pure cruft) |
|
||
|
||
void1 pages with **no** wiki counterpart (these are Void-app dev docs, salvaged in Task 6, not deleted): Active Projects Status, Agent Roster & Personas, Cron Tasks & Schedules, Deployment Guide, Path B — Build Log, Security Posture & Known Issues, The Void — Architecture & Agent System, The Void — Dashboard Progress (2026-05-14), Homelab Topology, Dashboard rebuild & Orthos overhaul (2026-05-16, also in wiki — moves to The Void, removed from wiki).
|
||
|
||
---
|
||
|
||
## Helper: SQL shell used throughout
|
||
|
||
All SQL steps assume this is exported in the working shell:
|
||
|
||
```bash
|
||
export PGPASSWORD=eIvGMUmYxlVdWnkSZmRQ0EJ8v81
|
||
Q() { psql -h 192.168.1.215 -U void -d void -X "$@"; } # interactive
|
||
QT(){ psql -h 192.168.1.215 -U void -d void -X -A -t "$@"; } # scalar
|
||
```
|
||
|
||
Resolve space UUIDs once and reuse (slugs are stable):
|
||
|
||
```sql
|
||
-- run: Q -c "SELECT slug,id FROM spaces ORDER BY slug;"
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 0 — Safety net
|
||
|
||
### Task 0: Snapshot + logical backup
|
||
|
||
**Files:** none (infra)
|
||
|
||
- [ ] **Step 1: Snapshot both Void CTs on host Z** (standing rule: backup before major changes)
|
||
|
||
Run (on Z, `.124`):
|
||
```bash
|
||
ts=$(date +%Y%m%d_%H%M)
|
||
pct snapshot 310 predocs_${ts}
|
||
pct snapshot 311 predocs_${ts}
|
||
```
|
||
Expected: two snapshots created, no error.
|
||
|
||
- [ ] **Step 2: Logical dump of the prod DB to this box**
|
||
|
||
Run:
|
||
```bash
|
||
export PGPASSWORD=eIvGMUmYxlVdWnkSZmRQ0EJ8v81
|
||
pg_dump -h 192.168.1.215 -U void -d void -Fc -f /project/backups/void-predocs-$(date +%Y%m%d_%H%M).dump
|
||
ls -lh /project/backups/void-predocs-*.dump
|
||
```
|
||
Expected: a >0-byte custom-format dump. (`mkdir -p /project/backups` first if missing.)
|
||
|
||
- [ ] **Step 3: Record current counts as the rollback baseline**
|
||
|
||
Run:
|
||
```bash
|
||
Q -c "SELECT s.slug, (SELECT count(*) FROM pages p WHERE p.space_id=s.id) pages,
|
||
(SELECT count(*) FROM projects pr WHERE pr.space_id=s.id) projects
|
||
FROM spaces s ORDER BY s.slug;"
|
||
```
|
||
Expected: matches the inventory in this plan's header (void 1/3, void1 25/17, wiki 24/0, plans 6/0, void3 8/0, bookmarks 0/0, external-research 0/0). If it does **not** match, STOP — the data drifted; re-audit before proceeding.
|
||
|
||
---
|
||
|
||
## Phase 1 — Page ordering foundation (code)
|
||
|
||
This is the only code change. It gives every space a stable, intentional order instead of alphabetical-by-title, which is the root cause of "Overview is buried."
|
||
|
||
### Task 1: Add `position` column + order by it
|
||
|
||
**Files:**
|
||
- Create: `lib/db/migrations/020_page_position.sql`
|
||
- Modify: `lib/db/repos/pages.js:46-52` (`listBySpace`)
|
||
- Modify: `lib/api/routes/pages.js` (allow `position` in the update schema)
|
||
- Test: `tests/repos/pages_position.test.js`
|
||
|
||
- [ ] **Step 1: Write the migration**
|
||
|
||
`lib/db/migrations/020_page_position.sql`:
|
||
```sql
|
||
-- 020: explicit page ordering within a space (and within a parent).
|
||
ALTER TABLE pages ADD COLUMN IF NOT EXISTS position integer NOT NULL DEFAULT 0;
|
||
CREATE INDEX IF NOT EXISTS idx_pages_space_position ON pages (space_id, position, title);
|
||
```
|
||
|
||
- [ ] **Step 2: Write the failing test**
|
||
|
||
`tests/repos/pages_position.test.js`:
|
||
```js
|
||
import { describe, it, expect, beforeAll } from 'vitest';
|
||
import { create, listBySpace, update } from '../../lib/db/repos/pages.js';
|
||
import { create as createSpace } from '../../lib/db/repos/spaces.js';
|
||
|
||
describe('page ordering', () => {
|
||
let sid;
|
||
beforeAll(async () => { sid = (await createSpace({ slug: 'ord-'+Date.now(), name: 'Ord' }, 'test')).id; });
|
||
it('orders by position then title', async () => {
|
||
const a = await create({ space_id: sid, slug: 'a', title: 'Zzz', body_md: '' }, 'test');
|
||
const b = await create({ space_id: sid, slug: 'b', title: 'Aaa', body_md: '' }, 'test');
|
||
await update(a.id, { position: 1 }, 'test');
|
||
await update(b.id, { position: 9 }, 'test');
|
||
const list = await listBySpace(sid);
|
||
expect(list.map(p => p.title)).toEqual(['Zzz', 'Aaa']); // position 1 before 9 despite title
|
||
});
|
||
});
|
||
```
|
||
|
||
- [ ] **Step 3: Run it, verify it fails**
|
||
|
||
Run: `cd /project/src/void-v2 && npx vitest run tests/repos/pages_position.test.js`
|
||
Expected: FAIL (`update` rejects `position`, or order is alphabetical).
|
||
|
||
- [ ] **Step 4: Update `listBySpace` ordering**
|
||
|
||
In `lib/db/repos/pages.js`, change the `listBySpace` query (currently `ORDER BY title`) to:
|
||
```js
|
||
export async function listBySpace(space_id) {
|
||
const { rows } = await pool.query(
|
||
`SELECT id, space_id, slug, title, parent_id, position, updated_at
|
||
FROM pages WHERE space_id=$1 ORDER BY position, title`, [space_id]
|
||
);
|
||
return rows;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Allow `position` through update**
|
||
|
||
In `lib/db/repos/pages.js` `update()`, add `'position'` to the updatable `fields` array (currently `['slug','title','body_md','body_html','parent_id','embedding']`):
|
||
```js
|
||
const fields = ['slug','title','body_md','body_html','parent_id','embedding','position'];
|
||
```
|
||
In `lib/api/routes/pages.js`, add to the page update zod schema (next to `body_html`):
|
||
```js
|
||
position: z.number().int().optional(),
|
||
```
|
||
|
||
- [ ] **Step 6: Run tests, verify pass**
|
||
|
||
Run: `npx vitest run tests/repos/pages_position.test.js`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 7: Full suite green**
|
||
|
||
Run: `npx vitest run`
|
||
Expected: all pass (no regressions from the ordering change).
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add lib/db/migrations/020_page_position.sql lib/db/repos/pages.js lib/api/routes/pages.js tests/repos/pages_position.test.js
|
||
git commit -m "feat(pages): explicit position ordering within a space"
|
||
```
|
||
|
||
### Task 2: Sectioned page rendering in the space view
|
||
|
||
**Files:**
|
||
- Modify: `public/views/space.js:14-18,49-52,77-85`
|
||
|
||
Currently `space.js` renders pages as a single flat table. Change it to render a **page tree**: top-level pages (no parent, or the space's root page) as section headers, their children indented beneath. Backward-compatible — flat spaces (all pages parent-null) render as before, just ordered.
|
||
|
||
- [ ] **Step 1: Add a tree renderer** (replace `tableRow` helper, lines 14-18)
|
||
|
||
```js
|
||
function pageLink(p) {
|
||
return el('a', { href: '#/page/' + p.id }, p.title || '(untitled)');
|
||
}
|
||
|
||
// Build parent→children map and render top-level pages as section blocks.
|
||
function renderPageTree(pages, refs) {
|
||
const byParent = new Map();
|
||
for (const p of pages) {
|
||
const k = p.parent_id || '__root__';
|
||
if (!byParent.has(k)) byParent.set(k, []);
|
||
byParent.get(k).push(p);
|
||
}
|
||
const roots = byParent.get('__root__') || [];
|
||
const blocks = [];
|
||
for (const r of roots) {
|
||
const kids = byParent.get(r.id) || [];
|
||
blocks.push(el('div', { class: 'doc-section' },
|
||
el('h4', { style: { margin: '12px 0 4px' } }, pageLink(r)),
|
||
kids.length
|
||
? el('ul', { class: 'plain', style: { margin: '0 0 0 14px' } },
|
||
kids.map(k => {
|
||
const gk = byParent.get(k.id) || [];
|
||
return el('li', {}, pageLink(k),
|
||
gk.length ? el('ul', { class: 'plain', style: { margin: '0 0 0 14px' } },
|
||
gk.map(g => el('li', {}, pageLink(g)))) : null);
|
||
}))
|
||
: null));
|
||
}
|
||
if (refs.length) blocks.push(el('div', { class: 'doc-section' },
|
||
el('h4', { style: { margin: '12px 0 4px' } }, 'References'),
|
||
el('ul', { class: 'plain', style: { margin: '0 0 0 14px' } },
|
||
refs.map(rf => el('li', {}, el('a', { href: '#/ref/' + rf.id }, rf.title || rf.source_url))))));
|
||
return blocks;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Use it in the Pages card** (replace the `rows` block, lines 49-52 + 77-85)
|
||
|
||
Remove the `const rows = [...]` block. Replace the final "Pages & references" card with:
|
||
```js
|
||
el('div', { class: 'card' },
|
||
el('h3', {}, `Pages & references${(pages.length + refs.length) ? ` (${pages.length + refs.length})` : ''}`),
|
||
(pages.length + refs.length)
|
||
? el('div', {}, renderPageTree(pages, refs))
|
||
: el('p', { class: 'muted' }, 'Nothing here yet.'))
|
||
```
|
||
|
||
- [ ] **Step 3: Smoke locally against prod data (read-only)**
|
||
|
||
Run the app pointed at prod read-only, or eyeball after deploy. Minimum: `node -e "require('./public/views/space.js')"` won't run (browser ESM) — instead verify via deploy in Task 3.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add public/views/space.js
|
||
git commit -m "feat(space-view): render pages as ordered sectioned tree"
|
||
```
|
||
|
||
### Task 3: Deploy the code change
|
||
|
||
**Files:** none (deploy)
|
||
|
||
- [ ] **Step 1: Bump version** in `package.json` + `server.js` VERSION const + add a CHANGELOG entry (alpha-20).
|
||
|
||
- [ ] **Step 2: Deploy + migrate**
|
||
|
||
Run:
|
||
```bash
|
||
cd /project/src/void-v2
|
||
./deploy/push.sh # rsync + npm i --omit=dev + restart (TARGET defaults root@192.168.1.216)
|
||
ssh root@192.168.1.216 'cd /opt/void-server && npm run migrate' # applies 020
|
||
ssh root@192.168.1.216 'systemctl restart void-server'
|
||
```
|
||
|
||
- [ ] **Step 3: Verify**
|
||
|
||
Run:
|
||
```bash
|
||
curl -s http://192.168.1.216:3000/health
|
||
Q -c "\d pages" | grep position
|
||
Q -c "SELECT name FROM schema_migrations WHERE name='020_page_position.sql';"
|
||
```
|
||
Expected: health = `2.0.0-alpha.20`; `position` column present; migration row present. Open `void.hynesy.com` → a space → confirm pages render as a tree (still alphabetical until positions are set in Phase 2).
|
||
|
||
---
|
||
|
||
## Phase 2 — Wiki → traditional documentation area
|
||
|
||
Make `wiki` the ordered, sectioned source of truth, and remove Void-app dev docs that don't belong in a homelab wiki (they move to The Void in Phase 4/6).
|
||
|
||
### Task 4: Section the Wiki + set order
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Move Void-app dev docs OUT of `wiki` into `void` (The Void)**
|
||
|
||
These 6 "Void 2.0 — *" pages + "Dashboard rebuild & Orthos overhaul" are project history, not homelab infra:
|
||
```sql
|
||
WITH w AS (SELECT id FROM spaces WHERE slug='wiki'),
|
||
v AS (SELECT id FROM spaces WHERE slug='void')
|
||
UPDATE pages SET space_id=(SELECT id FROM v), parent_id=NULL
|
||
WHERE space_id=(SELECT id FROM w)
|
||
AND title IN (
|
||
'Void 2.0 — Deployment (CT 310 + 311)',
|
||
'Void 2.0 — Plan 1 Foundation (complete)',
|
||
'Void 2.0 — Plan 2 API + UI (complete)',
|
||
'Void 2.0 — Plan 3 Capture (complete)',
|
||
'Void 2.0 — Plan 4 Workers (complete)',
|
||
'Dashboard rebuild & Orthos overhaul (2026-05-16)'
|
||
);
|
||
```
|
||
(These are re-parented under The Void's "Void 2.0 — Build Log" in Task 7.)
|
||
|
||
- [ ] **Step 2: Create three section parent-pages under the wiki root**
|
||
|
||
```sql
|
||
WITH w AS (SELECT id FROM spaces WHERE slug='wiki'),
|
||
root AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM w) AND slug='hynesy-homelab')
|
||
INSERT INTO pages (space_id, slug, title, body_md, parent_id, position)
|
||
SELECT (SELECT id FROM w), x.slug, x.title,
|
||
'_Section index. Pages in this section are listed below._', (SELECT id FROM root), x.pos
|
||
FROM (VALUES
|
||
('sec-start-here','Start Here',0),
|
||
('sec-hosts-services','Hosts & Services',1),
|
||
('sec-operations','Operations & Infrastructure',2)
|
||
) AS x(slug,title,pos)
|
||
ON CONFLICT (space_id, slug) DO NOTHING;
|
||
```
|
||
|
||
- [ ] **Step 3: Re-parent each content page under the right section + set positions**
|
||
|
||
```sql
|
||
-- helper CTE pattern: set parent + position by title
|
||
WITH w AS (SELECT id sid FROM spaces WHERE slug='wiki'),
|
||
sec AS (SELECT slug, id FROM pages WHERE space_id=(SELECT sid FROM w) AND slug LIKE 'sec-%')
|
||
UPDATE pages p SET
|
||
parent_id = (SELECT id FROM sec WHERE sec.slug = m.section),
|
||
position = m.pos
|
||
FROM (VALUES
|
||
-- Start Here
|
||
('Overview', 'sec-start-here', 0),
|
||
('Network map', 'sec-start-here', 1),
|
||
('Master Index', 'sec-start-here', 2),
|
||
-- Hosts & Services
|
||
('Mediastack LXC (100)', 'sec-hosts-services', 0),
|
||
('Ollama LXC (102)', 'sec-hosts-services', 1),
|
||
('Open WebUI LXC (103)', 'sec-hosts-services', 2),
|
||
('BookStack LXC (104)', 'sec-hosts-services', 3),
|
||
('iVentoy PXE LXC (107)', 'sec-hosts-services', 4),
|
||
('Gramps LXC (109)', 'sec-hosts-services', 5),
|
||
('OpenClaw VM (200)', 'sec-hosts-services', 6),
|
||
('Jellyfin plugins', 'sec-hosts-services', 7),
|
||
('USB auto-sync drive', 'sec-hosts-services', 8),
|
||
('Claude Code LXC deployer (agentic.sh)', 'sec-hosts-services', 9),
|
||
-- Operations & Infrastructure
|
||
('Cluster and HA', 'sec-operations', 0),
|
||
('Operations notes', 'sec-operations', 1),
|
||
('AI Usage', 'sec-operations', 2),
|
||
('Next steps & follow-ups', 'sec-operations', 3)
|
||
) AS m(title, section, pos)
|
||
WHERE p.space_id=(SELECT sid FROM w) AND p.title = m.title;
|
||
```
|
||
|
||
- [ ] **Step 4: Set section order on the root's children** (sections already have positions 0/1/2 from Step 2; verify root page sorts first)
|
||
|
||
```sql
|
||
WITH w AS (SELECT id FROM spaces WHERE slug='wiki')
|
||
UPDATE pages SET position=-1 WHERE space_id=(SELECT id FROM w) AND slug='hynesy-homelab';
|
||
```
|
||
|
||
- [ ] **Step 5: Verify the tree**
|
||
|
||
```sql
|
||
WITH w AS (SELECT id FROM spaces WHERE slug='wiki')
|
||
SELECT COALESCE(par.title,'(root)') AS parent, p.position, p.title
|
||
FROM pages p LEFT JOIN pages par ON par.id=p.parent_id
|
||
WHERE p.space_id=(SELECT id FROM w)
|
||
ORDER BY COALESCE(par.position,-2), par.title NULLS FIRST, p.position, p.title;
|
||
```
|
||
Expected: root → Start Here(Overview, Network map, Master Index) → Hosts & Services(...) → Operations(...). Open `void.hynesy.com` → Wiki space → confirm **Overview is at the top**, grouped under sections. This resolves the user's "out of order" complaint.
|
||
|
||
---
|
||
|
||
## Phase 3 — Dedup void1 ↔ wiki
|
||
|
||
Per the verdict table. Merges (content edits) go through the **web page editor** (regenerates html/embedding); structural drops via SQL.
|
||
|
||
### Task 5: Salvage divergent facts, then drop void1 duplicates
|
||
|
||
**Files:** none (web editor + SQL on prod)
|
||
|
||
- [ ] **Step 1: Merge the DIVERGE page — Ollama LXC (102)**
|
||
|
||
Open the **wiki** "Ollama LXC (102)" page in the Void editor. Reconcile against the void1 copy using these authoritative facts (void1's are newer; cross-checked vs memory `reference-ollama-ct102`):
|
||
- Binary path: **`/usr/share/ollama`** for models; service user **`ollama`** (not root); installed via the community-script then upgraded. (Resolve the `/usr/bin` vs `/usr/local/bin` conflict by verifying live: `pct exec 102 -- which ollama` — use the real path; do not leave both.)
|
||
- Keep wiki-only content: the **PATH gotcha**, the **keep-alive / multi-model tuning after the 62 GiB RAM upgrade**, and the **driver 595.58.03** detail.
|
||
- Keep void1-only content: the **"CRITICAL: preserving config across upgrades"** section (systemd drop-in for `0.0.0.0:11434` binding) — this is the most important salvage; verify it's present in the merged page.
|
||
- Add a one-line lineage note at top: `> Consolidated from the Void 1 and BookStack copies, 2026-06-05.`
|
||
Save. Confirm the page renders and a search for "preserving config" returns it.
|
||
|
||
- [ ] **Step 2: Merge the wiki-superset pages** (Operations notes, Overview, Network map, Gramps LXC (109))
|
||
|
||
For each, diff the void1 copy and append any **void1-only** lines that carry real facts into the wiki copy via the editor. Use this to see exactly what's void1-only:
|
||
```bash
|
||
diff <(QT -c "SELECT body_md FROM pages p JOIN spaces s ON s.id=p.space_id WHERE s.slug='void1' AND p.title='<VOID1 TITLE>'") \
|
||
<(QT -c "SELECT body_md FROM pages p JOIN spaces s ON s.id=p.space_id WHERE s.slug='wiki' AND p.title='<WIKI TITLE>'")
|
||
```
|
||
Title pairs: Operations notes↔Operations notes; Overview↔Overview; Network map↔Network map; "Gramps Web — CT 109 (2026-05-25)"↔"Gramps LXC (109)". Lines prefixed `<` are void1-only — judge each; most will be stale and can be skipped. Save each edited wiki page.
|
||
|
||
- [ ] **Step 3: Fold Homelab Topology into wiki Network map**
|
||
|
||
void1 "Homelab Topology" has no wiki twin but overlaps "Network map". Diff it against wiki Network map; salvage any unique device/IP rows into Network map, then it's covered by the void1 drop in Step 5.
|
||
|
||
- [ ] **Step 4: Verify nothing unique is about to be lost**
|
||
|
||
```sql
|
||
-- void1 pages that will be dropped, with their wiki survivor lengths for a final sanity glance
|
||
WITH v AS (SELECT id FROM spaces WHERE slug='void1'),
|
||
w AS (SELECT id FROM spaces WHERE slug='wiki')
|
||
SELECT p.title, length(p.body_md) v1len,
|
||
(SELECT length(body_md) FROM pages wp WHERE wp.space_id=(SELECT id FROM w)
|
||
AND wp.title = CASE p.title
|
||
WHEN 'Mediastack Lxc' THEN 'Mediastack LXC (100)'
|
||
WHEN 'Iventoy Pxe Lxc' THEN 'iVentoy PXE LXC (107)'
|
||
WHEN 'Usb Autosync' THEN 'USB auto-sync drive'
|
||
WHEN 'Gramps Web — CT 109 (2026-05-25)' THEN 'Gramps LXC (109)'
|
||
ELSE p.title END) wikilen
|
||
FROM pages p WHERE p.space_id=(SELECT id FROM v) ORDER BY p.title;
|
||
```
|
||
Expected: every row that is being dropped has a non-null `wikilen` (a survivor exists). Investigate any NULL before deleting.
|
||
|
||
- [ ] **Step 5: Delete the void1 duplicate + intra-dup pages**
|
||
|
||
```sql
|
||
WITH v AS (SELECT id FROM spaces WHERE slug='void1')
|
||
DELETE FROM pages WHERE space_id=(SELECT id FROM v) AND title IN (
|
||
'Next steps & follow-ups','Open WebUI LXC (103)','OpenClaw VM (200)',
|
||
'BookStack LXC (104)','Claude Code LXC deployer (agentic.sh)','Claude LXC deployer',
|
||
'Iventoy Pxe Lxc','Mediastack Lxc','Usb Autosync',
|
||
'Operations notes','Overview','Network map','Master Index',
|
||
'Gramps Web — CT 109 (2026-05-25)','Ollama LXC (102)','Homelab Topology'
|
||
);
|
||
```
|
||
Expected: `DELETE 16`. (Leaves only the 9 Void-app-specific pages in void1, salvaged next.)
|
||
|
||
---
|
||
|
||
## Phase 4 — Collapse void1 → The Void
|
||
|
||
### Task 6: Salvage void1's unique dev docs into The Void
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Create a "Void 1.x — Final State / Retrospective" page** (the record of where Void 1 ended)
|
||
|
||
```sql
|
||
WITH v AS (SELECT id sid FROM spaces WHERE slug='void')
|
||
INSERT INTO pages (space_id, slug, title, body_md, position)
|
||
VALUES ((SELECT sid FROM v), 'void1-retrospective', 'Void 1.x — Final State / Retrospective',
|
||
$md$# Void 1.x — Final State / Retrospective
|
||
|
||
**Status at retirement (2026-06-05):** Void 1 ran on **CT 301**, `192.168.1.11:2424`, `void.hynesy.com`.
|
||
At the 8b cutover (2026-06-05, alpha-18) `void.hynesy.com` was repointed to **Void 2** (CT 311, `.216`).
|
||
CT 301 is **legacy-but-running**, kept as instant rollback; scheduled to be vzdump'd then retired after the grace period.
|
||
|
||
## What Void 1 was
|
||
Cradle-themed homelab dashboard (Node + Express + `node:sqlite`, gridstack "Sacred Valley", 8 character agents).
|
||
Architecture, agent system, dashboard progress and the Path B rebuild log are preserved as child pages of this page.
|
||
|
||
## Projects completed / migrated
|
||
- Sacred Valley dashboard, agent roster (Dross/Yerin/Little Blue/Orthos/Eithan/Lindon/Mercy), cron briefings.
|
||
- All knowledge migrated into Void 2 spaces (Wiki + The Void) on 2026-06-04–05.
|
||
|
||
## Lineage
|
||
Services first documented/managed under Void 1 now live in the **Wiki** (source of truth) and, where they evolved,
|
||
the improved state is noted there — e.g. **Mediastack (CT 100)** began under Void-1 docs and is now Z→Z3 replicated and
|
||
documented under Wiki › Hosts & Services with a Void-2 lineage note. See linked references.
|
||
$md$, 1)
|
||
ON CONFLICT (space_id, slug) DO NOTHING;
|
||
```
|
||
|
||
- [ ] **Step 2: Move the remaining void1 pages into The Void, nested under the retrospective**
|
||
|
||
```sql
|
||
WITH v1 AS (SELECT id FROM spaces WHERE slug='void1'),
|
||
vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
retro AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM vd) AND slug='void1-retrospective')
|
||
UPDATE pages SET space_id=(SELECT id FROM vd), parent_id=(SELECT id FROM retro)
|
||
WHERE space_id=(SELECT id FROM v1) AND title IN (
|
||
'The Void — Architecture & Agent System',
|
||
'The Void — Dashboard Progress (2026-05-14)',
|
||
'Path B — Build Log',
|
||
'Deployment Guide',
|
||
'Cron Tasks & Schedules',
|
||
'Security Posture & Known Issues',
|
||
'Active Projects Status',
|
||
'Agent Roster & Personas'
|
||
);
|
||
```
|
||
Expected: `UPDATE 8`. (Agent Roster stays a live reference under The Void; the rest are historical children of the retrospective.)
|
||
|
||
### Task 7: Migrate void1 projects + reparent the moved build-log pages
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Move real homelab projects into The Void with corrected status**
|
||
|
||
```sql
|
||
WITH v1 AS (SELECT id FROM spaces WHERE slug='void1'),
|
||
vd AS (SELECT id FROM spaces WHERE slug='void')
|
||
UPDATE projects p SET space_id=(SELECT id FROM vd), status=m.st
|
||
FROM (VALUES
|
||
('Homelab','active'),
|
||
('Homelab Atlas','active'),
|
||
('Knowledge Pipeline','active'),
|
||
('Network Rebuild','paused'),
|
||
('Sacred Valley Widgets — Phase 4 Follow-up','done'),
|
||
('USB Auto-Sync Drive','idea'),
|
||
('VM 203 Docker Stack Rebuild','active'),
|
||
('Win10 → Mediastack Migration','idea'),
|
||
('Z2 → Cluster Migration','active'),
|
||
('iVentoy PXE Server','paused')
|
||
) AS m(name, st)
|
||
WHERE p.space_id=(SELECT id FROM v1) AND p.name=m.name;
|
||
```
|
||
Expected: `UPDATE 10`.
|
||
|
||
- [ ] **Step 2: Salvage agent persona one-liners into the Agent Roster page, then delete the 7 agent "projects"**
|
||
|
||
The 7 agent-named projects (Dross, Eithan, Lindon, Little Blue, Mercy, Orthos, Yerin) are personas, not projects. Their descriptions are 1-liners. Append any not already on "Agent Roster & Personas" (now in The Void), then:
|
||
```sql
|
||
WITH v1 AS (SELECT id FROM spaces WHERE slug='void1')
|
||
DELETE FROM projects WHERE space_id=(SELECT id FROM v1)
|
||
AND name IN ('Dross','Eithan','Lindon','Little Blue','Mercy','Orthos','Yerin');
|
||
```
|
||
Expected: `DELETE 7`. (Live agents already exist in the `agents` table; these project stubs are redundant.)
|
||
|
||
- [ ] **Step 3: Reparent the 6 Void-2 dev docs moved in Task 4/Step 1 under the Build Log**
|
||
|
||
```sql
|
||
WITH vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
bl AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM vd) AND title='Void 2.0 — Build Log')
|
||
UPDATE pages SET parent_id=(SELECT id FROM bl)
|
||
WHERE space_id=(SELECT id FROM vd) AND title IN (
|
||
'Void 2.0 — Deployment (CT 310 + 311)',
|
||
'Void 2.0 — Plan 1 Foundation (complete)',
|
||
'Void 2.0 — Plan 2 API + UI (complete)',
|
||
'Void 2.0 — Plan 3 Capture (complete)',
|
||
'Void 2.0 — Plan 4 Workers (complete)',
|
||
'Dashboard rebuild & Orthos overhaul (2026-05-16)'
|
||
);
|
||
```
|
||
Expected: `UPDATE 6`.
|
||
|
||
### Task 8: Handle void1 conversations, then delete the void1 space
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Drop the 30 conversations** (historical Dross/companion chat logs — user confirmed 2026-06-05: drop)
|
||
|
||
```sql
|
||
WITH v1 AS (SELECT id FROM spaces WHERE slug='void1')
|
||
DELETE FROM conversations WHERE space_id=(SELECT id FROM v1);
|
||
-- (messages cascade via FK)
|
||
```
|
||
|
||
- [ ] **Step 2: Confirm void1 is empty of survivors**
|
||
|
||
```sql
|
||
WITH v1 AS (SELECT id FROM spaces WHERE slug='void1')
|
||
SELECT
|
||
(SELECT count(*) FROM pages WHERE space_id=(SELECT id FROM v1)) pages,
|
||
(SELECT count(*) FROM projects WHERE space_id=(SELECT id FROM v1)) projects,
|
||
(SELECT count(*) FROM conversations WHERE space_id=(SELECT id FROM v1)) convos,
|
||
(SELECT count(*) FROM refs WHERE space_id=(SELECT id FROM v1)) refs;
|
||
```
|
||
Expected: all `0`. If not, STOP and reconcile.
|
||
|
||
- [ ] **Step 3: Delete the void1 space**
|
||
|
||
```sql
|
||
DELETE FROM spaces WHERE slug='void1';
|
||
```
|
||
Expected: `DELETE 1` (cascades any stragglers).
|
||
|
||
### Task 9: Rebuild a single Master Index
|
||
|
||
**Files:** none (web editor on prod)
|
||
|
||
- [ ] **Step 1:** The wiki "Master Index" survived (wiki copy was fuller). Open it in the editor and update links so they point at the new sectioned Wiki structure + The Void hub; remove dead links to deleted void1 pages. Save.
|
||
|
||
---
|
||
|
||
## Phase 5 — Fold void3 into the Void 3.0 project
|
||
|
||
### Task 10: Move void3 pages into The Void under a Void 3.0 hub page, link to the project
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Create a Void 3.0 hub page in The Void**
|
||
|
||
```sql
|
||
WITH vd AS (SELECT id sid FROM spaces WHERE slug='void')
|
||
INSERT INTO pages (space_id, slug, title, body_md, position)
|
||
VALUES ((SELECT sid FROM vd),'void3-hub','Void 3.0 — Roadmap & Audit (2026-06-02)',
|
||
'_Point-in-time homelab evolution audit + roadmap, migrated from the former void3 space. Child pages are the original audit notes._', 2)
|
||
ON CONFLICT (space_id, slug) DO NOTHING;
|
||
```
|
||
|
||
- [ ] **Step 2: Move all 8 void3 pages under the hub**
|
||
|
||
```sql
|
||
WITH v3 AS (SELECT id FROM spaces WHERE slug='void3'),
|
||
vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
hub AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM vd) AND slug='void3-hub')
|
||
UPDATE pages SET space_id=(SELECT id FROM vd), parent_id=(SELECT id FROM hub)
|
||
WHERE space_id=(SELECT id FROM v3);
|
||
```
|
||
Expected: `UPDATE 8`.
|
||
|
||
- [ ] **Step 3: Link the hub page to the "Void 3.0" project**
|
||
|
||
```sql
|
||
WITH vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
pr AS (SELECT id FROM projects WHERE space_id=(SELECT id FROM vd) AND name='Void 3.0'),
|
||
hub AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM vd) AND slug='void3-hub')
|
||
INSERT INTO entity_links (from_type, from_id, to_type, to_id, relation)
|
||
VALUES ('project',(SELECT id FROM pr),'page',(SELECT id FROM hub),'reference');
|
||
```
|
||
|
||
- [ ] **Step 4: Move the void3 conversation (if any) then delete the space**
|
||
|
||
```sql
|
||
WITH v3 AS (SELECT id FROM spaces WHERE slug='void3')
|
||
DELETE FROM conversations WHERE space_id=(SELECT id FROM v3); -- user confirmed: drop
|
||
DELETE FROM spaces WHERE slug='void3';
|
||
```
|
||
Expected: `DELETE 1`.
|
||
|
||
---
|
||
|
||
## Phase 6 — Relocate `plans`, decide `external-research`
|
||
|
||
**User decision (2026-06-05): KEEP the plan pages** — give them a home in The Void (not the Wiki, since they are project artifacts not infra reference). Move them under an "Implementation Plans" hub page in `void` and link each to its related project.
|
||
|
||
### Task 11: Move plan pages into The Void under an "Implementation Plans" hub, then delete the empty plans space
|
||
|
||
**Files:** none (SQL on prod)
|
||
|
||
- [ ] **Step 1: Create the hub page in The Void**
|
||
|
||
```sql
|
||
WITH vd AS (SELECT id sid FROM spaces WHERE slug='void')
|
||
INSERT INTO pages (space_id, slug, title, body_md, position)
|
||
VALUES ((SELECT sid FROM vd),'implementation-plans','Implementation Plans',
|
||
'_Implementation plans for homelab + Void projects, migrated from the former plans space. Canonical copies also live in the repo `docs/superpowers/plans/` and `~/.claude/plans/`. Child pages below; each is linked to its related project._', 3)
|
||
ON CONFLICT (space_id, slug) DO NOTHING;
|
||
```
|
||
|
||
- [ ] **Step 2: Move all 6 plan pages under the hub**
|
||
|
||
```sql
|
||
WITH p AS (SELECT id FROM spaces WHERE slug='plans'),
|
||
vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
hub AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM vd) AND slug='implementation-plans')
|
||
UPDATE pages SET space_id=(SELECT id FROM vd), parent_id=(SELECT id FROM hub)
|
||
WHERE space_id=(SELECT id FROM p);
|
||
```
|
||
Expected: `UPDATE 6`.
|
||
|
||
- [ ] **Step 3: Link each plan page to its related project** (where one exists in The Void)
|
||
|
||
```sql
|
||
WITH vd AS (SELECT id sid FROM spaces WHERE slug='void')
|
||
INSERT INTO entity_links (from_type, from_id, to_type, to_id, relation)
|
||
SELECT 'project', pr.id, 'page', pg.id, 'reference'
|
||
FROM (VALUES
|
||
('Plan: Homelab USB Auto-Sync Drive', 'USB Auto-Sync Drive'),
|
||
('Plan: The Void — Path B Rebuild (Mastra Agent Framework)', 'Void 1.x'),
|
||
('Plan: Homepage-style Service Cards in Sacred Valley','Void 2.0'),
|
||
('Plan: Replace BookStack with Mercy''s Records (Option B)', 'Void 3.0')
|
||
) AS m(page_title, project_name)
|
||
JOIN pages pg ON pg.space_id=(SELECT sid FROM vd) AND pg.title=m.page_title
|
||
JOIN projects pr ON pr.space_id=(SELECT sid FROM vd) AND pr.name=m.project_name;
|
||
```
|
||
(The two Farm plans — "Farm (won) Failure-Recovery Plan", "Farm Timelapse System — Implementation Plan" — have no matching project in The Void; they remain under the hub, unlinked. Optionally create Farm projects later.)
|
||
|
||
- [ ] **Step 4: Confirm plans space is empty, then delete it**
|
||
|
||
```sql
|
||
SELECT count(*) FROM pages WHERE space_id=(SELECT id FROM spaces WHERE slug='plans'); -- expect 0
|
||
WITH p AS (SELECT id FROM spaces WHERE slug='plans')
|
||
DELETE FROM conversations WHERE space_id=(SELECT id FROM p); -- drop the placeholder convo
|
||
DELETE FROM spaces WHERE slug='plans';
|
||
```
|
||
Expected: count `0`, then `DELETE 1`.
|
||
|
||
### Task 12: Decide `external-research`
|
||
|
||
**Files:** none
|
||
|
||
- [ ] **Step 1:** `external-research` is empty but is the bound Space for the MCP external-research agent (`reference-void-mcp-endpoint`). Check it's still in use:
|
||
```sql
|
||
SELECT a.slug, a.scopes FROM agents a WHERE a.scopes->>'space_id' = (SELECT id::text FROM spaces WHERE slug='external-research');
|
||
```
|
||
- [ ] **Step 2:** If an agent is bound → **keep** the space (add a one-line description page explaining its purpose). If no agent → `DELETE FROM spaces WHERE slug='external-research';`.
|
||
|
||
---
|
||
|
||
## Phase 7 — Lineage cross-links
|
||
|
||
### Task 13: Express doc lineage between The Void projects and Wiki service docs
|
||
|
||
**Files:** none (SQL + web editor on prod)
|
||
|
||
- [ ] **Step 1: Mediastack lineage (the user's example)** — add an evolution note + link
|
||
|
||
In the editor, append to Wiki "Mediastack LXC (100)":
|
||
```
|
||
> **Lineage:** First documented under Void 1. Now CT 100 on Z, Donatello/Leonardo pools, syncoid daily replica Z→Z3, and the Void-2 ingress host. See The Void › Void 2.0.
|
||
```
|
||
Then link the Void 2.0 project → the Mediastack page:
|
||
```sql
|
||
WITH vd AS (SELECT id FROM spaces WHERE slug='void'),
|
||
pr AS (SELECT id FROM projects WHERE space_id=(SELECT id FROM vd) AND name='Void 2.0'),
|
||
w AS (SELECT id FROM spaces WHERE slug='wiki'),
|
||
pg AS (SELECT id FROM pages WHERE space_id=(SELECT id FROM w) AND title='Mediastack LXC (100)')
|
||
INSERT INTO entity_links (from_type, from_id, to_type, to_id, relation)
|
||
VALUES ('project',(SELECT id FROM pr),'page',(SELECT id FROM pg),'reference');
|
||
```
|
||
|
||
- [ ] **Step 2: Repeat for the other materially-evolved services** — Ollama (GPU userspace driver + sharing), Cluster and HA (qdevice, replication). Same pattern: add a one-line lineage note in the Wiki page + an `entity_links` row from the relevant Void project.
|
||
|
||
---
|
||
|
||
## Phase 8 — Verify, re-embed, finalize
|
||
|
||
### Task 14: Final verification
|
||
|
||
**Files:** none
|
||
|
||
- [ ] **Step 1: Space inventory is the target shape**
|
||
|
||
```sql
|
||
SELECT s.slug, (SELECT count(*) FROM pages p WHERE p.space_id=s.id) pages,
|
||
(SELECT count(*) FROM projects pr WHERE pr.space_id=s.id) projects
|
||
FROM spaces s ORDER BY s.slug;
|
||
```
|
||
Expected: `bookmarks`, `void` (≈12 pages incl. retrospective+build-log children+void3 hub; ~13 projects), `wiki` (≈21 pages: root + 3 sections + 17 content), and `external-research` only if kept. No `void1`/`void3`/`plans`.
|
||
|
||
- [ ] **Step 2: No orphaned page references** (links pointing at deleted pages)
|
||
|
||
```sql
|
||
SELECT count(*) FROM entity_links el
|
||
WHERE el.to_type='page' AND NOT EXISTS (SELECT 1 FROM pages p WHERE p.id=el.to_id);
|
||
```
|
||
Expected: `0`. Delete any orphans found.
|
||
|
||
- [ ] **Step 3: Re-embed edited/moved pages so hybrid search stays accurate**
|
||
|
||
Content edits made via the web editor already re-embed. For pages changed only by SQL (parent/position/space moves) embeddings are still valid (body unchanged). If any body was edited via SQL, run the app's embed backfill:
|
||
```bash
|
||
ssh root@192.168.1.216 'cd /opt/void-server && node lib/db/backfill_embeddings.js 2>/dev/null || echo "no backfill script — re-save the page in the editor"'
|
||
```
|
||
|
||
- [ ] **Step 4: UI walkthrough** — open `void.hynesy.com`:
|
||
- Wiki space: Overview at top, three sections in order, no Void-2 plan docs.
|
||
- The Void space: projects Void 1.x/2.0/3.0 + the 10 homelab projects with corrected statuses; Void 1.x retrospective with its historical children; Void 3.0 hub with the 8 audit pages; Build Log with its dev-doc children.
|
||
- Search "preserving config across upgrades" → returns the merged Ollama page.
|
||
|
||
- [ ] **Step 5: Update the project memory** — note the consolidation done (spaces 7→3, wiki sectioned, void1/void3/plans retired) in `void-v2-roadmap` / `void-v2-execution-in-progress`, since the roadmap's "clean up old void1/void3/plans spaces" item is now complete.
|
||
|
||
### Task 15: BookStack — minimal (per user: secondary mirror only)
|
||
|
||
**Files:** none
|
||
|
||
- [ ] **Step 1:** Leave BookStack content as-is (it's already Overview-first). Do **not** invest in re-chaptering. Optionally add one note to BookStack "Overview": `> Primary docs now live in The Void Wiki (void.hynesy.com). This BookStack is a secondary reference mirror.` Skip if not wanted.
|
||
|
||
---
|
||
|
||
## Self-review notes
|
||
- **Spec coverage:** ordering fix (Tasks 1-3, Phase 2), dedup with lineage-aware merges (Phase 3), collapse void1 + preserve Void 1.x record (Phase 4), void3 fold (Phase 5), plans/external-research (Phase 6), lineage cross-links incl. mediastack example (Phase 7), Wiki-as-source-of-truth + BookStack demoted (Phase 2 + Task 15). All requested scope covered.
|
||
- **Destructive steps** (Tasks 5,7,8,10,11) are each gated by a verification query proving a survivor exists before delete, and the whole run is recoverable from Task 0's snapshot + pg_dump.
|
||
- **Confirm-with-user gates:** conversation deletion (Task 8/10/11), external-research deletion (Task 12), keeping plan pages browsable (Task 11).
|
||
- **Reversibility:** all Phase 1 code is additive (nullable/defaulted column); content moves are reversible from the dump.
|