@konneal/engine 0.1.0

package/docs/paper-oiml-bulletin.mdx

@@ -0,0 +1,419 @@
+---
+title: "Grounding legal metrology: a retrieval-augmented question-answering service over the OIML publications corpus"
+subtitle: "Draft article for the OIML Bulletin"
+date: 2026-08-30
+figures: paper-assets
+---
+
+export const Figure = ({ id, src, caption, width = 760 }) => (
+  <figure id={id} style={{ margin: "24px auto", textAlign: "center" }}>
+    <img src={src} alt={caption} width={width} style={{ maxWidth: "100%", height: "auto" }} />
+    <figcaption style={{ fontSize: "0.85em", color: "#475569", marginTop: 8 }}>{caption}</figcaption>
+  </figure>
+);
+
+*Draft article for the OIML Bulletin — 2026-08-30. Style: Bulletin
+technical article (MS Word single-column on submission; this is the
+authoring source). Numbers are production-measured unless noted.*
+
+---
+
+## Abstract
+
+The OIML publishes close to 900 documents — Recommendations, Basic
+publications, Guides, Documents and Expert reports — that together form
+the reference library of legal metrology. Finding what they say has
+required knowing the corpus before querying it. We describe a
+question-answering service, **OIML SMART AI** (ai.oimlsmart.org), that
+answers natural-language questions from the indexed publications with
+clause-level citations, verbatim quote anchors for normative values, and
+typed renderings of the tables and equations the answers depend on — and
+it reads figures and user-supplied photographs directly, from pixels. The
+service measures every component it ships: a golden question set,
+retrieval metrics in the tradition of the information-retrieval
+literature, and judged faithfulness. We report the measured design
+decisions, the corpus-structure findings that shaped them, and the open
+path: producer-native ingestion of the Metanorma document model so that
+any Metanorma-authored corpus can be indexed the same way.
+
+---
+
+## 1. Introduction
+
+Legal metrology's knowledge lives in a large, cross-referential,
+multi-edition corpus. A typical working question — *"what is the maximum
+permissible error for a class III nonautomatic weighing instrument?"* —
+requires knowing which Recommendation applies (OIML R 76-1), which
+edition is current, which clause holds the table, and how to read the
+table's rows against the instrument's verification scale intervals.
+Every one of those steps assumes corpus knowledge the questioner may not
+have.
+
+Question answering over such corpora has been transformed by
+retrieval-augmented generation (RAG): a language model is given passages
+retrieved from a trusted corpus and may use only those. The engineering
+challenge is no longer whether a model can write fluent prose — it can —
+but whether the *right passages* are found, whether the answer stays
+*faithful* to them, and whether the reader can *verify* the result. Our
+service is built around those three properties.
+
+This article describes the architecture as deployed, the measurements
+that shaped it, and the corpus findings — including errors in the
+bibliographic record itself — that surfaced because the system keeps
+score. It closes with the producer-native ingestion path (Metanorma
+Knowledge Objects) and what it makes possible for other standards bodies.
+
+## 2. What the service does
+
+A user asks a question in any language. The service:
+
+1. **Understands the question** with a small language model — language,
+   named publication, edition, defined terms, complexity. There are no
+   keyword rules; the same model makes these judgements for every
+   question.
+2. **Retrieves in parallel** — three lanes leave the question at the
+   same instant: the vector index is queried with the question's
+   embedding while understanding is still running (the dense lane's
+   results are reused unchanged when understanding adds nothing), a
+   full-corpus keyword index catches exact identifiers, part numbers
+   and defined terms that vector similarity alone misses, and
+   understanding's refinements — a named publication, an edition —
+   arrive as metadata filters on the dense query.
+3. **Ranks** the fused candidates with a cross-encoder; complex
+   questions get a second, stronger re-ranking pass.
+4. **Answers from the retrieved passages only**, under a contract that
+   requires inline citations (`[OIML R 60-1:2021 §4.4.2]`) and verbatim
+   quote anchors for normative values.
+5. **Verifies** the answer after generation: a deterministic check that
+   every quoted phrase exists in a cited passage; a separate judge that
+   scores faithfulness; a correction-and-retry when either fails. An
+   answer that cannot be verified is never written to the answer cache.
+
+<Figure
+  id="fig-architecture"
+  src="paper-assets/architecture.svg"
+  caption="Figure 1 — A question's path through the service. Three retrieval lanes run concurrently; every answer passes mechanical verification before it is served or cached. The edition registry derives publication status from supersession links, never from a status field."
+/>
+
+When the question names a publication, answers are steered to the
+current edition by a registry derived from the bibliographic record's
+supersession links (§5). When the answer depends on a table or
+equation, the interface renders the *producer's* typed object — the
+actual rows and columns — never the model's re-typing of it (§6).
+
+If the corpus does not contain the answer, the system says so in one
+canonical sentence and redirects; refusals are never cached, because a
+refusal is a property of the moment, not of the question.
+
+## 3. Corpus and structure
+
+The indexed corpus comprises the English editions of the OIML
+publications (~900 documents, ~9.3 million words). Documents are chunked
+along clause boundaries — never arbitrary token windows — and each chunk
+carries provenance: publication identifier, edition, language, clause
+anchor, and bibliographic status.
+
+Three corpus-level findings shaped the design:
+
+**The bibliographic status field disagrees with its own record.** In 58
+of 224 publication families, the machine-readable status field claims a
+document is current while the same record's supersession links say
+otherwise. The service therefore *derives* status from the links and
+ignores the field. More consequentially, 36 of 224 families have no
+recorded successor link at all, so the current edition cannot be derived
+for them; the registry surfaces these gaps rather than guessing. Both
+numbers are the worklist for upstream bibliographic corrections — the
+kind that serving surfaces only because it keeps score.
+
+**Identifiers are identity, not display.** A cross-referenced audit of
+the dirty corpus found documents whose machine-readable identifier was
+a placeholder ("OIML D 0:0000", "OIML D X") or polluted with language
+markers — around 200 records — making them unreachable by
+doc-scoped retrieval. Identifiers are now derived from slug identity
+with placeholders never winning, and the index is reconciled against
+the canonical chunk set: the first census measured 49,553 live vectors
+against 31,512 canonical — 18,041 strays from every prior re-chunking,
+deleted in place (upserts never delete). A retrieval service that never
+enumerates its own index serves ghosts.
+
+**Tables are where the normative values live.** Maximum permissible
+errors, accuracy-class limits, verification interval bounds — the values
+practitioners ask for — are tabular. Flattening tables into prose loses
+the row/column geometry that makes them answerable. The index now treats
+tables as atomic typed objects (§6).
+
+**Structure is a retrieval signal.** Standards are hierarchically
+organized with extensive cross-references; the system indexes the
+section hierarchy and the citation graph as a queryable graph (7,128
+nodes, 6,486 edges) alongside the text, so a defined term can be
+resolved to the documents that define it even when the question's
+vocabulary does not match the corpus's.
+
+## 4. Retrieval: what the measurements showed
+
+We evaluate retrieval with a golden question set (now 29 questions
+including eight table-value questions with witness rows) using
+recall@5, average precision@5, and mean reciprocal rank@5 — the protocol
+of the standards-retrieval literature. Single runs proved noisy (±5
+percentage points); all reported numbers are means over three runs on a
+quiet account.
+
+The single largest measured improvement came from making keyword
+retrieval a **full-corpus first stage** rather than a re-scoring of the
+vector results: recall@5 rose from 86% to 95%. The reason is structural
+— standards vocabulary is exact ("n_LC", "R 60-3", "creep"), and dense
+embeddings alone miss exact identifiers that a lexical scan of the whole
+corpus recovers. Fusing both rankings (reciprocal rank fusion) lifted
+precision and MRR without costing recall.
+
+The second improvement came from **contextual enrichment**: a one-time
+pass that prepends a short model-written preamble to every chunk ("this
+clause defines the accuracy-class limits for load cells") before
+embedding and indexing. This is the contextual-retrieval recipe
+validated industry-wide; our corpus measurement confirmed it, and the
+one-time cost (~$0.0017 per chunk) is amortized over every future
+answer.
+
+With the typed-table lane live (§6), retrieval lanes running
+concurrently with query understanding, edition steering active (§5) and
+multimodal generation on (§6), the current baseline is:
+
+| Metric | Value |
+|---|---|
+| Recall@5 (mean of 3) | **94.3%** (range 93.1–96.6) |
+| Average precision@5 | 0.82 |
+| MRR@5 | 0.87 |
+| End-to-end golden cases | 14/14 |
+
+These numbers are on our own golden set, not on the benchmarks of the
+works we build on — the honest comparison is per-technique, on the same
+corpus, before and after. So read: the full-corpus lexical stage is the
+ETSI study's recipe (ref 1) — adopting it lifted recall@5 here from 86%
+to 95%; the contextual preambles are Anthropic's contextual retrieval
+(ref 3) — confirmed on this corpus at ~$0.0017 per chunk one-time; the
+clause-boundary, structure-preserving chunking follows the same
+structure-aware line as refs 2 and 7, which our typed-unit pin extends
+from "chunk better" to "guarantee the answering object a slot." Two
+elements of the deployed system have no counterpart in the cited work:
+the symbolic-reference contract, under which table data never passes
+through the model at all (refs 2's error-reduction approach still
+re-generates tables; we removed the corruption channel), and the
+mechanical post-generation verification of every answer (quote anchors,
+unit references, retyped-table detection) with a faithfulness judge that
+sees the passages actually used.
+
+Two structural additions complete the retrieval story. First, the
+corpus is a tree — every chunk carries its clause anchor — and the
+serving path uses the tree: a hit's score blends its neighbouring
+clauses' scores, evidence is presented to the answer model in document
+reading order, and a ranked section summary resolves to its quotable
+child clauses (adapted from FABLE/BEAR, ref 7, at none of its index-time
+cost, because Metanorma documents arrive as trees rather than needing
+one inferred). Second, everyday words rarely match defined terms — the
+one gap that failed for every corpus representation equally — so a
+terminology index of the corpus's defined concepts links a question's
+phrasing to candidate terms, and the answer model adjudicates and leads
+with the corpus's own term, quoting its definition ("my output keeps
+drifting" resolves to *span stability*, with the verbatim definition and
+its defining clause cited).
+
+## 5. Editions and trust
+
+Which edition applies is as consequential as what it says. The service's
+registry of publication families and editions is derived from
+supersession links, not from status fields (§3). Citations carry the
+edition and status of every source; superseded sources are marked.
+Answers to questions that name a publication are steered to the current
+edition; answers that must cite a superseded edition (the 2021 passages
+do not reproduce a table the 2017 edition carries) say so explicitly.
+
+Steering is measured, not assumed, and two mechanisms earned their place
+by fixing observed failures. Superseded editions match archaic phrasing
+strongly — a complex verification question once cited R 76-1:1992/1988
+while the current 2006 edition was crowded out of the passage window —
+so ranking now demotes older-edition chunks of a publication whenever a
+newer edition of the same publication is present in the evidence
+(cross-publication recency is deliberately untouched: a 1992 document
+that is still current must not lose to unrelated 2024 ones). And because
+query understanding can pin an edition for the wrong family, an edition
+pin that the corpus itself fails to corroborate is dropped to the
+document-level filter. After both fixes the probe cites R 76-1:2006 in
+force, with one legitimate 1988 tail citation for a clause only that
+edition carries; the window's measured average precision (0.85) and MRR
+(0.88) are the best the service has recorded.
+
+## 6. Tables, equations, and figures as typed objects
+
+The most consequential rendering decision: the language model never
+re-types normative data. When an answer depends on a table, the model
+emits a symbolic reference to the table's unit (`[[u:table-1]]`); the
+server validates the reference against the passages actually used and
+resolves it to the producer's typed payload — columns, rows, units. The
+interface renders the exact object. Small verbatim values in prose are
+permitted and mechanically verified against the source. The payload
+never passes through the model's output, so it cannot be corrupted by
+generation.
+
+The same principle extends from rendering to judgment: the model never
+judges what a machine can compute. Where the corpus's machine-readable
+models carry checkable objects — a constraint with an OCL expression, a
+requirement with a threshold limit — a question naming one gets it
+EXECUTED: the question's values bind to the rule's own parameters, the
+check evaluates deterministically, and the verdict (pass, or the
+standard's own violation word, with the arithmetic shown, or void naming
+exactly what is missing) is attached to the answer as computed data.
+Two sibling capabilities complete the set: provable absence (a topic
+that a standard does not constrain returns an enumeration certificate
+over its entire model plane — N nodes enumerated, zero matches — rather
+than a refusal) and answer verification (any answer checkable against
+the corpus: verbatim-quote containment, object-reference resolution, a
+judged faithfulness score labeled as judged).
+
+<Figure
+  id="fig-contract"
+  src="paper-assets/contract-v2.svg"
+  caption="Figure 2 — The answer contract. The model writes prose with inline citations and symbolic references; three mechanical checks run after generation; the server resolves surviving references to the producer's payloads and the client renders them."
+/>
+
+Figures are described by a vision-capable model that reads the actual
+image pixels; equations are carried in their authoring-native formats
+(AsciiMath and MathML) with a plain-language description. Both arrive as typed objects with the same validation.
+
+Figures also flow the other way: when the retrieved passages contain
+figure units, their actual images are attached to the answer model's
+input, so descriptions and reasoning come from the drawing itself — the
+model reads labels that exist only in the pixels (the pixel-label
+probe — "what are the labeled example cases in the R 60-2 design-shapes
+figure?" — is answered A, B and C from the drawing, stable across
+repeated runs). Two measured invariants keep that true: assets must be
+readable by vision pipelines (vector-sourced rasters that draw black on
+transparent alpha flatten to a solid black rectangle inside a vision
+model, whatever a browser shows — a corpus sweep detects and repairs
+them), and images ride their own message in the generation call (long
+passage text and image parts in one message triggers provider errors
+that scale with payload). Users can likewise attach a photograph (an
+instrument nameplate, a scale dial, a schematic) to their question; the
+text still drives retrieval, and the image gives the model the visual
+context, under the same citation contract.
+
+## 7. Models, cost, and sovereignty
+
+All models are open-weight and served on a single cloud platform
+(Cloudflare Workers AI); no corpus data is sent to proprietary model
+providers. The answer model (GLM-5.3 Flash, natively multimodal) serves
+all tiers at approximately $0.001 per answer. The full one-time corpus
+preparation — contextual enrichment of 42,000 chunks — cost
+approximately $75. Daily serving at current traffic is under $5 per
+month including infrastructure. The model policy is deliberately
+cost-first on the serving path (every question pays it) and quality-first
+on one-time work (enrichment, captioning, evaluation), where quality
+persists into every future answer.
+
+One lesson generalizes: read the model card before wiring a model. Three
+separate live failures traced to defaults we never set — a
+reasoning-effort parameter that silently defaults to maximum (starving
+small output budgets), sampling defaults that let a thinking model loop
+(repetition consuming the token budget that carried the structured
+output), and a degraded non-thinking mode we were unknowingly paying
+for. Every call site now states its reasoning mode, its sampling, and a
+budget the reasoning cannot starve; the discipline costs nothing and
+removed an entire class of silent failure.
+
+## 8. The producer-native path: Metanorma Knowledge Objects
+
+OIML publications are authored in Metanorma, a model-driven document
+system: the source of truth is a typed document model, not any rendered
+PDF or HTML. The service's newest ingestion path consumes that model
+directly — one bundle per document containing typed units (clauses,
+tables, terms, equations, figures, requirements), a section graph, a
+native Glossarist glossary, and Relaton bibliographic objects — and
+replaces HTML scraping end to end for the cleanly-authored portion of
+the corpus. The format, Metanorma Knowledge Objects (MKO), is specified
+as Metanorma note 116 with the consumer contract (symbolic unit
+references and typed excerpts) contributed from this work.
+
+<Figure
+  id="fig-mko"
+  src="paper-assets/mko-ingest.svg"
+  caption="Figure 3 — Producer-native ingestion. Each authored document exports as one MKO bundle; chunking, enrichment and indexing are derived from the bundle, and re-ingest is incremental by content hash."
+/>
+
+This path matters beyond OIML: any standards body whose publications are
+authored in Metanorma gets structured, table-aware, graph-connected
+question answering over its corpus without scraping renderings. The
+guidelines for building such a service from scratch accompany this
+article.
+
+## 9. Evaluation as a discipline
+
+The service's answers are evaluated on three axes, continuously:
+
+- **Retrieval** (recall, precision, MRR against the golden set with
+  witness citations)
+- **Faithfulness** (an independent judge scores whether each claim is
+  supported by the retrieved passages — with the important lesson that
+  the judge must see the passages the answer was actually built from,
+  not a fresh retrieval)
+- **User feedback** (thumbs up/down on every answer, logged to the same
+  evaluation loop)
+
+Every change ships through the same gate — literally one command:
+golden suite ×3 and the capability battery ×6 against the live service,
+where any failed run fails the command. The suites also run in CI and
+the service's cache versions flush on every retrieval change so no
+answer is served from a superseded index. A humility note from the
+measurement machinery itself: the capability battery's runner once
+omitted to set a non-zero exit code on failure, so a failing battery
+reported green through the gate — the same class of silent failure the
+cache-version discipline exists to prevent. Exit codes are part of the
+measurement contract now. The gate rejects as often as it accepts.
+A candidate change that unioned additional retrieval candidates into a
+rewritten query's pool — a plausible-looking "more evidence" improvement
+— dropped recall@5 from 94.3% to 89.7%: topically close but wrong
+documents outscored the right ones under the cross-encoder, and the
+per-case diff named the three failing questions. The fix (additive
+candidates may only replace an identical query, never dilute a rewritten
+one) is now a comment in the code. A second candidate — grading
+document-scoped retrieval more aggressively — was measured, found to buy
+nothing, and reverted the same day. Additive is not free; the suite, not
+the author, decides.
+
+## 10. Conclusions and outlook
+
+A grounded, citation-linked, typed-rendering question-answering service
+over the OIML corpus is measurable, economical, and — with the
+producer-native ingestion path — increasingly maintained by the
+documents' own structure rather than by scraping their renderings. The
+open work is equally concrete: upstream bibliographic corrections for
+the 36 families without derivable current editions; unit-level language
+tagging so bilingual annexes inside English editions stop masquerading
+as main text; a publisher-specific identifier flavor so citation joins
+become exact; collection-level bundles for cross-document reasoning; and
+interlingual unit alignment so the same clause can be answered in every
+OIML language. The requirements behind several of these belong to the
+authoring system itself, and we have filed them with the Metanorma
+document model team as the producer side of an AI-native publishing
+stack.
+
+The service is live at ai.oimlsmart.org. Try it, and tell us when it is
+wrong — the feedback button is the fastest path into the evaluation
+loop that everything above runs on.
+
+---
+
+### References
+
+1. Al Masoud, A., Arazzi, M., Germani, S., Nocera, A. *Exploring
+   Structural Complexity in Normative RAG with Graph-based approaches: A
+   case study on the ETSI Standards.* arXiv:2604.09868 (2026).
+2. Guttal, P., et al. *Structure-Aware Chunking for Tabular Data in
+   Retrieval-Augmented Generation.* arXiv:2605.00318 (2026).
+3. Anthropic. *Contextual Retrieval.* Engineering blog (2024).
+4. Günther, M., et al. *Late Chunking: Contextual Chunk Embeddings Using
+   Long-Context Embedding Models.* arXiv:2409.04701 (2024).
+5. Lewis, P., et al. *Retrieval-Augmented Generation for
+   Knowledge-Intensive NLP Tasks.* NeurIPS (2020).
+6. Metanorma. *MN 116: Metanorma Knowledge Objects (MKO) machine
+   serialization format.* Metanorma documentation (2026).
+7. Xu, L., et al. *Equipping Retrieval-Augmented LLMs with Document
+   Structure Awareness.* arXiv:2510.04293 (2025).

package/docs/product-branding-options.md

@@ -0,0 +1,172 @@
+# Product and branding options for the standards-intelligence engine
+
+> Status: DECIDED (2026-09-12) — Option 1, a new high-level product.
+> **The name is Konneal** (decided 2026-09-13; the GitHub org and the
+> domain are secured — **konneal.org**). The name decodes on three levels, all of them
+> the product's own: K = knowledge (K-onneal is knowledge annealment,
+> the methodology this system invented and published); anneal stays
+> fully legible inside the spelling, so the name carries the story in
+> one step; and konne(ction) — the SDO connects to its members,
+> questions connect to clauses, citations connect answers to the
+> original document. Web collision scan found no company, product or
+> brand using either Konneal or Konnea; formal trademark screening
+> (classes 9/42, target jurisdictions) remains the one professional
+> step before public marketing.
+>
+> Suite frame: *authored in Metanorma, modeled in Primmel, served by
+> Konneal.* Deployments stay white-labeled per SDO — "[SDO] Answers,
+> powered by Konneal" — as OIML SMART AI presents today. When the
+> engine is extracted (migration step 5), it lands in the Konneal org;
+> this repository becomes publisher-oiml, the reference profile.
+
+## The suite frame (applies to every option)
+
+The pipeline has three layers, and the measured staircase prices them:
+
+| Layer | Product role | What it gives the SDO |
+|---|---|---|
+| Metanorma | Authoring | The document as a model, not a rendering: clause structure, typed units, renderings |
+| Primmel | Modeling | The standard as executable rules: constraints, calculations, sequences |
+| The engine (this system) | Serving | Cited answers, verdicts, proofs of absence, edition awareness, on the SDO's own domain |
+
+A deployment is white-labeled to the SDO (`ai.<sdo>.org`, their theme,
+their identity provider), so the brand decision here concerns the
+product the SDO buys — the engine and its integration contract — not the
+name their users see. The staircase is the cross-sell narrative: plain
+text answers 2 of 18 capability probes, Metanorma-authored content
+unlocks typed retrieval, and Primmel models unlock execution.
+
+---
+
+## Option 1 — a new high-level product (recommended)
+
+**Category.** A standards-intelligence platform for standards
+organizations: grounded question answering, conformance checking by
+execution, and corpus verification over the SDO's own publications.
+
+**Promise.** Your members ask; your standards answer — every claim
+cited to the clause, every conformance question decided by executing
+your own rules, on your domain, under your brand.
+
+**Buyer.** The SDO secretary general, publication director, or the
+owner of the member-services programme. This buyer purchases member
+value and organizational authority, not tooling.
+
+**Name candidates** (the decision this document defends is the level,
+not the word; candidates for the naming sprint):
+- *Anneal* — coined from the project's own methodology (knowledge
+  annealment), family-fits Metanorma and Primmel as a coined single
+  word, and the methodology is already published in the whitepaper.
+  Cost: it needs one sentence of explanation, as Metanorma once did.
+- *Verdict* — named for the flagship capability (conformance by
+  execution). Strong and concrete; crowded trademark space.
+- *Plain descriptive* ("Standards Answers Platform") — fastest to
+  understand, weakest to own; workable as the category label whatever
+  the brand is named.
+
+Deployment-level naming pattern: `[SDO] Answers`, powered by the
+product — mirroring how OIML SMART AI presents today.
+
+**Suite mechanics.** The product consumes Metanorma renderings and
+Primmel packages as profile inputs. The measured staircase is the sales
+tool: it shows an SDO exactly which capabilities their current content
+unlocks and what the next layer buys. Each layer sells the next without
+the next being mandatory.
+
+**Go to market.** Direct to SDOs that already author in Metanorma
+(shortest path to the full staircase), with OIML SMART AI as the
+reference deployment and the whitepaper as the technical proof. The
+publisher profile is the integration contract an SDO's team can
+evaluate in an afternoon.
+
+**Risks.** A new brand costs market education, and the product must
+carry its own demand generation. Mitigated by the reference deployment
+and by the suite story, which lets Metanorma's existing SDO
+relationships do the introductions without lending the product
+Metanorma's name.
+
+---
+
+## Option 2 — a Metanorma family product ("Metanorma Answers")
+
+**Category.** The AI layer of the Metanorma toolchain: answers and
+execution over Metanorma-authored corpora.
+
+**Promise.** Standards you author in Metanorma become answerable and
+executable, automatically.
+
+**Buyer.** The existing Metanorma buyer: standards editors and
+toolchain owners inside SDOs.
+
+**Name.** Rides the family: Metanorma Answers, Metanorma AI.
+
+**Suite mechanics.** Collapses the serving layer into the authoring
+brand. The staircase still exists technically but is branded as one
+product's capability tiers.
+
+**Advantages.** Fastest to market: the brand exists, the relationships
+exist, the story ("author it, then serve it") is one sentence.
+
+**Risks — the reasons this is not the recommendation.**
+- It implies the content must be Metanorma-authored, which the engine
+  does not require; SDOs with legacy corpora would read themselves out
+  of the market.
+- It caps the product as a toolchain add-on in the buyer's mind, and
+  the buyer is wrong: the person who buys member-facing answers is not
+  the person who buys the authoring toolchain.
+- It spends Metanorma's brand equity on a service with different
+  quality attributes (a wrong answer damages the authoring brand's
+  credibility by association).
+- It forecloses the Primmel story: execution-the-top-of-the-staircase
+  deserves its own co-branding rather than being a feature of the
+  authoring tool.
+
+---
+
+## Option 3 — a Primmel family product
+
+**Category.** The serving and execution surface of the Primmel model
+world.
+
+**Promise.** Ask your Primmel models anything; the answers are
+computed, not retrieved.
+
+**Buyer.** Modelers and the (currently small) Primmel community.
+
+**Risks — disqualifying today.** Primmel is the youngest brand with the
+least market recognition; the engine is not about Primmel (retrieval,
+enrichment and citation machinery stand entirely apart from the model
+plane); and equating the product with executable models under-sells the
+90 percent of the system that works on plain corpora. This route
+becomes interesting only if Primmel itself becomes the strategic brand
+of the estate, which is a larger decision than this one.
+
+---
+
+## Comparison and recommendation
+
+| Criterion | New product | Metanorma sub-brand | Primmel sub-brand |
+|---|---|---|---|
+| Buyer fit | Secretary/publication director (the one with budget for member value) | Toolchain owner | Modeler |
+| Implies Metanorma required | No | Yes | No (implies Primmel) |
+| Brand risk to existing products | None | Answers' quality reflects on Metanorma | Ditto |
+| Time to market | Slower (new brand) | Fast | Slow |
+| Ownable position | The category itself | A feature of a toolchain | A feature of a modeling tool |
+| White-label per SDO | Natural | Awkward (whose name does the SDO's user see?) | Awkward |
+
+**Recommendation: Option 1.** The engine is architecturally,
+commercially and reputationally a distinct product. Bring it to market
+as a new high-level brand, marketed as part of the suite — *authored in
+Metanorma, modeled in Primmel, served by [new brand]* — with each
+deployment white-labeled to the SDO. Run the naming as its own short
+sprint with proper trademark screening; "Anneal" is the internal
+candidate with the strongest story.
+
+**What would change this answer:**
+- If the go-to-market constraint is the next two quarters and Metanorma
+  channel relationships are the only realistic demand source, Option 2
+  becomes the pragmatic bridge — ideally as "X, from the makers of
+  Metanorma" rather than "Metanorma X", preserving the exit path to a
+  standalone brand.
+- If the estate decides Primmel is the strategic brand everything else
+  rides on, revisit Option 3 — but that is a portfolio-level decision.

package/docs/projects-design.md

@@ -0,0 +1,88 @@
+# Projects — design (draft for review)
+
+> The question: should chats group into **projects** that share a
+> per-project contextual memory? Yes — and the parts already exist.
+> This is the design; nothing is implemented yet.
+
+## 1. Prior art — what the best got right and wrong
+
+| System | Model | What we take | What we avoid |
+|---|---|---|---|
+| **Claude Projects** | knowledge files + custom instructions scoped to a bucket of chats | per-project memory *files* (not a single prompt box); chats join/leave freely | no file-version awareness (stale PDFs silently ground answers) |
+| **ChatGPT Projects** | pinned docs + project instructions; every chat in the project sees them | explicit membership: a chat is IN a project, visibly | memory edits don't re-trigger anything — old answers keep their old grounding, undiscoverably |
+| **Notion/Linear "projects"** | a project is a *container* with its own views and defaults | defaults ride the project (scope, language), not the client | — |
+| **GitHub repos** | shared context = files in the tree; issues/PRs reference them | memory files are addressable objects (ids), not ambient goo | — |
+
+The failure modes to design against: **invisible grounding** (an answer
+shaped by memory the user forgot was on), **stale memory** (edited file,
+cached answers), and **membership confusion** (chat drifts between
+projects).
+
+## 2. The design
+
+A **project** is a container that owns: member-scoped memory files,
+default database scope, and a set of conversations. Everything else in
+the ask path already exists.
+
+### Data model (D1)
+
+```sql
+projects (id, sub, name, default_datasets TEXT, created_at)
+  -- memory files move from user-level to project-level:
+project_files (id, project_id, name, content, updated_at)
+  -- conversations gain an optional home:
+ALTER TABLE conversations ADD COLUMN project_id TEXT NULL;
+```
+
+Per-user today's `memories` table remains the *personal* tier; project
+files are the *shared* tier. The ask accepts both; the note builder
+labels them: "the user's personal memory" / "the project's shared
+memory".
+
+### The three rules that make it honest
+
+1. **Selection is visible and per-question.** The memory chips the
+   answer USED are echoed in the response (`context_applied` gains a
+   `memory: [...]` block) and rendered on the message — an answer shaped
+   by memory says so, on its face. (The context-chip echo already works
+   this way.)
+2. **Memory salts the cache.** Already shipped for personal memories
+   (#185): the file-id set is part of the cache key. Project memory
+   joins the same salt — edit a project file, and every keyed answer
+   for that selection misses and regenerates.
+3. **Membership is a move, not a copy.** A conversation belongs to at
+   most one project (a nullable `project_id`); moving it re-scopes its
+   NEXT answer, never rewrites history. Old messages keep their
+   recorded grounding (the `context_applied` column already persists
+   per answer).
+
+### UX
+
+- Sidebar: a **Projects** section above conversations — project rows
+  with their conversation counts; selecting one filters the list and
+  sets the composer's default scope/memory (visible as chips under the
+  composer, toggleable like datasets/memory rows — one grammar users
+  already know).
+- Project settings drawer: name, default databases, shared memory files
+  (the same editor modal as #171), and the member list when sharing
+  arrives.
+- A conversation outside any project behaves exactly as today.
+
+### What projects unlock next (the payoff)
+
+- **Team tier**: `project_members` — shared memory becomes the lab's
+  institutional memory ("our instruments, our classes"), the natural
+  members'-side feature.
+- **Cross-chat continuity**: a project summary (the existing history
+  summarizer, run over the project's conversations) grounds *new*
+  chats in what the project already established — continuity without
+  leaking between projects.
+- **Reproducible scoped sessions**: default scope + shared memory +
+  the corpus generation stamp = an answer set a reviewer can re-run.
+
+## 3. Effort
+
+Small: two D1 tables + one column, CRUD that mirrors #171's handlers,
+an echo field, and sidebar/composer UI in the shipped grammar. The
+expensive-looking parts (injection, salting, toggles, echo) already
+exist from the dataset-scope and memory work.