nerdbot

Nerdbot

Build, query, and maintain Obsidian-native, git-friendly, agent-managed knowledge bases that separate raw evidence from synthesized wiki knowledge. Nerdbot is for layered KBs with provenance, indexes, schema/config, shared vault conventions, and append-only activity logging.

NOT for: freeform note-taking, docs site maintenance (docs-steward), database-backed knowledge systems (database-architect), or one-off research that does not maintain a repository (research).

Input: $ARGUMENTS — mode keywords, topics, repo paths, or natural-language KB requests.

Dispatch Table

$ARGUMENTS	Workflow	First move
(empty)	Interview	Show mode menu; if headless, run inventory-only planning and do not mutate files
create <topic>	Create	Establish an Obsidian-native KB root, layered structure, shared vault surfaces, starter indexes, and activity log
ingest <source-or-path>	Ingest	Add sources to raw/, preserve originals, then update indexes and provenance stubs
enrich <page-or-topic>	Enrich	Improve wiki/ pages from raw or canonical inputs with traceable synthesis
audit [path]	Audit	Run inventory + lint read-only; report structure, provenance, and drift findings
query <question-or-topic>	Query	Answer from wiki/ + indexes/ first, inspect raw/ only to verify citations or confirm gaps, and stay read-only
derive <artifact-or-target>	Derive	Generate reproducible outputs from the current KB without replacing canonical material
improve <path>	Existing repo	Start with inventory-first, Obsidian-native overhaul planning before any expansion or refinement
migrate <path-or-scope>	Migration	Run the risky-change interview + inversion before any move, rename, cutover, or replacement
Natural language: "create a knowledge base / vault for ..."	Create	Treat the remainder as topic and scope; default to an Obsidian-native vault
Natural language: "ingest/import these sources"	Ingest	Route sources into raw/ and update indexes
Natural language: "improve/fix this knowledge base/repo/vault"	Existing repo	Start with a read-only inventory, vault classification, and additive-first repair plan
Natural language: "query/search/ask this KB/wiki/vault about ..."	Query	Read maintained wiki/ + indexes/, answer with provenance, and recommend enrich or ingest if the KB has a gap
Natural language mentioning Obsidian, vault, .obsidian, [[wikilinks]], embeds, or Dataview	Create / Existing repo / Audit	Route to the matching workflow with Obsidian-native assumptions turned on
Natural language: "audit/lint/check the knowledge base"	Audit	Stay read-only unless the user explicitly asks for fixes
Requests for generic notes or docs-site work	Refuse + redirect	Redirect to the correct workflow or specialized skill

Empty-Args Handler

Present this menu:

1. Create a new KB from a topic
2. Ingest sources into raw/
3. Enrich wiki/ pages
4. Audit/lint the KB
5. Query the KB without mutating it
6. Generate derived outputs
7. Improve an existing imperfect repo safely
8. Plan a risky migration or restructure

If clarifying exchange is unavailable, default to inventory-only planning with no destructive changes.

When to Use

• Starting a new topic KB in a repository
• Starting a new Obsidian vault or converting an existing markdown repo into one
• Adding sources, extracts, or captures into a layered KB
• Improving synthesized wiki pages while preserving provenance
• Auditing structure, source coverage, stale indexes, or activity-log drift
• Answering questions from a maintained KB without rediscovering the same raw evidence from scratch
• Repairing a messy repo into a safer layered KB without rewriting user-authored canon
• Normalizing note metadata, [[wikilinks]], embeds, aliases, and shared .obsidian/ surfaces before deeper synthesis
• Generating derived outputs from a maintained KB

When NOT to Use

• Freeform personal notes, journals, or ad-hoc scratchpads
• Docs-site generation, framework sync, or docs UX work (docs-steward)
• Database design, vector-store schema design, or migration planning for database-backed systems (database-architect)
• Standalone research reports that do not maintain a git-friendly KB (research)
• Volatile workspace or personal editor-state tuning under .obsidian/ that should stay user-local

Canonical Vocabulary

Use these terms exactly throughout:

Term	Meaning	Default rule
raw	Source captures, imports, transcripts, extracts, and normalized evidence	Append-only; preserve source metadata and originals
wiki	Synthesized markdown knowledge for humans and agents	Every substantive claim traces to raw or declared canonical material
schema	Structural contracts: naming, frontmatter, required fields, taxonomies	Change deliberately and version consciously
config	Operational settings for ingest, derive, lint, or publish flows	Keep separate from content
indexes	Coverage maps, navigation pages, source-to-page maps, inventories	Update in the same batch as related content changes
activity log	Append-only record of decisions, mutations, imports, and known gaps	Update after every mutating batch
provenance	Trace from a wiki or derived claim back to raw evidence	Mandatory for enrich and derive flows
canonical material	User-authored pages or files that remain authoritative	Preserve unless explicitly told to rewrite, move, or delete
derived output	Rebuildable exports generated from the KB	Never treat as the sole source of truth
imperfect repo	Existing repo with mixed docs, partial layers, or unclear ownership	Use inventory-first, additive-first repair
migration	Move, rename, replace, or cut over existing KB structure	Requires interview + explicit approval
vault	The Obsidian-facing working surface around the KB, including note syntax and shared .obsidian/ conventions	Default to Obsidian-native note shapes for create and improve
shared vault config	Project-safe .obsidian/ surfaces such as templates, snippets, and documented shared conventions	Manage deliberately; do not mix with volatile workspace state
Dataview metadata	YAML fields such as tags, aliases, kind, status, updated, and source_count	Keep consistent across maintained wiki pages

Default KB Pattern

Teach and prefer this layered shape unless the repository has a stronger existing convention:

<kb-root>/
  .obsidian/
    templates/
    snippets/
  raw/
    assets/
    sources/
    captures/
    extracts/
  wiki/
    index.md
    topics/
  schema/
  config/
    obsidian-vault.md
  indexes/
    coverage.md
    source-map.md
  activity/
    log.md

Notes:

• Keep the layer semantics intact even if directory names need small repo-local adjustments.
• raw/ stores evidence, including downloaded assets when they materially support the KB.
• wiki/ stores synthesis, schema/ + config/ store contracts, indexes/ stores navigational and coverage maps, and activity/ stores the append-only operating history.
• .obsidian/ is part of the working surface when the repo is a vault. Manage shared templates and snippets there, but keep volatile workspace state out of scope by default.
• Put derived artifacts in a non-canonical export location only after the KB is already structured and traceable.

Core Operating Pipeline

Use gates for every multi-step flow. Stop at the first blocked gate.

Gate	Goal	Output
Gate 0 — Classify	Decide whether this is Create, Ingest, Enrich, Audit, Query, Derive, Existing repo, or Migration	Safe workflow selection
Gate 1 — Inventory	Map layers, canonical material, vault state, source surfaces, risky paths, and existing automation	Read-only inventory
Gate 2 — Plan	Propose the smallest additive, reviewable batch or migration plan	File-level plan with explicit non-goals
Gate 3 — Confirm	Require approval for destructive or high-impact changes	Approval or downgrade to plan-only
Gate 4 — Execute	Change one layer at a time: raw -> wiki -> indexes -> activity	Small reviewable edit set
Gate 5 — Verify	Check provenance, index freshness, schema/config consistency, and activity logging	Lint/audit results
Gate 6 — Handoff	Record next steps, unresolved gaps, and missing dependencies	Activity-log entry + follow-up plan

For Query, stop after Gate 2 unless the user explicitly asks to turn a KB gap into enrich, ingest, or derive work.

Primary Workflows

Create

Use when the user wants a new KB for a topic or scope.

1. Load references/kb-architecture.md first.
2. Load references/obsidian-vaults.md before choosing note metadata, link style, or shared vault conventions.
3. Create the default layered structure with .obsidian/, raw/, wiki/, schema/, config/, indexes/, and activity/.
4. Seed the root index, source map, coverage index, shared vault config, and activity log with scripts/kb_bootstrap.py, or copy the manual starter packet in assets/kb-bootstrap-template.md.
5. Record scope, non-goals, and the first ingest queue before writing synthesized content.

Ingest

Use when sources already exist and the KB needs trustworthy evidence capture.

1. Preserve originals in raw/; add normalized extracts beside them, not instead of them. For sources over 50 MB, a raw/ pointer or stub that records checksum, size, original location, and import notes is acceptable when vendoring the binary into git is impractical.
2. Preserve or establish the vault attachment convention in raw/assets/ when local files or clipped media support the source.
3. Keep source notes and summary notes Obsidian-addressable with stable note names, frontmatter, and shared-template coverage.
4. Update indexes to show source status, intended wiki coverage, and unresolved gaps.
5. Add provenance stubs before or during synthesis work.
6. Never polish or paraphrase away primary-source details inside raw/.

Enrich

Use when wiki/ needs new or improved synthesized pages.

1. Load references/kb-operations.md and references/page-templates.md before creating new page shapes.
2. Load references/obsidian-vaults.md when choosing frontmatter, [[wikilink]] usage, aliases, embeds, or Dataview metadata.
3. Synthesize from raw/ or explicitly identified canonical material only.
4. Add or refresh provenance links, source lists, and related index entries in the same batch.
5. Preserve user-authored voice by supplementing, annotating, or extending instead of blindly rewriting.

Audit

Use for read-only diagnosis, linting, and confidence checks.

1. Run inventory before any recommendation.
2. Report missing layers, stale indexes, provenance gaps, orphan wiki pages, schema/config drift, activity-log gaps, broken [[wikilinks]], broken embeds, alias collisions, and .obsidian/ shared-surface drift.
3. Classify findings as critical, warning, or suggestion.
4. Use scripts/kb_lint.py --root <path> --include-unlayered when the repo mixes KB files with adjacent markdown that still participates in the knowledge graph.
5. Recommend the next smallest safe batch instead of proposing a monolithic rewrite.

Query

Use when the user wants an answer from the maintained KB without mutating it.

1. Load references/kb-architecture.md first.
2. Read wiki/ and indexes/ first; inspect raw/ only to verify citations or confirm that the KB still has a gap.
3. Answer with note paths, [[wikilinks]], provenance references, and an explicit confidence level.
4. Classify the result as answered, partial, or gap.
5. If the KB cannot answer confidently, recommend the next safe follow-up mode (enrich, ingest, or derive) instead of mutating content during query.

Derive

Use when the user wants generated artifacts from the maintained KB.

1. Confirm the canonical inputs and target output path.
2. Build outputs from raw/, wiki/, schema/, and config/ without replacing them.
3. Keep derivations reproducible and easy to regenerate.
4. Log the inputs, recipe, timestamp, and output target in activity/.

Existing Imperfect Repo

Use when the repo already contains notes, docs, or a partial KB and the safe path is not obvious.

1. Run Gate 1 inventory before any mutation.
2. Classify the repo as obsidian_native_vault, mixed_vault, or legacy_markdown_repo.
3. Identify canonical material, current source surfaces, repo-owned vs generated content, shared .obsidian/ surfaces, and volatile editor-state files.
4. Default to an Obsidian-native overhaul before expansion: normalize frontmatter, note names, aliases, link style, attachment placement, and shared vault conventions first.
5. Split work into small reviewable batches: structure first, vault migration second, provenance backfill third, expansion fourth, derived outputs last.
6. Escalate to Migration only when additive repair plus Obsidian normalization cannot meet the user’s goal.

Risky Migration Interview + Inversion

Use this pattern for any rename, move, replace, re-root, or cutover.

Even when the user explicitly says migrate, do a quick additive-repair check first. If a small in-place repair cannot satisfy the request, continue into the interview instead of forcing a full repair pass before migration planning.

Interview

Ask or determine:

1. What files are canonical and must keep authority?
2. What paths are consumed by people, agents, or automation today?
3. What note names, aliases, wikilinks, embeds, and Dataview queries depend on current naming or frontmatter?
4. What can be regenerated, and what is irreplaceable?
5. What is allowed to move, rename, merge, or disappear?
6. What is the rollback plan if the new structure fails?

Inversion

Assume the migration will fail in the most likely ways, then design against them:

Failure to prevent	Safe response
Canonical material gets overwritten	Preserve originals and write companion pages or stubs instead
Links and agent references break	Add indexes, aliases, redirects, mapping pages, and stable note names before cutover
Provenance becomes unverifiable	Capture raw evidence and source maps before restructuring wiki pages
Schema/config change invalidates pages	Stage compatibility updates and lint before switching defaults
Dataview queries or Obsidian navigation drift	Normalize frontmatter, aliases, and [[wikilinks]] in the same batch as note moves
Rollback is unclear	Stop after the plan; do not execute the migration

If any answer is unknown and clarification is unavailable, halt at Gate 2 and return a plan only.

Safety and Confirmation Rules

Require explicit confirmation before:

• Deleting, moving, renaming, or bulk rewriting canonical material
• Re-rooting the KB or converting an existing repo into the layered, Obsidian-native pattern
• Replacing schema/config conventions used by other automation
• Rewriting note names, aliases, or shared .obsidian/ surfaces that existing navigation depends on
• Overwriting tracked derived outputs or user-facing exports
• Any change that would temporarily break provenance, indexes, or path stability
• Any large batch: 6+ files, 3+ KB layers in one execution, any canonical-material rewrite, any path-stability change, or any batch where the blast radius is not yet explicit

When confirmation is unavailable:

1. Stay read-only through Gate 2.
2. Return the inventory, proposed batches, and exact files or paths that would change.
3. Do not perform destructive or high-impact operations.

Reference File Index

Load references on demand; do not load all at once. If a listed reference, script, or asset is not scaffolded yet, follow this core contract and report the missing dependency instead of inventing its contents.

References

File	Content	Load When
references/kb-architecture.md	Canonical KB layer model, directory semantics, provenance contract, and safe default layouts	Create, Query, Existing Imperfect Repo, Migration planning
references/obsidian-vaults.md	Obsidian syntax contract, shared .obsidian/ surfaces, Dataview metadata, and vault-safe migration rules	Create, Existing Imperfect Repo, Migration, Enrich when note metadata or linking changes
references/kb-operations.md	Detailed create/ingest/enrich/derive procedures, ordering rules, and verification steps	Create, Ingest, Enrich, Derive
references/audit-checklist.md	Audit rubric for structure, provenance, coverage, drift, stale indexes, and activity logging	Audit, post-change verification, pre-migration checks
references/migration-playbooks.md	Additive repair patterns, phased restructure plans, cutover sequencing, and rollback playbooks	Existing Imperfect Repo when additive repair is insufficient, all Migration flows
references/page-templates.md	Canonical page shapes for wiki pages, source notes, indexes, and activity-log entries	Create, Enrich, Derive, additive repair that adds missing pages

Scripts

Script	Purpose	Use When
scripts/kb_inventory.py	Inventory layers, canonical material, risky paths, source surfaces, vault signals, and missing shared vault structure	Gate 1 for Audit, Existing Imperfect Repo, and every Migration
scripts/kb_lint.py	Check provenance, index freshness, schema/config drift, wikilinks, embeds, aliases, required files, and activity-log coverage	Gate 5 after any mutating batch and before declaring work complete
scripts/kb_bootstrap.py	Scaffold the approved layered structure, shared .obsidian/ surfaces, and default starter files	Create and additive repair after Gate 3 approval; never for cutover or overwrite-by-default

Run from the skill root:

• python3 scripts/kb_inventory.py --root .
• python3 scripts/kb_lint.py --root . --fail-on warning
• python3 scripts/kb_lint.py --root . --include-unlayered for mixed repos where important markdown still lives outside the default layers
• python3 scripts/kb_bootstrap.py --root ./knowledge-base --dry-run

Assets

Asset path	Use When
assets/kb-bootstrap-template.md	Manual starter packet for wiki/index.md, indexes/source-map.md, indexes/coverage.md, and activity/log.md when scripted scaffolding is not the right fit
assets/activity-log-template.md, assets/*-page-template.md	Optional activity-log and wiki-page starters during Create, Enrich, or additive repair; never overwrite existing user-authored files by template expansion without explicit approval

Examples

Example: Create a new KB for a topic

/nerdbot create "field guide to agentic knowledge bases"

Expected flow:

1. Load references/kb-architecture.md.
2. Choose the KB root and scaffold raw/, wiki/, schema/, config/, indexes/, and activity/.
3. Seed wiki/index.md, indexes/source-map.md, indexes/coverage.md, and activity/log.md with scripts/kb_bootstrap.py or the manual packet in assets/kb-bootstrap-template.md.
4. Record scope, constraints, and the first ingest queue before writing synthesized topic pages.

Example: Improve an existing KB in an arbitrary repo

/nerdbot improve ./client-repo

Expected flow:

1. Run scripts/kb_inventory.py first.
2. Identify canonical user-authored material, current source files, existing indexes, and risky paths.
3. Propose an Obsidian-native overhaul plan: add missing indexes/ and activity/, establish a safe raw/ intake area, normalize note metadata, introduce shared vault surfaces, and map existing docs into the wiki/ layer without destructive rewrites.
4. After approval, execute the smallest batch and run scripts/kb_lint.py, adding --include-unlayered when adjacent markdown still participates in the repo's knowledge graph.

Example: Query a maintained KB

/nerdbot query "What do we know about vendor pricing risk?"

Expected flow:

1. Load references/kb-architecture.md.
2. Read wiki/ and indexes/ first to locate the maintained synthesis and its coverage state.
3. Inspect raw/ only if a citation needs verification or the KB appears incomplete.
4. Return an answer with note paths, [[wikilinks]], provenance references, and an explicit confidence level.
5. If the KB is still partial or has a gap, recommend enrich or ingest as the next safe follow-up instead of mutating content during the query.

Example: Overhaul an existing repo into an Obsidian-native vault

/nerdbot improve ./client-repo turn this into an Obsidian vault before you expand it

Expected flow:

1. Run scripts/kb_inventory.py first and classify the repo's vault state.
2. Identify canonical material, current consumers, existing note names, aliases, embeds, and any .obsidian/ shared config.
3. Plan the smallest safe vault-overhaul batch: shared templates, metadata normalization, link normalization, path mapping, and attachment placement.
4. Require approval before any rename, move, or cutover.
5. Run scripts/kb_lint.py after each approved batch to verify [[wikilinks]], embeds, aliases, provenance, indexes, and the activity log.

Critical Rules

1. Inventory first: do not mutate an existing repo before mapping canonical material, layers, and risky paths.
2. Preserve user-authored canonical material unless the user explicitly authorizes rewrite, move, or deletion.
3. Prefer additive repair over migration, but default existing repos toward an Obsidian-native overhaul before deeper expansion or refinement.
4. Query is read-only by default; answer from the maintained KB unless the user explicitly asks for follow-on mutation.
5. Never synthesize wiki/ content without provenance to raw/ or declared canonical material.
6. Keep raw/ append-only; preserve originals and store normalization as separate artifacts, or use a provenance-rich pointer/stub for sources over 50 MB when vendoring the binary is impractical.
7. Prefer wiki/ + indexes/ before mining raw/; use raw/ to verify citations or confirm gaps, not to bypass missing synthesis.
8. Update related indexes/ and the activity log in the same batch as content or structure changes.
9. If the KB cannot answer confidently during query, state the gap and recommend enrich, ingest, or derive instead of mutating content in place.
10. Keep changes small and reviewable; split structural, content, and derived-output work into separate batches.
11. Treat derived outputs as rebuildable products, not canonical knowledge.
12. Use the migration interview + inversion before any rename, move, replace, or cutover.
13. When confirmation is unavailable, stop after inventory + plan for any high-impact operation.
14. If a referenced file or script is missing, follow this body and report the gap; do not invent nonexistent guidance or pretend checks passed.
15. Normalize existing repos toward Obsidian-native note metadata, [[wikilinks]], and shared vault conventions before expanding the wiki surface.
16. Manage .obsidian/ as a shared working surface only for project-safe templates, snippets, and documented conventions; do not rewrite volatile workspace state by default.
17. Use the default layered vocabulary exactly: raw, wiki, schema, config, indexes, activity log, provenance, canonical material, derived output, imperfect repo, migration, vault, shared vault config, Dataview metadata.