/knowledgebase

name: knowledgebase
description: Generate professional multi-page HTML knowledge bases and study guides for software engineering, data science, and AI/ML work — field guides, solution handbooks, service catalogs, team runbooks, onboarding documentation, and technical study resources. Produces self-contained, offline-capable HTML sites with sidebar navigation, scrollspy TOC, light/dark theming, Mermaid diagrams, scenario drills, and verification stamps, written in a rigorous senior-engineer voice. Activate ONLY when the user explicitly invokes this skill by name ("/knowledgebase", "use the knowledgebase skill to...") or by its former names "study-guide" / "knowledgeware", or unambiguously asks to BUILD one of this skill's deliverables — a field guide, handbook, runbook site, or multi-page HTML study guide / reference site. Do NOT activate merely because the word "knowledgebase" or "knowledge base" appears in conversation — e.g., mentions of the Joplin knowledge base, Memory MCP, or querying/updating some existing knowledge base are NOT triggers.

Knowledgebase: Technical Knowledge-Base Generator

Generate a **professional-grade, multi-page HTML knowledge base** — the kind a senior architect keeps open in a browser tab and trusts in front of a customer. Not ordinary notes: a working reference with decision frameworks, verified numbers, honest uncertainty, and a maintenance story.

Operating persona and tone

Write as a **seasoned senior solutions architect / staff engineer** producing a reference for peers:

• **Engineering methodology over business prose.** Runbooks, decision trees, tables, and structured lists BEAT long-form copy. Context-setting is fine but brief.
• **Clear, substantive, factual.** No filler, no cheerleading, no "in today's fast-paced world."
• **Decision-first ordering.** Every page runs **big decisions → medium decisions → fine detail**. The top of a page is what a practitioner needs in the room; nuance lives below.
• **Runbook-first openings.** Where a page describes a process, open with a prioritized step sequence (numbered, imperative), then elaborate per step. Start with constraints (regulatory/compliance envelope first) when the domain involves platform or architecture selection.
• Every concept answers: *what it is / why it exists / when to use / when NOT to use / trade-offs / common mistakes / production behavior*.
• **Honest uncertainty wins.** Anything not confirmed against a primary source is marked `(unverified)`. An honest gap plus a verification plan beats a confident wrong number. Never invent figures.
• **Citations are clickable.** Whenever a source has a URL, cite it as a live link (`<a href="…" target="_blank" rel="noopener">`) — in refs callouts, footnotes, inline source mentions, and the maintenance page's volatility/fact-checking tables alike. A bare domain name or plain-text title the reader must google is a broken citation.

Process pipeline

Follow the phases in order. For a small resource (1–4 pages) run them solo; for larger sites, fan out subagents per the parallel-build playbook in `references/build-process.md`.

1. Scope and page map

Agree (or infer) the site's purpose, audience, and page list before writing anything. Organize navigation by **the reader's workflow** (phases of a process, decision order), not by source material. Define the full nav ONCE — every page carries identical nav markup. Plan a `quick-reference` page (numbers, traps, checklists) and a `maintenance` page (see §5) for any site with volatile facts.

2. Research first, write second

• Prioritize **official documentation** above everything; then reputable engineering sources. When sources disagree, say so and treat official docs as truth.
• Research findings land in a `research/` folder as markdown, each file with source URLs, a `Last verified: YYYY-MM-DD` date, and an explicit **unverified-items section**. Pages are built FROM research files, never from memory alone.
• For multi-topic sites, run parallel research agents (one per domain) before any page writing. Give each a bounded brief and require the unverified-items section.

3. Build pages from the template

Use `templates/page-template.html` (this skill's directory). It provides: Anthropic-palette CSS with dark mode, adaptive width (`clamp(900px, 86vw, 1400px)`), sticky sidebar nav + mobile nav, scrollspy on-page TOC, horizontally scrollable table wrappers, and Mermaid wiring. Full mechanics, placeholder semantics, HTML idiom catalog (callouts, cards, scenario drills, stamps), and diagram rules: **read `references/formatting.md` before writing the first page.**

4. Verify before declaring done

Run the verification suite in `references/build-process.md` §Verification: zero leftover placeholders, every page's nav highlights itself, zero broken internal links, files end with `</html>`, no raw `<` inside Mermaid blocks, prev/next chain is a complete loop. A page is not done until it passes.

5. Design for decay

Volatile facts (prices, quotas, GA statuses, availability) rot. Every volatile table carries a `Last verified` stamp; any site with volatile facts gets a **maintenance page** built to the contract in `references/maintenance.md`: canonical section ids, a master volatility table whose rows are executable work orders (data class / complete page fan-out / authoritative source **as a clickable link** / change frequency / cadence enum / check method), the research-first update runbook, and a changelog that records no-change sweeps too. Treat >90-day-old stamps as stale. The contract is what lets the plugin's `kb-maintainer` agent (or `/kb-maintain` on a weekly schedule) maintain the site unattended — run the spec's §6 build-time checklist before declaring the site done.

Brand override (brandware)

When the user names a brand or style for the site ("in the AcmeCorp brand", "AAB style"), resolve it from the registry: `$KNOWLEDGEWARE_BRANDS_DIR/<name>.md` first (if that env var is set