Core concepts

The knowledge base

The knowledge base is a structured, verified representation of what your product actually does. It's not documentation someone wrote — it's extracted from the source code, grounded in file:line references, and updated when the code changes.

Domains and features

Your product is organized into domains (business areas like "Banking", "Authentication", "Billing") and features within each domain (like "Credit cards", "Two-factor auth", "Invoicing"). This hierarchy is the taxonomy — proposed during discovery, approved by a human.

Claims and trust

A claim is a single statement about product behavior: "The daily repayment cron runs at 20:00 UTC" or "A returned payment incurs a $40 fee." Every claim has a trust status:

• Verified — a passing test exercises this behavior. The claim is grounded in both code AND tests.
• Asserted — extracted from code, but no test covers it. The claim is likely true but unproven.
• Drifted — was verified, but the linked test no longer passes or the code changed. The claim may be stale.

Trust is the product's core signal. A feature with 90% verified claims is well-tested. A feature with 80% asserted claims needs test coverage.

Mechanical facts

Facts are deterministic, non-LLM data extracted directly from the code:

• Entities — database tables with column details
• Routes — HTTP endpoints with auth requirements
• Routines — scheduled jobs with cron expressions
• Parameters — constants and configuration values
• Flags — feature flags with providers and gate sites
• Events — analytics tracking calls with providers and properties
• Experiments — A/B tests with variants and metrics
• Security — static analysis findings (OWASP-mapped)

Facts are always correct by construction — they're pattern-matched from the source, not LLM-generated.

The guide

Each scanned feature gets a guide — a comprehensive document generated from the claims and facts. The guide includes:

• Narrative — what the feature is in business terms
• Design principles — cross-cutting invariants
• Lifecycle — end-to-end state flow
• Business risks — operational risk assessment
• Vendor dependencies — external service exposure
• User journey — the end-user experience as a story
• Known limitations — tech debt and deferred work
• Compliance flags — PII, financial data, and regulatory surface
• Data model — tables with column-level detail
• Route map — all HTTP endpoints
• Scheduled jobs — background processes
• Feature flags — behavioral gates
• Event tracking — analytics events and coverage gaps
• E2E test plan — test scenarios with steps and expected results
• Glossary — domain terminology

The pipeline

Discovery

Analyzes the codebase structure (routes, navigation, schemas, modules, guards) to propose a taxonomy. Fast, cheap, no LLM extraction. The result is a set of proposed domains and features for human review.

Approval

The human trust gate. A proposed taxonomy is reviewed in the web app. Accepting a feature materializes it — creates the Feature and Domain rows the scanner reads. Rejecting records the decision so re-discovery doesn't re-propose it.

Scan

Deep-reads one feature's code: extracts claims, synthesizes an overview, collects mechanical facts, and (optionally) generates a guide with deep-dive chapters, front matter, and structural references. The expensive step.

Re-scan

When the code changes, re-scanning updates the knowledge base. The pipeline is incremental: unchanged files are hash-skipped, the extraction cache serves repeated content, and only modified claims are re-linked.

Spec changes

A spec change is a pending product modification — something the knowledge base says should change. Sources:

• Linear ticket — drafted from the AI chat when a user discusses changing product behavior
• Scan-detected drift — the code changed but the KB hasn't been updated
• GitHub PR — a PR that modifies files covered by the KB

Spec changes flow through: open → implementing → resolved or dismissed.

Trust and verification

Kanon never auto-publishes. Every piece of the pipeline has a human gate:

• Discovery produces proposals for review
• The guide carries trust badges (verified/asserted/drifted)
• AI chat answers cite their sources — an uncited sentence is visibly weaker
• Linear tickets are drafts the user edits and approves
• Spec changes must be explicitly resolved