wiki-builder

name	wiki-builder
type	capability
description	Serve any directory of markdown files as a beautiful, navigable browser wiki — sidebar navigation, on-page table of contents, frontmatter metadata chips, and interactive ECharts charts. Use when the user wants to view, browse, preview, or serve markdown files (notes, research, a brain/knowledge base, a company wiki) as a local website. Triggers: 'serve wiki', 'start wiki server', 'render markdown as a website', 'open my notes in the browser', 'view brain as wiki', 'open wiki'. Self-contained Bun + markdown-it server; runs a local HTTP server, mutates nothing.
requires	["analyst-kit-core"]

Preamble (run first)

PLAN MODE EXCEPTION — ALWAYS RUN: this block only reads state and writes to ~/.analyst-kit/.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
if [ ! -x "$_AK/bin/analyst-kit-preamble" ]; then
  for d in ~/.claude/skills/analyst-kit-core .claude/skills/analyst-kit-core ~/.codex/skills/analyst-kit-core .codex/skills/analyst-kit-core; do
    [ -x "$d/bin/analyst-kit-preamble" ] && _AK="$d" && break
  done
  [ -x "$_AK/bin/analyst-kit-preamble" ] || _AK="$(find ~/.claude/plugins -maxdepth 6 -type d -name analyst-kit-core 2>/dev/null | head -1)"
  [ -n "$_AK" ] && { mkdir -p ~/.analyst-kit; printf '%s' "$_AK" > ~/.analyst-kit/core-path; } || true
fi
[ -x "$_AK/bin/analyst-kit-preamble" ] && "$_AK/bin/analyst-kit-preamble" --skill wiki-builder 2>/dev/null || echo "AK_CORE: not found (continue without runtime)"

Read the echoed state and act. Skip ALL bullets below if DEDUP: yes or AK_CORE: not found:

• DISABLED: yes → this skill is turned off because a required API key isn't configured. Do not run it. Tell the user it's off, name the missing key (see MISSING_KEYS), and offer to enable it — either they give you the key now (store it with "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>, which re-enables the skill) or they say "set up analyst-kit" for full setup. Then stop; do not attempt the skill's work.
• First run — ONBOARDED: no → orient the user once, then run "$_AK/bin/analyst-kit-setup" finish (this covers the telemetry notice, so skip the TEL_PROMPTED bullet this turn):
  1. Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and a learnings log together in one folder (default ~/.analyst-kit); offer to move it with "$_AK/bin/analyst-kit-setup" home <dir>.
  2. Telemetry (a notice, not a question) — usage telemetry is on by default: only skill name, duration, outcome, and version, tagged with a per-machine device id derived from the hardware/OS, never repo names, paths, tickers, or content; opt out anytime by asking to turn Analyst Kit telemetry off.
  3. Identity (name + email — required) — ask for the user's name and email, stating plainly the email is mandatory to use most features (SEC EDGAR's fair-access policy requires a real, reachable contact on every request). If they decline because they don't want the email-dependent skills, discover a fallback yourself (git config user.email, gh api user, …) and pass it with --fallback in step 5.
  4. Offer full setup — ask if they'd like to configure API keys for all skills now. If yes, Read "$_AK/references/intro.md" and follow it. If no, continue — you'll ask for a key only when a skill needs one.
  5. Run "$_AK/bin/analyst-kit-setup" finish --name "<name>" --email "<email>" (add --fallback for a discovered email; run plain finish only if no email could be found at all). If it echoes INVALID_EMAIL, re-ask and run it again.
• User asks to set up Analyst Kit at any time (e.g. "set up analyst-kit", "help me set up Analyst Kit", "configure all skills") → Read "$_AK/references/intro.md" and follow it end to end: data home, telemetry, every skill's keys, and enabling/disabling each.
• TEL_PROMPTED: no (returning user) → give the telemetry notice once, then run "$_AK/bin/analyst-kit-setup" ack-telemetry.
• If the user asks to turn telemetry off (now or anytime): before flipping it, make a sincere case once — telemetry is what tells the maintainers which skills break, which run slow, and where users get stuck, so keeping it on directly improves their experience; it never includes their data. Offer "$_AK/bin/analyst-kit-config" set telemetry anonymous (drops the device id) as a middle ground. If they still want out, run "$_AK/bin/analyst-kit-config" set telemetry off immediately and without further argument.
• Before running any script that needs an API key: source both the data home's .env and the current directory's .env into the shell so scripts can read stored keys: set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a (where $AK_HOME is the path printed on the AK_HOME: line above). Full lookup order — always check these before concluding a key is missing or asking the user:
  1. current shell environment
  2. $AK_HOME/.env (keys stored by analyst-kit-setup)
  3. .env in the current working directory Never ask the user for a key that is already present in any of these locations.
• MISSING_KEYS not none → for each listed key with KEY_PROMPTED_<KEY>: no: explain where to get it, ask for the value, and run "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>. If declined, run "$_AK/bin/analyst-kit-setup" skip-key <KEY> (this disables the skills that need it) and continue — never block the skill.
• UPGRADE: UPGRADE_AVAILABLE <old> <new> → say "Analyst Kit skills is available (you have ) — update?". If yes: Read "$_AK/references/upgrade.md" and follow it. If declined: run "$_AK/bin/analyst-kit-update-check" --snooze <new>.
• LEARNINGS entries shown → these are past mistakes/preferences for this user; respect them and do not repeat logged pitfalls.

Then proceed with the skill. At the very end, run the Completion block at the bottom of this file.

Wiki Builder

Serve any directory of markdown files as a navigable browser wiki. The renderer runs on the fly — no pre-building, no generated output written to disk.

Requirements

• Bun must be installed (bun --version). If missing, install it with curl -fsSL https://bun.sh/install | bash (macOS/Linux) or see https://bun.sh.

Run

Always run from the skill directory so the renderer's templates/assets resolve.

cd "$(dirname SKILL.md)"   # the directory containing this file

# First run only: install dependencies (node_modules is NOT bundled with the skill)
[ -d node_modules ] || bun install

# Serve a directory of markdown files
bun run serve.ts /path/to/notes

Then open http://localhost:4000/wiki/.

• Serve the current directory: bun run serve.ts
• Custom port + site name: PORT=3000 WIKI_SITE_NAME="My Notes" bun run serve.ts /path/to/notes

Dependencies are installed on first use rather than shipped with the skill, so they stay current and the skill itself holds only source + instructions. The [ -d node_modules ] || bun install guard makes the first run self-installing.

Environment variables

Variable	Default	Description
PORT	4000	HTTP port
WIKI_DIR	cwd	Directory to serve (overridden by the first CLI arg)
WIKI_SITE_NAME	Brain Wiki	Site name in the topbar
WIKI_NO_CHARTS	unset	Set to 1 to disable the ECharts CDN

Page frontmatter

Each markdown file may declare frontmatter to control its sidebar placement and metadata chips:

---
title: My Page
navGroup: Reference   # sidebar section (default: Pages)
navOrder: 1           # sort order within group
ticker: NVDA          # rendered as a metadata chip
author: Mohit
updated: 2026-06-05
---

Charts

Render interactive ECharts from a fenced chart block containing an ECharts option object (optionally with caption and height):

```chart
{ "type": "line", "xAxis": { "data": ["Q1","Q2","Q3"] }, "series": [{ "data": [10,14,11] }] }
```

File structure

wiki-builder/
  SKILL.md              ← this file
  serve.ts              ← entry point (Bun HTTP server)
  package.json          ← dependency manifest
  bun.lock              ← pinned versions for reproducible `bun install`
  wiki/
    index.ts            ← markdown renderer (markdown-it + nunjucks)
    assets/
      theme.css         ← styles
      wiki.js           ← TOC + chart init
    templates/
      layouts/
        page.njk        ← HTML template

Completion (run last)

Audit before you deliver. If this run produced a research deliverable carrying quantitative or factual claims — a deep dive, thematic/value-chain map, technical call, company wiki, or financial model — you MUST verify it before presenting it. If a research-auditor subagent is available (the analyst-kit plugin ships one), invoke it via the Task tool, handing it the draft and the data artifacts you used; on a runtime without subagents, run the same checks yourself. Resolve every CRITICAL finding and disclose any UNVERIFIED ones; never deliver on a FAIL verdict without fixing it first. Skip this only for pure data-fetch/utility runs with no analytical claims.

PLAN MODE EXCEPTION — ALWAYS RUN: writes only to ~/.analyst-kit/. Replace OUTCOME with one of DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
[ -x "$_AK/bin/analyst-kit-log" ] && "$_AK/bin/analyst-kit-log" end --skill wiki-builder --outcome OUTCOME 2>/dev/null || true

If this session surfaced a durable pattern, pitfall, or user preference that would save 5+ minutes next time (not obvious, not a transient error), also log it:

"$_AK/bin/analyst-kit-learn" add '{"skill":"wiki-builder","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'