docir — design documents

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.

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 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.

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 only the orphan check reads them, 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 check-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.

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" (app.py:138) 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 assumes (identifiers.py:23-25).

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.

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 nothing refreshes for you.

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

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