# Architecture

> [!NOTE]
> This page is for anyone deciding whether to install the skills it describes. A shorter version, for readers aged 13 to 18, is in [architecture.en-simple.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/simple/).

Knowledge Trust Ladder (KTL) is an architecture inspired by [LOKF](https://lokf.nolan-nichols.com/specification/), by [LinkML](https://linkml.io/linkml/) and by this poem:

> "We lasso the world with networks of silver-coloured Italian hemp,\
> We bind down the world into some sort of order;\
> We balance the earth in a pair of scales of our own devising."\
> — Amy Lowell, *The Congressional Library* (1922)

KTL keeps any repository's scattered knowledge as a **collection**: catalogued, authenticated and explained, with the trust in every claim left visible. Four Agent Skills build and keep it. Registrar automation checks every record and guards every confirmation, in continuous integration (CI) on each pull request, as a museum's registrar keeps its collection's records. A toolkit underneath supplies schema and tooling. Two Obsidian plugins are optional, for a vault with no CI.

**An agent derives it. Deterministic tools check it. A named person vouches for it. The bundle records which of the three happened to every claim.**

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/knowledge-trust-ladder-card-dark.svg">
    <img src="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/knowledge-trust-ladder-card.svg" alt="Knowledge Trust Ladder: raw sources become a knowledge bundle, kept by five roles: sidecar, librarian, registrar, curator and docent" width="720" />
  </picture>
</p>

## Why libraries have catalogues

Knowledge already exists: in code, documents, diagrams, policies, operational records. What's missing is a [**context layer**](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/context-layer/): a governed layer between those sources and whoever consumes them, that persists from one task to the next. Without it every task starts the same way: find the material, connect it, judge what's still true. The next person or assistant does that work again.

A **knowledge bundle** is the catalogue: a plain folder of Markdown concept files that keeps the work instead of discarding it. It is useful only when a reader can tell which entries are sound, and that depends on one question: *who is responsible for the quality of this context?* The trust ladder is the answer, written into each entry: where the entry came from and how far it has been checked, in [plain words](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/architecture/#trust-stays-visible). One bundle is one repository's context layer, and [context-layer.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/context-layer/) says how several bundles become one catalogue.

## Prose, Structure, Meaning, Context

A bundle is prose a person reads, structure a schema checks, meaning a graph can query, and context the next task can start from. It is written in **[LOKF](https://pypi.org/project/lokf/)** (Linked Open Knowledge Format), [a semantic profile of OKF](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) whose [specification](https://lokf.nolan-nichols.com/specification/) is [a single LinkML schema](https://github.com/nicholsn/lokf/blob/v0.9.0/lokf.yaml). People, agents and any tool that speaks OKF, JSON Schema, JSON-LD, SHACL or [another supported format](https://linkml.io/linkml/generators/index.html) can read it.

**KTL is an OKF runtime.** OKF sets out to "standardize the small set of frontmatter fields that make an agent-maintained corpus **trustable**, without prescribing any runtime". In KTL those fields are the rungs a claim climbs and the gate that refuses a `human:` confirmation no person can be tied to. LOKF supplies "a fixed taxonomy of concept types", which OKF leaves to the producer. A domain whose concepts stop fitting it [extends the schema](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-curator/references/domain-schemas.md), so its own types are checked rather than tolerated. Whoever uses a claim as context, person or agent, also reads how far it has been checked, whether from one bundle or from [many federated into one layer](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/context-layer/#many-bundles-federated-into-one-context-layer-the-design).

## Four skills, three lines of the poem

| Skill | Role | Runs |
| --- | --- | --- |
| [`ktl-sidecar`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-sidecar/SKILL.md) | **Sidecar**, *lays the network*. Installs the sidecar from bundled templates: `.lokf/`, a dot-folder beside the code like `.git/`, kept out of the project's build. It holds tooling, docs, a dummy skeleton at `.lokf/knowledge/`, and a `knowledge_bundle` link for folder pickers that hide dot-folders. Repairs a broken sidecar file. Its [portability page](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-sidecar/references/portability.md) covers Windows, macOS, other forges, no git and synced folders. | once |
| [`ktl-librarian`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-librarian/SKILL.md) | **Librarian**, *binds it into order*. Scrapes the repository, derives concepts with their sources, classifies them, links them with typed relationships, audits, and hands off for review. Like a real librarian it catalogues without vouching: *facts about the repository*, never verdicts about truth. | often, including on a schedule |
| [`ktl-curator`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-curator/SKILL.md) | **Curator**, *holds the scales*. A person's assistant. It shows what needs a look, puts the source next to the claim, and records the verdict (confirm, correct, retire, send back) in the bundle's own frontmatter. *Judgements a person made*, never facts it derived. | a little, regularly |
| [`ktl-docent`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-docent/SKILL.md) ([examples](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/examples/docent/)) | **Docent**, *guides the visitors*, the role the poem leaves implicit, because the collection exists for them. Answers from the bundle and labels how far each concept has been trusted. Checks exact values at the source. When the bundle has no answer it explores the repository and records the miss, which becomes the librarian's next task. Like a real docent it explains the exhibition without moving anything on the shelves: read-only on the bundle. | whenever anyone asks |

**Curator** is the museum sense, the one who authenticates, weighs provenance and decides what goes on exhibit. It is not the data-management sense, which is the **librarian**'s job. The curator is always a person, and the skill and the plugin that carry the name reach no verdict of their own.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/ktl-review-session-dark.svg">
    <img src="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/ktl-review-session.svg" alt="The curator's review session: one concept, one verb, one person's answer, written into the concept's own frontmatter" width="720" />
  </picture>
</p>

On a fresh repository they run in order: **sidecar**, then **librarian** filling the bundle with drafts, then **curator**, where a person turns drafts into confirmed knowledge. After that it is a loop: the **librarian** refreshes on a schedule, readers report what the bundle missed, and the **curator** reviews what is new or changed.

### The fifth role, which is not a skill

The **registrar** keeps the records in order: each accession (an item added to the collection) documented, its provenance filed, nothing entered in a form the catalogue can't read. No human has to do this: the `lokf` toolkit checks every change, and CI's [`knowledge-registrar.yaml`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/.github/workflows/knowledge-registrar.yaml) checks every pull request that touches the bundle. It also ties each confirmation that is added or removed to the confirming person's approval or signed commit.

At the librarian's [desk](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/glossary/desk/) the registrar is `knowledge-apply.sh`, *the pen*, the only way the librarian writes the bundle, and it refuses a change that would fake or remove a confirmation ([who writes the bundle](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/for-the-curious/#who-writes-the-bundle-and-what-checks-it)). At the reader's desk and the curator's it is `knowledge-report.sh`, which computes each trust label and the bundle's health line, so that neither is a model's arithmetic. These are the deterministic tools of the summary at the top of this page: a check gives the same answer every time, which neither the librarian nor the curator can promise.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/ktl-architecture-dark.svg">
    <img src="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/ktl-architecture.svg" alt="Who writes the bundle and what checks it: the librarian writes only patch.yaml, which the pen, knowledge-apply.sh, applies to the bundle; the curator writes a verified event in that person's name through ktl-curator or the plugin; the docent writes nothing there, and knowledge-feedback.sh records a reader's miss. Below, the registrar's gate checks each pull request, and knowledge-report.sh computes every trust label on each read" width="720" />
  </picture>
</p>

***As a flow diagram, drawn with Archify: [light](https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/companions/ktl-architecture.svg), [dark](https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/companions/ktl-architecture-dark.svg).***

In [Obsidian](https://obsidian.md/) there is no CI, so two optional plugins work inside the editor. [KTL Registrar](https://w3id.org/ktl/registrar/) does the registrar's work, checking each record as it is typed. [KTL Curator](https://w3id.org/ktl/curator/) is the curator's assistant, and runs this repository's `ktl-curator` review session with no agent in the loop ([The bundle in Obsidian](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/obsidian/)).

In the **three lines of defence** that regulated industries use, the librarian and the curator are the first line, the registrar the second, and the bundle holds the evidence a third line would need ([three-lines.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/three-lines/)).

### The fifth skill, which is not a role

[`ktl-prose`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-prose/SKILL.md) is the **librarian**'s copy editor. It rewords what an agent wrote, in plain English, before a person confirms it. It changes the wording and never a fact, it leaves every byte of frontmatter alone, and it never touches a concept a person wrote or confirmed. It is optional.

### The sixth skill, which publishes the bundle

[`ktl-website`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/skills/ktl-website/SKILL.md) builds a website for the bundle. It has a page per concept with its trust label, the health page, the knowledge graph and search by trust and type, and it serves the four files `lokf export` writes beside the pages. The repository's README, docs, changelog and LinkML schema pages join them when it has them. Its data joins them as SQLite databases to open in Datasette Lite, once a person turns that on. A workflow publishes the site to GitHub Pages. This repository's [site](https://w3id.org/ktl/) is the template's first copy. The website skill is optional, like `ktl-prose`.

## Trust stays visible

The **curator** reports each concept's trust record in plain words:

- **Confirmed by a person**: a named person checked it against its source.
- **Checked by automation only**: automation re-checked that the source still matches, and no person has.
- **Nobody has checked this yet**: no check of any kind is recorded.
- **Still a draft**, **reopened**, **edited since a person last confirmed it**, **past its review date**, **a reader disputed this**, **retired** or **retired, replaced by** its successor; and, for prioritising, how many other concepts rely on each one. A question asked after a confirmation reopens a concept and flags what waits. It never drops the rung. Only an edit after the confirmation does that.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/trust-ladder-dark.svg">
    <img src="https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/trust-ladder.svg" alt="The trust ladder: still a draft, checked by automation, confirmed by a person. It shows what drops a concept a rung, and what only flags it" width="720" />
  </picture>
</p>

***As a flow diagram, drawn with Archify: [light](https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/companions/trust-ladder.svg), [dark](https://noelmcloughlin.github.io/knowledge-trust-ladder/assets/companions/trust-ladder-dark.svg).***

The labels are computed from the frontmatter on every read, never stored, so they always agree with what they describe. Each is a signal for the reader to weigh, never a score. The number to watch is **confirmed by a person: n of N**. It is meant to rise slowly, a handful of concepts in a sitting.

## Read on

| | |
| --- | --- |
| How to install the six skills, which ones to start with, and how to pin them to one release | [install.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/install/) |
| The context layer: what it is, how one bundle already is one, and why bundles federate through domains | [context-layer.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/context-layer/), and [what it integrates with](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/context-layer-technology/) |
| A federation of bundles: domains as manifests, tiers of domains, the workspace built ahead of time, what exists and what remains a design, and the decisions an adopter must make | [federation.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/federation/) |
| Knowledge outside the repository: wiki pages, documents and files in other repositories, mirrored by the ingest so the bundle can cite them | [ingest.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/ingest/) |
| The mechanics: who writes the bundle and what checks it, the four levels of checking, which the plugins run live, how readers and verdicts steer the next run, and what to do when a bundle outgrows LOKF's vocabulary | [for-the-curious.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/for-the-curious/) |
| What the project's own words mean, such as *sidecar*, *registrar*, *docent*, *desk* and *the pen* | [the bundle's glossary](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/glossary/) |
| The bundle in Obsidian, and the two plugins | [obsidian.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/obsidian/) |
| Where each role sits in the three lines of defence, and [the model's critics](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/three-lines/#what-the-critics-say) | [three-lines.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/three-lines/) |
| Whether KTL helps a repository whose content is Agent Skills, and what remains to do there | [skills-repositories.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/skills-repositories/) |
| Versioning: all six skills are released under one `vMAJOR.MINOR.PATCH`, so a set pinned to one tag agrees with itself | [releasing.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/releasing/), [CHANGELOG.md](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/CHANGELOG.md) |
| Contributing, the repository tree, and reporting a security issue | [CONTRIBUTING.md](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/CONTRIBUTING.md), [repository-layout.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/docs/repository-layout/), [SECURITY.md](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/SECURITY.md) |

## Credits

- [Nolan Nichols](https://lokf.nolan-nichols.com/), creator of [LOKF](https://lokf.nolan-nichols.com/specification/) (Linked Open Knowledge Format) and its [toolkit](https://github.com/nicholsn/lokf).
- The [LinkML Community](https://linkml.io/), creators of [LinkML](https://linkml.io/linkml/), the schema language LOKF is written in.
- [Google Cloud](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing), creator of the Open Knowledge Format (OKF) specification that LOKF profiles.
- [Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), a pattern for building personal knowledge bases with LLMs.
- [WikiSkill](https://arxiv.org/abs/2608.27454) by Tang et al. (Google Research, 2026) and [SkillWiki](https://arxiv.org/abs/2606.16523) by Huang et al. (2026), two papers whose reading changed how the skills learn from readers and verdicts.
- [Archify](https://github.com/tt-a1i/archify) by tt-a1i, under the MIT License, which draws the flow diagrams in `.assets/companions/`. They embed the JetBrains Mono font, under the SIL Open Font License.

This is an independent project. It is not affiliated with, endorsed by, or an
official distribution of LOKF or of the Open Knowledge Format. "LOKF" and
"Linked Open Knowledge Format" refer to the format and toolkit published by
Nolan Nichols; "OKF" and "Open Knowledge Format" to the specification
published by Google Cloud. Both are used here as descriptors, under their own
open terms.

## License

[Apache License 2.0](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/LICENSE).