@cueloop/client 0.1.0-alpha.15 → 0.1.0-alpha.17

package/src/components/WalkWizard.tsx

@@ -0,0 +1,146 @@
+/**
+ * The guided walk's focused card wizard: one card per changed file
+ * floating over the dimmed diff, with a plain step count in the title - no
+ * progress bar. Below the main card a separate gray-bordered block carries
+ * the submitting agent's note for the file, when one exists. Past the last
+ * file the end card offers the submit action directly with honest counts.
+ * The keys live in the keymap's walk overlay; this component only renders.
+ */
+
+import React from "react";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import type { WalkFile } from "../walk";
+import { viewedCount } from "../walk";
+import { Card } from "./primitives/Card";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface WalkWizardProps {
+  files: WalkFile[];
+  /** The wizard step; index === files.length renders the end card. */
+  index: number;
+  viewedPaths: ReadonlySet<string>;
+  /** The agent's note for the current file; the gray block renders only when set. */
+  note?: string;
+  /** Terminal width bounds the card width. */
+  terminalWidth: number;
+  /** End-card submit: leaves the walk and opens the rail confirm. */
+  onSubmitRequest: () => void;
+  onBack: () => void;
+  theme?: Theme;
+}
+
+/** The card never crowds the terminal edge nor stretches past reading width. */
+function wizardWidth(terminalWidth: number): number {
+  return Math.min(72, Math.max(24, terminalWidth - 8));
+}
+
+/** Note rows from a crude wrap estimate, capped so the block stays a block. */
+function noteRows(note: string, innerWidth: number): number {
+  return Math.min(3, Math.max(1, Math.ceil(note.length / Math.max(1, innerWidth))));
+}
+
+export function WalkWizard({
+  files,
+  index,
+  viewedPaths,
+  note,
+  terminalWidth,
+  onSubmitRequest,
+  onBack,
+  theme,
+}: WalkWizardProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const width = wizardWidth(terminalWidth);
+  const viewed = viewedCount(files, viewedPaths);
+  const atEnd = index >= files.length;
+  const currentFile = files[index];
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        alignItems: "center",
+        justifyContent: "center",
+        flexDirection: "column",
+      }}
+    >
+      <box style={{ width, flexDirection: "column" }}>
+        {atEnd || !currentFile ? (
+          <Card
+            title=" walk complete "
+            contentRows={3}
+            borderColor={tokens.green}
+            backgroundColor={tokens.panel}
+            theme={theme}
+          >
+            <text fg={tokens.text}>
+              {viewed === files.length
+                ? `every file viewed (${viewed}/${files.length})`
+                : `${viewed} of ${files.length} files viewed`}
+            </text>
+            <box style={{ height: 1 }} />
+            <Toolbar>
+              <Button variant="solid" marginRight={2} onPress={onSubmitRequest} theme={theme}>
+                {" Submit review "}
+              </Button>
+              <Button onPress={onBack} theme={theme}>
+                {" [ back "}
+              </Button>
+            </Toolbar>
+          </Card>
+        ) : (
+          <>
+            <Card
+              title={` file ${index + 1} of ${files.length} · ${viewed} viewed `}
+              contentRows={3 + Math.max(1, currentFile.preview.length)}
+              borderColor={tokens.accent}
+              backgroundColor={tokens.panel}
+              theme={theme}
+            >
+              <text fg={tokens.text}>{currentFile.path}</text>
+              <text>
+                <span fg={tokens.green}>{`+${currentFile.added}`}</span>
+                <span fg={tokens.textDim}>{" "}</span>
+                <span fg={tokens.red}>{`-${currentFile.removed}`}</span>
+                <span fg={tokens.textDim}>{viewedPaths.has(currentFile.path) ? " · viewed" : ""}</span>
+              </text>
+              <box style={{ height: 1 }} />
+              {currentFile.preview.length === 0 ? (
+                <text fg={tokens.textDim}>(no changed lines)</text>
+              ) : (
+                currentFile.preview.map((previewLine, previewIndex) => (
+                  <text
+                    key={previewIndex}
+                    style={{ wrapMode: "none" }}
+                    fg={previewLine.sign === "+" ? tokens.insFg : tokens.delFg}
+                  >
+                    {previewLine.sign + previewLine.text}
+                  </text>
+                ))
+              )}
+            </Card>
+            {note !== undefined ? (
+              <box style={{ marginTop: 1, flexDirection: "column" }}>
+                <Card
+                  title=" agent note "
+                  contentRows={noteRows(note, width - 4)}
+                  borderColor={tokens.border}
+                  backgroundColor={tokens.panel}
+                  theme={theme}
+                >
+                  <text fg={tokens.textMuted}>{note}</text>
+                </Card>
+              </box>
+            ) : null}
+          </>
+        )}
+      </box>
+    </box>
+  );
+}

package/src/components/__snapshots__/stories.test.tsx.snap

@@ -1184,6 +1184,136 @@ exports[`stories catalog theme-context/ProviderSwap renders, snapshots, and carr
                                                                                 
                                                                                 
                                                                                 
+                                                                                
+"
+`;
+
+exports[`stories catalog ConfirmCard/WithViewedSummary renders, snapshots, and carries its colors: ConfirmCard/WithViewedSummary 1`] = `
+"╭─ submit review ─────────────────────╮ 
+│ 1 annotations · 0 blocking          │ 
+│ 2/3 files viewed                    │ 
+│                                     │ 
+│  Comment  [Approve]  Changes        │ 
+│                                     │ 
+│ summary for the agent (optional)    │ 
+│                                     │ 
+│  Submit    Cancel                   │ 
+╰─────────────────────────────────────╯ 
+                                        
+                                        
+                                        
+                                        
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCard renders, snapshots, and carries its colors: WalkWizard/EndCard 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ every file viewed (3/3)                                              │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCardPartialPass renders, snapshots, and carries its colors: WalkWizard/EndCardPartialPass 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ 1 of 3 files viewed                                                  │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/FirstFile renders, snapshots, and carries its colors: WalkWizard/FirstFile 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 1 of 3 · 0 viewed ─────────────────────────────────────────────╮    
+    │ packages/daemon/src/store.ts                                         │    
+    │ +12 -3                                                               │    
+    │                                                                      │    
+    │ +const viewed = new Set<string>();                                   │    
+    │ +record.viewedPaths = [...viewed];                                   │    
+    │ -// viewed tracking lives in the client only                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/WithAgentNote renders, snapshots, and carries its colors: WalkWizard/WithAgentNote 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 2 of 3 · 1 viewed ─────────────────────────────────────────────╮    
+    │ packages/client/src/walk.ts                                          │    
+    │ +48 -0                                                               │    
+    │                                                                      │    
+    │ +export function firstUnviewedIndex(files, viewed) {                 │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+    ╭─ agent note ─────────────────────────────────────────────────────────╮    
+    │ New module: pure helpers that pick the next unviewed file. No IO,    │    
+    │ unit tested.                                                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
                                                                                 
 "
 `;

package/src/components/stories.test.tsx

@@ -1,5 +1,5 @@
 /**
- * The catalog IS the regression suite (#86): every exported story renders in
+ * The catalog IS the regression suite: every exported story renders in
  * a virtual terminal, its char frame snapshots, and its declared colors must
  * appear among the styled spans. A component file without a colocated
  * stories file fails the harness, so the safety net cannot silently thin.

package/src/components/story-fixtures.ts

@@ -1,7 +1,7 @@
 /** Shared fixture data for the stories catalog: one plan session, one diff. */
 
 import type { Annotation, ReviewSession } from "@cueloop/schema";
-import { buildDisplay, marksByDisplay } from "../view";
+import { buildDisplay, marksByDisplay } from "../view-plan";
 import { diffRows } from "../view-diff";
 
 export const FIXTURE_PLAN = `# Migration Plan

package/src/components/story.ts

@@ -1,5 +1,5 @@
 /**
- * The story contract (#86). Every component file in components/ ships a
+ * The story contract. Every component file in components/ ships a
  * colocated *.stories.tsx that exports `meta` plus named Story objects.
  * The catalog IS the regression suite: stories.test.tsx walks every story,
  * snapshots its char frame, and asserts declared colors against the styled

package/src/components/syntax-highlight.ts

@@ -1,5 +1,5 @@
 /**
- * Code highlighting tokens (#86): the theme's named tokens projected onto
+ * Code highlighting tokens: the theme's named tokens projected onto
  * tree-sitter capture names for the native code renderable. One SyntaxStyle
  * per theme object, cached, so every code block on screen shares a handle.
  * Unknown languages simply render unstyled - highlighting is an enhancement,

package/src/components/theme-context.tsx

@@ -1,5 +1,5 @@
 /**
- * Provider theming for the component system (#86). The context default is the
+ * Provider theming for the component system. The context default is the
  * built-in dark theme, so embedding a component (or rendering a story) needs
  * no provider at all. One ThemeProvider swap switches the live theme; every
  * component also accepts an optional `theme` prop that overrides the context

package/src/components/truncate-text.ts

@@ -0,0 +1,6 @@
+/** Truncate text to one line of at most maxLength characters, ellipsis-terminated. */
+
+export function truncateToSingleLine(value: string, maxLength: number): string {
+  const oneLine = value.replace(/\n/g, " ");
+  return oneLine.length > maxLength ? oneLine.slice(0, maxLength - 1) + "…" : oneLine;
+}

package/src/config.test.ts

@@ -7,9 +7,9 @@ import { DARK } from "./theme";
 
 describe("loadConfig", () => {
   test("defaults when no file exists", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.keys["comment"]).toEqual(["c"]);
-    expect(c.theme.accent).toBe(DARK.accent);
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(config.keys["comment"]).toEqual(["c"]);
+    expect(config.theme.accent).toBe(DARK.accent);
   });
 
   test("user config rebinds actions and overrides theme tokens", () => {
@@ -20,12 +20,12 @@ describe("loadConfig", () => {
       `[keys]\ncomment = "a"\nsubmit = ["return", "S"]\n\n[theme]\naccent = "#ff0000"\n`,
     );
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["a"]);
-      expect(c.keys["submit"]).toEqual(["return", "S"]);
-      expect(c.keys["cut"]).toEqual(["x"]); // untouched defaults survive
-      expect(c.theme.accent).toBe("#ff0000");
-      expect(c.theme.green).toBe(DARK.green);
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.keys["comment"]).toEqual(["a"]);
+      expect(config.keys["submit"]).toEqual(["return", "S"]);
+      expect(config.keys["cut"]).toEqual(["x"]); // untouched defaults survive
+      expect(config.theme.accent).toBe("#ff0000");
+      expect(config.theme.green).toBe(DARK.green);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -39,8 +39,8 @@ describe("loadConfig", () => {
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[keys]\ncomment = "z"\n`);
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.keys["comment"]).toEqual(["z"]);
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+      expect(config.keys["comment"]).toEqual(["z"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -51,8 +51,8 @@ describe("loadConfig", () => {
     const path = join(dir, "config.toml");
     writeFileSync(path, "not [valid toml");
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["c"]);
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.keys["comment"]).toEqual(["c"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -61,12 +61,12 @@ describe("loadConfig", () => {
 
 describe("integrations.obsidian config", () => {
   test("defaults when the section is absent", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.integrations.obsidian.vault).toBeUndefined();
-    expect(c.integrations.obsidian.folder).toBe("cueloop");
-    expect(c.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
-    expect(c.integrations.obsidian.separator).toBe("space");
-    expect(c.integrations.obsidian.exportOn).toBe("manual");
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(config.integrations.obsidian.vault).toBeUndefined();
+    expect(config.integrations.obsidian.folder).toBe("cueloop");
+    expect(config.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
+    expect(config.integrations.obsidian.separator).toBe("space");
+    expect(config.integrations.obsidian.exportOn).toBe("manual");
   });
 
   test("user config sets the section; invalid enum values are ignored", () => {
@@ -77,12 +77,12 @@ describe("integrations.obsidian config", () => {
       `[integrations.obsidian]\nvault = "/notes/vault"\nfolder = "plans"\nexportOn = "approve"\nseparator = "comma"\n`,
     );
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.integrations.obsidian.vault).toBe("/notes/vault");
-      expect(c.integrations.obsidian.folder).toBe("plans");
-      expect(c.integrations.obsidian.exportOn).toBe("approve");
-      expect(c.integrations.obsidian.separator).toBe("space"); // invalid value falls back
-      expect(c.keys["comment"]).toEqual(["c"]); // other sections untouched
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.integrations.obsidian.vault).toBe("/notes/vault");
+      expect(config.integrations.obsidian.folder).toBe("plans");
+      expect(config.integrations.obsidian.exportOn).toBe("approve");
+      expect(config.integrations.obsidian.separator).toBe("space"); // invalid value falls back
+      expect(config.keys["comment"]).toEqual(["c"]); // other sections untouched
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -96,10 +96,10 @@ describe("integrations.obsidian config", () => {
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[integrations.obsidian]\nfolder = "repo-plans"\n`);
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
-      expect(c.integrations.obsidian.exportOn).toBe("resolve");
-      expect(c.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+      expect(config.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
+      expect(config.integrations.obsidian.exportOn).toBe("resolve");
+      expect(config.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/src/config.ts

@@ -1,5 +1,5 @@
 /**
- * Layered TOML config (#20): built-in defaults → user config → trusted repo
+ * Layered TOML config: built-in defaults → user config → trusted repo
  * config → env. Sections: [keys] action = "combo" (every action rebindable),
  * [theme] per-token overrides, [integrations.obsidian] notes-vault export.
  */
@@ -46,6 +46,7 @@ export const DEFAULT_KEYS: Record<string, string[]> = {
   delete_annotation: ["backspace"],
   submit: ["return", "enter"],
   quit: ["q"],
+  walk: ["w"],
 };
 
 function parseToml(text: string): Record<string, unknown> {
@@ -82,19 +83,19 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
   const integrations = raw["integrations"] as Record<string, unknown> | undefined;
   const obsidian = integrations?.["obsidian"] as Record<string, unknown> | undefined;
   if (obsidian) {
-    const o = out.integrations.obsidian;
-    if (typeof obsidian["vault"] === "string") o.vault = obsidian["vault"];
-    if (typeof obsidian["folder"] === "string") o.folder = obsidian["folder"];
-    if (typeof obsidian["filenameFormat"] === "string") o.filenameFormat = obsidian["filenameFormat"];
-    const sep = obsidian["separator"];
-    if (sep === "space" || sep === "dash" || sep === "underscore") o.separator = sep;
-    const on = obsidian["exportOn"];
-    if (on === "approve" || on === "resolve" || on === "manual") o.exportOn = on;
+    const obsidianConfig = out.integrations.obsidian;
+    if (typeof obsidian["vault"] === "string") obsidianConfig.vault = obsidian["vault"];
+    if (typeof obsidian["folder"] === "string") obsidianConfig.folder = obsidian["folder"];
+    if (typeof obsidian["filenameFormat"] === "string") obsidianConfig.filenameFormat = obsidian["filenameFormat"];
+    const separator = obsidian["separator"];
+    if (separator === "space" || separator === "dash" || separator === "underscore") obsidianConfig.separator = separator;
+    const exportOn = obsidian["exportOn"];
+    if (exportOn === "approve" || exportOn === "resolve" || exportOn === "manual") obsidianConfig.exportOn = exportOn;
   }
   return out;
 }
 
-export function loadConfig(opts: { repoRoot?: string; userConfigPath?: string } = {}): CueloopConfig {
+export function loadConfig(options: { repoRoot?: string; userConfigPath?: string } = {}): CueloopConfig {
   let config: CueloopConfig = {
     keys: { ...DEFAULT_KEYS },
     theme: { ...DARK },
@@ -102,10 +103,10 @@ export function loadConfig(opts: { repoRoot?: string; userConfigPath?: string }
     integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
   };
   const userPath =
-    opts.userConfigPath ??
+    options.userConfigPath ??
     process.env.CUELOOP_CONFIG ??
     join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml");
-  for (const path of [userPath, opts.repoRoot ? join(opts.repoRoot, ".cueloop", "config.toml") : undefined]) {
+  for (const path of [userPath, options.repoRoot ? join(options.repoRoot, ".cueloop", "config.toml") : undefined]) {
     if (!path || !existsSync(path)) continue;
     try {
       config = layer(config, parseToml(readFileSync(path, "utf8")));

package/src/editor.ts

@@ -1,5 +1,5 @@
 /**
- * File-level edit mode = the $EDITOR hand-off (#22, #11): write the working
+ * File-level edit mode = the $EDITOR hand-off: write the working
  * copy to a temp file, run the user's editor on it, read the result back.
  * Tests point CUELOOP_EDITOR at a non-interactive command.
  */

package/src/herdr.ts

@@ -1,5 +1,5 @@
 /**
- * First-class herdr return (#23): a review opened beside an agent should hand
+ * First-class herdr return: a review opened beside an agent should hand
  * focus back to the agent's pane when it closes, not leave the reviewer on a
  * dead tab. Detection is the ambient env contract; the return target comes
  * from CUELOOP_RETURN_PANE (set by whoever opened this pane) or the session's

package/src/key-bindings.test.ts

@@ -8,7 +8,7 @@ import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
 import { KeyBindings } from "./key-bindings";
 
-function bindings(context: { overlay?: "none" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
+function bindings(context: { overlay?: "none" | "walk" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
   const resolver = new KeyBindings(DEFAULT_KEYS);
   resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
   return resolver;
@@ -62,6 +62,17 @@ describe("mode layers own their keys", () => {
     expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
   });
+
+  test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    const resolver = bindings({ overlay: "walk" });
+    expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
+    expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("walk_submit");
+    expect(resolver.resolveAction({ name: "q", shift: false })).toBe("quit");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+  });
 });
 
 describe("getActiveKeys-generated status hints", () => {
@@ -89,6 +100,12 @@ describe("getActiveKeys-generated status hints", () => {
     expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe("verdict ←/→ · ⏎ submit · esc cancel");
   });
 
+  test("walk hint", () => {
+    expect(bindings({ overlay: "walk" }).statusHint("walk")).toBe(
+      "walk · ] next (marks viewed) · [ back · esc leave walk · q quit",
+    );
+  });
+
   test("read-only hint", () => {
     expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
   });

package/src/key-bindings.ts

@@ -1,5 +1,5 @@
 /**
- * Binding resolution over @opentui/keymap (#86): the loaded config keymap
+ * Binding resolution over @opentui/keymap: the loaded config keymap
  * registers as layers (grammar, span, compose, submit, completion) on one
  * Keymap instance, key events resolve to action names through its dispatch,
  * and the status-line hints generate from getActiveKeys() - a rebound key
@@ -24,7 +24,7 @@ export interface KeyLayerContext {
 }
 
 /** Hint templates keyed by the same view states the status line shows. */
-export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "read-only";
+export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
 
 type HintEntry =
   | { text: string }
@@ -70,6 +70,13 @@ const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
     { commands: ["submit_verdict"], label: "submit" },
     { commands: ["cancel_submit"], label: "cancel" },
   ],
+  walk: [
+    { text: "walk" },
+    { commands: ["walk_next"], label: "next (marks viewed)" },
+    { commands: ["walk_prev"], label: "back" },
+    { commands: ["walk_leave"], label: "leave walk" },
+    { commands: ["quit"], label: "quit" },
+  ],
   "read-only": [
     { text: "observer - read-only" },
     { commands: ["down", "up"], label: "move" },
@@ -243,6 +250,20 @@ export class KeyBindings {
       bindings: SPAN_COMMANDS.map(([key, command]) => ({ key, cmd: command })),
       commands: SPAN_COMMANDS.map(([, command]) => record(command)),
     });
+    // the walk wizard: prev/next stepping, leave, and submit from the end card
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "walk",
+      bindings: [
+        { key: "]", cmd: "walk_next" },
+        { key: "[", cmd: "walk_prev" },
+        { key: "escape", cmd: "walk_leave" },
+        { key: "return", cmd: "walk_submit" },
+        { key: "enter", cmd: "walk_submit" },
+        { key: "q", cmd: "quit" },
+      ],
+      commands: [record("walk_next"), record("walk_prev"), record("walk_leave"), record("walk_submit"), record("quit")],
+    });
     this.keymap.registerLayer({
       priority: 20,
       when: () => this.context.overlay === "compose",