Knowledge Base

Use scripts/knowledge-base first. It is a short alias for the underlying knowledge-base-cli launcher.

Platform Support

• scripts/knowledge-base is the preferred launcher script.
• scripts/knowledge-base-cli is the underlying launcher script.
• Prebuilt binaries are expected in scripts/bin/ for:
  • macOS arm64
  • Linux x86_64
  • Windows x86_64
• If no compatible binary exists and the full source repo is present with Go installed, the launcher falls back to go run.

Setup

Read Setup Guide.

Command Contract

Global flags:

• --project-root <path> default cwd
• --corpus <name> optional
• --format <json|text> default json
• --output <path> optional

Commands:

• index build
• index status
• search --query "<text>" --limit <n>
• show --id <value>
• show --path <path>
• corpora list
• config validate

Fast Path

Use this order for normal discovery:

1. search
2. show on the best one or two hits
3. open source markdown only after the CLI narrows the target

Do not run config validate or index status first unless the task is explicitly about setup or freshness.

Guardrails

• Prefer --format json for machine parsing.
• Do not treat the index as source of truth.
• If search or index status returns stale: true, rebuild before relying on fresh edits.
• After editing knowledge-base markdown, run the repo’s KB validator first if one exists, then run index build.
• Prefer this CLI over broad rg scans when the corpus is configured and the task is discovery.
• If search fails with config or index errors, then run config validate or index build as needed.
• Keep query rewrites tight. Try at most 3 compact variants before giving up.

Querying

• Start with the user’s topic as a short noun phrase.
• For broad architecture questions, prefer repo-native terms over full sentences.
• Good rewrites:
  • multitenancy -> tenant, multitenancy, tenant context, schema tenant
  • caching -> cache, cache invalidation, tenant cache
  • basket API -> basket architecture, basket api, basket mutations

When To Preflight

• Run index status only when freshness matters or after KB edits.
• Run config validate only when setup is failing or the CLI returns config errors.
• Run index build only when the index is missing, stale, or you changed KB files.

Command Patterns

Search first:

scripts/knowledge-base --project-root /path/to/repo search --query "basket architecture" --limit 5

Show the best hit:

scripts/knowledge-base --project-root /path/to/repo show --id docs-basket-index

Check freshness only when needed:

scripts/knowledge-base --project-root /path/to/repo index status

Validate setup only on failure:

scripts/knowledge-base --project-root /path/to/repo config validate

Rebuild the index:

scripts/knowledge-base --project-root /path/to/repo index build