From f6fc37d74f0b027ea7cfb1c6ff5c9e362d8af465 Mon Sep 17 00:00:00 2001
From: Szymon Szukalski <szymon@szymonszukalski.com>
Date: Fri, 10 Apr 2026 13:44:48 +1000
Subject: Add Org refile configuration

---
 docs/plans/2026-04-10-org-refile-design.md | 70 ++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 docs/plans/2026-04-10-org-refile-design.md

(limited to 'docs/plans/2026-04-10-org-refile-design.md')

diff --git a/docs/plans/2026-04-10-org-refile-design.md b/docs/plans/2026-04-10-org-refile-design.md
new file mode 100644
index 0000000..ae7e881
--- /dev/null
+++ b/docs/plans/2026-04-10-org-refile-design.md
@@ -0,0 +1,70 @@
+# Org Refile Design
+
+## Context
+
+The configuration already has the core minibuffer completion stack in place:
+
+- `lisp/ss-ui.el` enables Vertico, Orderless, and Marginalia globally.
+- `lisp/ss-org.el` owns base Org configuration.
+- `lisp/ss-agenda.el` already discovers `org-agenda-files` from the journal and
+  PARA directories.
+
+The missing piece is Org refile configuration. The requested behavior is to
+refile Org entries to any heading in the current `org-agenda-files`, using a
+single, path-oriented prompt that works well with the existing Vertico-based
+completion UI.
+
+## Options Considered
+
+### 1. Recommended: configure built-in Org refile against `org-agenda-files`
+
+- Use Org's standard `org-refile` command and target machinery.
+- Refresh `org-agenda-files` before refile so the target set stays aligned with
+  the existing agenda discovery rules.
+- Configure path-based completion so Vertico and Orderless present the target
+  list cleanly.
+
+This keeps the workflow conventional, reuses existing repository structure, and
+avoids maintaining a parallel refile implementation.
+
+### 2. Add a custom wrapper command with richer target formatting
+
+- Build a custom candidate list for headings across agenda files.
+- Pass the chosen destination back into Org's refile internals.
+
+This could show more custom metadata, but it duplicates behavior Org already
+provides and increases maintenance cost for little practical gain.
+
+### 3. Add more completion packages just for refile
+
+- Introduce a Vertico extension or a separate package to alter refile prompts.
+
+This adds package surface area without first exhausting the built-in Org and
+completion capabilities already present in the config.
+
+## Chosen Design
+
+Use option 1.
+
+- Configure `org-refile-targets` to use `org-agenda-files` with unrestricted
+  heading depth.
+- Enable outline-path completion so identically named headings are
+  distinguishable by their parent path.
+- Use the direct, path-based completion flow rather than an additional outline
+  navigation step.
+- Refresh `org-agenda-files` before refile by reusing the existing agenda file
+  discovery helper instead of copying the directory rules.
+- Keep the change inside the existing module boundaries: Org behavior in
+  `lisp/ss-org.el`, with a UI tweak in `lisp/ss-ui.el` only if the current
+  completion categories need one.
+
+## Verification
+
+- Add focused ERT coverage for the refile setup helper and variable values.
+- Run `emacs --batch -Q --load ./init.el` from the repository root.
+
+## Documentation Impact
+
+`README.md` should be updated to describe that Org refile targets any heading in
+`org-agenda-files` and uses the configured minibuffer completion stack for
+path-based target selection.
\ No newline at end of file
-- 
cgit v1.2.3