Lore — knowledge scrolls injected on demand

Lore is the curated knowledge layer of Korva. Markdown scrolls auto-load when their triggers (file globs, keywords, task phrases) match the AI session. Twenty-five scrolls ship with the v1.0 release.

Updated: 2026-04-30

Lore is the curated knowledge layer of Korva. Each “scroll” is a self-contained Markdown file that gets injected into the AI session when its triggers match the file the developer just opened, the keywords in the prompt, or the type of task being performed.

The result: when you open src/payments/checkout.ts, your AI already knows about Stripe idempotency, PCI compliance and decimal-math precision — without you typing a single word.

Anatomy of a scroll

Every scroll has a YAML frontmatter:

---
id: nestjs-hexagonal           # kebab-case, must match the directory name
version: 1.2.0                 # semver — bump when behaviour changes
team: backend                  # backend | frontend | devops | qa | security | all
stack: NestJS, TypeScript, Hexagonal Architecture
last_updated: 2026-04-30       # ISO date
---

…three trigger axes (any match wins):

files — globs (*.ts, *.config.ts, Dockerfile)
keywords — terms found in the prompt or snippet (5–12 typical)
tasks — imperative phrases (“creating a controller”, “writing tests”)

…and a fixed body structure:

Context (2–4 sentences) — why this matters, the production risks
Rules (5–10 rules) — each with executable code and realistic domain names
Anti-patterns (3–5 pairs) — ❌ BAD with explanation + ✅ GOOD with the fix

Token budgets

Scrolls have hard caps so they never blow up the AI context window:

Tier	Cap	When loaded
Hot path	< 1,500 tokens	Every session that triggers it
Common	< 4,000 tokens	When triggered by file/keyword
Reference	< 8,000 tokens	Only on explicit request

Most scrolls are in the Common tier.

The 25 curated scrolls (v1.0)

ID	Team	Stack
`forge-sdd`	all	The 5-phase Spec-Driven Development workflow itself
`skill-authoring`	all	How to write scrolls that score well at trigger time
`claude-api`	all	Anthropic SDK — caching, streaming, tool use, batch
`mcp-builder`	all	Building MCP servers — naming, schemas, errors
`security-patterns`	backend	bcrypt, JWT, timing-safe, RBAC, rate limiting
`token-efficiency`	all	Read-before-write, edit-over-rewrite, context budget
`nestjs-hexagonal`	backend	Ports, adapters, domain/application/infrastructure
`nestjs-bff`	backend	BFF pattern, stateless, circuits to external APIs
`error-handling`	backend	Go errors, Result types, HTTP error mapping
`testing-jest`	backend	AAA, port mocks, fixtures, coverage
`typescript`	backend	Branded types, discriminated unions, type guards
`payments-stripe`	backend	Webhook idempotency, PCI compliance, dedup
`api-design`	backend	REST: versioning, pagination, envelopes, OpenAPI
`cloud-sync`	backend	Chunk dedup, idempotency, outbox, conflict resolution
`sqlite-concurrency`	backend	Write-queue, busy_timeout, “database is locked”
`release-engineering`	devops	Conventional commits, semver, release-please
`observability`	backend	OpenTelemetry: logs, metrics, traces
`docker-k8s`	devops	Resource limits, probes, secret management
`gitlab-ci`	devops	Multi-stage builds, Vault integration, Harbor
`nx-monorepo`	backend	Scoped libs, import paths, caching, generators
`playwright-e2e`	qa	Page objects, visual regression, integration
`plugin-architecture`	backend	Registries, manifest versioning, sandboxing
`frontend-design`	frontend	UI patterns, theming, animation, dark mode
`react-nextjs`	frontend	React 19, Next 15, App Router, server components
`angular-wc`	frontend	Angular 20, Signals, Web Components, OnPush

Lore Community bridge

Beyond the 25 curated scrolls, lore/community/autoskills/SCROLL.md is a registry-bridge that maps 60+ technologies to community skills hosted on skills.sh — React, Next.js, Vue, Nuxt, Angular, Astro, Node.js, Go, Python, FastAPI, Django, Rails, Prisma, Stripe, Clerk, Vercel, Cloudflare, Playwright and more. Combined with your private team scrolls, this gives every project an authoritative knowledge base out of the box.

Lifecycle of a scroll inside an AI session

The AI assistant boots and calls vault_context with project, prompt and file_paths.
The Vault matches triggers across active scrolls (curated under ~/.korva/lore/curated/ and team scrolls under lore/private/).
The matching scrolls are returned as auto_skills inline with the response.
The AI consumes them silently as authoritative guidance.
The developer experiences the AI “already knowing” the team’s rules.

Writing your own scroll

The fastest path is korva lore add (interactive) or copy lore/SCROLL_TEMPLATE.md, fill in the frontmatter, and drop the file in lore/private/<id>/SCROLL.md. See skill-authoring for the canonical example.

Forge SDD — how scrolls are loaded between phases
Teams admin — distributing private scrolls to your team