Synonyms and homonyms are findings, not tidy-ups: where one word means two things
(`stale`, `resolved`), that is recorded rather than smoothed over.

## document

One markdown file with YAML frontmatter, identified by a type-prefixed id, and the unit of everything docir does: validation, retrieval, relation, staleness.

**Owner:** repo maintainer · **Used in:** documents, indexing, tags, CLI

**Evidence:**
- `src/docir/modules/documents/domain/entities/document.py:19-38`

## index

The derived SQLite projection of the documents — metadata, FTS5 full text, relation graph, embedding vectors and the id counter. Gitignored and rebuildable.

**Owner:** repo maintainer · **Used in:** platform.persistence, documents, indexing

**Conflicts:** 
- *context* the "rebuildable" claim; *definition* "Rebuildable" is true of six of the seven tables. `id_sequences` is part of the index by every structural definition (it lives in the index database, is created by the index migration, is gitignored) but is NOT reconstructed by `reindex`. The word "derived" is doing work it cannot support for that one table, and the consequence is issue-b7ddde3ce860.; *gap* issue-b7ddde3ce860

**Evidence:**
- `README.md:20-35`
- `src/docir/platform/persistence/alembic/versions/0001_initial_index.py`

## stale

OVERLOADED — three unrelated meanings in one codebase: (1) a document past its type's review cadence (the product feature, adr-bd7c4f3c5764); (2) an index row whose file changed out-of-band (`StaleWriteError`, the concurrency guard); (3) an index row for a file that no longer exists (`for stale in uow.documents.all()` in the reindex removal sweep).

**Owner:** repo maintainer · **Used in:** documents.domain, documents.application, platform.errors

**Conflicts:** 
- *context* document_service.update(); *definition* The local variable `stale` (sense 2) sits eleven lines from `self._is_stale(...)` (sense 1) in the same method. Both are booleans about the same document and they mean entirely different things.; *gap* issue-d8295c5c76d1

**Evidence:**
- `src/docir/modules/documents/domain/services/graph_checks.py:84`
- `src/docir/platform/errors/__init__.py:101-104`
- `src/docir/modules/documents/application/services/document_service.py:136`
- `src/docir/modules/documents/application/services/maintenance_service.py:168`

## archived

A document withdrawn from retrieval but kept on disk and in the metadata table. Set by `docir archive`; reversible.

**Owner:** repo maintainer · **Used in:** documents, indexing

**Conflicts:** 
- *context* inactive status; *definition* `inactive_statuses` (e.g. `resolved`, `superseded`, `deprecated`) also withdraws a document from the list read paths. Two independent mechanisms with near-identical user-visible effect, different flags to defeat (`--include-archived` vs `--include-resolved`), and different enforcement points — which is why one of them leaks through graph expansion and the other does not.; *gap* issue-8c37bf22ba3c

**Evidence:**
- `src/docir/modules/documents/application/services/document_service.py:161-188`

## resolved

In the CLI: the flag name `--include-resolved` for "also show documents in an inactive status" — on every type, including ones with no status called `resolved`.

**Owner:** repo maintainer · **Used in:** CLI, documents.application

**Conflicts:** 
- *context* the schema; *definition* `resolved` is a status of exactly two types (`issue` in the software profile, `incident` in ops). For a `decision` the flag means "include rejected and superseded"; for a `policy`, "include superseded and retired". The wire field is named `include_inactive` — correctly — and the CLI renames it to something narrower on the way out. A user asking for decisions cannot guess that `--include-resolved` is the flag they need.; *gap* issue-efc29234eb57

**Evidence:**
- `src/docir/entry_points/cli/app.py:269`
- `288`
- `303`
- `src/docir/entry_points/dispatch.py:116`

## related

The outgoing typed edges of a document (`RelatedRef{target, kind}`).

**Owner:** repo maintainer · **Used in:** documents.domain, platform.persistence, frontmatter

**Conflicts:** 
- *context* on disk vs in the API; *definition* In frontmatter an entry is either a bare id or `{to: <id>, kind: <k>}`. In JSON output the same edge is `{target: <id>, kind: <k>}`. The key is `to` in one representation and `target` in the other, for the same field of the same object.; *gap* issue-8d5b5b45e2fc

**Evidence:**
- `src/docir/modules/documents/domain/value_objects/relations.py`

## level

A per-type integer expressing architectural abstraction height; a dependency edge from a higher level to a lower one is reported as a layering violation.

**Owner:** repo maintainer · **Used in:** documents.domain.schema, graph_checks

**Conflicts:** 
- *context* the shipped software profile; *definition* The levels assigned (decision 3, issue 1) make the ordinary and intended relationship "this decision addresses that issue" a violation. The term's definition and the shipped values disagree about what the ordering means.; *gap* issue-40d1792bc9f9

**Evidence:**
- `src/docir/modules/documents/domain/schema.py:46-47`
- `src/docir/modules/documents/domain/services/graph_checks.py:194-223`

## check / lint

`check` = Tier 1, structural, non-blocking-but-CI-gateable. `lint --deep` = Tier 2, advisory heuristics.

**Owner:** repo maintainer · **Used in:** CLI, documents.application

**Conflicts:** 
- *context* `--strict`; *definition* `check` is documented as producing "warnings rather than failing an agent mid-task" (graph_checks.py:3-5), yet `--strict` turns every one of them into a build failure with no severity distinction. The tier model says these are warnings; the CI integration treats them as errors.; *gap* issue-9cb85759076d

**Evidence:**
- `src/docir/entry_points/cli/app.py:419-456`
- `CLAUDE.md`

## score

The reciprocal-rank-fusion value for a context result.

**Owner:** repo maintainer · **Used in:** indexing.domain, CLI output, README

**Conflicts:** 
- *context* what a reader will assume; *definition* Published as a bare number in agent-facing JSON, where it reads as a relevance measure. It is a rank-position artefact: bounded near 1/(k+1)+1/(k+1) ≈ 0.033, essentially identical for a perfect match and a nonsense query. README:95 says "ordering is the point", which is correct — but the value is still emitted, and nothing prevents an agent thresholding on it.; *gap* issue-93152f7b9213

**Evidence:**
- `src/docir/modules/indexing/domain/scoring.py:44-73`
- `README.md:90-95`

## home / store

The single resolved directory holding docs/, docs-schema.yaml and the index.

**Owner:** repo maintainer · **Used in:** config, CLI, docs

**Conflicts:** 
- *context* naming; *definition* Called "home" in code and `--home`/`DOCIR_HOME`, "store" in the CLI help and adr-20eec6e2e2ca, and "data root" in the `--home` option help — three names for one concept in user-facing text.; *gap* issue-a40dbcc7a19a

**Evidence:**
- `src/docir/config/settings.py:51-104`

## profile

A named bundle of document types layered onto the frozen core schema.

**Owner:** repo maintainer · **Used in:** documents.infra, CLI

**Evidence:**
- `src/docir/modules/documents/infra/profiles.py:41-208`

## skeleton

A `DocumentSummary`: frontmatter, typed edges and staleness, with no body. The unit the list read paths return and the source of the token savings.

**Owner:** repo maintainer · **Used in:** documents.application, README

**Evidence:**
- `src/docir/modules/documents/application/dto.py:84-108`

## owner

A free-form string naming who is accountable for re-verifying a document.

**Owner:** repo maintainer · **Used in:** documents.domain, graph_checks

**Conflicts:** 
- *context* what the word implies vs what it does; *definition* The word implies an accountable party. The field is written, stored, and interpolated into one `check` message — nothing else. It cannot be queried or filtered on, triggers no notification, and is not validated against anything. It names a responsibility the system never routes to anyone.; *gap* issue-b4f441c7210f

**Evidence:**
- `src/docir/modules/documents/domain/entities/document.py:37`