Decisions
27 decisions described. A decision is a choice made for the project, with its context, its options and what it affects.
| Decision | Date | First line | Links |
|---|---|---|---|
| Bounded neighbourhood | 2026-09-12 | Co-occurrence is accumulated per paragraph and never materialised as a full matrix. Only the fifty best neighbours of each node are kept, ranked by count then by identifier. | 50 |
| Confidence and provenance on every link | 2026-09-12 | Every link carries a confidence between 0 and 1 and at least one provenance. When methods agree, confidences combine and every provenance is kept. The first version stores the score, orders mentions with it, and does not show it. | 9 |
| Core, plugins, preset | 2026-09-12 | The core reads markdown and produces JSON and depends on no office format nor system tool. Readers, converters, importers, viewers and heavy projections are plugins declared in the configuration. The unscoped concordance package is the preset that enables all of them. | 12 |
| Declarative profile | 2026-09-12 | The meta-model is a YAML profile validated by a schema. The engine knows only types, attributes, relations and scores. Adding a type or a relation pair is a profile change, never a code change. | 15 |
| Deterministic identifiers | 2026-09-12 | An entity's identifier is its source name and its relative path without extension or type suffix, slugified; a frontmatter identifier takes precedence. Never a random identifier. The identifier is the page address. | 13 |
| Findings, not failures | 2026-09-12 | A content anomaly becomes a finding, never a crash. The build fails only when the configuration says so. Every check is a pure function in a registry shared by the build and the linter, and a test enforces their parity. | 13 |
| Fonts from a third-party host | 2026-09-12 | The first draft of the theme named its font families by loading them from a public font host, as most static sites do: one stylesheet link, no file to ship. Superseded by self-hosted fonts: a page that fetches a font from another host does not work from the disk, leaks the address of every reader to that host, and contradicts the rule that the site emits no request the project did not choose. | 14 |
| GPL-3.0-or-later | 2026-09-12 | Every package of the tool is published under the GNU General Public License, version 3 or later, and a licence inventory of the dependencies is regenerated and verified before every release; a dependency whose licence is outside the allow-list fails the check, and widening the list is a decision of the maintainers. The wiki a project generates with the tool is the project's own: the licence covers the tool, not what it documents. | 7 |
| ICU message catalogues | 2026-09-13 | Every label of the generated site goes through a message catalogue per locale in ICU MessageFormat, plurals, selections, numbers and dates expressed in the message itself, stored as JSON in the format translation platforms exchange. Message identifiers are typed from the source catalogue, so that a missing key or variable fails the build, and a test checks that every locale carries every key. Messages are resolved at build: the published HTML contains final strings and no localisation library runs in the browser; dates and numbers use the platform formatters. A project overrides any message through the labels of its theme.yaml. | 13 |
| Keyword page threshold | 2026-09-12 | A keyword page exists from three occurrences in at least two files; below that, the word is searchable but has no page. The threshold is configurable, and the build reports how many pages it generated and how many expressions it discarded. | 10 |
| Links are authoritative | 2026-09-12 | A markdown link to another note is the strongest relation the tool knows: confidence 1.00, above anything inferred, and a frontmatter reference comes next at 0.90. What an author wrote is never overturned by what the tool recognised: the relation of a mapped section or of a typed attribute stands, inference only fills what nobody declared, and the page tells a written link from a recognised word by the way it is drawn. A link to a missing file is an error, a link to a document attaches it, a link from a note to itself yields nothing, and several links to one target are one link with several provenances. | 20 |
| Locale per source | 2026-09-12 | Each source declares its locale as a BCP 47 tag, defaulting to the project locale. A language is described by data, never by code: a pack holding its name, its apostrophes, its collation options, its plural suffix rules and its stopwords, which the locale selects together with the type prefixes of the profile for that language; word segmentation and collation come from the platform's Unicode implementation. The engine ships en and fr; a regional variant such as fr-CA uses the pack of its language until a plugin registers a more specific one, other languages are packs shipped by plugins, and a tag with no pack is a build error. The adding a language pack process is the path. | 22 |
| Lock file for human decisions | 2026-09-13 | concordance.lock.yaml, in the configuration repository, records what a person decided and the tool must not reconsider: accepted and rejected links, merged and separated twin resources, rejected term candidates. The build reads the file the lock key names, validates it against its schema and stops on a missing or invalid one, as on a configuration error: a decision is never dropped in silence. The keyword discovery honours rejected_terms, compared on the normalised form of the language pack, and the reconciliation of twin resources the merged and separated pairs, whatever the score; the links are recorded for a later version, and the configuration validator says so. The build log counts the decisions applied. Nothing is ever written into a knowledge repository, and a decision lives next to the configuration, versioned, reviewed like any change. | 17 |
| MinHash for twin resources | 2026-09-13 | The text similarity that helps recognise the forms of one document works on extracted text, never on binary content, and never compares every pair. Each text goes to its comparison form, then to shingles of five words, then to a MinHash signature of 128 functions under a fixed seed; LSH banding, four rows per band, enumerates the candidate pairs, two signatures that share no band being never compared, so that the full matrix is never built. In auto mode the pairs estimated at 0.5 or more have their exact Jaccard index recomputed on the full shingle sets, and the finding gives the share of lines in common; a pair whose word counts differ by more than half is an inclusion rather than a duplicate and its content signal is capped. Resources are sorted by identifier before anything else, so two runs give the same result. | 21 |
| No database | 2026-09-13 | The graph is built in memory and serialised to model.json, canonically sorted and validated by a published schema; concordance render reads it without touching the sources, and a Cypher export is provided for those who want the graph elsewhere. No server, no database and no state between two builds other than the pipeline cache: the model is a file that a pipeline writes, commits, diffs and serves. | 11 |
| One familiar chrome | 2026-09-13 | The default theme looks like a wiki its readers already know, from the analyst to the architect: spaces, a tree, a breadcrumb, a title, the text, a table of contents. What distinguishes the site is not the layout but the right panel, which shows where a subject is evoked elsewhere without anyone having written those references. Four choices hold the chrome together. One type family for the text, headings included, the hierarchy coming from size and weight, and a monospace family for paths and identifiers only. Labels in plain language, "Related pages", "Cited", "Something to correct?", never the vocabulary of the pipeline. No account: the site is static and public, without avatar, profile or share button, and the top bar carries no build statistic. An accent that is rare, marking links and the current position, never a status or a decoration; the dark mode is a second palette measured on its own, not an inversion of the light one. The page reads at three widths, the tree and the blocks of the panel folding as native disclosures where the screen has no room, so that the same HTML serves a phone and a desk without a script. | 28 |
| Paginated mentions | 2026-09-12 | The first twenty mentions of an entity are in the served HTML; the rest loads from a JSON fragment specific to that entity. Never a global index. | 16 |
| Purpose-built contract viewer | 2026-09-13 | The contract of an API is shown by a viewer the tool builds itself, rather than by the interactive API console the specification first named for OpenAPI contracts. That console weighs more than the page budget of the site, expects to fetch the specification over the network, and offers to call the API from the page; the site is static, works from the disk, keeps every page under its budget and never calls the systems it documents. | 35 |
| Reproducible builds | 2026-09-13 | Two builds of the same sources write the same bytes. Every list is sorted canonically before it is written, findings by check, source, path, line and message, entities by identifier, links by their triple, provenances by method, path and line; a step that runs in parallel sorts its results before writing them; nothing random is ever written, and the only timestamp is the at field of the build log, also the at of the build block of the model, pinned by SOURCE_DATE_EPOCH following the reproducible-builds convention. A double-build test and a continuous-integration step compare every file of two builds of the golden corpus, so that a published site can be diffed against the previous one. | 25 |
| Self-hosted fonts | 2026-09-13 | A font family named in theme.yaml is not a download: the project ships its font files itself under the assets of its theme and binds them with @font-face rules in its stylesheet, and the default theme emits no request to any other host. The two families of the default theme, Instrument Sans for the text and IBM Plex Mono for paths and identifiers, ship with the site under assets/fonts/ with their licence, so that a project without a theme of its own reads in them from the disk. A test checks that no page and no stylesheet references a font host. The site therefore works from the disk, behind a proxy that reaches nothing, and without telling a third party who reads which page; the price is a folder of font files, in the site for the default families and in the configuration repository for a project's own, the white label fixture of the tool showing the layout. | 22 |
20 decisions of 27 — pagination by twenty. The Links column counts the related pages, which brings the most central decisions of the journey to the top.