@stjbrown/agent-knowledge 0.1.0-beta.1

package/skills/kb/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: kb
+description: >-
+  Portable OKF knowledge bundle for coding-agent memory and LLM wikis. Use when the user wants to
+  start a wiki, ingest a source, query project knowledge with citations, lint for drift, or
+  visualize connections; whenever a repo has a knowledge/ bundle that should inform the task; and
+  when another kb-* skill needs the shared spec, glossary, templates, or trust model.
+version: 0.1.0
+tags: [knowledge, okf, bundle, hub]
+---
+
+# kb — bundles
+
+**Hub** for the `kb-*` family: vocabulary, shared reference, routing. Knowledge **compounds** —
+compiled once, kept current, not re-derived per query. Does not modify a bundle — routes to the
+skill that does.
+
+## Key terms
+
+[references/glossary.md](references/glossary.md) defines the vocabulary. Minimum before routing:
+**Bundle**, **Ingest**, **Progressive disclosure**, **Trust model** (see
+[trust-model.md](references/trust-model.md)).
+
+## The one hard rule
+
+A bundle is **conformant** iff every non-reserved `.md` file has parseable YAML frontmatter with a
+non-empty `type`. Everything else is soft guidance — consumers MUST tolerate missing optional fields,
+unknown types, and broken links. Never reject a bundle over them. Full rules:
+[references/SPEC.md](references/SPEC.md) §9.
+
+## Route to the right skill
+
+| The user wants to… | Use |
+|---|---|
+| Start a new bundle | [`kb-init`](../kb-init/SKILL.md) |
+| Capture, ingest, file, or process a source (note, transcript, PDF, image, URL) | [`kb-ingest`](../kb-ingest/SKILL.md) |
+| Ask what the bundle knows; look something up; explore connections | [`kb-query`](../kb-query/SKILL.md) |
+| Health-check the bundle (**drift**, orphans, contradictions, conformance) | [`kb-lint`](../kb-lint/SKILL.md) |
+| See the bundle as a graph | [`kb-visualize`](../kb-visualize/SKILL.md) |
+
+If a `knowledge/` bundle exists and would inform the current task, consult it via
+[`kb-query`](../kb-query/SKILL.md) before answering from scratch — even when the user didn't ask an
+explicit knowledge question.
+
+## Shared reference (single source of truth)
+
+Every `kb-*` skill reads these rather than restating them, so the family stays consistent:
+
+- [references/SPEC.md](references/SPEC.md) — OKF v0.1, vendored verbatim.
+- [references/glossary.md](references/glossary.md) — leading words and definitions.
+- [references/trust-model.md](references/trust-model.md) — the maintenance rules.
+- [templates/](templates/) — `concept.md`, `index.md`, `log.md` starters.
+- [example-bundle/](example-bundle/) — a tiny conformant bundle: a worked example, and the seed
+  `kb-init` copies from.

package/skills/kb/example-bundle/concepts/customers.md

@@ -0,0 +1,15 @@
+---
+type: customer
+title: Customers
+description: The people and organizations that place orders.
+tags: [sales]
+timestamp: 2026-01-01T00:00:00Z
+---
+
+Customers are the accounts that place [orders](orders.md). Each customer has a stable `customer_id`
+used as the join key from the orders concept.
+
+# Examples
+
+- `cust_001` — Acme Corp, enterprise account.
+- `cust_002` — Jane Diaz, individual.

package/skills/kb/example-bundle/concepts/orders.md

@@ -0,0 +1,19 @@
+---
+type: order
+title: Orders
+description: Purchases placed by customers.
+tags: [sales, revenue]
+timestamp: 2026-01-01T00:00:00Z
+---
+
+Orders are purchases placed by [customers](customers.md), joined on `customer_id`. Revenue is the
+sum of order totals across successful orders.
+
+# Schema
+
+| Field | Type | Description |
+|---|---|---|
+| `order_id` | string | Unique order identifier. |
+| `customer_id` | string | The [customer](customers.md) who placed the order. |
+| `total_usd` | number | Order total in US dollars. |
+| `status` | string | `success`, `pending`, or `refunded`. |

package/skills/kb/example-bundle/index.md

@@ -0,0 +1,20 @@
+---
+okf_version: "0.1"
+---
+
+# Example Knowledge Bundle
+
+A tiny, fully conformant OKF bundle — a worked example of the format and the seed `kb-init` copies
+when scaffolding a new bundle. Replace this content with your domain.
+
+## Spec
+
+How this bundle is organized (its schema layer — read this first when maintaining it).
+
+* [Concept Types](spec/types.md) - the `type` vocabulary this bundle uses.
+* [Conventions](spec/conventions.md) - folder taxonomy and ingest/maintenance conventions.
+
+## Concepts
+
+* [Customers](concepts/customers.md) - the people who place orders.
+* [Orders](concepts/orders.md) - what customers buy.

package/skills/kb/example-bundle/log.md

@@ -0,0 +1,6 @@
+# Log
+
+## 2026-01-01
+
+**Creation** — Seeded the example bundle: [types](spec/types.md), [conventions](spec/conventions.md),
+and the [customers](concepts/customers.md) and [orders](concepts/orders.md) concepts.

package/skills/kb/example-bundle/spec/conventions.md

@@ -0,0 +1,36 @@
+---
+type: Spec Section
+title: Conventions
+description: Folder taxonomy and ingest/maintenance conventions for this bundle.
+tags: [schema, meta]
+timestamp: 2026-01-01T00:00:00Z
+---
+
+# Conventions
+
+How this bundle is structured and maintained. The `kb-*` skills read this to fit themselves to the
+domain.
+
+## Folder taxonomy
+
+- `concepts/` — the domain entities (`customer`, `order`).
+- `spec/` — this schema layer ([types](types.md) + conventions).
+- `references/` — mirrored external sources as `type: Reference` concepts (none yet).
+
+## Naming
+
+Lowercase, underscores for multi-word filenames. A concept's filename is its identity; keep it
+stable (supersede rather than rename when meaning changes).
+
+## Ingest routing
+
+When ingesting a source, extract entities and route them: people → `concepts/` as `customer`;
+purchases → `concepts/` as `order`; the source document itself → `references/` as `Reference`, cited
+by whatever it supports.
+
+## Maintenance
+
+Follow the trust model (see the `kb` skill's `references/trust-model.md`): append-only on meaning,
+supersede with provenance, `conflicts_with` over silent overwrite, events additive, every change
+logged. Keep each directory's `index.md` current; regenerate any `_overview` after its children
+change.

package/skills/kb/example-bundle/spec/types.md

@@ -0,0 +1,23 @@
+---
+type: Spec Section
+title: Concept Types
+description: The type vocabulary this bundle uses.
+tags: [schema, meta]
+timestamp: 2026-01-01T00:00:00Z
+---
+
+# Concept Types
+
+The `type` values used by concepts in this bundle. OKF requires only that `type` be non-empty; this
+list is *this bundle's* convention, so the `kb-*` skills route consistently. Extend it as the domain
+grows.
+
+| type | Meaning | Lives in |
+|---|---|---|
+| `Spec Section` | A rule about how this bundle is organized (like this file). | `spec/` |
+| `customer` | A person or org that places orders. | `concepts/` |
+| `order` | A purchase made by a customer. | `concepts/` |
+| `Reference` | A mirror of external source material (points at it via `resource`). | `references/` |
+
+Replace these with your own domain's entities (e.g. `person`, `deal`, `metric`, `character`,
+`chapter`).

package/skills/kb/references/SPEC.md

@@ -0,0 +1,451 @@
+# Open Knowledge Format (OKF)
+
+**Version 0.1 — Draft**
+
+OKF is an open, human- and agent-friendly format for representing
+*knowledge* — the metadata, context, and curated insight that surrounds
+data and systems. It is designed to be authored by people, generated by
+agents, exchanged across organizations, and consumed by both.
+
+The format is intentionally minimal: a directory of markdown files with
+YAML frontmatter. There is no schema registry, no central authority, and
+no required tooling. If you can `cat` a file, you can read OKF; if you
+can `git clone` a repo, you can ship it.
+
+---
+
+## 1. Motivation
+
+The space of knowledge representation for AI agents is evolving quickly,
+and many incompatible conventions are emerging. OKF takes the position
+that knowledge is best represented in commonly accessible, established
+formats that are:
+
+- **Readable** by humans without tooling.
+- **Parseable** by agents without bespoke SDKs.
+- **Diffable** in version control.
+- **Portable** across tools, organizations, and time.
+
+The format is minimally opinionated. It standardizes only the small set
+of structural conventions needed to make a knowledge corpus
+*self-describing* — anything beyond that is left to the producer.
+
+### Goals
+
+1. Define a universal format that **enrichment agents** can write into.
+2. Inform how **consumption agents** should read and traverse it.
+3. Facilitate **exchange** of knowledge across systems and organizations.
+4. Standardize the small number of **required** fields that must be
+   present for content to be meaningfully consumed.
+
+### Non-goals
+
+- Defining a fixed taxonomy of concept types.
+- Prescribing storage, serving, or query infrastructure.
+- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
+  OKF *references* them; it does not subsume them.
+
+---
+
+## 2. Terminology
+
+- **Knowledge Bundle** — A self-contained, hierarchical collection of
+  knowledge documents. The unit of distribution.
+- **Concept** — A single unit of knowledge within a bundle. Represented
+  as one markdown document. May describe a tangible asset (a table, an
+  API), an abstract idea (a metric, a business process), or anything in
+  between.
+- **Concept ID** — The path of the concept's file within the bundle,
+  with the `.md` suffix removed. For example, `tables/users.md` has
+  concept ID `tables/users`.
+- **Frontmatter** — YAML metadata block delimited by `---` at the top of
+  a markdown file.
+- **Body** — Everything in the file after the frontmatter.
+- **Link** — A standard markdown link from one concept to another, used
+  to express relationships beyond the implicit parent/child hierarchy.
+- **Citation** — A link from a concept to an external source that
+  supports a claim in the body.
+
+---
+
+## 3. Bundle Structure
+
+A bundle is a directory tree of markdown files. The directory structure
+is independent of the domain — producers organize concepts however makes
+sense for the knowledge being captured.
+
+```
+path/to/bundle/
+├── index.md                      # Optional. Directory listing for progressive disclosure.
+├── log.md                        # Optional. Chronological history of updates.
+├── <concept>.md                  # A concept at the bundle root.
+└── <subdirectory>/               # Subdirectories organize concepts into groups.
+    ├── index.md
+    ├── <concept>.md
+    └── <subdirectory>/
+        └── …
+```
+
+A bundle MAY be distributed as:
+
+- A git repository (recommended — provides history, attribution, diffs).
+- A tarball or zip archive of the directory.
+- A subdirectory within a larger repository.
+
+### 3.1 Reserved filenames
+
+The following filenames have defined meaning at any level of the
+hierarchy and MUST NOT be used for concept documents:
+
+| Filename     | Purpose                                                |
+|--------------|--------------------------------------------------------|
+| `index.md`   | Directory listing. See §6.                             |
+| `log.md`     | Update history. See §7.                                |
+
+All other `.md` files are concept documents.
+
+Tags themselves remain a first-class concept — see the `tags`
+frontmatter field in §4.1. OKF does not specify a separate file format
+for aggregating documents by tag; producers that want a tag-browsing
+view can synthesize one at consumption time by scanning frontmatter.
+
+---
+
+## 4. Concept Documents
+
+Every concept is a UTF-8 markdown file. It has two parts:
+
+1. A **YAML frontmatter block**, delimited by `---` on its own line at
+   the start of the file and a closing `---` on its own line.
+2. A **markdown body**, containing free-form content.
+
+### 4.1 Frontmatter
+
+```yaml
+---
+type: <Type name>                  # REQUIRED
+title: <Optional display name>
+description: <Optional one-line summary>
+resource: <Optional canonical URI for the underlying asset>
+tags: [<tag>, <tag>, …]            # Optional
+timestamp: <ISO 8601 datetime>     # Optional last-modified time
+# … other producer-defined key/value pairs
+---
+```
+
+**Required:**
+
+- `type` — A short string identifying the kind of concept. Consumers
+  use this for routing, filtering, and presentation. Example values:
+  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
+  `Playbook`, `Reference`.
+
+  Type values are **not** registered centrally. Producers SHOULD pick
+  values that are descriptive and self-explanatory; consumers MUST
+  tolerate unknown types gracefully (typically by treating them as
+  generic concepts).
+
+**Recommended (in priority order):**
+
+- `title` — Human-readable display name. If omitted, consumers MAY
+  derive a title from the filename.
+- `description` — A single sentence summarizing the concept. Used by
+  `index.md` generators, search snippets, and previews.
+- `resource` — A URI that uniquely identifies the underlying asset the
+  concept describes. Absent for concepts that describe abstract ideas
+  rather than physical resources.
+- `tags` — A YAML list of short strings for cross-cutting categorization.
+- `timestamp` — ISO 8601 datetime of last meaningful change.
+
+**Extensions:** Producers MAY include any additional keys. Consumers
+SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
+documents with unrecognized fields.
+
+### 4.2 Body
+
+The body is standard markdown. Producers SHOULD favor structural
+markdown — headings, lists, tables, fenced code blocks — over freeform
+prose, since structure aids both human reading and agent retrieval.
+
+There are no required body sections. The following section headings have
+**conventional** meaning and SHOULD be used when applicable:
+
+| Heading        | Purpose                                                |
+|----------------|--------------------------------------------------------|
+| `# Schema`     | Structured description of an asset's columns/fields.   |
+| `# Examples`   | Concrete usage examples, often as fenced code blocks.  |
+| `# Citations`  | External sources backing claims in the body. See §8.   |
+
+### 4.3 Example: a concept bound to a resource
+
+```markdown
+---
+type: BigQuery Table
+title: Customer Orders
+description: One row per completed customer order across all channels.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders, revenue]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                              |
+|---------------|-----------|------------------------------------------|
+| `order_id`    | STRING    | Globally unique order identifier.        |
+| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in US dollars.               |
+| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |
+
+# Joins
+
+Joined with [customers](/tables/customers.md) on `customer_id`.
+
+# Citations
+
+[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
+```
+
+### 4.4 Example: a concept not bound to a resource
+
+```markdown
+---
+type: Playbook
+title: Incident response — data freshness alert
+description: Steps to triage a freshness alert on the orders pipeline.
+tags: [oncall, incident]
+timestamp: 2026-04-12T09:00:00Z
+---
+
+# Trigger
+
+A freshness alert fires when `orders` lags more than 30 minutes behind
+its expected SLA. See the [orders table](/tables/orders.md).
+
+# Steps
+
+1. Check the [ingestion job dashboard](https://example.com/dash).
+2. …
+```
+
+---
+
+## 5. Cross-linking
+
+Concepts MAY link to other concepts using standard markdown links. Two
+forms are supported:
+
+### 5.1 Absolute (bundle-relative) links
+
+Begin with `/`, interpreted relative to the bundle root.
+
+```markdown
+See the [customers table](/tables/customers.md) for the join key.
+```
+
+This is the **recommended** form because it is stable when documents are
+moved within their subdirectory.
+
+### 5.2 Relative links
+
+Standard markdown relative paths.
+
+```markdown
+See the [neighboring concept](./other.md).
+```
+
+### 5.3 Link semantics
+
+A link from concept A to concept B asserts a *relationship*. The
+specific kind of relationship (parent/child, references, joins-with,
+depends-on, etc.) is conveyed by the surrounding prose, not by the link
+itself. Consumers that build a graph view typically treat all links as
+directed edges of an untyped relationship.
+
+Consumers MUST tolerate broken links — a link whose target does not
+exist in the bundle is not malformed; it may simply represent
+not-yet-written knowledge.
+
+---
+
+## 6. Index Files
+
+An `index.md` file MAY appear in any directory, including the bundle
+root. It enumerates the directory's contents to support **progressive
+disclosure** — letting a human or agent see what is available before
+opening individual documents.
+
+Index files contain no frontmatter. The body uses one or more sections,
+each grouping concepts under a heading:
+
+```markdown
+# Section / Group Heading
+
+* [Title 1](relative-url-1) - short description of item 1
+* [Title 2](relative-url-2) - short description of item 2
+
+# Another Section
+
+* [Subdirectory](subdir/) - short description of the subdirectory
+```
+
+Entries SHOULD include the description from the linked concept's
+frontmatter. Producers MAY generate `index.md` automatically; consumers
+MAY synthesize one on the fly when none is present.
+
+---
+
+## 7. Log Files (optional)
+
+A `log.md` file MAY appear at any level of the hierarchy to record the
+history of changes to that scope. The format is a flat list of
+date-grouped entries, newest first:
+
+```markdown
+# Directory Update Log
+
+## 2026-05-22
+* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
+* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
+
+## 2026-05-15
+* **Initialization**: Created foundational directory structure.
+* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
+```
+
+Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
+prose; the leading bold word (`**Update**`, `**Creation**`,
+`**Deprecation**`, etc.) is a convention, not a requirement.
+
+---
+
+## 8. Citations
+
+When a concept's body makes claims sourced from external material,
+those sources SHOULD be listed under a `# Citations` heading at the
+bottom of the document, numbered:
+
+```markdown
+# Citations
+
+[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
+[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
+```
+
+Citation links MAY be absolute URLs, bundle-relative paths, or paths
+into a `references/` subdirectory that mirrors external material as
+first-class OKF concepts.
+
+---
+
+## 9. Conformance
+
+A bundle is **conformant** with OKF v0.1 if:
+
+1. Every non-reserved `.md` file in the tree contains a parseable YAML
+   frontmatter block.
+2. Every frontmatter block contains a non-empty `type` field.
+3. Every reserved filename (`index.md`, `log.md`) follows the structure
+   described in §6 and §7 respectively when present.
+
+Consumers SHOULD treat all other constraints as soft guidance. In
+particular, consumers MUST NOT reject a bundle because of:
+
+- Missing optional frontmatter fields.
+- Unknown `type` values.
+- Unknown additional frontmatter keys.
+- Broken cross-links.
+- Missing `index.md` files.
+
+This permissive consumption model is intentional: OKF is meant to
+remain useful as bundles grow, get refactored, and are partially
+generated by agents.
+
+---
+
+## 10. Relationship to other formats
+
+OKF is intentionally close to several established patterns:
+
+- **LLM "wiki" repositories** that use markdown + frontmatter as
+  agent-readable knowledge bases.
+- **Personal knowledge tools** like Obsidian and Notion, which use
+  hierarchical markdown with cross-links.
+- **"Metadata as code"** approaches that store catalog metadata
+  alongside source code rather than in a separate registry.
+
+OKF differs primarily in being **specified** — pinning down the small
+set of rules needed for interoperability without dictating tooling.
+
+---
+
+## 11. Versioning
+
+This document specifies OKF version **0.1**. Future revisions will be
+versioned in the form `<major>.<minor>`:
+
+- A **minor** version bump introduces backward-compatible additions
+  (new optional fields, new conventional section headings).
+- A **major** version bump may make breaking changes (renaming required
+  fields, changing reserved filenames).
+
+Bundles MAY declare the OKF version they target by including
+`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
+only place frontmatter is permitted in an `index.md`). Consumers that
+do not understand the declared version SHOULD attempt best-effort
+consumption rather than refusing the bundle.
+
+---
+
+## Appendix A — Minimal example bundle
+
+```
+my_bundle/
+├── index.md
+├── datasets/
+│   ├── index.md
+│   └── sales.md
+└── tables/
+    ├── index.md
+    ├── orders.md
+    └── customers.md
+```
+
+`datasets/sales.md`:
+
+```markdown
+---
+type: BigQuery Dataset
+title: Sales
+description: All sales-related tables for the retail business.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
+tags: [sales]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+The sales dataset contains transactional tables, including
+[orders](/tables/orders.md) and [customers](/tables/customers.md).
+```
+
+`tables/orders.md`:
+
+```markdown
+---
+type: BigQuery Table
+title: Orders
+description: One row per completed customer order.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                  |
+|---------------|-----------|------------------------------|
+| `order_id`    | STRING    | Unique order identifier.     |
+| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in USD.          |
+
+Part of the [sales dataset](/datasets/sales.md).
+```

package/skills/kb/references/glossary.md

@@ -0,0 +1,61 @@
+# Glossary
+
+The vocabulary of the `kb-*` skills and OKF. Terms are **leading words** — reused verbatim across
+skills, prompts, and a bundle's own concept names so the shared language makes both execution and
+invocation reliable.
+
+## Structure
+
+- **Bundle (knowledge bundle)** — a directory tree of markdown concepts, the unit of production and
+  exchange. OKF's own term for the `knowledge/` package. May be shipped as a git repo, an archive,
+  or a subdirectory of a larger repo. A project MAY contain several bundles under one `knowledge/`
+  folder, each self-contained, with a top-level `knowledge/index.md` cataloging them.
+- **Concept** — one markdown file: one idea, entity, asset, or claim. Has a YAML frontmatter block
+  and a markdown body.
+- **Concept ID** — a concept's path within the bundle with `.md` removed (`people/jane.md` →
+  `people/jane`). How concepts are referenced.
+- **Reserved files** — `index.md` (directory listing) and `log.md` (change history). Not concepts;
+  carry no frontmatter (except the root `index.md`, which may declare `okf_version`).
+- **Schema layer** — the bundle's domain rules: its `type` vocabulary, folder taxonomy, naming, and
+  ingest routing conventions. Lives in `spec/` (as OKF concepts) so generic `kb-*` skills read it and
+  fit any domain. What [kb-init](../../kb-init/SKILL.md) writes; what makes a bundle portable.
+
+## Frontmatter
+
+- **type** *(required)* — a short, producer-chosen string naming the kind of concept (e.g. `person`,
+  `deal`, `metric`, `Reference`). The only required field.
+- **Recommended** — `title`, `description`, `resource` (a canonical URI, for concepts bound to a real
+  asset), `tags`, `timestamp` (ISO 8601).
+- **Extension keys** — any additional keys are allowed and preserved. The trust model uses
+  `status`, `supersedes`, `superseded_by`, `conflicts_with`.
+
+## Content types
+
+- **Reference** — a concept (`type: Reference`) that mirrors external **source** material and points
+  at it via `resource`, keeping the source *in* the bundle. Distinct from synthesis: a Reference is
+  a faithful pointer + extract, not our opinion.
+- **Synthesis** — a concept that is *our* analysis, comparison, or roll-up. It cites references; it
+  is not one.
+- **Overview** — a synthesized roll-up of a section, regenerated from its child concepts.
+
+## Navigation
+
+- **Progressive disclosure** — read `index.md` first, follow section indexes, then follow
+  cross-links only into relevant concepts. Scales to hundreds of concepts with no embeddings; add a
+  search tool only when a bundle outgrows it.
+- **Cross-link** — a standard markdown link from one concept to another; a directed, untyped edge
+  whose meaning is carried by the surrounding prose. Prefer **relative** links (they render
+  everywhere, including GitHub, when the bundle is nested).
+- **Compounding** — the property that makes the effort worthwhile: every ingested source and every
+  filed-back answer makes the bundle richer, rather than being re-derived per query.
+
+## Maintenance (trust model)
+
+- **Ingest** — read a raw source, extract its signal, and integrate it across the bundle.
+- **Supersede** — replace a claim by writing a *new* concept and marking the old one
+  `status: superseded` with `superseded_by`, keeping it on disk for history. Never rewrite a claim
+  in place.
+- **Conflict** — when new information merely disagrees, link the two with `conflicts_with` and keep
+  both active; do not silently pick a winner.
+- **Drift** — the decay a compounding bundle accumulates (stale claims, orphans, contradictions,
+  missing links). What [kb-lint](../../kb-lint/SKILL.md) fights.