feat(selector): make an empty project list explain how to fill it

[abeljim8am]

Stacked on #29 → #28 → #27. Review those first; this PR's diff is only the Phase 3 commit.

Why

Flock deliberately does not go hunting for projects on its own (your call in the Phase 0 planning), and bare flock now opens the selector (#29). Those two together mean an empty project list is the first screen a new user sees — and it said " no project folders configured" and stopped there. A status line reporting itself, with no way to act on it.

It is now the setup instructions:

 no project folders configured
 add them to your config.kdl:
     flock {
         root_dirs "~/src" "~/work"
     }
 then reopen the selector

The configured-but-empty state got the same treatment. " no projects found" alone gives no way to spot the common misconfiguration, so it now names it: root_dirs is scanned one level deep, so a root pointed at a project rather than at the folder containing it finds nothing — and individual_dirs is the option for a folder that is itself a project.

Both blocks fall back to a single line that still names the fix when the pane is too short for the full form; a truncated block would trail off mid-snippet, which is worse than a compact line. A search with no matches stays a plain status line — mid-search is not the moment for setup instructions.

What I dropped, and why

The plan's second bullet was an in-app "add a project folder" action that writes to flock { }. I recommended against it and you agreed, so it is not here.

The only way a plugin can persist to config.kdl is reconfigure, which rewrites the entire file from the serialized config. It does back the old one up and prepend a pointer to the backup — but comments and formatting do not survive in the live file. It also needs a new Reconfigure permission, which is a one-time dialog for every existing user, and for a declaratively-managed config (nix, dotfiles, chezmoi) it would replace the symlink and break the manager. Paying all of that to save one paste, on a file the user owns and that we deliberately document with comments, is the wrong trade.

Recorded in the plan doc as revisitable only if the flock { } block can be patched surgically with comments preserved.

Verification

• cargo xtask test — 2371 passing, 0 failures. cargo xtask format --check clean.
• 7 new tests. project_hint is a pure function returning rows, so the logic is tested directly: the unconfigured block names file + snippet, the short-pane fallback still names problem and fix, every tier fits the capacity it was given (looped over capacities 0–7), the configured-but-empty block names the one-level-deep behaviour and individual_dirs, and a non-empty query stays a plain status line. One test goes through render to prove the multi-row wiring and that the block is not selectable.
• Checked as rendered, not just as asserted. I replayed the pty output of a real session onto a character grid to see the actual screen. This mattered: each row is separately cursor-positioned, so the multi-line text is not contiguous in the byte stream and my first grep -F on the whole phrase reported "not found" even though it was rendering correctly. Verifying by substring search alone would have been misleading in both directions.
• Also worth noting from that session: the selector opens on the Sessions tab, so reaching the projects empty state needs a Tab — the block is not what a first-run user sees until they switch. Worth a follow-up thought about which tab the picker should open on when no projects are configured.

Note on the .wasm asset

zellij-utils/assets/plugins/flock-selector.wasm is regenerated and included, because release builds embed assets/plugins while debug builds read target/ (consts.rs:169-182) — without it the change would not ship. Rebuilding also rewrote the other fourteen plugin assets (they were last built with a different toolchain); those are reverted, per AGENTS.md's guidance to avoid committing regenerated assets that are not part of the change.

🤖 Generated with Claude Code

[abeljim]

Superseded by mega PR #35