docs: record four ADRs for gloss design decisions

The four decisions called out in the brainstorm now have their own
files under docs/decisions/, each with Context / Decision /
Consequences / Alternatives Considered.

- 0001 — storage path default: respects org-directory if set, falls
  back to user-emacs-directory.
- 0002 — auto-fetch on local miss: silent fall-through, network
  failures surface via the regular error rollup. No y/n prompt for
  v1.
- 0003 — drill direction: every entry exports as twosided. One card
  per entry, both directions over time, no per-entry override.
- 0004 — HTML strip strategy: libxml-parse-html-region. Plain text
  only, no italic/bold preservation. Online fetch disabled package-wide
  for the session if libxml is missing.

The "Open Questions" section in the design doc is now "Decisions
Recorded" with links into the ADRs.

1 files changed, 51 insertions, 0 deletions

diff --git a/docs/decisions/0002-auto-fetch-on-local-miss.org b/docs/decisions/0002-auto-fetch-on-local-miss.org
new file mode 100644
index 0000000..399d520
--- /dev/null
+++ b/docs/decisions/0002-auto-fetch-on-local-miss.org
@@ -0,0 +1,51 @@
+#+TITLE: ADR-2: Auto-fetch on local miss
+#+DATE: 2026-04-30
+#+STATUS: Accepted
+
+* Context
+
+When the user runs =gloss-lookup= on a term that isn't in the local
+cache, the package can either prompt before going online or fall
+through silently. The trade-off is between explicit consent (no
+surprise network calls) and frictionless typical use.
+
+* Decision
+
+Silent fall-through. On a cache miss, =gloss-lookup= calls the online
+fetcher without asking. Network failures surface clearly via the
+error rollup (see ADR on the error taxonomy in the design doc).
+
+If a user wants a strict offline mode, they can wrap =gloss-lookup= or
+unbind =gloss-fetch-sources= to nil. v1 does not ship a defcustom toggle.
+
+* Consequences
+
+*Positive.*
+
+- The common case (term not in glossary, want a definition) takes
+  one keystroke (=C-h g g=) instead of two.
+- The user-facing message on a network failure is the same shape as
+  any other failure mode — there's no special "you would have hit
+  the network" affordance to explain.
+
+*Negative.*
+
+- A user on a metered connection or in a restricted environment
+  might prefer an explicit prompt. v1 doesn't accommodate that.
+- A typo on the term means a wasted network call. The cost is small
+  (one HTTP request to Wiktionary) and the failure is fast.
+
+* Alternatives Considered
+
+*y/n prompt before fetch.* Rejected: the answer would be "yes" 99%
+of the time, and the prompt becomes friction the user trains
+themselves to ignore. The 1% offline case is better handled by
+detecting the failure than by pre-asking permission.
+
+*Defcustom =gloss-auto-fetch=.* Rejected for v1: adds a knob with no
+clear default. If shakedown reveals a real need, adding the knob in
+v1.1 is straightforward — silent fall-through is the harder default
+to walk back.
+
+*Hard-fail offline.* Rejected: turns "not in glossary" into a fatal
+error, which is the wrong shape for what should be a soft fall-through.