feat!: simplify popup_mode with auto-detection via env var

Drop the PID-file hack. The tmux script now passes ORG_SUPER_AGENDA_POPUP=1
via new-session -e so nvim sees it at startup. wipe() checks the env var
lazily at call time, so popup mode works without any user config.
hide_command defaults to 'tmux detach-client' which cleanly closes the
display-popup when attach-session exits.

BREAKING CHANGE: users on the old PID-file hide_command must update their
tmux script and remove the manual popup_mode config block.

Author: hamidi-dev

README.md

@@ -163,10 +163,11 @@ return {
       -- Global fallback sort for groups that omit `sort`
       group_sort = { by='date_nearest', order='asc' },
 
-      -- Popup mode: run in a persistent tmux session for instant access
+      -- Popup mode: auto-detected when launched via the tmux script (ORG_SUPER_AGENDA_POPUP=1).
+      -- Override only if you use a different popup mechanism.
       popup_mode = {
-        enabled      = false,
-        hide_command = nil, -- e.g., "tmux detach-client"
+        enabled      = vim.env.ORG_SUPER_AGENDA_POPUP == '1',
+        hide_command = 'tmux detach-client',
       },
 
       debug = false,
@@ -443,17 +444,43 @@ When you press `s` and wait, a colored menu appears showing all available states
 
 ## 🪟 Popup Mode (tmux integration)
 
-Run OrgSuperAgenda in a dedicated tmux session for instant access. When enabled, pressing `q` hides the session instead of closing the buffer.
+Run OrgSuperAgenda in a dedicated tmux session for instant access. Pressing `q` hides the popup (nvim keeps running in the background) instead of closing the buffer.
+
+**No config needed** — popup mode is auto-detected when launched via the script below.
+
+**tmux script** (`~/.local/bin/tmux-org-agenda.sh` or anywhere on your `$PATH`):
+
+```bash
+#!/usr/bin/env bash
+SESSION="_org_agenda"
+
+if ! tmux has-session -t "=$SESSION" 2>/dev/null; then
+  tmux new-session -d -s "$SESSION" -e "ORG_SUPER_AGENDA_POPUP=1" \
+    "nvim +'autocmd User VeryLazy ++once OrgSuperAgenda fullscreen'"
+  tmux set-option -t "$SESSION" status off
+fi
+
+tmux display-popup -w 100% -h 99% -E \
+  "tmux attach-session -t '=$SESSION'"
+```
+
+**tmux binding**:
+
+```tmux
+bind -n 'M-a' run-shell -b "$HOME/.local/bin/tmux-org-agenda.sh"
+```
+
+That's it. The `ORG_SUPER_AGENDA_POPUP=1` env var tells the plugin it's running in a popup, so `q` runs `tmux detach-client` to hide the popup cleanly.
+
+Override if you use a different mechanism:
 
 ```lua
 popup_mode = {
-  enabled      = true,
-  hide_command = "tmux detach-client",
+  enabled      = true,            -- or use your own detection logic
+  hide_command = "my-hide-cmd",   -- anything that dismisses your popup
 }
 ```
 
-You can bind a tmux key to toggle the popup session for quick agenda access.
-
 ---
 
 ## ⚠️ Safety & behavior details

lua/org-super-agenda/adapters/neovim/actions.lua

@@ -791,8 +791,11 @@ function A.set_keymaps(buf, win, line_map, reopen)
 
   -- close
   local function wipe()
-    local popup = cfg.popup_mode
-    if popup and popup.enabled and popup.hide_command then
+    local popup = get_cfg().popup_mode
+    -- Check enabled lazily at call time: explicit config OR env var set in the nvim session.
+    -- The env var approach is the zero-config path for the tmux script.
+    local enabled = popup and (popup.enabled or vim.env.ORG_SUPER_AGENDA_POPUP == '1')
+    if enabled and popup and popup.hide_command then
       -- Popup mode: detach from tmux session to hide the popup
       vim.fn.system(popup.hide_command)
     else

lua/org-super-agenda/config.lua

@@ -174,10 +174,12 @@ M.defaults = {
   -- Global fallback sort for groups that don't specify their own `sort`
   group_sort = { by = 'date_nearest', order = 'asc' },
 
-  -- Popup mode: when enabled, 'q' detaches from tmux instead of closing the buffer
+  -- Popup mode: when enabled, 'q' hides the popup instead of closing the buffer.
+  -- Auto-detected when launched via the org-super-agenda tmux script (ORG_SUPER_AGENDA_POPUP=1).
+  -- Override `hide_command` if you use a different popup mechanism.
   popup_mode = {
-    enabled = false,
-    hide_command = nil, -- e.g., "tmux detach-client"
+    enabled = vim.env.ORG_SUPER_AGENDA_POPUP == '1',
+    hide_command = 'tmux detach-client', -- closes the display-popup when attach-session exits
   },
 
   debug = false,