docs(krl): sharpen four-op glosses, add Retrieve clause + QL-deferral ADR

- README 'four KRL operations': add the four-verb glosses (construct/
  transform/resolve/retrieve) and a Retrieve clause stating Retrieve recovers
  resolution-relevant artefacts (presentations, invariants, witnesses,
  equivalence classes, prior resolutions, explanations, provenance) and is NOT
  arbitrary database querying; generic access is an engine-layer affordance.
- docs/decisions/0002-query-language-deferred.adoc: ADR recording that querying
  stays a mode of KRL; a sibling query language is deferred (not rejected)
  behind an explicit trigger list, and if built will be a KRL-family
  projection/reporting dialect over TangleIR, not a rival paradigm.
- CITATION.cff: authorship/citation metadata (anti-commoditisation provenance).
- ROADMAP: fix placeholder title; point Future Directions at the ADR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017TXizM5c1Yd9HWf7Y15YH2

Author: claude

CITATION.cff

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+cff-version: 1.2.0
+message: "If you use KRL (Knot Resolution Language), please cite it as below."
+title: "KRL — Knot Resolution Language"
+abstract: >-
+  KRL is QuandleDB's canonical resolution DSL: a database-facing language whose
+  domain is knot/tangle identity, equivalence, transformation, and disambiguation.
+  It is the user- and author-facing language for constructing, transforming,
+  resolving, and retrieving knot/tangle presentations, invariants, witnesses,
+  equivalence classes, and disambiguation results, lowering through TangleIR into
+  Tangle-level computation over the QuandleDB and Skein.jl backends.
+type: software
+authors:
+  - family-names: Jewell
+    given-names: "Jonathan D. A."
+    email: j.d.a.jewell@open.ac.uk
+    alias: hyperpolymath
+license: MPL-2.0
+repository-code: "https://github.com/hyperpolymath/krl"
+url: "https://github.com/hyperpolymath/krl"
+keywords:
+  - knot theory
+  - resolution language
+  - knot identity
+  - equivalence
+  - disambiguation
+  - domain-specific language

README.adoc

@@ -94,9 +94,18 @@ KRL is *not* responsible for:
 
 == The four KRL operations
 
+KRL has exactly four operations. The four-verb shape is deliberate: it stops
+"querying" from becoming the whole identity of the language.
+
+[horizontal]
+*construct*:: create or declare presentations, structures, claims, datasets
+*transform*:: rewrite, normalize, compose, concatenate, permute, mutate
+*resolve*:: decide / disambiguate / evaluate equivalence or identity questions
+*retrieve*:: inspect, fetch, project, explain, or return stored or computed results
+
 [cols="1,2,1,2"]
 |===
-|Operation |Knot concept |Repo |Example syntax
+|Operation |Knot concept |Primary site |Example syntax
 
 |*Construct* |Tangles, ports, composition, tensor |TanglePL
 |`compose sigma1 sigma1` +
@@ -113,11 +122,26 @@ KRL is *not* responsible for:
 `classify t` +
 `near t`
 
-|*Retrieve* |Jones/Alexander invariants, indexed store |Skein.jl
+|*Retrieve* |Invariants, witnesses, stored resolutions |Skein.jl + QuandleDB
 |`find where jones = p` +
 `where crossing < 8`
 |===
 
+[NOTE]
+====
+*Retrieve is not arbitrary database querying.* It recovers
+*resolution-relevant artefacts*: presentations, invariants, witnesses,
+equivalence classes, prior resolutions, explanations, and provenance.
+
+Generic data access — arbitrary filters, dashboards, reporting, analytics,
+exploratory search, index tuning — is an *engine-layer* affordance (Skein.jl
+predicates over SQLite; QuandleDB's filtered endpoints), deliberately *not*
+elevated to a KRL operation or a rival query language. A separate query
+language is *deferred*, not absent; see
+`docs/decisions/0002-query-language-deferred.adoc` for the rationale and
+trigger conditions.
+====
+
 == Grammar (sketch)
 
 ----

ROADMAP.adoc

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-= YOUR Template Repo Roadmap
+= KRL Roadmap
 
 == Current Status
 
@@ -20,4 +20,11 @@ Initial development phase.
 
 == Future Directions
 
-_To be determined based on community feedback._
+* *Query language: deferred.* Querying stays a mode of KRL (the `retrieve`
+  operation), not a sibling language. A separate query language is deferred until
+  sustained non-resolution operations accrue — dashboards, arbitrary filters,
+  administrative analytics, bulk reporting, exploratory search, index tuning. If
+  built, it will be a KRL-family projection/reporting dialect compiling to TangleIR,
+  not a rival paradigm. See `docs/decisions/0002-query-language-deferred.adoc`.
+
+_Otherwise to be determined based on community feedback._

docs/decisions/0002-query-language-deferred.adoc

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= Architecture Decision Record: 0002-query-language-deferred
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->
+
+# 2. Query language deferred — querying stays a mode of KRL
+
+Date: 2026-06-18
+
+## Status
+
+Accepted
+
+## Context
+
+KRL is a *resolution language*, not a query language. Its identity is the four
+operations — *construct*, *transform*, *resolve*, *retrieve* — and the four-verb
+shape is deliberate: it stops "querying" from becoming the whole identity of the
+language.
+
+A recurring pressure works against this:
+
+- Databases are *expected* to ship a query language; its apparent absence reads as
+  "toy" to evaluators arriving with SQL / Cypher / AQL muscle memory.
+- The *retrieve* operation, by name, can drag readers back toward "query language".
+- There is a genuine future need for non-resolution data operations: dashboards,
+  arbitrary filters, administrative analytics, bulk reporting, exploratory search,
+  index tuning.
+
+But the two failure modes are asymmetric:
+
+- *No query language* is a **messaging** problem — cheap, reversible, fixable with
+  documentation.
+- *A premature, weak query language* is a **reputation** problem — it invites direct
+  comparison with mature query languages on their own turf, where a young project
+  loses, and first impressions in developer tooling are durable. A bounced evaluator
+  is hard to win back.
+
+Query *access* already exists at the engine/API layer (Skein.jl composable
+predicates over SQLite; QuandleDB's filtered HTTP endpoints). What is declined here
+is a *first-class, branded query language* that competes as a paradigm. Those are
+different things.
+
+There is also a strategic-identity dimension. A capability framed as "a query
+sublanguage" is absorbable as a feature ("the next AQL add-in module"); a *named
+category* — resolution as a paradigm for equivalence / identity determination — is
+not. Keeping KRL a language rather than a query mode is therefore also how the work
+retains a distinct, attributable identity, especially if the broader bet (resolution
+as a general primitive for determining equivalent acts and things, including for AI)
+pays off.
+
+## Decision
+
+1. Querying remains a *mode of KRL* — the *retrieve* operation — not a first-class
+   sibling language. No separate query language is built now.
+
+2. *Retrieve* is defined narrowly. It recovers **resolution-relevant artefacts**:
+   presentations, invariants, witnesses, equivalence classes, prior resolutions,
+   explanations, and provenance. It is **not** arbitrary database querying.
+
+3. Generic data access (arbitrary filters, dashboards, reporting, analytics,
+   exploratory search, index tuning) is an *engine-layer* affordance (Skein.jl /
+   SQLite; QuandleDB endpoints), deliberately not elevated to a KRL operation.
+
+4. A separate query language is *deferred, not rejected*. It becomes warranted only
+   when sustained non-resolution database operations accumulate — the trigger list:
+   dashboards, arbitrary filters, administrative analytics, bulk reporting,
+   exploratory search, index tuning.
+
+5. *Pre-committed shape.* If/when that query language is built, it will be a
+   *KRL-family projection / reporting dialect that compiles to the same TangleIR and
+   engine* — one semantic core with a reporting surface — not an independent rival
+   paradigm. This makes it structurally impossible for the future query language to
+   be a "me-too" graph/relational language.
+
+## Consequences
+
+### Positive
+
+- KRL leads from strength (resolution — where it has no competitor) rather than
+  fighting established query languages on their turf.
+- The distinctive, attributable identity ("knot resolution", a named paradigm) is
+  preserved against commoditisation.
+- No premature surface to poison first impressions.
+
+### Negative
+
+- Evaluators expecting a headline query language must be pointed at the engine-layer
+  access path and the *retrieve* clause; the absence must be *explained*, not shipped
+  around.
+
+### Neutral
+
+- The decision is revisited when the trigger conditions accrue; this ADR is then
+  superseded by the ADR that specifies the deferred dialect.