# Examples: `ktl-docent` answering questions

Eight questions asked against this repository's own `.lokf/knowledge/` bundle, following `skills/ktl-docent/SKILL.md` exactly. That means: read the bundle first, widen along typed relations before searching the repo, and verify exact values at the source before stating them. State each concept's trust label, and fall back, out loud, only when the bundle has no answer. The answers are captured output.

Trust labels here mean what `skills/ktl-curator/references/trust-fields.md` defines. At the time these were run, no concept in this bundle had been confirmed by a person yet, since `ktl-curator` had not been run. So every answer below is at most "checked by automation only" or "nobody has checked this yet", which examples 2 and 6 themselves demonstrate. The answers are what the **docent** said then. Some of the pages it checked have been rewritten since (`CONTRIBUTING.md` is now a shorter checklist), so take the sources named as current, not the values quoted.

## 1. "What is LOKF?"

> LOKF (Linked Open Knowledge Format) is a semantic profile of OKF in which
> every field, type, and relationship is bound to a public vocabulary, so the
> same Markdown expands losslessly to JSON-LD and RDF (bundle:
> `glossary/lokf.md`, checked by automation only).

*One concept fully answers the question, so the answer skips the full footer per the skill's own rule for that case.*

## 2. "What does OKF require of a concept file?"

> OKF (Open Knowledge Format) requires only that a concept file's path serve
> as its ID and that its YAML frontmatter carry a `type` field - everything
> else is optional. A consumer must never reject a bundle for missing
> optional fields, unknown types, unknown keys, or broken cross-links.

```text
From the bundle:
- OKF (glossary/okf.md) - checked by automation only
- OKF specification (v0.2) (references/okf-specification.md) - nobody has checked this yet
```

*Two related concepts, two different labels. The glossary term was re-verified against its internal resource file this session; the Reference concept's resource is an external URL that was not re-fetched, so it carries no `verified` event yet.*

## 3. "I have a repo with no `.lokf/` yet - which skill do I run first?"

> Run `ktl-sidecar` first. It's the one-shot bootstrap that creates the
> `.lokf/` sidecar - tooling, docs, and a dummy skeleton - from bundled
> templates, then hands off to `ktl-librarian` to fill it with real
> knowledge.

```text
From the bundle:
- ktl-sidecar skill (playbooks/ktl-sidecar-skill.md) - checked by automation only
```

## 4. "How do ktl-librarian and ktl-curator relate?"

> `ktl-curator` `dependsOn` `ktl-librarian`: the curator's job - recording a
> person's verdicts - only makes sense once the librarian has derived
> concepts to review. The relationship also marks the boundary between them:
> the librarian deals in facts about the repository and never vouches for
> them; the curator deals in judgments a person made and never derives facts
> itself.

```text
From the bundle:
- ktl-librarian skill (playbooks/ktl-librarian-skill.md) - checked by automation only
- ktl-curator skill (playbooks/ktl-curator-skill.md) - checked by automation only
  (dependsOn -> ktl-librarian-skill)
```

## 5. "How do I contribute a change to these skills?"

> There's no build step - the skills are Markdown, YAML, and one shell
> script. Clone the repo and run `bash scripts/validate-repository.sh`.
> Before opening a pull request, run five checks: the repository-contract
> script, `gh skill publish --dry-run` (if the GitHub CLI is installed),
> `shellcheck` on any changed script, `actionlint` on any changed workflow
> (including the templates under `skills/ktl-sidecar/templates/github/`),
> and a `CHANGELOG.md` entry under `[Unreleased]` if the change alters
> behavior.

```text
From the bundle:
- Contributing (playbooks/contributing.md) - checked by automation only
Checked at source: CONTRIBUTING.md's "Before opening a pull request" section -
  all five items match exactly what the bundle claims.
```

## 6. "What GitHub CLI version do I need for `gh skill`?"

> The bundle's Reference concept says `gh skill` was added in GitHub CLI
> v2.90.0, and `README.md` independently states the same figure. I opened the
> concept's actual source to confirm the number directly, but the manual page
> at `cli.github.com/manual/gh_skill_install` documents current behavior, not
> a changelog - it doesn't state a version number itself, so I can't
> independently confirm v2.90.0 from that specific page. Both places in this
> repository agree, but I'd check the GitHub CLI release notes before relying
> on the exact number.

```text
From the bundle:
- gh skill (GitHub CLI) (references/gh-skill-cli.md) - nobody has checked this yet
Checked at source: cli.github.com/manual/gh_skill_install - does not state a version number
Gap recorded: none - the bundle's claim isn't contradicted, just unconfirmable at this page
```

*This is "verify exact values at the source" when the source lacks the value to confirm: the answer says so, rather than repeating the bundle's number as fact.*

## 7. "What's the roadmap for a fifth skill after ktl-docent?"

> I don't see anything in the bundle about a planned fifth skill - the
> Explanation concept on why there are four roles explains the current
> design, not a roadmap, and I searched the rest of the repository too.
> There's no mention of a fifth skill anywhere. This looks like a genuine gap
> rather than something I missed.

```text
From the bundle: (none relevant)
Gap recorded: Miss - "What's the roadmap for a fifth skill after ktl-docent?" -
  no answer found anywhere in the bundle or repository.
```

The **docent** asked once this session whether to record gaps in `.lokf/feedback.md`; the answer was yes, so this one was written there: see
[`.lokf/feedback.md`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/.lokf/feedback.md). `ktl-librarian`'s next run will either turn it into a concept or note that no roadmap exists.

*Since this capture the repository has gained a fifth skill, `ktl-prose`. The answer above stays as it was given, and the librarian's next refresh records the new skill.*

## 8. "Who do I contact to report a security issue, and is that policy confirmed by a person?"

> Use GitHub's private vulnerability reporting (linked from `SECURITY.md`)
> rather than a public issue or a direct email - that's the documented
> channel, not the maintainer's personal contact. The bundle records the
> maintainer as Noel McLoughlin (the bundle's `publisher`). As for whether the
> security policy itself has been confirmed by a person: no - it's still a
> draft, checked by automation only. Nobody has reviewed it by hand yet.

```text
From the bundle:
- Security policy (policies/security.md) - still a draft; checked by automation only
Checked at source: SECURITY.md's "Reporting a vulnerability" section - matches exactly
```

## Which concept answers each question

The link checker follows each link below on every build, so a concept that is renamed or deleted fails the build with its question beside it. The librarian never derives from this page, since `playbooks/knowledge-sources.md` keeps `docs/examples/` out of its sources, so the questions stay held out from the bundle they test.

| Question | Concept that answers it today |
| --- | --- |
| 1. What is LOKF? | [glossary/lokf.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/glossary/lokf/) |
| 2. What does OKF require of a concept file? | [glossary/okf.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/glossary/okf/), [references/okf-specification.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/references/okf-specification/) |
| 3. Which skill do I run first? | [playbooks/ktl-sidecar-skill.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/playbooks/ktl-sidecar-skill/) |
| 4. How do ktl-librarian and ktl-curator relate? | [playbooks/ktl-librarian-skill.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/playbooks/ktl-librarian-skill/), [playbooks/ktl-curator-skill.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/playbooks/ktl-curator-skill/) |
| 5. How do I contribute a change? | [playbooks/contributing.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/playbooks/contributing/) |
| 6. What GitHub CLI version do I need? | [references/gh-skill-cli.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/references/gh-skill-cli/) |
| 7. What is the roadmap for a fifth skill? | [playbooks/ktl-prose-skill.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/playbooks/ktl-prose-skill/), [explanation/why-four-roles.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/explanation/why-four-roles/); a miss when captured, and the skill exists now |
| 8. Who do I contact about a security issue? | [policies/security.md](https://noelmcloughlin.github.io/knowledge-trust-ladder/knowledge/policies/security/) |

[`tests/docent-holdout.yaml`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/tests/docent-holdout.yaml) holds the same pairs as data, [`tests/test_docent_holdout.py`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/tests/test_docent_holdout.py) checks on every pull request that each concept still exists, and `just docent-eval` runs the docent on them weekly through `claude plugin eval`, from the cases under [`evals/`](https://github.com/noelmcloughlin/knowledge-trust-ladder/blob/a70038260880b7d9f47cd7e8ac796b2a2213168e/evals/README.md).

---

Try these yourself once `ktl-docent` is installed, or ask your own: that is the point of the skill.