# 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.