**Class:** misleading · **Severity:** material
**Flow:** arch-90c90751344f · **Step:** running a command before docir init
**Question:** issue-b86a75d656ea · **Frequency:** any user who forgets `docir init` — the second step of the quickstart

## Finding

Commands run in an uninitialised repository silently fall back to the global `~/.docir` and succeed, writing documents outside the repo.

## What happens today

`Settings.resolve` returns the global default with no signal (settings.py:104), and `load_schema` writes a default schema on first touch (schema_loader.py:26-31). `docir add` reports success and a relative path that looks repo-local.

## Impact

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

## Proposed default

Report the resolved store (and whether it was discovered or defaulted) in write-command output, or warn once when falling back to global.

## Resolution

FIXED 2026-07-29, taking both halves of the proposed default rather than choosing between them, because they address different things. (1) Every write reports the resolved `store`. This is the part that fixes "misleading": `path` is relative to the *store*, so it read as repo-local wherever the store actually was, and nothing in the payload named it. Zero noise, machine-readable, and it removes the ambiguity for every write whether or not anything warns. (2) A stderr warning, but ONLY when the global fallback happens inside a git repository. `Settings` now records `home_origin` (flag | env | project | global) and `is_unintended_global_fallback()` combines it with an upward walk for `.git` — the same walk `discover_project_home` does, one directory name over. THE NARROWING IS THE DESIGN, NOT AN OPTIMISATION. The global store is a real feature for personal notes, so falling back to it is not an error and erroring would break that workflow. Warning on *every* fallback would fire on correct usage — the issue-9cb85759076d/issue-40d1792bc9f9 failure mode, hit three times in this codebase already. Inside a repo with no `.docir/` is the one case where the user almost certainly meant the repo. NO NEW FLAG for the opt-out: setting `DOCIR_HOME` takes the `env` branch rather than the fallback branch, so someone who does mean the global store from inside a repo already has a way to say so. Pinned by test_explicit_docir_home_opts_out. Verified on the real CLI across all three shapes: repo without `.docir` warns, plain directory does not, repo with `.docir` does not — and `store` is present in all three.

## Actors affected

- repository maintainer
- AI coding agent

## Evidence

- `src/docir/config/settings.py:96-104`
- `src/docir/modules/documents/infra/schema_loader.py:26-31`

---

Migrated from the discovery gap register (GAP-023); the register itself now lives in this store.