1 files changed, 55 insertions, 0 deletions
diff --git a/docs/decisions/0001-storage-path-default.org b/docs/decisions/0001-storage-path-default.org
new file mode 100644
index 0000000..539cba7
--- /dev/null
+++ b/docs/decisions/0001-storage-path-default.org
@@ -0,0 +1,55 @@
+#+TITLE: ADR-1: Storage path default
+#+DATE: 2026-04-30
+#+STATUS: Accepted
+
+* Context
+
+The glossary is a single org file. The package needs a default location
+that integrates with the user's existing org workflow when one exists,
+and falls back gracefully otherwise. The choice is visible to users via
+the =gloss-file= defcustom and to the file system as the path that gets
+auto-created on first save.
+
+* Decision
+
+Default =gloss-file= to:
+
+#+begin_src emacs-lisp
+(expand-file-name "gloss.org" (or org-directory user-emacs-directory))
+#+end_src
+
+If =org-directory= is set, the glossary lives next to the user's other
+org files. If it isn't, the glossary lives under =user-emacs-directory=
+(typically =~/.emacs.d/=).
+
+* Consequences
+
+*Positive.*
+
+- Users with an established =org-directory= get the glossary in their
+  org tree without configuration.
+- Users without =org-directory= still get a sensible default path that
+  doesn't require a directory tree to exist.
+- The path is writable on every supported platform without privilege.
+
+*Negative.*
+
+- =user-emacs-directory= isn't intended for user data — it's
+  configuration. Users who care will set =gloss-file= explicitly.
+- A user who later sets =org-directory= won't see the glossary move.
+  =gloss-file= is captured at defcustom evaluation time, not on each
+  call. This is documented in the README troubleshooting section.
+
+* Alternatives Considered
+
+*Hardcoded path* — e.g. =~/.gloss.org= or =~/gloss.org=. Rejected:
+ignores the org-directory convention; doesn't respect user
+preferences for where data lives.
+
+*XDG_DATA_HOME* — e.g. =~/.local/share/gloss/gloss.org=. Rejected:
+correct in spirit but adds a layer the user doesn't otherwise see in
+their org workflow. The whole point is "this is one of your org
+files."
+
+*Package-data dir* — e.g. inside the gloss package's install location.
+Rejected: data shouldn't live with code; survives reinstalls poorly.