agent-docs

Kevin Wiki - Agent Index

This file is a navigation index for agents, not the wiki manual. Keep it short, delete no-op instructions, and load linked files only when the task needs them. Durable behavior belongs in skills/**/SKILL.md, wiki/meta/*.md, scripts, or generated indexes.

Start Here

  1. Find a page with kb <words> and read its top with kb get <name> (scripts/kb.mjs; bootstrap links it to ~/.local/bin/kb).
  2. Read wiki/meta/wiki-brain-operating-model.md before changing how pages are shaped, found, written or kept fresh.
  3. Run npm run status and report the stale pages, waiting notes and overdue items it lists.
  4. wiki/USER.md, wiki/SOUL.md, wiki/HEARTBEAT.md and wiki/meta/agent-operations-hub.md are references. Open them when the task needs them, not at the start of every session.

Operating Rules

  • Treat this checkout as kevin-wiki no matter what the local folder is named.
  • Use kb first for Kevin-specific people, tools, concepts, decisions and prior ingests, qmd query for fuzzy meaning search, and rg for exact strings.
  • Read the relevant installed skill before specialized work. Skill sources live in skills/{engineering,productivity,personal,misc,in-progress,deprecated}/<slug>/SKILL.md.
  • Do not do one-off recurring work. Prototype once, then codify through skill-creator, a script, or an automation.
  • Do not discard uncommitted work you did not create. Use a separate worktree when the main checkout is dirty or shared.
  • For X/bookmark work, use skills/productivity/x-bookmark-absorb/SKILL.md and enriched records under raw/x-bookmarks/enriched/.
  • A page's frontmatter updated: is the day someone last checked it is true. Bump it only when you verify the page, and add a dated Timeline line with the source.
  • After wiki edits, rebuild generated surfaces that changed and append wiki/log.md.
  • Replace code with a clean cutover: delete the old path and update every caller instead of adding a fallback or a second copy. Stored data and wiki pages need Kevin's decision first. See wiki/concepts/cutover-not-compatibility.md.

Pointers

Need Open
How the brain works: lookup, card, notes, freshness wiki/meta/wiki-brain-operating-model.md
Task routing and read order wiki/meta/agent-operations-hub.md
Filing, merging, and page shape wiki/meta/wiki-brain-operating-model.md, wiki/RESOLVER.md
Capture or pasted URL/post/repo wiki/meta/capture-ingest-protocol.md
Skills and command inventory wiki/meta/skill-registry.md, wiki/meta/slash-command-index.md
Tool/service/CLI choice wiki/meta/capability-routing-map.md, wiki/SKILL-RESOLVER.md
Generated output ownership wiki/meta/generated-surface-contract.md
Wiki page format wiki/meta/wiki-page-format.md
Scripts scripts/SKILL.md
UI app ui/SKILL.md
Agent-docs kit scripts/agent-docs/SKILL.md, skills/productivity/agent-docs/SKILL.md

Closeout Map

Change Minimum closeout
Wiki page edits npm run build-index; qmd update/embed when available; wiki/log.md
scripts/kb.mjs, aliases or summaries of key pages npm run kb:test; npm run kb:eval; npx tsx scripts/doctor.ts --only retrieval gates on evals/kb-retrieval-heldout.json. Never edit a page to pass a held-out case.
Weekly harvest kb inbox and kb stale lists empty or explained; kb inbox done <file...> for each note written
Skill source/routing edits npm run skill-registry; npm run skills:check; relevant doctors
Slash-command or package-script edits npm run slash-command-index; npm run slash-command-index:check
Agent config edits npm run bootstrap; npx tsx scripts/doctor.ts --only config-sync
Agent pack/capsule edits npm run agent-packs:refresh; npm run agent-packs:check
.vercelignore, ui/package.json, ui/scripts/ or agent-doc (AGENTS.md, README.md, SKILL.md) edits pnpm --dir ui test:vercel-upload
X bookmark absorption npm run audit:x-bookmarks; npm run audit:x-bookmark-artifacts; npx tsx scripts/doctor.ts --only x-bookmarks

Agent-docs Auto Facts

  • Name: kevin-wiki
  • Package manager: npm
  • Languages: typescript
  • Framework: n/a
  • Package scripts detected: 75. Use package.json as the exhaustive source.
  • npm run dev - cd ui && corepack pnpm@10.30.0 dev
  • npm run build - corepack pnpm@10.30.0 --dir ui install --frozen-lockfile && corepack pnpm@10.30.0 --dir ui run build
  • npm run agent-docs - npx tsx scripts/agent-docs/index.ts
  • npm run slash-command-index - npx tsx scripts/generate-slash-command-index.ts
  • npm run build-index - npx tsx scripts/build-index.ts
  • Keep this block compact. Put full command catalogs in a generated command index, not in AGENTS.md.
Directory Skill Purpose
demos/reticle-design-system-demo/ demos/reticle-design-system-demo/SKILL.md Next 16 Reticle design-system demo with live structural-visibility controls, server-side specimen request storage, and local Reticle design rules.
scripts/ scripts/SKILL.md tsx maintenance CLIs — index/lint/doctor the wiki, ingest + sync sources, run automations, serve MCP/voice.
scripts/agent-docs/ scripts/agent-docs/SKILL.md The Agent-Docs Mesh kit — detects a repo, scaffolds/adopts AGENTS.md + per-dir SKILL.md non-destructively, and runs docs-doctor.
scripts/lib/ scripts/lib/SKILL.md Shared, unit-tested helpers for the scripts/ CLIs — state, absorb-log, integration DB, Google auth, agent-config sync, bookmark enrichment.
ui/ ui/SKILL.md Next.js App Router viewer for the wiki + /me portfolio — renders the markdown knowledge base with search, graph, and OG images.
ui/scripts/ ui/scripts/SKILL.md Build-time scripts for the viewer — bundle wiki content for the app and enforce/test inline citations and gate passwords.
  • (none detected)
  • Use Graphify for repo topology, path/explain/affected questions, PR risk, and unfamiliar codebase orientation.
  • Use rg for exact strings; use Kevin-Wiki qmd for people, tools, decisions, and compiled wiki knowledge.
  • Use agent-browser for browser/UI work; use Playwright only for committed regression tests.
  • Runtime memories (Hermes/Hindsight/Honcho) are not project truth until written back to AGENTS.md, SKILL.md, or the wiki.
  • Status: cd ~/repos/Kevin-Wiki && npm run graphify:sidecar -- status --run outputs/graphify/kevin-wiki
  • Build from this repo: PROJECT_ROOT="$(pwd)" && cd ~/repos/Kevin-Wiki && npm run graphify:sidecar -- build "$PROJECT_ROOT" --run outputs/graphify/kevin-wiki --no-viz
  • Query after build: cd ~/repos/Kevin-Wiki && npm run graphify:sidecar -- query "what should I inspect first?" --run outputs/graphify/kevin-wiki
  • Never run Graphify installers/hooks or commit generated graphify-out/ artifacts.