feat(setup): make a fresh install land in Flock, not plain Zellij

Everything that distinguishes Flock — the sidebar dock, the project selector,
agent status — was opt-in through hand-authored KDL, so `flock` with no config
was byte-for-byte upstream `zellij`. Phase 0 of the out-of-the-box plan:

- default_layout ships as "flock" instead of being unset, so the sidebar is
  docked on startup.
- Super s opens the project selector. Super is swallowed by some terminals
  before Flock sees it; documented, with the rebind.
- flock-selector and flock-sidebar are registered as plugin aliases, and the
  bundled layouts now reference those aliases instead of restating args. Folder
  args are therefore stated once in config.kdl and reach the layouts, the
  keybinding, and each project session's sidebar alike.
- Sessions created from the selector default to the `flock` layout. They
  previously got Zellij's `default`, leaving a project opened *through* Flock
  with no sidebar and no way back to the selector.

The alias indirection removes an existing bug class by construction rather than
by discipline: a keybinding whose arg set disagreed with the layout's used to
miss the running selector and launch a second one (see the subset-match test in
plugins/plugin_map.rs). With one source of truth the sets cannot disagree.

Because the alias is resolved late and silently — an unresolved alias just loads
no plugin and renders an empty dock — both bundled layouts get a test asserting
they resolve against the shipped default config.

BREAKING: a custom ~/.config/flock/layouts/default.kdl is no longer loaded on
startup, since resolution now looks for the name "flock". Set
default_layout "default" to restore it, or rename the file to flock.kdl. Pinned
by tests in both directions.

Author: abeljim8am

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
+* feat(setup): make a fresh install land in Flock rather than in plain Zellij.
+  Everything that distinguishes Flock — the sidebar dock, the project selector,
+  agent status — was previously opt-in through hand-authored KDL, so `flock` with
+  no config behaved exactly like upstream `zellij`. Now:
+  - `default_layout` ships as `"flock"` (the default chrome plus the sidebar as a
+    left-edge dock) instead of being unset.
+  - `Super s` opens the project selector.
+  - `flock-selector` and `flock-sidebar` are registered as plugin aliases, so
+    their folder args are stated **once** in `config.kdl` and reach the bundled
+    layouts, the keybinding, and each project session's sidebar alike. The
+    bundled layouts now reference those aliases instead of restating args, which
+    removes by construction the arg-set disagreement that made a keybinding
+    launch a second selector.
+  - Sessions created from the selector default to the `flock` layout, so a
+    project opened through Flock has the sidebar. Previously they got Zellij's
+    `default` layout with no way back to the selector.
+
+  **Breaking:** a custom `~/.config/flock/layouts/default.kdl` is no longer
+  loaded on startup, because layout resolution now looks for the name `flock`.
+  Set `default_layout "default"` in your `config.kdl` to get it back, or rename
+  the file to `flock.kdl`. Setting `default_layout` to any explicit value has
+  always taken precedence and still does.
 
 ## [26.10.1] - 2026-07-28
 * fix(remote): make the sidebar's upgrade confirmation mouse-reachable, report

README.md

@@ -50,27 +50,64 @@ cargo xtask run
 cargo xtask test
 ```
 
-## Enable Flock
+## Configure Flock
 
-The bundled `flock-selector` and `flock-sidebar` layouts work out of the box.
-Remote providers are opt-in:
+Flock works with no configuration: it starts with the sidebar docked to the left
+edge, and `Super s` opens the project selector. The one thing it cannot guess is
+where your projects live.
+
+Point it at them in `~/.config/flock/config.kdl` by giving the bundled
+`flock-selector` alias its folder args:
 
 ```kdl
-plugin location="zellij:flock-selector" {
-    root_dirs "~/src"
-    codespaces_enabled "true"
-    devcontainers_enabled "true"
-    coder_enabled "true"
+plugins {
+    flock-selector location="zellij:flock-selector" {
+        cwd "/"
+        root_dirs "~/src;~/work"      // each scanned one level deep
+        individual_dirs "~/dotfiles"  // each is itself one project
+    }
+    flock-sidebar location="zellij:flock-sidebar" {
+        cwd "/"
+        root_dirs "~/src;~/work"
+        individual_dirs "~/dotfiles"
+    }
 }
+```
+
+These are *aliases*, so this is the only place the args are stated — the bundled
+layouts, the `Super s` keybinding, and the sidebar in each project session all
+resolve through them. Run `flock setup --dump-config` to see the shipped defaults
+with every option documented inline.
 
-plugin location="zellij:flock-sidebar" {
-    root_dirs "~/src"
-    codespaces_enabled "true"
-    devcontainers_enabled "true"
-    coder_enabled "true"
+If `Super s` does nothing, your terminal is intercepting `Super` (Cmd on macOS)
+before Flock sees it. Bind a key that does reach the app — this adds to the
+shipped binding rather than replacing it, which is harmless:
+
+```kdl
+keybinds {
+    shared_except "locked" {
+        bind "Alt s" {
+            LaunchOrFocusPlugin "flock-selector" {
+                floating true
+                move_to_focused_tab true
+            };
+        }
+    }
 }
 ```
 
+Remote providers are opt-in, because each needs an authenticated CLI on `PATH`.
+Add them to the aliases above:
+
+```kdl
+codespaces_enabled "true"
+devcontainers_enabled "true"
+coder_enabled "true"
+ssh_enabled "true"
+```
+
+To get the plain upstream Zellij chrome instead, set `default_layout "default"`.
+
 Provider requirements:
 
 - Codespaces: authenticated `gh` CLI.

default-plugins/flock-selector/src/config.rs

@@ -19,7 +19,13 @@ use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
 
 /// Layout new sessions open with when none is configured.
-pub const DEFAULT_SESSION_LAYOUT: &str = "default";
+///
+/// The bundled `flock` layout, not Zellij's `default`: a session opened *from
+/// the selector* that lacked the sidebar dock had no way back to the selector
+/// and no agent status, which is the entire reason to pick a project through
+/// Flock. Remote-bound sessions already default to a dock-bearing layout (see
+/// `codespaces::FLOCK_LAYOUT_TEMPLATE`); this makes local ones agree.
+pub const DEFAULT_SESSION_LAYOUT: &str = "flock";
 pub const DEFAULT_CODER_DOTFILES_PARAMETER: &str = "dotfiles_uri";
 pub const DEFAULT_CODER_DOTFILES_BRANCH_PARAMETER: &str = "dotfiles_branch";
 

zellij-utils/assets/config/default.kdl

@@ -204,6 +204,21 @@ keybinds {
         // conjure a second dock pane, which is exactly what a plugin-URL pipe does
         // when the keybind's configuration doesn't match the layout's.
         bind "Alt b" { MessagePlugin { name "flock-toggle-dock"; }; }
+        // Open the project selector. Deliberately bound through the
+        // `flock-selector` *alias* (declared in the `plugins` block below) and
+        // with no configuration of its own: the alias is the single place the
+        // selector's args are stated, so this binding can never disagree with
+        // the layout's copy and launch a second selector.
+        //
+        // Note that `Super` (Cmd on macOS) is swallowed by some terminal
+        // emulators before Flock ever sees it. Rebind this to eg. "Alt s" if
+        // the key does nothing in your terminal.
+        bind "Super s" {
+            LaunchOrFocusPlugin "flock-selector" {
+                floating true
+                move_to_focused_tab true
+            };
+        }
     }
     shared_except "normal" "locked" {
         bind "Enter" "Esc" { SwitchToMode "Normal"; }
@@ -248,6 +263,51 @@ plugins {
     configuration location="zellij:configuration"
     plugin-manager location="zellij:plugin-manager"
     about location="zellij:about"
+
+    // The two Flock plugins. Aliasing them here is what makes their
+    // configuration statable *once*: a layout, a keybinding and a generated
+    // remote layout can all say `location="flock-selector"` with no args, and
+    // every one of them resolves to the same configuration. Adding args at a
+    // call site still overrides the alias, so a single layout can opt out.
+    //
+    // Point the selector at your projects by giving the alias its folder args:
+    //
+    //   flock-selector location="zellij:flock-selector" {
+    //       root_dirs "~/src;~/work"     // each scanned one level deep
+    //       individual_dirs "~/dotfiles" // each is itself one project
+    //   }
+    //
+    // The sidebar takes the same folder args and uses them to decide which
+    // sessions belong to which project, so keep the two in sync.
+    //
+    // Remote providers are opt-in and off by default, because each needs an
+    // authenticated CLI on PATH to work at all:
+    //
+    //   codespaces_enabled "true"    // needs an authenticated `gh`
+    //   devcontainers_enabled "true" // needs the `devcontainer` CLI + Docker
+    //   coder_enabled "true"         // needs an authenticated `coder`
+    //   ssh_enabled "true"           // saved-hosts tab; Ctrl-o adds a host.
+    //                                // Key or agent auth is required — the
+    //                                // transport runs ssh with BatchMode=yes.
+    //
+    // Selector-only (the sidebar never creates workspaces), and applied only
+    // when the chosen Coder template exposes the named parameter:
+    //
+    //   coder_dotfiles_uri "https://github.com/example/dotfiles.git"
+    //   coder_dotfiles_branch "main"
+    //   coder_dotfiles_parameter "dotfiles_uri"
+    //   coder_dotfiles_branch_parameter "dotfiles_branch"
+    //
+    // `cwd` is a reserved plugin property: it sets the plugin's initial working
+    // directory (its `/host` mount) and is deliberately *not* forwarded as a
+    // configuration key. Both plugins need `/` because the project folders they
+    // scan are arbitrary host paths outside any single project.
+    flock-selector location="zellij:flock-selector" {
+        cwd "/"
+    }
+    flock-sidebar location="zellij:flock-sidebar" {
+        cwd "/"
+    }
 }
 
 // Plugins to load in the background when a new session starts
@@ -344,11 +404,15 @@ load_plugins {
 //
 // theme "default"
 
-// The name of the default layout to load on startup
-// Default: "default"
+// The name of the default layout to load on startup.
 // (Requires restart)
 //
-// default_layout "compact"
+// Flock ships "flock" rather than upstream Zellij's "default": it is the
+// "default" layout plus the flock-sidebar as a left-edge dock, which is what
+// makes agent status and session switching visible without any setup. Set this
+// to "default" for the plain upstream Zellij chrome, or to "compact" /
+// "classic" / "strider" for the other bundled layouts.
+default_layout "flock"
 
 // Choose the mode that zellij uses when starting up.
 // Default: normal

zellij-utils/assets/layouts/flock-selector.kdl

@@ -1,11 +1,12 @@
 // The `flock-selector` layout floats the project picker over a fresh session —
-// the cold-shell entry point for a `zf = "zellij --layout flock-selector"`
-// alias, mirroring the user's `zs = "zellij --layout sessionizer"`.
+// the cold-shell entry point, reached with `flock --layout flock-selector`.
 //
-// Folder sources are passed to the plugin as KDL args, matching
-// zellij-sessionizer's arg shape (individual_dirs / root_dirs / session_layout /
-// cwd). The values below are placeholders — a real config (e.g. the nix module)
-// overrides them by shipping its own copy of this layout, or the user edits it.
+// This layout deliberately carries no folder args. The picker resolves them
+// from the `flock-selector` alias in config.kdl, which is the one place they
+// are stated: adding `root_dirs` there reaches this layout, the `Super s`
+// keybinding, and the sidebar in every project session alike. Restating them
+// here would not just be redundant — a set that disagreed with the keybinding's
+// would make `Super s` miss the running picker and launch a second one.
 layout {
     // Keep the cold-selector session alive until the floating picker is ready.
     // An interactive default shell can exit during startup (eg. from shell
@@ -16,25 +17,11 @@ layout {
     }
     floating_panes {
         pane {
-            plugin location="zellij:flock-selector" {
-                cwd "/"
+            plugin location="flock-selector" {
                 // Rename this cold-shell entry session to a fixed name so it is
                 // always the same session (and the sidebar hides it) instead of
                 // a random throwaway name accumulating in the workspace list.
                 session_name "flock-selector"
-                // individual_dirs "/path/to/project;/another/project"
-                // root_dirs "/path/to/projects;/path/to/work"
-                // session_layout "default"
-                // coder_enabled "true"
-                // Saved-SSH-hosts tab (Ctrl-o adds a host; key/agent auth is
-                // required — the transport runs ssh with BatchMode=yes).
-                // ssh_enabled "true"
-                // Optional, applied only when the selected Coder template
-                // exposes this conventional parameter.
-                // coder_dotfiles_uri "https://github.com/example/dotfiles.git"
-                // coder_dotfiles_branch "main"
-                // coder_dotfiles_parameter "dotfiles_uri"
-                // coder_dotfiles_branch_parameter "dotfiles_branch"
             }
             width "70%"
             height "70%"

zellij-utils/assets/layouts/flock.kdl

@@ -9,8 +9,12 @@ layout {
     // owns which one is in effect (Alt b toggles it) and clamps both so the
     // content area always stays usable. `closed_size` must stay under the
     // sidebar's 16-column label threshold for the rail to render.
+    //
+    // Referenced through the `flock-sidebar` alias (not `zellij:flock-sidebar`)
+    // so the folder args a user adds to that alias in config.kdl reach the
+    // sidebar here without editing this layout.
     dock size=40 closed_size=5 {
-        plugin location="zellij:flock-sidebar"
+        plugin location="flock-sidebar"
     }
     pane size=1 borderless=true {
         plugin location="tab-bar"

zellij-utils/src/input/unit/layout_test.rs

@@ -2581,6 +2581,79 @@ fn flock_builtin_layout_loads_with_swap_layout() {
     .unwrap();
 }
 
+#[test]
+fn flock_bundled_layout_dock_resolves_through_the_shipped_alias() {
+    // The bundled flock layout names the sidebar by *alias*
+    // (`location="flock-sidebar"`), not by `zellij:flock-sidebar`, so that folder
+    // args a user adds to that alias in config.kdl reach the sidebar without
+    // editing the layout. That indirection is silent when it breaks: an
+    // unresolved alias simply loads no plugin and the dock renders empty. Assert
+    // the shipped default config actually resolves it.
+    let kdl_layout = include_str!("../../../assets/layouts/flock.kdl");
+    let mut layout = Layout::from_kdl(kdl_layout, Some("flock.kdl".into()), None, None).unwrap();
+
+    let dock_run = &dock_of(&layout).run;
+    assert!(
+        matches!(dock_run, RunPluginOrAlias::Alias(alias) if alias.name == "flock-sidebar"),
+        "the dock should name the sidebar by alias, got {:?}",
+        dock_run
+    );
+    assert!(
+        dock_run.get_run_plugin().is_none(),
+        "an alias should be unresolved before populating"
+    );
+
+    let default_config = crate::input::config::Config::from_default_assets().unwrap();
+    layout.populate_plugin_aliases_in_layout(&default_config.plugins);
+
+    let resolved = dock_of(&layout)
+        .run
+        .get_run_plugin()
+        .expect("the shipped default config must define a `flock-sidebar` alias");
+    assert_eq!(
+        resolved.location,
+        RunPluginLocation::parse("zellij:flock-sidebar", None).unwrap(),
+        "the alias must resolve to the built-in flock-sidebar plugin"
+    );
+}
+
+#[test]
+fn flock_selector_bundled_layout_resolves_through_the_shipped_alias() {
+    // Same contract for the cold-shell picker layout. It keeps only
+    // `session_name` as a call-site arg; everything else must come from the
+    // alias, so that this layout and the `Super s` keybinding agree on
+    // configuration and the keybinding focuses the running picker instead of
+    // launching a second one.
+    let (layout_path, kdl_layout, _) =
+        Layout::stringified_from_default_assets(std::path::Path::new("flock-selector")).unwrap();
+    let mut layout = Layout::from_kdl(&kdl_layout, Some(layout_path), None, None).unwrap();
+
+    let default_config = crate::input::config::Config::from_default_assets().unwrap();
+    layout.populate_plugin_aliases_in_layout(&default_config.plugins);
+
+    let (_, floating_panes) = layout.template.clone().expect("layout has a template");
+    let selector = floating_panes
+        .iter()
+        .find_map(|pane| match pane.run.as_ref() {
+            Some(Run::Plugin(run)) => run.get_run_plugin(),
+            _ => None,
+        })
+        .expect("the selector layout floats a resolved plugin pane");
+    assert_eq!(
+        selector.location,
+        RunPluginLocation::parse("zellij:flock-selector", None).unwrap(),
+    );
+    assert_eq!(
+        selector
+            .configuration
+            .inner()
+            .get("session_name")
+            .map(|s| s.as_str()),
+        Some("flock-selector"),
+        "the call-site session_name must survive alias merging"
+    );
+}
+
 fn dock_of(layout: &Layout) -> &DockLayout {
     layout.dock.as_ref().expect("layout should have a dock")
 }

zellij-utils/src/kdl/snapshots/zellij_utils__kdl__bare_config_from_default_assets_to_string.snap

@@ -172,6 +172,12 @@ keybinds clear-defaults=true {
         bind "Alt p" { TogglePaneInGroup; }
         bind "Alt Shift p" { ToggleGroupMarking; }
         bind "Ctrl q" { Quit; }
+        bind "Super s" {
+            LaunchOrFocusPlugin "flock-selector" {
+                floating true
+                move_to_focused_tab true
+            }
+        }
     }
     shared_except "locked" "move" {
         bind "Ctrl h" { SwitchToMode "move"; }
@@ -267,6 +273,12 @@ plugins {
     filepicker location="zellij:strider" {
         cwd "/"
     }
+    flock-selector location="zellij:flock-selector" {
+        cwd "/"
+    }
+    flock-sidebar location="zellij:flock-sidebar" {
+        cwd "/"
+    }
     plugin-manager location="zellij:plugin-manager"
     session-manager location="zellij:session-manager"
     status-bar location="zellij:status-bar"
@@ -282,4 +294,5 @@ load_plugins {
 web_client {
     font "monospace"
 }
+default_layout "flock"