docir — design documents

How the corpus stays consistent: reindex, check, repair, and the merge guard.

The three tiers deciding what blocks a write, what a check reports and what stays advisory, plus how a schema change is detected against the index build.

With no repository above the store, docir check skips unmatched-code, code-unwatched, code-changed and code-drifted without a word, even when documents declare code globs.

An agent audits a store by trusting docir check's findings at under half the cost of auditing without docir, and a check that could not resolve code globs says so instead of reading clean.

Why check reports code-unwatched for a glob that resolves and carries no digest, why check --fix may repair it when its three siblings need a judgement, and why it is a warning.

What happens when a document is created, edited, archived or deleted: id allocation, schema validation, the index update, and how a diverged file is handled.

How a query becomes results: full-text and vector rankings fused, section-level embeddings, default status visibility, and reads spanning peer stores.

What a document is as markdown: every frontmatter field, what validates it, and the tag registry the tags resolve against.

The command vocabulary agents drive docir with, the static site build, and a worked flow through them end to end.

The three tiers deciding what blocks a write, what a check reports and what stays advisory, plus how a schema change is detected against the index build.

How the corpus stays consistent: reindex, check, repair, and the merge guard.

The shape of the system: git as the source of truth, the SQLite index as a derived projection, the layer map and the daemon — with each part of the pipeline in its own document.

The MUST/SHOULD module rules this codebase is held to, and how CI proves them.

How a decision is captured: validate, allocate an id, write the file, project the index.

How a repository gets a store and an agent learns to drive it.

How the controlled vocabulary is registered, renamed and retired.

How a task turns into a ranked document set: hybrid fusion plus graph expansion.

Why lint --deep gets no contradiction-candidate finding: the embedder scores subject and not stance, and every threshold reaching this corpus's three recorded contradictions admits sixteen thousand pairs.

Why check --fix reads commit history to pick the established document, and why a filename tiebreak now says it could not tell.

Why delete refuses an id more than one file claims whatever flags it is given, and why that refusal reads the files rather than the index.

Why docir_doctor is the second exception to one-tool-per-dispatcher-command, and why the composition and payload moved out of the CLI to get there.

Why the ambient update notice is opted into by `docir init` rather than a shell, what it refuses to tell a checkout, and where MCP carries it.

Why check gains --against rather than a command of its own, why both its findings are errors, and why an unreadable ref must not be silence.

Why check reports code-unwatched for a glob that resolves and carries no digest, why check --fix may repair it when its three siblings need a judgement, and why it is a warning.

Why .gitignore drops files from a code: glob only while the glob reaches something else, and why a glob that reaches nothing but ignored files is honoured instead of erased.

Why the fingerprint behind code-drifted consults the repository's own .gitignore files, and only those — not git check-ignore, not the user's global excludes.

Why the model is cached in the user-level ~/.docir/models, passed as fastembed's cache_dir argument rather than left to its temp-directory default.

Why the writing skill forbids appending a dated section for every change, and why that rule ships as prevention rather than as a new lint finding.

Why the deprecation register is a command and a tool, what test lets it be one when the rest of doctor is not, and why it is not folded into store_status.

Why new meaning goes in a new key older builds ignore, why the fallback is a store_format floor read before the schema resolves, and why neither reaches a build already installed.

Why drift is measured from a baseline the write mints, why that is a second digest beside the verified one, and why re-declaring a glob never clears a drift.

Why deprecations carry a sunset date, why docir doctor is the channel rather than a release note, and why --strict stays green until the date passes.

An inline types: entry missing prefix/statuses/default_status is folded into the resolved type key by key instead of replacing it, so a store can set one property of a core or profile type without pinning the rest.

One max_body_chars per type, read by both tiers; max_body_chars_enforce decides whether it refuses the write or only reports it, so the Tier 2 smell is never a second number.

Why upstream feedback ships as its own opt-in skill that only drafts a report, why it is suggested at every adoption moment but never installed by default, and why the agent never files it.

The eleven shapes that look like catalogue smells and are deliberately kept, and the shared read/write predicate that makes splitting DocumentService a regression.

Why [[...]] cross-references now resolve against ids, filename stems and title slugs, why the unresolved ones are a Tier 1 warning where unresolved mentions are not, and why they still feed no check.

A flat reply budget made `docir self upgrade` impossible on a large corpus, because the command that always makes docir's most expensive request was bounded by a number chosen for an ordinary one.

Why a content edit revokes a verification, why the cadence restarts from the revocation rather than from creation, and why only a standing verification can be revoked.

Why check stopped reading the mention graph and gained an isolated: reason instead — a judgement about a queue must not empty the queue.

Why an absent `verified` falls back to `created` rather than `updated`, and why absent is not treated as infinitely stale.

Why a fresh clone or git worktree now rebuilds its index on open instead of failing until someone runs reindex, why only the empty case qualifies, and why the embedding drain stays off that path.

Why a store describes itself in its own stores.yaml, and why that sentence rides on every federated row beside the store path.

Why every change touching a committed file, the on-disk contract or the index schema is run against the docir release on PyPI, in both directions, before it ships.

Why an index holding nothing beside files on disk is an error rather than a warning: --strict was a merge gate that passed by reading nothing.

One flag was answering two questions — where two types sit, and whether one waits for the other — so a decision refining a superseded one read as ready to start.

query --expr filters on an expression over each document and its resolved edges, which is the ability to state a rule without docir shipping any.

Why the environment checks scattered across five commands became one command, and why the corpus is deliberately not part of it.

The two questions store checks left open answer to 'nothing to add', and answering them found that a mistyped field matched nothing silently.

Giving implements a machine meaning would warn on ordinary modelling, so it stays a word for the reader — and a kind gains a property on evidence, not on symmetry.

checks: in docs-schema.yaml runs a store's own JMESPath rules as Tier 1 warnings, which is how docir gains a validator without gaining an opinion.

Why the packaged CLI guide became SKILL.md plus one-level-deep reference files, and why installing a skill sweeps the files a build no longer ships.

Prose naming a source path is not evidence a document governs it — the examples, the historical records and the inventories are indistinguishable from the text.

The gates pass on defects that only a real store with history and a warm daemon exposes — 0.18.0 shipped three of them past a fully green suite.

Why get takes several ids and id#heading addresses in one request, why the plural payload key rather than the result count decides the reply shape, and why an address that does not resolve is data instead of an error.

Query rewriting belongs at the caller, which is a frontier model that has read the code, so docir ships no generative model and accepts several queries instead.

Rewriting a query with its top hits' own words costs 0.13 recall@5 on docir's corpus, because the first pass is already good enough that feedback only drifts.

Interleaving per-query rankings keeps what a correct extra phrasing finds while bounding what a wrong one costs — the only one of three fusion shapes that does both.

A business feature is done when an agent holding only the installed package can tell what it is, when to reach for it and how to invoke it — and somebody has followed those instructions to check.

Weighting the literal task removes --also's gain along with its risk, because an extra query is powerful exactly to the degree it can outvote the task.

Why docir agent update reports 'unchanged' when a release moved only the version stamp, and why the file is rewritten anyway.

Why ids named in a body become mention edges, why no Tier 1 check reads them (orphan did, until adr-e98749aa457d), why they stay out of frontmatter, and what following them cost in the benchmark.

Retire reindex --embeddings instead of repairing it: it recomputed exactly the vectors a rebuild recomputes anyway, for the same time, and skipped both stamps.

Why --verified fingerprints the globs a document governs, why the digests live in the file, and why the resulting code-changed finding stays a warning.

Why the command run after a schema edit reports what that schema costs the corpus, reads files rather than the index, and never changes the exit code.

Why the AGENTS.md block became a pointer (description + path) and now always installs the skill it names, instead of embedding a second copy of the guide.

Why documentation-writing rules ship as their own opt-in skill rather than a section of the CLI guide, and why the length rule is a section limit rather than a word count.

Why the command-resolution guard covers CLAUDE.md and the project store as well as the shipped guide, why a retired binary name needs a separate check, why the unreal-command exemption list may only shrink, and why type/status values are checked against the shipped vocabulary.

Why docir update can retype a document while its id and prefix stay put, and why a schema can subtract a type the core or a profile contributed.

Why docir build renders mermaid fences as diagrams, and why the runtime is a build input like --logo rather than a vendored asset.

Why docir reads fan out across a committed list of peer stores, why peers are opened read-only, and why the merge sorts on similarity rather than score.

One command for the steps that follow a new docir release, and why installing the new docir is not one of them.

How docir self upgrade installs a new docir, which installs it refuses to touch, and why the release check is opt-in.

Why a store records the resolved schema it was built against, why reindex is the only thing that advances it, and why the finding is a warning that must never become an error.

Gap 6 closes as a decision: a testable decision is bound to the test that enforces it, CI prints the decisions a branch touches as a notice, and docir builds no DSL, sandbox or per-language analyzer.

Custom relation kinds could join none of the sets that decide cycles, layering and successor traversal, so they were silently exempt from all three; symmetric/dependency/successor become declarable properties.

Why the published index shows applied filters as removable chips, accepts tracker-style tokens (type:x, is:stale, -status:y), records each facet step in history, and dims zero-count options instead of dropping selections.

Why docir build emits graph.html — a deterministic per-type constellation map of the corpus — plus a landing-page index, and why the graph is a domain projection (graph_payload) rather than a second data path.

Why docir mcp serve is a third client of the dispatcher rather than a second implementation.

Why per-section vectors exist: 56% of the corpus was outside the model's token window and absent from the semantic index.

Why docir build renders a static site, and why the module takes JSON rather than a DocumentService.

Why docir has no reranker: three models and three shortlist widths all ranked worse than plain RRF fusion.

Why the tag-key grammar lives in platform rather than being written twice or crossing a module boundary.

Why a real embedding model is the default and the hashing embedder only the fallback.

Why a qa profile, a release_note type and schema introspection were added.

Why a project-local .docir store is discovered the way git finds .git.

Why agent-instruction scaffolding is a self-contained module that bypasses the daemon.

Why the schema is a frozen domain-agnostic core plus swappable domain profiles.

Why relation edges carry a kind, and how the on-disk form stays backward compatible.

Why staleness is owner + verified + review cadence data rather than a heuristic.

Why tests live in a central tree mirroring the modules instead of beside them.

Why no authorization or cross-cutting machinery exists in a single-user local CLI.

Why one shared SQLite schema and unit-of-work spans all contexts, and what that costs.

Why the codebase is vertical bounded-context modules with tach proving the boundaries in CI.

With no repository above the store, docir check skips unmatched-code, code-unwatched, code-changed and code-drifted without a word, even when documents declare code globs.

Why add --code a --code b wrote only b, and why every list flag now takes both the repeated and the comma-separated form.

Why a repeated tag failed every reindex, why a repeated glob or edge made --replace-body refuse the document for good, and where the repeat is now dropped.

Why a pinned uv-tool receipt made `docir self upgrade` claim the newest build, and what docir now says instead of guessing.

The guard uses tmp_path for a home it asserts is not under the temp directory, so it fails on Linux whatever the code does, and a symlinked temp dir hid that on macOS.

update, archive and unarchive act on one of two files claiming an id without saying which; nothing is lost, but the edit lands somewhere the caller did not choose.

Two branches off one base allocate the same next id; nothing warns before the merge, and check --fix picked the survivor by filename whenever both were created the same day.

Every step of delete reads the index, which holds one row per id, so a delete against two files claiming one id acts on a file nobody chose and breaks edges to the survivor.

fastembed builds its ONNX session with no thread limit unless one is passed; DOCIR_EMBED_THREADS caps it, and the daemon respawns when it changes.

The fix for issue-ec3819b1f13c excluded ignored files from matching as well as fingerprinting, silencing every document governed by a vendored or mirrored source.

The oracle checks that each line the prose carries resolves; nothing checked that every command is carried, so doctor and two daemon subcommands went unlisted.

A glob declared before the code it governs records no digest, so no finding reads it and no edit to that code is ever reported.

Line numbers move with every insertion above them; five documents carried citation columns that had shifted wholesale, and a sample of eighteen in-bounds ones found seven pointing at the wrong symbol.

_normalize strips a leading dot as a character class, so a document governing .github/workflows/** can never be returned by the reverse query — while check's own matcher, which does not share the function, reports its drift correctly.

The generated ignore list omits release-check.json, and an existing store's copy is written once by init and never brought up to a later release — so the feedback/ entry never reaches the stores that predate it.

The federated reader caches each opened peer per container, so a peer repaired after first contact keeps being skipped over the socket while --no-daemon reads it — and the comment beside the cache promises the opposite.

cli_oracle had two extractors and they disagreed about fenced code, so a dead command name sat in an architecture note's worked example with every prose guard green.

Both read Settings.socket_path directly to report it, so the sandbox that made every dispatched command fall back still ends these two in a traceback.

The daemon loads the schema once at startup, its watcher does not react to the schema file, and nothing stamps that file into the pid record — so a schema change is honoured only in-process until the daemon is stopped.

The client spawns the daemon on first dispatch and has no fallback, so a sandbox that denies the socket or log directory turns every read into a traceback — though --no-daemon answers the same read.

fastembed's default cache is under the temp directory, so the 64 MB download is re-paid whenever the OS sweeps — and where there is no temp directory, every read crashes before docir runs.

Every file under a code: glob is hashed, ignored ones included, so one compile drifts every document governing a source tree that holds build output.

code: patterns ending in ** fingerprinted __pycache__ alongside the source, so a digest moved when no line was edited and differed across machines.

The client spawns a daemon, waits, and reports the wait — so a store whose schema will not load reaches the caller as a timeout instead of the reason, which stays in daemon.log.

docir mcp serve dies in build_server when the schema will not load, so the client sees only a closed connection where the CLI prints the error that names the fix.

Drift digests are written only by --verified, and in docir's own store none of the 99 documents naming the code they govern ever was — so nothing reported when that code moved.

doctor carries every dated announcement and has no MCP tool, so the agent the dates were written for cannot read them.

A partial type block loads only on an unreleased docir, so every command refuses for anyone on the current release — and it has already disabled docir's own published-build check.

The one audited smell still untreated: 2,072 lines over CSS, the index page, the document page, the chips and the markdown pipeline.

162 prose links in a maintained store were parsed by nothing: build published brackets, a retitle broke inbound links in silence, and finding the one that was broken took four hand-written passes.

`resync` keys the full rebuild on docir's version, so a release that changed neither the model nor the chunking still recomputes every vector — 58.4s against 1.5s on this repository.

An older build finds a migration revision it does not ship and dies in alembic before any docir code runs, so the finding that exists to report exactly this is never reached.

A verification could be stamped and never withdrawn, so correcting a bad stamp meant the hand-edit the CLI exists to prevent.

Staleness fell back to `updated` when `verified` was absent, so writing a re-check into a document nobody had vouched for cleared it from the review queue.

Naming an id in prose cleared the orphan warning, so writing the triage of the orphan list closed every id on it — including the ones the triage said were still unwired.

The read/write round trip on one section duplicates its heading, and no edit mode but --replace-body --force can undo it.

update and get answer 'no document with id' in any checkout whose derived index was never built, so the message denies a document that is on disk.

skill and README named mermaid 10.9.3 on the false grounds that 11 is ESM-only, while docir's own pages.yml published with 11.16.1.

The model cache never hit: the workflow cached ~/.cache/fastembed while fastembed 0.8 writes to $TMPDIR/fastembed_cache, so every run re-downloaded 64MB.

check --strict ran on a gitignored index, so dangling edges — half the merge guard — never fired; CI now reindexes and runs doctor --strict first.

A job-level env used the runner context, so GitHub rejected ci.yml and zero jobs ran; actionlint now gates workflows locally and in CI.

The port declares a vector-width property nothing outside the embedding package consumes, and the fastembed adapter keeps it correct with a self-correcting field the library can answer directly.

bge-small-en-v1.5 is compiled in as the only real embedder, so a corpus not written in English retrieves worse than plain full-text search, with nothing to report it.

benchmarks/ lives in the repository, so an adopter inherits docir's retrieval numbers as a claim with no way to reproduce them on their own documents.

context and search return score and similarity with none of the terms behind them, so an agent cannot tell a bad ranking from an empty corpus and ranking changes are debugged with print statements.

Both halves are answered: the model-free rewrite measured worse, and generation is closed by adr-27c63ad02695 — what remains is accepting caller-supplied queries.

docir build parses bodies with the CommonMark preset, which passes raw HTML through, so a script tag in a contributed document runs on the published site.

The --embeddings flag re-embeds exactly what a plain reindex already re-embeds, for the same time, while skipping the two stamps the rebuild writes — so it is dominated by the command it modifies.

docir self upgrade ran an unconditional full reindex, and 96% of that is re-embedding: 58.4s of 60s on a 315-document store whose files had not moved.

docir update patches every other frontmatter field but not type, so retyping a corpus means hand-editing the markdown the CLI exists to own.

merge-forward keeps the first heading, then the merged block hard-splits, so the second section's heading names no chunk and matched_section can never point at it.

A repeated heading makes --section resolve to the first occurrence and leaves the second unreachable by name, silently.

Every profiles: key merges the core unconditionally, so decision and its adr prefix exist in every store — an unused name stays addable and its prefix cannot be reused.

markdown_sections.py has no fence tracking, so --section returns a fragment ending in an unclosed fence and --replace-section silently orphans the rest of the body.

26 documents, 30 sections, none over the chunk ceiling and none quoting a fenced heading — so the splitter never runs and a chunking regression scores identically.

Startup still dominates after the SQLAlchemy fix: ~0.49s of a 0.53s warm-daemon read is process start and imports. What remains is pydantic-settings (~97ms) and docir's own 130 modules.

Both halves shipped: query --expr asks a question, and checks: in docs-schema.yaml states a rule the store runs.

test_an_empty_store_says_so holds or fails on where rich broke the line, which depends on the tmp path inside the message.

schema-drift reports a schema change after the fact; nothing renders the effect of an edit beforehand, and the file's meaning is not its text because the core and profiles merge into it.

unknown-tag and unknown-status are reported, but an edge carrying an unregistered kind is served by get, traversed by context and flagged by nothing; only rewriting it is refused.

Adding 'required:' to a live type leaves every existing document in violation with no finding of any kind; the first report is an unrelated update failing, one document at a time.

docs-schema.yaml has no version and the index records nothing about the schema it was built against, so a release editing the core or a profile changes what every store enforces with no local edit and no report.

No frontmatter field points at code, and the schema's 'required' hook that appears to allow one is unsatisfiable — which blocks enforcement against code and AST-anchored staleness alike.

Chunk vectors decide the ranking and the winning ordinal is discarded before the result is built, so an agent must fetch the whole body or discover headings in a second round trip.

The flag takes heading text and adds the ## itself; passing '## Resolution' silently writes '## ## Resolution', which no section-edit mode can repair.

'required:' accepts any name but is checked with getattr on the entity, so an unsatisfiable name loads fine and then rejects every add of that type, naming the write rather than the schema.

A cycle is only meaningful for relation kinds that assert direction; counting the default symmetric kind made 120 correct edges unrecordable in this store.

Nothing compares the running daemon's version against the installed one; after an upgrade or a source edit every command is answered by the old code, and the wrong answer looks normal.

Every client-side daemon error escapes the CLI's error mapping, so the default execution mode reports failure as a stack trace.

Coverage checklist: "Admin: who can override a rule, and is the override audited?" — the override exists, the audit does not.

On docir's own corpus all 14 duplicate findings are pairs already joined by an edge: the relation is the answer to the finding.

Every confirmed failure mode in this analysis ends in a state the product detects and cannot exit, and the documented recovery contradicts the product's second thesis.

A typo in `FastEmbedEmbedder.embed` would have shipped green to every default install.

ADR-0006 argues staleness must be honest human re-verification; a bulk administrative edit silently forges it.

The most likely adopter is precisely a project that already keeps ADRs in markdown — the audience the product describes.

The command exists to catch schema edits before they reach a write; this is the most likely schema error and it passes.

Tier 0 accepts a self-edge; `docir check` then reports a one-node cycle that no edit but removing the edge can clear.

'Knows what's stale' is one of six rows in the README comparison table. Detection works; the loop that would make it matter is absent.

Documents intended for a repo land in the user's home directory, ungitted and invisible to teammates, with no error at any point.

Contradicts a documented invariant.

The most natural thing a user will model produces a warning they cannot silence, which trains them to ignore `check` output — and compounds GAP-006.

Every confirmed failure mode in this run (GAP-003, GAP-007, GAP-009) terminates in a state the product detects and cannot exit.

The registry can only grow.

"Is this decision still current?" is the question the relation graph most needs to answer, and it is the one direction not traversed.

A glossary, a rule register and a probe log are long by definition; the check has no way to know that and advises splitting them.

A user rebuilding after a hand-edit that broke frontmatter is told the rebuild succeeded.

A third route to a duplicate id, and the sharpest one.

A store is created somewhere the user did not ask for, and if the CWD happens to be a repository they now have an unrequested `.docir/` in it — which is exactly what happened to the analyst while…

The single most likely user action outside the CLI has no stated contract.

The most likely adopter is exactly a project already keeping markdown ADRs.

Small per document, paid on every read.

One field is wrong on one rarely-hit path.

Two teammates in different timezones can stamp different dates for the same moment; staleness can differ by a day.

An agent following the guide after a merge gets an error instead of a rebuilt index, and the merge-safety workflow the guide exists to teach silently does not run.

Fires on the documented happy path with no concurrency, no --force and no unusual input. It contradicts the project's first thesis, so the answer also decides whether that thesis…

docir's headline claim is "token-cheap for agents" and `context` is the flagship command with a default limit of 5. The overrun scales with exactly the well-linked corpus the…

An agent asking for current context receives closed work items it was promised it would not see, and cannot tell which results honoured the filter.

An agent that reads output and then hand-writes frontmatter will use the wrong key.

There is a defensible argument for the current behaviour — "the issue this decision resolved is worth seeing even though it is closed" — but nothing states it, and the…

An agent cannot distinguish relevant context from noise, so it either always trusts the results (and is misled on unrelated tasks) or never does.

Compounds Q-003 — the response is unbounded in size and unfiltered in quality.

A user who reaches for the more specific-sounding flag gets nothing and no explanation.

"Parallel agents" is the exact scenario the invariant claims to protect, and `--no-daemon` is the mode most likely to appear in scripts and CI.

Directly negates the product's headline claim.

Coverage checklist: 'who can override a rule, and is the override audited?'

A team that adopts the documented gate gets a red build on day one and will remove it — which also removes the duplicate-id detection that is the gate's stated purpose and the…

Data corruption reachable from a plausible command, shipped in 0.7.0.

The one CI integration the product advertises cannot be adopted as documented.

Launders the one trust signal the product offers.

Minor discoverability friction.

Reasonable design; undocumented, and surprising given tags appear in output.

A command whose entire purpose is "check an edit before it reaches a write" passes the most likely schema error, and the eventual message misdirects.

"Knows what's stale" is one of six rows in the README's comparison table (README:44) and one of four bullets in "The model".

Silent loss of a decision record on the documented happy path.

A once-per-repo onboarding command that reports success while doing nothing; the user proceeds believing their agent knows how to drive docir.

`docir init` is step 2 of the quickstart; forgetting it produces no error.

Once-per-repo onboarding command reporting success while doing nothing.

The guard exists and is computed; applying it to one of five edit modes is a decision nothing records.

Introduced by the GAP-023 fix, which reasoned about writes only.

The fast path silently has different semantics from the full path — deletions are invisible to it.

Vocabularies drift and need consolidating; the registry can only grow.

A bulk mutation reports as a single-key operation.

A dead column that turned out to be load-bearing.

The client reported failure for work the daemon completed, then resent the request — a write slower than five seconds ran twice.

Maintenance hazard only; no user-visible defect.

A nested `.docir` captures every command run beneath it, and the parent store's `check` never sees those documents.

Not a defect in the code; a defect in the ability to make decisions about the code.

Under-return looks like corpus scarcity rather than filtering.

'Is this decision still current?' is the question the relation graph most needs to answer, and it is the one direction not traversed.

Two agents will produce `auth`, `Auth` and `authentication` and nothing objects.

Detection is good; the exit is undocumented.

A user querying decisions has no reason to guess that a flag named --include-resolved controls whether superseded decisions appear.

README:42 claims "Retrieval by meaning ✅ (lexical + semantic)" against RAG's ✅ and plain files' ❌.

Latent only.

A harness that cannot move is read as "no regression" when it means "not measured".

Compounds Q-004: it guarantees a finding on the most natural modelling, which trains users to ignore `check` output entirely.

This is why every gap in the register carries `frequency: unknown`, why the retrieval constants (25 FTS candidates, 0.9 similarity, 8000 chars, RRF k=60) cannot be tuned on…

Fine at the 'thousands of documents' scale the id-entropy comment in identifiers.py assumes; nothing states the ceiling or what happens past it.

The graph — the feature that distinguishes docir from a folder of files — silently accumulates unresolvable edges, in the canonical files, permanently.

A user re-running init to refresh the .gitignore destroys a customised schema.

Where docir stands against the retrieval, agent-memory, ADR and spec-driven markets on 2026-08-24, and the six gaps still open.

What score and similarity each mean on a context or search hit, which one --min-score filters, and the two hits it never drops.

What the default embedder costs to install, what the model-free fallback loses, and how a store names a different model.

What the adjacent tools do, where docir is unique, and the ranked list of features it does not have.

Scope, method and budget for the second discovery pass: the surface v0.2.1 never examined, probed rather than read.

The executed probes behind the gap register: what was run, what came back, and what it proved.

The eight actors that drive docir, their goals and their authority (there is no permission model).

47 reconstructed business rules with evidence, examples and boundaries; every one unconfirmed by a human.

The business outcome, scope and coverage the discovery run was framed against.

What was executed against the CLI in the 0.8.0+ pass, what it returned, and the four areas deliberately not reached.

13 terms defined with owner and evidence, including the words that mean two things.

An agent audits a store by trusting docir check's findings at under half the cost of auditing without docir, and a check that could not resolve code globs says so instead of reading clean.

The release check moved out of one person's shell and into the store, and stopped naming a command four of six installations cannot run.

Three reported defects closed, all the same shape: docir answering about something it had not looked at — a daemon it could not start, a file git already ignored, a generated file written once.

A code: glob now reports drift from the write that declared it rather than from a review almost nobody performed, and a store says which docir it needs before an older build fails on the wrong thing.

[[...]] cross-references resolve against ids, filename stems, title slugs and titles, render as the target's current title, and the ones pointing at nothing are a Tier 1 warning; underneath, the six largest classes were split with every surface held byte-identical.

The reply timeout stopped bounding how long a command may take, and vectors stopped being recomputed when nothing the model reads had changed: 146s to 2.6s on docir's own corpus.

What shipped in 0.24.0: a verification that is withdrawn when its content moves, a way to take a stamp back, and the two queues that emptied themselves.

The read/write round trip on one section stopped duplicating its heading, and --remove-section became the exit for a body that already has one.

Opening a store with files and no index now rebuilds it with the vectors deferred, and the miss that used to report the document as gone names the unbuilt index instead.

The release that labelled every federated hit with the corpus behind it, and found that a fully green change can still break every read for anyone a version behind.

`docir doctor` reports the conditions that make docir answer wrongly without failing — added while fixing four of this project's own gates that were green because they read nothing.

The release that made retrieval inspectable: a swappable model, a benchmark an adopter can run, a rank trace, and two ways to hand docir a better question.

checks: lets a store declare its own rules in docir's grammar, and the guard added alongside found that a mistyped expression had been silently matching nothing.

The two transports an agent can use — the installed CLI skill or the bundled MCP server — and why both answer identically.

How a corpus renames a type and keeps the ids it already has: disable_types frees the prefix, then documents are retyped one at a time.

How a store federates reads over declared peers: stores.yaml, --store, why writes and build never federate, and why ranking merges on similarity.

How docir build renders the corpus for the people who approve decisions: the flags, publishing from CI, the --out guard, and mermaid diagrams.

What to run after a new docir release: the package, the derived index, and the generated files — the ones self upgrade refreshes and the ones it does not.

The staged procedure an AI agent follows when reviewing new code.

How to publish docir to PyPI with uv and GitHub Actions trusted publishing.