Quartz 4

Wiki Schema

16 min read

Wiki Schema

The canonical reference for how every page in this wiki is structured. Follow this exactly.

See also: CONDUCT — companion doc covering agent behaviour (when to create/update/archive/delete, cross-agent etiquette, conflict resolution). SCHEMA defines structure; CONDUCT defines conduct. Both required reading at session start.

Domain

pvs’s home lab: AI/ML inference and training, Kubernetes infrastructure, autonomous agents, web applications, security research, and operational knowledge.

File Naming

  • Lowercase, hyphens, no spaces: transformer-architecture.md
  • Projects use directory structure: projects/<slug>/index.md
  • Session logs: projects/<slug>/sessions/YYYY-MM-DD.md
  • Never use underscores, camelCase, or spaces in filenames

Frontmatter (required on every compiled page)

---
title: "Human-readable page title"
type: entity | concept | comparison | query | project | session
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [from taxonomy below]
sources: [raw/articles/source.md, raw/team-knowledge/lesson.md]
status: active | stale | archived     # optional, default: active
---

All fields except status are required. Always bump updated when editing.

Page Types

entity

One page per distinct thing (tool, service, model, person, component).

---
title: "llama.cpp"
type: entity
created: 2026-04-22
updated: 2026-04-22
tags: [inference, tool, open-source]
sources: [raw/articles/llama-cpp.md]
---
 
# llama.cpp
 
## What it is
<1-3 sentence summary>
 
## Key facts
- <fact with date if relevant>
- <fact>
 
## How we use it
<our specific setup, config, quirks>
 
## Related
- `vllm` — alternative inference server (see [[skills/mlops/inference/vllm/SKILL.md]])
- [[concepts/hermes-k8s-deployment]] — where it runs

concept

One page per idea, pattern, or technique.

---
title: "KV cache quantization"
type: concept
created: 2026-04-22
updated: 2026-04-22
tags: [inference, optimization]
sources: []
---
 
# KV cache quantization
 
## What it is
<definition>
 
## How it works
<explanation>
 
## Tradeoffs
<what you gain and lose>
 
## Open questions
<what's unresolved>
 
## Related
- `llama-cpp` — supports q4_0, q8_0 KV cache
- [[skills/mlops/inference/vllm/SKILL.md]] — different approach

comparison

Side-by-side analysis of 2+ things.

---
title: "llama.cpp vs vLLM"
type: comparison
created: 2026-04-22
updated: 2026-04-22
tags: [inference, comparison]
sources: []
---
 
# llama.cpp vs vLLM
 
## Why compare
<context>
 
## Comparison
 
| Dimension | llama.cpp | vLLM |
|---|---|---|
| Speed | ... | ... |
| VRAM | ... | ... |
 
## Verdict
<synthesis>

project

Overview page for a long-running project. Lives at projects/<slug>/index.md.

---
title: "Smart Groceries"
type: project
created: 2026-04-22
updated: 2026-04-22
tags: [web-app, project]
sources: []
status: active
---
 
# Smart Groceries
 
## Goal
<desired end state>
 
## Budget
- **Schedule:** Daily at HH:MM UTC
- **Time per session:** N minutes
 
## Status
<current state — what's done, what's next>
 
## Sessions
- Session example: `YYYY-MM-DD` — initial setup

session

Daily work log for a project. Lives at projects/<slug>/sessions/YYYY-MM-DD.md.

---
title: "Smart Groceries — 2026-04-22"
type: session
created: 2026-04-22
updated: 2026-04-22
tags: [project, session]
sources: []
---
 
# Smart Groceries — Session 2026-04-22
 
## Goal
<what you planned to do>
 
## Progress
- 02:00 — started, read project index
- 02:05 — <what you did>
- 02:30 — <what you did>
 
## Outputs
- git commit abc123: "initial project scaffold"
- created projects/smart-groceries/sessions/2026-04-22.md
 
## Issues / Questions
- QUESTION: should the frontend use React or plain HTML? (for pvs)
- BLOCKED: Woolworths API requires auth — need credentials
 
## Status
partial — scaffold done, API integration next

query

Answer to a specific research question.

---
title: "What quantization is best for 24GB VRAM?"
type: query
created: 2026-04-22
updated: 2026-04-22
tags: [inference, optimization]
sources: [raw/team-knowledge/some-lesson.md]
---
 
# What quantization is best for 24GB VRAM?
 
## Short answer
<1-2 sentences>
 
## Detail
<full analysis>
 
## Sources
<what was consulted>

Tag Taxonomy

Every tag on a page must exist here. Add new tags to this list before using them.

Technical

  • model, architecture, benchmark, training, inference
  • optimization, fine-tuning, alignment, quantization
  • tool, library, framework, api

Infrastructure

  • kubernetes, docker, gitlab, ci-cd, storage, networking, infrastructure
  • monitoring, deployment, security, backup

Domain

  • web-app, agent, wiki, research, data
  • open-source, commercial, paper

Organisation

  • person, company, lab, project, session

Meta

  • comparison, timeline, controversy, prediction
  • migration, lesson, pattern, troubleshooting

Skills (for auto-generated skill entity pages)

  • skill — for pages created from skills/ directory entries
  • technique — for methodology/recipe-style skills
  • notes — for raw reference/source files without structured content

Additional Tool Tags (commonly used by infrastructure and tool entities)

  • cache — for caching mechanisms, tools, and strategies
  • knowledge-base — for wiki/knowledge base systems
  • markdown — for markdown processing/rendering tools
  • web — for web-related tools, frameworks, and technologies

Monitoring & Operations (added 2026-04-25)

  • alertmanager, alerts, grafana, observability, prometheus — monitoring stack
  • ops, operations, runbook — operational procedures

Data & Search (added 2026-04-25)

  • embeddings, vector-db, qdrant, ranking, wiki-search — data pipelines and search

Tool-Specific Tags (added 2026-04-25)

  • browser, camofox, web-capture — browser automation tools
  • email, gmail, slack, mcp, oauth, google-workspace — communication and auth tools
  • calendar, sheets — Google Workspace tools

Domain-Specific Tags (added 2026-04-25)

  • asx, finance, trading, ibkr — finance/trading domain

Organization Tags (added 2026-04-25)

  • contacts, profile, communication, privacy-aware — people and org data

Project Meta Tags (added 2026-04-25)

  • capability, planning, roadmap, inventory, rebuild
  • self-improvement, self-administration, sync, integration, coach, mr

Additional Meta Tags (added 2026-04-25)

  • audit, critical, inbox, docs

Runbook & Operations Tags (added 2026-05-01)

  • runbook — for operational runbook pages
  • tier1, tier2, tier3 — alert severity tiers
  • cluster-ops — cluster operations procedures
  • auto-draft — auto-generated draft content

Infrastructure Specific Tags (added 2026-05-01)

  • k8s — Kubernetes shorthand
  • container, oom — container runtime specifics
  • proxmox — Proxmox virtualization
  • gvisor — gVisor sandboxing
  • concept — generic concept classification

Domain-Specific Service Tags (added 2026-05-01)

Missing Tags (added 2026-05-04)

  • ai — general AI topics
  • agents — agent system pages
  • hermes — Hermes-specific
  • active — status indicator
  • agent-feedback, feedback, review — feedback and review content
  • coaching — coaching/advisor content
  • conduct, governance, rules, meta — governance docs
  • spec — specification documents
  • project-session — project session logs
  • report — report/summary documents
  • tools — general tools reference
  • development — development process
  • cron — cron job related
  • overnight, automated, cluster — ops automation
  • index — index/catalogue pages
  • f5-tts, tts, voice — voice/TTS specific (distinct from general audio)
  • latency — latency/performance metric
  • microk8s — MicroK8s specific
  • video-generation, synthetic-avatar, talking-head — video/avatar generation
  • investment, tax — finance/investment analysis

Additional Common Tags (added 2026-05-31)

  • has-correction, has-instruction, has-tool-error — task quality markers
  • source-cli, source-api_server, source-cron — content source origin
  • legend, legend-os — Legend OS project references
  • task, visual-test, folder-inbox — Mercury task categories
  • ux, portal, goal-reflection, goals — UX and goal tracking
  • journal, telemetry, frontend — logging and system metrics
  • svelte, self-improve, rag-alternative — web frameworks and AI patterns
  • cycle, workspace, visual-audit — process and workspace categories
  • testing, legend-os, qa, smart-groceries, ci — project and quality domains
  • persona, test-result, vt-006, vt-003, vt-007, vt-005, vt-010 — testing IDs
  • multi-agent — multi-agent system patterns

Lint & Automation Tags (added 2026-05-31)

  • automation, autonomous — automation-related content
  • autopilot — autopilot session and mode logs
  • lint, wiki-lint, wiki-lint-daily, wiki-cleanup — wiki linting processes
  • auto-generated, generated — auto-generated pages
  • janitor, cluster-janitor — cluster janitor operations

Visual Test Tags (added 2026-05-31)

  • vt-001 through vt-015 — visual test identifiers

General Utility Tags (added 2026-05-31)

  • navigation — navigation-related content
  • playwright, screenshot, visual — browser automation and screenshots
  • blocker — issues that are blocking progress
  • cronjob — cron job related content
  • bugfix, feature — changelog categories
  • infra, services — infrastructure and services
  • search — search-related functionality
  • cleanup — cleanup operations
  • status — status reporting
  • social, notifications — social features and notifications
  • productivity — productivity tracking
  • sso — single sign-on

Additional Tags (added 2026-05-31, lint batch)

  • daily — daily recurring content / daily sessions
  • schema-drift — schema consistency issues
  • bugs, resolved — bug tracking and resolution
  • queue — task queue related
  • smtp, mastodon — mail and federation services
  • humhub — HumHub platform
  • configuration, cli, template — config and CLI tools
  • vdi, personas — virtual desktops and persona systems
  • bug-fixes — bug fix tracking
  • cycle-report — periodic cycle reports
  • setup, spawning, gateway — provisioning and gateway topics
  • baseline — baseline measurements
  • hermes-meta — meta-Hermes content
  • test-report, smoke-test — testing artifacts
  • bill-scan — bill scanning project
  • verification, regression — verification and regression testing
  • peft, lora, qlora, dpo, ppo, grpo, rlhf — fine-tuning methods
  • imap — IMAP protocol
  • kanban, github, git — project management and VCS
  • reminders, debugging — reminders and debug content
  • signup, deploy — user onboarding and deployment
  • yaml, populate, keyboard — YAML, data population, keyboard input
  • mattermost, provisioning — Mattermost chat and provisioning
  • done — completed item indicator
  • diagrams, post-deploy — diagrams and post-deployment content
  • widget — UI widget components
  • wiki-health — wiki health metrics
  • settings, audit-log, gaming, learnings, archived — settings, audit logs, gaming VM, learnings, archived items
  • spotcheck, plan — spot-checks and planning
  • source-workspace, noise-reduction — workspace sources and noise reduction
  • cluster-watch — cluster monitoring
  • sprint — sprint tracking
  • queue-redesign — task queue redesign project
  • build, typescript — build system and TypeScript
  • source-email — email as content source
  • evidence, acceptance, ralph-loop — evidence gathering, acceptance criteria, Ralph’s feedback loop
  • projects — generic projects reference

Lint & Automation Tags (added 2026-05-31)

  • automation, autonomous — automation-related content
  • autopilot — autopilot session and mode logs
  • lint, wiki-lint, wiki-lint-daily, wiki-cleanup — wiki linting processes
  • auto-generated, generated — auto-generated pages
  • janitor, cluster-janitor — cluster janitor operations

Visual Test Tags (added 2026-05-31)

  • vt-001 through vt-015 — visual test identifiers

General Utility Tags (added 2026-05-31)

  • navigation — navigation-related content
  • playwright, screenshot, visual — browser automation and screenshots
  • blocker — issues that are blocking progress
  • cronjob — cron job related content
  • bugfix, feature — changelog categories
  • infra, services — infrastructure and services
  • search — search-related functionality
  • cleanup — cleanup operations
  • status — status reporting
  • social, notifications — social features and notifications
  • productivity — productivity tracking
  • sso — single sign-on

Hierarchy and Index Rules (2026-04-24)

  • asx-trading, backtesting, synthesis, pipeline — ASX trading project
  • paper-trading, paper-mode — paper trading modes
  • design, trading-platform, ui — design system tags
  • platform-reference, quantitative, equity-analysis — research platforms
  • platforms, reference, scanning — platform landscape
  • decision, ai-research, announcements — project meta
  • mercury, calliope, queue, hermes-meta — agent system tags
  • comms — communication infrastructure
  • daily — daily session tagging

Missing Tags (added 2026-05-04)

  • ai — general AI topics
  • agents — agent system pages
  • hermes — Hermes-specific
  • active — status indicator
  • agent-feedback, feedback, review — feedback and review content
  • coaching — coaching/advisor content
  • conduct, governance, rules, meta — governance docs
  • spec — specification documents
  • project-session — project session logs
  • report — report/summary documents
  • tools — general tools reference
  • development — development process
  • cron — cron job related
  • overnight, automated, cluster — ops automation
  • index — index/catalogue pages
  • f5-tts, tts, voice — voice/TTS specific (distinct from general audio)
  • latency — latency/performance metric
  • microk8s — MicroK8s specific
  • video-generation, synthetic-avatar, talking-head — video/avatar generation
  • investment, tax — finance/investment analysis

Additional Common Tags (added 2026-05-31)

  • has-correction, has-instruction, has-tool-error — task quality markers
  • source-cli, source-api_server, source-cron — content source origin
  • legend, legend-os — Legend OS project references
  • task, visual-test, folder-inbox — Mercury task categories
  • ux, portal, goal-reflection, goals — UX and goal tracking
  • journal, telemetry, frontend — logging and system metrics
  • svelte, self-improve, rag-alternative — web frameworks and AI patterns
  • cycle, workspace, visual-audit — process and workspace categories
  • testing, legend-os, qa, smart-groceries, ci — project and quality domains
  • persona, test-result, vt-006, vt-003, vt-007, vt-005, vt-010 — testing IDs
  • multi-agent — multi-agent system patterns

Hierarchy and Index Rules (2026-04-24)

  • has-correction, has-instruction, has-tool-error — Mercury task state flags
  • source-cli, source-cron, source-api_server — Mercury task source origin
  • folder-inbox — inbox/task folder classification

Legend Project Tags (added 2026-05-31)

  • legend, legend-os — Legend OS project pages
  • visual-test, visual-audit — visual testing content
  • frontend, svelte, qa, ux, portal — Legend frontend/UX domain

Session & Journal Tags (added 2026-05-31)

  • session, journal — session and journal content (distinct from project-session)
  • goal-reflection, goals — goal tracking and reflection content
  • cycle — cyclic/recurring pattern

Testing & CI Tags (added 2026-05-31)

  • visual-test, testing, test-result, qa — testing domain
  • ci — continuous integration

Other Common Tags (added 2026-05-31)

  • research, self-improve, rag-alternative — research and improvement
  • workspace, persona, telemetry — workspace and persona content
  • smart-groceries — Smart Groceries project reference

Hierarchy and Index Rules (2026-04-24)

New Tags Added by Lint (2026-05-06)

  • animation, avatar, diffusion, video — video/avatar generation domain
  • backtest, rebalancing, trading-strategy — trading strategy tags
  • geopolitics, news-signals — market signals research
  • cron-session — cron-generated session logs
  • bugs, fixes, infra-fix — operational fix tracking

Remaining Lint Tags (added 2026-06-01)

  • daily — daily recurring content / daily sessions
  • mercury — Mercury agent system pages
  • vt-001 through vt-015 — visual test identifiers (full range coverage)
  • entity — entity page type classifier
  • test — testing content (distinct from specific test tags)
  • services — services directory/content
  • bug — bug tracking (singular, distinct from plural bugs)
  • blocked — items that are blocked on external factors
  • asx-trading — ASX trading project-specific content
  • personas — persona system pages
  • widget — UI widget components
  • post-deploy — post-deployment checklists/notes
  • provisioning — infrastructure provisioning
  • mattermost — Mattermost chat platform
  • diagrams — diagram/diagramming content
  • signup — user onboarding/signup flows
  • keyboard — keyboard input/content
  • done — completed item indicator

The wiki uses a fixed two-level hierarchy: root → categories → pages. No “flat” root index.

Fixed top-level directories

DirectoryWhat goes thereHas index.md?
concepts/Architectural patterns, techniques (type: concept)Required
entities/Durable things: tools, services, models, people, systems (type: entity)Required
memories/Long-term agent memory (USER.md, MEMORY.md) — not for browseRequired, minimal
projects/Active project work with session logs under <slug>/sessions/Required
queries/Agent-generated research answers (type: query)Required
raw/Source material: articles/, web-captures/, team-knowledge/, agent-tool-watch/Required at each level
skills/Reusable procedural skills, one per directory with a SKILL.md insideRequired

All other root-level files are single-purpose specials: index.md, SOUL.md, SCHEMA.md, SETTINGS.md, log.md.

Root index.md — landing-only

Maximum ~30 lines. Contents, in order:

  1. One-sentence wiki purpose.
  2. Two prominent links: [[SOUL.md]] (persona), [[SCHEMA.md]] (this file).
  3. A single table with the seven top-level categories — one row each, columns: link to <cat>/index, 1-line description, page count.
  4. Optional “Recent activity” bullet list with 3–5 items from log.md.

Root index NEVER lists individual pages. It NEVER embeds content from subpages. It is a navigation shim, not a directory.

Category <cat>/index.md — catalogue

Required frontmatter:

---
title: "<Category> Index"
type: entity
tags: [index]
---

Body layout:

  1. One-paragraph description of what lives in this category.
  2. If the category has subdirectories, a ## Subsections section listing each with a link to its own index.
  3. A ## Pages section listing all direct children of the category, grouped by tag or topic if more than ~20 entries. Each entry: - — short description.
  4. For projects/index.md: a table — columns Project, Status, Last Session, Link.
  5. For skills/index.md: grouped by domain (infra / research / communication / dev / meta).

Category indexes are rebuilt mechanically from the directory listing — any page without a link from its category index is an orphan.

Reachability invariant

Every .md file under the wiki must be reachable from /index.md by following wikilinks through at most two intermediate index pages. Equivalent statement: root → category-index → (optional subcategory-index) → leaf-page. Pages with no inbound link from an index are orphans and must be either linked or removed by the lint.

Search flow for Hermes

When Hermes needs to find knowledge:

  1. Start from /index.md to orient — category counts reveal where volume lives.
  2. Route by question type:
    • “how do I do X” → skills/index.md
    • “what is X / how does X work” → entities/index.md or concepts/index.md
    • “what did we do on project X” → projects/<slug>/index.md then the newest session
    • “source / citation for claim X” → raw/index.md then the relevant subcategory
    • “prior research answer” → queries/index.md
  3. Category indexes group by tag or date — scan those first before full-text search.
  4. Only full-text search (skill_view, read_file, grep) after the index flow fails.
  5. When adding a new page, also update its category’s index.md — the lint will otherwise flag it as an orphan.

What the daily lint enforces

  • Root index.md is ≤30 lines and contains no individual-page links.
  • Every directory under the wiki root has an index.md with YAML frontmatter.
  • Every leaf page is linked from its category index.
  • Category index counts match actual page counts.
  • Every tag used is present in the Tag Taxonomy above.

Per-project references/ convention

Every project under projects/<name>/ should have a references/ sub-dir capturing external references hermes collected (design refs, research papers, library docs, blog posts) BEFORE writing code:

projects/smart-groceries/
├── index.md
├── sessions/2026-04-27.md
└── references/
    ├── grocery-list-app-design.md          ← collected via web search
    ├── design-system-shopify-2026.md       ← screenshot + extracted notes
    └── shadcn-list-patterns.md

Each reference page has:

  • frontmatter type: reference + tags: [reference] + source_url
  • the screenshot (PNG path) inline
  • vision-extracted design notes (palette hexes, layout, typography, spacing)
  • a one-line “what we want to copy” summary

Mode A recipe (autopilot prompt) instructs hermes to populate references/ first when a project chunk involves frontend work, then iterate code with compare_to_reference-style vision checks until the score reaches ≥8/10.

Tiered qdrant: hot / warm / cold

Search performance + relevance scales as the corpus grows by routing points across three collections instead of one:

TierWhat’s thereWhen searched
wiki-hotaccessed within the last 7 daysalways (first)
wiki-warmnew content + everything elseif hot misses
wiki-coldnot accessed for 90+ daysif warm misses

wiki_search_semantic cascades hot → warm → cold; stops once it has limit results above the fallthrough score (0.55 by default). Each hit fires a background payload-set bumping last_accessed_at.

hermes-tier-promotion cron (daily, 03:30 Brisbane) moves points:

  • warm → hot when last_accessed_at >= now-7d
  • hot → warm when last_accessed_at < now-7d (idle demotion)
  • warm → cold when last_accessed_at < now-90d or never accessed
  • cold → warm when a search hit revives it (last_accessed_at >= now-90d)

New content from the indexer lands in wiki-warm (the alias of the legacy wiki collection — no migration needed).

What stays optimal automatically

  • hermes-vector-reconcile (hourly): wiki → qdrant idempotent rebuild
  • hermes-wiki-snapshot (every 15 min): wiki → gitlab repo
  • hermes-tier-promotion (daily 03:30 Sydney): tier reorganisation
  • hermes-search-quality-eval (Sunday 09:30 Sydney): runs canonical queries and asserts expected pages still surface in top-5. Drops → Slack alert + wiki/log.md entry. Catches embedder drift, type misclassification, runaway tier collapse.
  • hermes-schema-drift (Sunday 09:35 Sydney): diffs ls /wiki/ vs the known set in vector_lib.detect_type. Files a queue task if a new top-level dir is appearing as type: other.

What to do when search drops

Symptoms hermes (or pvs) might notice:

  • semantic search returns mostly emails or sessions instead of skills
  • type=memories filter returns nothing
  • expected page (e.g. MEMORY.md) doesn’t surface for queries that should match it

Diagnosis order:

  1. Check hermes-search-quality-eval’s last run. If it’s failing, the alert message lists which canonical queries regressed.
  2. Check qdrant point counts per type: 
    for t in email memories skills sessions concepts entities projects \
         queue raw ops queries projects-archived other; do
    curl -s -X POST http://qdrant.hermes.svc.cluster.local:6333/collections/wiki-warm/points/count \
        -H "Content-Type: application/json" \
        -d "{\"filter\":{\"must\":[{\"key\":\"type\",\"match\":{\"value\":\"$t\"}}]},\"exact\":true}" \
    | jq -r '. as $r | "\(.result.count // 0)\t'"$t"'"'
done
    other should be ≤1% of total; if higher, something’s miscategorised.
  3. Check tier sizes: 
    for c in wiki-hot wiki-warm wiki-cold; do
    curl -s http://qdrant.hermes.svc.cluster.local:6333/collections/$c \
    | jq -r ".result.points_count // \"err\"" | xargs -I N echo "$c: N"
done
    Hot should be small (~1-10k); warm large (~50-300k); cold whatever’s accumulated. If hot=0 after a week, the access-tracking write isn’t landing — check wiki_search_semantic logs.
  4. Force a reconcile to refresh embeddings if the embedder model changed: 
    kubectl -n hermes create job --from=cronjob/hermes-vector-reconcile reconcile-manual-$(date +%s)
  5. If detect_type is missing a new dir, the schema-drift cron files a queue task with the diagnosis. Resolve per the task’s options: recognize, move, or ignore.

Graph View

Backlinks